osc-js

library2.4.1jsnpmunverified

osc-js is an Open Sound Control (OSC) library for JavaScript, supporting Node.js and browser environments via UMD module. Current stable version is 2.4.1 (released monthly). It provides address pattern matching, timetag handling, built-in UDP, WebSocket, and bridge plugins, and a customizable Plugin API. Key differentiators include zero dependencies (except ws for Node.js), TypeScript definitions, and support for all OSC 1.0 specifications plus extended argument types.

messaging

npm install osc-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OSC-JS

osc-js

messagingjavascriptv2.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OSC

✓ import OSC from 'osc-js'

✗ const OSC = require('osc-js').OSC

Default export; UMD module works in Node and browser.

OSC.Message

✓ import OSC from 'osc-js'; const msg = new OSC.Message('/path', 1, 2)

✗ import { Message } from 'osc-js'

Message is a static property of the default export, not a named export.

OSC.WebsocketClientPlugin

✓ import OSC from 'osc-js'; new OSC.WebsocketClientPlugin()

✗ import { WebsocketClientPlugin } from 'osc-js'

Plugins are properties of the OSC class; not exported directly.

Shows basic setup: create OSC instance, listen for messages, send a message on open, and start listening on UDP port 9000.

import OSC from 'osc-js'; const osc = new OSC(); osc.on('/greeting', (message) => { console.log('Received:', message.args); }); osc.on('open', () => { const msg = new OSC.Message('/greeting', 'Hello OSC!'); osc.send(msg); }); osc.open({ port: 9000 }); // In a browser, default WebSocket client tries ws://localhost:8080

Debug

Known issues

breakingIn osc-js v2, the constructor signature changed: `new OSC(config)` where config is an options object, not separate arguments.

fix

Use `new OSC({ plugin: new OSC.DatagramPlugin() })` instead of `new OSC(OSC.DatagramPlugin())`

affects: >=2.0.0

deprecatedOSC.Bundle and timetag handling use the 'timetag' library; timetag representation may change in future versions.

fix

Use standard timetag format: [seconds, fractional_seconds]

affects: >=1.0.0

gotchaWhen using `osc.on('open', callback)`, the callback may be called multiple times if reconnection occurs; only one listener is recommended.

fix

Assign listener once; avoid calling `osc.on('open', ...)` inside other callbacks.

affects: *

gotchaIn browser, the default WebSocket client must be connected before sending messages; otherwise, messages are queued but not sent.

fix

Wait for 'open' event before calling `osc.send()`.

affects: *

Errors

Common errors & fixes

TypeError: osc_js_1.default is not a constructor

Using named import instead of default import in TypeScript.

fix

Use `import OSC from 'osc-js'` instead of `import { OSC } from 'osc-js'`

Error: Module not found: Error: Can't resolve 'bufferutil'

Optional WebSocket dependency missing in Node.js.

fix

Run `npm install bufferutil` or set `npm config set optional false`

WebSocket connection to 'ws://localhost:8080/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED

No WebSocket server running or wrong port.

fix

Start a WebSocket server (e.g., with OSC.WebsocketServerPlugin) on port 8080.

Upgrade

Version history

2.4.1latest on npm

Audit

Dependencies

wsoptionalWebSocket support in Node.js environments

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubssh://git@github.com/adzialocha/osc-js ↗

packageosc-js ↗

homepagehttps://github.com/adzialocha/osc-js#readme ↗