osc
Advanced tools
Readme
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.
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.
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:
| Transport | Supported Platforms |
|---|---|
| UDP | Node.js, Chrome Apps |
| Serial port | Node.js, Chrome Apps |
| Web Sockets | Browsers, Node.js, Chrome Apps |
| TCP | Node.js |
For stream-based protocols such as serial and TCP, osc.js will take care of SLIP framing for you.
osc.js supports all OSC 1.0 and 1.1 required types. It supports all OSC 1.1 optional types except Int64s ("h"), since JavaScript numbers are represented as IEEE 754 Doubles and thus don't have sufficient precision to represent all 64 bits. Int64 support using Google's long library is planned in the future.
osc.js consists of two distinct layers:
In-depth example osc.js applications for the browser, Node.js, and Chrome OS are available in the osc.js examples repository.
The osc.WebSocketPort object supports sending and receiving
OSC messages over Web Sockets.
| Property | Description | Default Value |
|---|---|---|
| url | The Web Socket URL to connect to (_required for clients_) | none |
<!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>
var oscPort = new osc.WebSocketPort({
url: "ws://localhost:8081" // URL to your Web Socket server.
});
oscPort.on("message", function (oscMsg) {
console.log("An OSC message just arrived!", oscMsg);
});
oscPort.send({
address: "/carrier/frequency",
args: 440
});
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
}
]
});
// 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",
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.
});
The osc.WebSocketPort object supports sending and receiving
OSC messages over Web Sockets.
| Property | Description | Default Value |
|---|---|---|
| url | The Web Socket URL to connect to (_required for clients_) | none |
| socket | A Web Socket instance to bind to (_required for servers_) | none |
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);
});
});
The osc.UDPPort object supports the sending and receiving of
OSC messages over Node.js's UDP sockets. It also supports multicast UDP.
| Property | Description | Default Value |
|---|---|---|
| localPort | The port to listen on (_required for UDP servers_) | 57121 |
| localAddress | The local address to bind to; will be ignored in the case of multicast UDP (_required for UDP servers_) | "127.0.0.1" |
| remotePort | The port to send messages on (_optional_) | none |
| remoteAddress | The address to send messages to (_optional_) | none |
| multicast | A flag determining whether to use multicast mode | false |
| multicastTTL | The time to live (number of hops) fora multicast connection | none |
// 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) {
console.log("An OSC bundle just arrived!", oscBundle);
});
// Open the socket.
udpPort.open();
// Send an OSC message to, say, SuperCollider
udpPort.send({
address: "/s_new",
args: ["default", 100]
}, "127.0.0.1", 57110);
<script src="../bower_components/osc.js/dist/osc-chromeapp.min.js"></script>
{
"name": "OSC.js Chrome App Demo",
"version": "1",
"manifest_version": 2,
"permissions": [
"serial"
],
"app": {
"background": {
"scripts": ["js/launch.js"],
"transient": true
}
}
}
// 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();
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.
There are two primary functions in osc.js used to read and write OSC data:
osc.readPacket(), which takes a DataView-friendly data buffer (i.e. an ArrayBuffer, TypedArray, DataView, or Node.js Buffer) and returns a tree of JavaScript objects representing the messages and bundles that were readosc.writePacket(), which takes a message or bundle object and packs it up into a Uint8Array or Buffer objectBoth functions take an optional withMetadata parameter, which 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 withMetadata argument to true.
osc.js represents bundles and messages as (mostly) JSON-compatible objects. Here's how they are structured:
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 withMetadata when reading the message).
{
address: "/an/osc/address",
args: [
{} // Raw or type-annotated OSC arguments
]
}
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>
]
}
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 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 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
}
Here are a few examples showing how OSC packets are mapped to JSON objects by osc.js.
| Message | Objects |
|---|---|
| "/carrier/freq" ",f" 440.4 | |
| "/float/andArray" ",f[ii]" 440.4 42 47 | |
| "/aTimeTag" ",t" 3608146800 2147483648 | |
| "/blob" ",b" 0x63 0x61 0x74 0x21 | |
| "/colour" ",r" "255 255 255 255" |
|
| "/midiMessage" ",m" 0x00 0x90 0x45 0x65 |
|
osc.js is written by Colin Clark and distributed under the MIT and GPL 3 licenses.
FAQs
A JavaScript Open Sound Control (OSC) library that works in Node.js and the browser.
The npm package osc receives a total of 2,435 weekly downloads. As such, osc popularity was classified as popular.
We found that osc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.
Security News
The NVD is facing a significant backlog with over 12,500 CVEs awaiting analysis, and more than 50% of known exploited vulnerabilities (KEVs) left unenriched since mid-February.