DOCSEARCHbyAlgolia
Submit Docs

osc.js Documentation

repository·main·Indexed 21 days ago

https://github.com/colinbdclark/osc.js

A cross-platform JavaScript library for reading and writing Open Sound Control (OSC) messages, compatible with Node.js and modern web browsers. It provides a low-level functional API for encoding and decoding OSC packets using TypedArrays and DataView, as well as a transport-agnostic Port API (including UDPPort and WebSocketPort) for sending and receiving messages via an EventEmitter-style interface.

Tokens
1.5K
Snippets
4
Records
8
Agent score
24%

What's inside osc.js

  1. How osc.js works: Functional API vs Port API

    main

    osc.js operates using two distinct layers:

    1. Low-level functional API: Provides stateless functions for reading and writing OSC packets (encoding/decoding). Use this if you want to write your own transports or need a low-level interface.
    2. Transport layer (Port API): Provides an EventEmitter-style API for sending and receiving OSC packets over various transports (UDP, WebSockets, etc.). This is the typical way to use the library.

    All Port objects are transport-agnostic at the core, meaning you can connect them to any source of incoming/outgoing data (Serial, WebRTC, WebSockets, etc.).

  2. Install osc.js via npm

    main

    To use osc.js in an npm-based project, add it to your package.json dependencies and run npm install.

    Example package.json snippet:

    {
    "name": "<your project name>",
    "version": "<your project version>",
    "dependencies": {
        "osc": "2.4.1"
    }
}
    npm install

  3. Install osc.js for Electron Applications

    main

    Because osc.js depends on native Node.js modules (like node-serialport), you must ensure they are compiled against the Electron version of Node.js.

    Option 1: Use electron-rebuild Follow the instructions for node-serialport and use electron-rebuild to recompile dependencies after running npm install.

    Option 2: Use an .npmrc file Create an .npmrc file in your project root to override the compile target. Ensure the target matches your Electron version.

    target=23.1.3
disturl=https://electronjs.org/headers
runtime=electron
build_from_source=true

  4. Use osc.WebSocketPort in the Browser

    main

    The osc.WebSocketPort allows sending and receiving OSC messages over WebSockets in a browser environment.

    Options:

    • url (required for clients): The Web Socket URL to connect to.
    • socket (optional): A Web Socket instance to bind to. If supplied, you are responsible for configuring and opening it.

    Implementation Steps:

    1. Include osc-browser.min.js in your HTML.
    2. Instantiate the port with a URL.
    3. Call .open().
    4. Listen for the ready event before calling .send().
    <script src="node_modules/osc.js/dist/osc-browser.min.js"></script>
    var oscPort = new osc.WebSocketPort({
    url: "ws://localhost:8081",
    metadata: true
});

oscPort.open();

oscPort.on("message", function (oscMsg) {
    console.log("An OSC message just arrived!", oscMsg);
});

oscPort.on("ready", function () {
    oscPort.send({
        address: "/carrier/frequency",
        args: [{ type: "f", value: 440 }]
    });
});

  5. osc.Port Methods

    main

    All osc.Port objects implement the following method for sending data:

    MethodDescriptionArguments
    sendSends an OSC package (message or bundle) on this Portpacket: the OSC message or bundle to send
    oscPort.send(packet);

  6. The osc.js Low-Level Functional API

    main

    The low-level API provides stateless functions for manual encoding and decoding of OSC data.

    Core Functions

    | Function | Description | Arguments | Return Value | | :--- | :--- | :--- | :| | osc.readPacket() | Decodes binary OSC into JS objects | data (Uint8Array), options (optional), offsetState (optional), length | An osc.js message or bundle object | | osc.writePacket() | Writes an OSC object to a binary array | packet (message/bundle), options (optional) | A Uint8Array |

    Data Structures

    Messages:

    {
    "address": "/an/osc/address",
    "args": [ { "type": "f", "value": 440.4 } ]
}

    Bundles:

    {
    "timeTag": { "raw": [123, 456], "native": 167890123 },
    "packets": [ { "address": "/msg", "args": [] } ]
}

    Argument Objects (with metadata): When metadata: true is used, arguments include type information:

    {
    "type": "f",
    "value": 444.4
}

    Configuration Options

    Both the functional API and Port constructors accept an options object:

    • metadata (boolean, default: false): If true, includes OSC type metadata in arguments.
    • unpackSingleArgs (boolean, default: true): If true, automatically unpacks single-argument messages so args is not wrapped in an extra array.
    // Reading a packet
try {
    const msg = osc.readPacket(rawUint8Array);
} catch (error) {
    console.error(error.message);
}

// Writing a packet
const binaryData = osc.writePacket(myOscObject);

  7. Use osc.UDPPort in Node.js

    main

    The osc.UDPPort supports sending and receiving OSC messages over Node.js UDP sockets, including broadcast and multicast.

    Options:

    • localPort: Port to listen on (default: 57121).
    • localAddress: Local address to bind to (default: `

  8. osc.Port Events

    main

    All osc.Port objects implement the Event Emitter API. Supported events include:

    EventDescriptionArguments
    readyFires when a Port is ready to send or receive messagesnone
    messageFires whenever an OSC message is receivedmessage (the OSC message), timeTag (sender's timestamp), info (remote info)
    bundleFires whenever an OSC bundle is receivedbundle (the OSC bundle), timeTag, info
    oscFires whenever any type of OSC packet is receivedpacket (message or bundle), info
    rawFires whenever any data is receiveddata (Uint8Array), info
    errorFires whenever an error occurserror (the Error object)