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.

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 Ports, for use in standard browsers, Chrome Apps, and Node.js applications. These include:

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 Bower, npm, or yarn. The latter two can be used for both client-side projects as well as Node.js applications, while Bower is typically used only for browser applications.

Installing with Bower

If you're developing a browser-based project, Bower is probably the simplest way to manage your dependency on osc.js. First, you'll need to install Bower, which requires Node.js.

For a Bower-based project, you'll typically want to make a bower.json configuration file. Something like this:

{
    "name": "<your project name>",
    "version": "<your project version>",
    "dependencies": {
        "osc.js": "2.2.0"
    }
}

Don't forget to update the name, version, and any other bower.json fields appropriately for your project.

And then, to install all your project's dependencies—including osc.js—just run

bower install

Your dependencies will be located in a directory called bower_components in your project root.

Installing with npm (or yarn)

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 package.json configuration file for it:

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

Don't forget to update the name, version, 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 node_modules in your project root.

How osc.js Works

osc.js consists of two distinct layers:

1. The low-level functional API, which provides simple stateless functions for reading and writing OSC packets.
2. The transport layer, which provide a simple EventEmitter-style API for sending an 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 osc.Port objects implement the following supported methods:

Events

All osc.Ports implement the Event Emitter API. The following events are supported:

Examples

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

These examples assume you are using Bower to install osc.js, but you can of course change the paths to refer to your node_modules if you're using npm.

Web Sockets in the Browser

The osc.WebSocketPort object supports sending and receiving OSC messages over Web Sockets.

Options

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="bower_components/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. 
});

Opening the Port:

oscPort.open();

Listening for incoming OSC messages:

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

Sending OSC messages:

// For most Ports, send() should only be called after the "ready" event fires. 
oscPort.on("ready", function () {
    oscPort.send({
        address: "/carrier/frequency",
        args: 440
    });
});

Sending OSC bundles:

oscPort.on("ready", function () {
    oscPort.send({
        timeTag: osc.timeTag(60), // Schedules this bundle 60 seconds from now. 
        packets: [
            {
                address: "/carrier/frequency",
                args: 440
            },
            {
                address: "/carrier/amplitude"
                args: 0.5
            }
        ]
    });
});
 

Using osc.js with Require.js

// Define your module paths, including osc.js' dependencies. 
// Note: these paths must resolve to wherever you have placed 
// osc.js, slip.js, and eventEmitter in your project. 
require.config({
    paths: {
        slip: "../bower_components/slip.js/dist/slip.min",
        EventEmitter: "../bower_components/eventEmitter/EventEmitter.min",
        long: "../bower_components/long/dist/Long.min",
        osc: "../bower_components/osc.js/osc-module.min"
    }
});
 
// Load it asynchronously. 
require(["osc"], function (osc) {
    // Do something with osc.js when it has fully loaded. 
});

Web Sockets in Node.js

The osc.WebSocketPort object supports sending and receiving OSC messages over Web Sockets.

Options

Sample Code

var osc = require("osc"),
    http = require("http"),
    WebSocket = require("ws");
 
// Create an Express server app 
// and serve up a directory of static files. 
var app = require("express").express(),
    server = app.listen(8081);
 
app.use("/", express.static(__dirname + "/static"));
 
// Listen for Web Socket requests. 
var wss = new WebSocket.Server({
    server: server
});
 
// Listen for Web Socket connections. 
wss.on("connection", function (socket) {
    var socketPort = new osc.WebSocketPort({
        socket: socket
    });
 
    socketPort.on("message", function (oscMsg) {
        console.log("An OSC Message was received!", oscMsg);
    });
});

UDP in Node.js

The osc.UDPPort object supports the sending and receiving of OSC messages over Node.js's UDP sockets. It also supports broadcast and multicast UDP.

Options

Sample Code

// Create an osc.js UDP Port listening on port 57121. 
var udpPort = new osc.UDPPort({
    localAddress: "0.0.0.0",
    localPort: 57121
});
 
// Listen for incoming OSC bundles. 
udpPort.on("bundle", function (oscBundle, timeTag, info) {
    console.log("An OSC bundle just arrived for time tag", timeTag, ":", oscBundle);
    console.log("Remote info is: ", info);
});
 
// Open the socket. 
udpPort.open();
 
 
// When the port is read, send an OSC message to, say, SuperCollider 
udpPort.on("ready", function () {
    udpPort.send({
        address: "/s_new",
        args: ["default", 100]
    }, "127.0.0.1", 57110);
});

Serial in a Chrome App

Including osc.js in your Chrome App page

<script src="../bower_components/osc.js/dist/osc-chromeapp.min.js"></script>

Defining the appropriate permissions in manifest.json

{
    "name": "OSC.js Chrome App Demo",
    "version": "1",
    "manifest_version": 2,
    "permissions": [
        "serial"
    ],
    "app": {
        "background": {
            "scripts": ["js/launch.js"],
            "transient": true
        }
    }
}

Connecting to the serial port and listening for OSC messages

// Instantiate a new OSC Serial Port. 
var serialPort = new osc.SerialPort({
    devicePath: "/dev/cu.usbmodem22131"
});
 
// Listen for the message event and map the OSC message to the synth. 
serialPort.on("message", function (oscMsg) {
    console.log("An OSC message was received!", oscMsg);
});
 
// Open the port. 
serialPort.open();

UDP in a Chrome App

The osc.UDPPort object supports the sending and receiving of OSC messages over a chrome.sockets.udp socket. It also supports broadcast and multicast UDP.

Options

Handling Errors

All osc.js Transport objects emit "error" messages whenever an error occurs, such as when a malformed message is received. You should always listen for errors and handle them in an appropriate manner for your application.

var port = osc.UDPPort();
port.on("error", function (error) {
    console.log("An error occurred: ", error.message);
});

The low-level osc.js API, described below, will throw JavaScript Error objects whenever an error occurs; they should be caught and handled using try/catch.

var msg;
 
try {
    msg = osc.readPacket(rawPacket);
} catch (error) {
    console.log("An error occurred: ", error.message);
}

The osc.js Low-Level API

OSC Bundle and Message Objects

osc.js represents bundles and messages as (mostly) JSON-compatible objects. Here's how they are structured:

Messages

OSC Message objects consist of two properties, address, which contains the URL-style address path and args which is an array of either raw argument values or type-annotated Argument objects (depending on the value of the metadata option used when reading the message).

{
    address: "/an/osc/address",
    args: [
        {} // Raw or type-annotated OSC arguments 
    ]
}

Bundles

OSC bundle objects consist of a time tag and an array of packets. Packets can be a mix of OSC bundle objects and message objects.

{
    timeTag: {
        // OSC Time Tag object 
    },
    packets: [
        {} // Nested OSC bundle and message objects> 
    ]
}

Argument Objects with Type Metadata

Type-annotated argument objects contain two properties: type, which contains the OSC type tag character (e.g. "i", "f", "t", etc.) and the raw value.

{
    type: "f", // OSC type tag string 
    value: 444.4
}

If you are using type-annotated arguments, you should also set the metadata option to true when you instantiate your OSCPort instance (or in the options argument to osc.writeMessage if you're using the low-level API).

Time Tags

Time tag objects contain two different representations: the raw NTP time and the equivalent (though less precise) native JavaScript timestamp. NTP times consist of a pair of values in an array. The first value represents the number of seconds since January 1, 1900. The second value is a Uint32 value (i.e. between 0 and 4294967296) that represents fractions of a second.

JavaScript timestamps are represented as milliseconds since January 1, 1970, which is the same unit as is returned by calls to Date.now().

{
    raw: [
        3608146800, // seconds since January 1, 1900. 
        2147483648  // fractions of a second 
    ],
    native: Number // Milliseconds since January 1, 1970 
}

Colours

Colours are automatically normalized to CSS 3 rgba values (i.e. the alpha channel is represented as a float from 0.0 to 1.0).

{
    r: 255,
    g: 255,
    b: 255,
    a: 1.0
}

Functions

There are two primary functions in osc.js used to read and write OSC data:

Options

Many osc.js functions take an options object that can be used to customize its behaviour. These options are also supported by all osc.Port objects, and can be included as a parameter in the options arguments passed to any Port constructor. The supported fields in an options object are:

• metadata: specifies if the OSC type metadata should be included. By default, type metadata isn't included when reading packets, and is inferred automatically when writing packets. If you need greater precision in regards to the arguments in an OSC message, set the metadata argument to true. Defaults to false.
• unpackSingleArgs: specifies if osc.js should automatically unpack single-argument messages so that their args property isn't wrapped in an array. Defaults to true.

Mapping OSC to JS

Here are a few examples showing how OSC packets are mapped to plain JavaScript objects by osc.js.

{
  address: "/carrier/freq",
  args: [440.4]
}

{
  address: "/carrier/freq",
  args: [
    440.4, [42.0, 47.0]
  ]
}

{
  address: "/scheduleAt",
  args: [
    {
      raw: [3608146800, 2147483648],
      jsTime: 1399158000500
    }
  ]
}

{
  address: "/blob",
  args: [
    Uint8Aray([0x63, 0x61, 0x74, 0x21])
  ]
}
    

{
  address: "/colour",
  args: [{
      r: 255,
      g: 255,
      b: 255,
      a: 1.0
    }
  ]
}

{
  address: "/midiMessage",
  args: [
    // Port ID, Status, Data 1, Data 2
    Uint8Array([0, 144, 69, 101])
  ]
}

License

osc.js is maintained by Colin Clark and distributed under the MIT and GPL 3 licenses.

Supported Environments

osc.js releases are tested and supported in the following environments:

Contributing to osc.js

Contributions and pull requests to osc.js are hugely appreciated. Wherever possible, all fixes and new features should be accompanied by unit tests to help verify that they work and avoid regressions. When new features are introduced, a pull request to the osc.js-examples repository with an example of how to use it is also appreciated.

Code should follow the style conventions of the project (such as they are), which can be automatically validated using JSHint by running grunt jshint.

Currently, the project is maintained by one person; sometimes it will take a bit of time to respond, review, and merge contributions. Help with bug triage, code reviews, testing, and examples is also welcome.

How to Build and Test Your Contributions

osc.js depends on npm, Grunt, and Testem. Make sure you have these installed, and then run the following commands to fetch all necessary dependencies:

npm install

To lint and generate builds from new source code:

grunt

Running the unit tests:

1. To run the fully automated tests, run "npm test"
2. To run the electron tests, run "npm run electron-test"

Contributors

• @colinbdclark wrote osc.js.
• @jacoscaz and @xseignard fixed bugs.
• @drart made and helped test some examples.
• @egasimus added support for 64-bit integers.
• @heisters contributed fixes for broadcast and multicast UDP on Node.js and improved time tag support.
• @tambien fixed error handling bugs in the transports layer.
• @janslow added support for passing remote information to all Port data events.