osc.js

osc.js is a library for reading and writing Open Sound Control messages in JavaScript. It works in both Node.js and in a web browser.

osc.js is maintained by Colin Clark. Please respect his unpaid labour (and that of other open source contributors), be kind, share projects you're working on, and consider contributing your own time to help improve the library. :heart:

Why osc.js?

There are several other OSC libraries available for JavaScript. However, most depend on Node.js-specific APIs. This means that they can't be run in a browser or on web-only platforms such as Chrome OS. osc.js uses only cross-platform APIs (TypedArrays and DataView), ensuring that it can run in any modern JavaScript environment.

osc.js is fast, comprehensive, fully spec-compliant, tested, modular, and provides a wide variety of optional transports for sending and receiving OSC data.

What Does it Do?

osc.js reads and writes OSC-formatted binary data into plain JavaScript objects. It provides adaptors for Node.js Buffer objects as well as standard ArrayBuffers.

The core of osc.js is transport agnostic. You can receive OSC data in whatever manner works best for your application: serial port APIs such as node-serialport or chrome.serial, socket APIs such as Node.js dgram or WebRTC data channels, WebSockets or binary XHR messages should all work. Connect osc.js up to your source of incoming/outgoing data, and you're all set. This approach is consistent with the design of Open Sound Control as a content format that is independent from its means of transport.

In addition to the low-level encoder/decoder functions, osc.js also provides a comprehensive set of transport objects, called <code>Port</code>s, for use in standard browsers, Chrome Apps, and Node.js applications. These include:

<table> <tr> <th>Transport</th> <th>Supported Platforms</th> </tr> <tr> <td>UDP</td> <td>Node.js, Chrome Apps</td> </tr> <tr> <td>Serial port</td> <td>Node.js, Chrome Apps</td> </tr> <tr> <td>Web Sockets</td> <td>Browsers, Node.js, Chrome Apps</td> </tr> <tr> <td>TCP</td> <td>Node.js</td> </tr> </table>

For stream-based protocols such as serial and TCP, osc.js will take care of SLIP framing for you.

Status

osc.js supports all OSC 1.0 and 1.1 required and optional types.

Installing osc.js

osc.js is typically installed via npm. Bower support is available, but is deprecated and untested.

Installing with npm

npm is a package manager for Node.js and web-based projects. Dependencies are registered in the npmjs.org registry.

For an npm-based project that depends on osc.js, you'll need a <code>package.json</code> configuration file for it:

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

Don't forget to update the <code>name</code>, <code>version</code>, and other package.json fields appropriately for your project.

Then, to install osc.js and all your other project dependencies, run:

npm install

Your dependencies will be located in a directory called <code>node_modules</code> in your project root.

Installing osc.js for use in Electron Applications

Electron allows developers to create applications using Web technologies and deploy them as native applications on Mac, Windows, and Linux.

Electron, however, ships with its own version of Node.js, which may be different from the version you have installed on your computer. osc.js depends on native Node.js modules such as node-serialport, which need to be compiled against the Electron version of Node.js in order for them to work correctly.

To install osc.js for Electron applications, there are two options:

Follow the instructions provided by the node-serialport project and use electron-rebuild to recompile your dependencies after running <code>npm install</code>
Use an <code>.npmrc</code> file to override npm's default compile target and runtime settings for Electron. Here's an example of an <code>.npmrc</code> file. Don't forget to make sure that the <code>target</code> property matches the version of Electron you're using:

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

How osc.js Works

osc.js consists of two distinct layers:

The low-level functional API, which provides simple stateless functions for reading and writing OSC packets.
The transport layer, which provides a simple EventEmitter-style API for sending and receiving OSC packets using a variety of transports such as UDP and Web Sockets.

Typically, you'll use the Port API for sending and receiving OSC packets over a particular transport, but if you want to write your own transports or want a lower-level interface, you can use the functional API directly.

Port API

Methods

All <code>osc.Port</code> objects implement the following supported methods:

<table> <tr> <th>Method</th> <th>Description</th> <th>Arguments</th> </tr> <tr> <td><code>send</code></td> <td>Sends an OSC package (either a message or a bundle) on this Port.</td> <td> <code>packet</code>: the OSC message or bundle to send<br /> </td> </tr> </table>

Events

All <code>osc.Port</code>s implement the Event Emitter API. The following events are supported:

<table> <thead> <tr> <th>Event</th> <th>Description</th> <th>Arguments</th> </tr> </thead> <tbody> <tr> <td><code>ready</code></td> <td>Fires when a Port is ready to send or receive messages.</td> <td>_none_</td> </tr> <tr> <td><code>message</code></td> <td>Fires whenever an OSC message is received by the Port.</td> <td> <code>message</code>: the OSC message received; <br /> <code>timeTag</code>: the time tag specified by the sender (may be <code>undefined</code> for non-bundle messages); <br /> <code>info</code>an implementation-specific remote information object </td> </tr> <tr> <td><code>bundle</code></td> <td>Fires whenever an OSC bundle is received. Subsequent <code>bundle</code> and/or <code>message</code> events will be fired for each sub-packet in the bundle.</td> <td> <code>bundle</code>: the OSC bundle received; <br /> <code>timeTag</code>: the time tag specified by the sender; <br /> <code>info</code>an implementation-specific remote information object </td> </tr> <tr> <td><code>osc</code></td> <td>Fires whenever any type of OSC packet is recieved by this Port.</td> <td> <code>packet</code>: the OSC message or bundle received<br /> <code>info</code>an implementation-specific remote information object </td> </tr> <tr> <td><code>raw</code></td> <td>Fires whenever any data is recieved by this Port.</td> <td> <code>data</code>: an Uint8Array containing the raw data received<br /> <code>info</code>an implementation-specific remote information object </td> </tr> <tr> <td><code>error</code></td> <td>Fires whenever an error occurs.</td> <td> <code>error</code>: the Error object that was raised </td> </tr> </tbody> </table>

Examples

In-depth example osc.js applications for the browser, Node.js, and Chrome OS are available in the osc.js examples repository.

Web Sockets in the Browser

The <code>osc.WebSocketPort</code> object supports sending and receiving OSC messages over Web Sockets.

Options

<table> <tr> <th>Property</th> <th>Description</th> <th>Default Value</th> </tr> <tr> <td>url</td> <td>The Web Socket URL to connect to (required for clients)</td> <td>none</td> </tr> <tr> <td>socket</td> <td>A Web Socket instance to bind to (optional); if supplied, it is your job to configure and open it appropriately</td> <td>none</td> </tr> </table>

Sample Code

More code examples showing how osc.js can be used in browser-based, Node.js, and Chrome App applications can be found in the osc.js examples repository.

Including osc.js in your HTML page:

<!DOCTYPE html>
<html>
    <head>
        <title>osc.js Web Sockets</title>
        <meta charset="UTF-8" />
        <script src="node_modules/osc.js/dist/osc-browser.min.js"></script>
    </head>
    <body></body>
</html>

Creating an OSC Web Socket Port object:

var oscPort = new osc.WebSocketPort({
    url: "ws://localhost:8081", // URL to your Web Socket server.
    metadata: true
});

Opening the Port:

oscPort.open();

Listening for incoming OSC messages:

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

Osc.js

Install / Use

README