Basic Usage

Installation

osc-js is a library which can be used in different JavaScript contexts, like Node.js, Webbrowsers, Chrome Apps, Electron apps etc. The recommended way for installation is to use a dependency management tool like npm to add osc-js to your project.

Add the library to your page with <script src="node_modules/osc-js/lib/osc.min.js"></script> or better require it via const OSC = require('osc-js').

Create an OSC instance

With default options

const osc = new OSC({
  discardLateMessages: false, /* ignores messages which timetags lie in the past */
  plugin: new OSC.WebsocketClientPlugin() /* used plugin for network communication */ 
});

You can also just call new OSC() without any options.

Options

Read more about discarding late messages under Temporal Semantics and OSC Time Tags in the OSC Specifications.

It is possible to hook custom plugin instances into osc-js (Plugin API). The library comes along with four handy built-in classes which you can use right away:

• OSC.WebsocketClientPlugin
• OSC.WebsocketServerPlugin
• OSC.DatagramPlugin
• OSC.BridgePlugin

Plugin options

The regarding plugins can take individual options in their constructors.

const osc = new OSC({
  plugin: new OSC.DatagramPlugin({ send: { port: 5311, host: '192.168.178.115' } })
});

Please check the plugin docs or source code for more information on possible plugin options.

Open connection

osc.open();

Use an option object for the connection plugin like osc.open({ port: 2211 }) when needed. This will override the global options set at the OSC instance creation.

Send a message

Define an address and the arguments during construction.

const message = new OSC.Message('/test/path', 521.25, 'teststring', 665);
osc.send(message);

It is possible to use an array of strings to define the OSC address.

const message = new OSC.Message(['test', 'path'], 123);
osc.send(message);

Types

OSC message arguments can be of type:

• integer 412, 553, 112
• float 21.212, 449.11
• string 'hello world'
• blob new Uint8Array([11, 44, 31]) for any kind of binary data

Add method

Use the add method to add more arguments after construction.

message.add('hello world');
message.add(new Uint8Array([11, 44, 31]));

Custom send options

Depending on the used plugin it is also possible to specify individual options for the regarding transfer of an OSC message or bundle. This will override the globally set options for this one action.

const message = new OSC.Message('/test/path');
osc.send(message, { host: '192.168.178.112' });

Please check the related plugin docs or source code for all options.

Send a bundle

Bundles can contain multiple messages or more bundles. They can be timed with a Timetag and will be executed then (when the receiver is able to interpret a bundle like that, osc-js is capable of doing so).

const message = new OSC.Message('/test/path', 521.25, 'teststring', 665);
const bundle = new OSC.Bundle([message], Date.now() + 5000); // read bundle in 5 seconds
osc.send(bundle);

Add method

Use the add method to add more bundle elements:

const bundle = new OSC.Bundle(Date.now() + 5000); // read bundle in 5 seconds
bundle.add(new OSC.Message('/test', 521));
bundle.add(new OSC.Message('/test/path', 'hello world'));

osc.send(bundle);

Set timestamp

Or add messages first and set the time with the timestamp method afterwards:

const message = new OSC.Message('/test', 521);
const anotherMessage = new OSC.Message('/test/path', 'hello world');
const bundle = new OSC.Bundle(message, anotherMessage);

bundle.timestamp(Date.now() + 5000); // read bundle in 5 seconds

osc.send(bundle);

Receive messages

A listener can be defined with the on method, specifing an OSC address to listen to and a function callback when a message with this address was received.

osc.on('/test', message => {
  console.log(message.args); // prints the message arguments
});

The listener makes use of pattern matching for incoming messages.

// server sends to address /in!trument/*, on client-side these will be called:
osc.on('/instrument/1', message => { });
osc.on('/instrument/2', message => { });
osc.on('/instrument/3', message => { });

// server sends to address /foo/bar, on client-side these will be called:
osc.on('*', message => { });
osc.on('/{foo,baz}/*', message => { });

Receive remote address information to find out from where the message came from:

osc.on('/instrument/*', (message, rinfo) => {
   console.log(rinfo)
})

More information about rinfo: https://nodejs.org/api/dgram.html#dgram_event_message

Status changes

Listen to status changes of the plugin.

Open, close and error events

osc.on('open', () => {
  // connection was established
});

osc.on('close', () => {
  // connection was closed
});

osc.on('error', (err) => {
  // an error occurred
});

Status

Return the current state at any time with the status method.

const status = osc.status();
if (osc.status() === OSC.STATUS.IS_OPEN) {
  // do something
}

// possible states are:
// IS_NOT_INITIALIZED
// IS_CONNECTING
// IS_OPEN
// IS_CLOSING
// IS_CLOSED

Close connection

osc.close();