📚 API Reference - Complete API reference generated from source code
📘 Usage Guide - Best practices, error handling, and troubleshooting
📖 Examples - Working examples for various use cases
The API reference is generated from the source JSDoc comments. If you change a public API or its JSDoc, run npm run docs and review docs/API.md.
Compatibility
Written as ESM and published with both ESM and CommonJS entry points.
Supports Node.js 20, 22, and 24+ in both ESM and CJS environments.
TypeScript
TypeScript type definitions are included! No need to install @types/node-osc.
The types are automatically generated from JSDoc comments during the build process and included with the package:
ESM consumers resolve declarations from types/*.d.mts
CommonJS consumers resolve declarations from dist/types/*.d.ts
This package publishes separate generated declaration outputs for the ESM source tree and the CommonJS build so TypeScript can resolve the correct types for each entry point.
Note: If you previously installed @types/node-osc, you should uninstall it to avoid conflicts:
npm uninstall @types/node-osc
More Examples
Sending with async/await
import { Client } from 'node-osc';const client = new Client('127.0.0.1', 3333);await client.send('/oscAddress', 200);await client.close();
Sending with callbacks
import { Client } from 'node-osc';const client = new Client('127.0.0.1', 3333);client.send('/oscAddress', 200, () => { client.close();});
Listening for OSC messages
import { Server } from 'node-osc';const oscServer = new Server(3333, '0.0.0.0', () => { console.log('OSC Server is listening');});oscServer.on('message', function (msg) { console.log(`Message: ${msg}`);});
Sending OSC bundles
import { Bundle, Client } from 'node-osc';const bundle = new Bundle(['/one', 1], ['/two', 2], ['/three', 3]);const client = new Client('127.0.0.1', 3333);await client.send(bundle);await client.close();
Listening for OSC bundles
import { Server } from 'node-osc';const oscServer = new Server(3333, '0.0.0.0', () => { console.log('OSC Server is listening');});oscServer.on('bundle', function (bundle) { bundle.elements.forEach((element) => { console.log(`Timestamp: ${bundle.timetag}`); console.log(`Message: ${element}`); });});
Low-Level Encoding and Decoding
For advanced use cases, you can directly encode and decode OSC messages:
import { Message, encode, decode } from 'node-osc';// Encode a message to binaryconst message = new Message('/oscillator/frequency', 440);const buffer = encode(message);// Decode binary data back to a messageconst decoded = decode(buffer);console.log('Address:', decoded.address);console.log('Value:', decoded.args[0].value);
This is useful for:
Sending OSC over non-UDP transports (WebSocket, TCP, HTTP)