pyOSC inspired library for sending and receiving OSC messages
npm install node-oscA no frills Open Sound Control client and server.
Heavily inspired by pyOSC.
Install using npm
``bash`
npm install node-osc
- 🚀 Simple and intuitive API
- 🔄 Both callback and async/await support
- 📦 Send and receive OSC messages and bundles
- 🌐 Works with both ESM and CommonJS
- 📘 TypeScript type definitions included (generated from JSDoc)
- 📝 Comprehensive documentation and examples
- ✅ Well tested and actively maintained
`js
import { Client } from 'node-osc';
const client = new Client('127.0.0.1', 3333);
await client.send('/oscAddress', 200);
await client.close();
`
`js
import { Server } from 'node-osc';
const server = new Server(3333, '0.0.0.0');
server.on('message', (msg) => {
console.log(Message: ${msg});`
});
- 📂 Documentation Hub - Complete documentation with navigation guide
- 📚 API Reference - Complete API reference generated from source code
- 📘 Usage Guide - Best practices, error handling, and troubleshooting
- 📖 Examples - Working examples for various use cases
Written using ESM, supports CJS.
Supports the latest versions of Node.js 20, 22, and 24 in both ESM + CJS.
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. A single .d.mts type definition format is provided that works for both ESM and CommonJS consumers.
Note: If you previously installed @types/node-osc, you should uninstall it to avoid conflicts:`bash`
npm uninstall @types/node-osc
`js
import { Client } from 'node-osc';
const client = new Client('127.0.0.1', 3333);
await client.send('/oscAddress', 200);
await client.close();
`
`js
import { Client } from 'node-osc';
const client = new Client('127.0.0.1', 3333);
client.send('/oscAddress', 200, () => {
client.close();
});
`
`js
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});`
});
`js
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();
`
`js
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});Message: ${element}
console.log();`
});
});
For advanced use cases, you can directly encode and decode OSC messages:
`js
import { Message, encode, decode } from 'node-osc';
// Encode a message to binary
const message = new Message('/oscillator/frequency', 440);
const buffer = encode(message);
// Decode binary data back to a message
const 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)
- Storing OSC messages to files or databases
- Testing and debugging OSC implementations
- Building custom OSC routers or processors
See the API Documentation for complete details.
Both callback and promise-based APIs work with CommonJS!
`js
const { Client, Server } = require('node-osc');
async function main() {
const server = new Server(3333, '0.0.0.0');
const client = new Client('127.0.0.1', 3333);
await new Promise((resolve) => {
server.on('listening', resolve);
});
server.on('message', (msg) => {
console.log(Message: ${msg});
});
await client.send('/hello', 'world');
await client.close();
await server.close();
}
main();
``
See the examples directory for more usage examples:
- client.js - CommonJS client example
- server.js - CommonJS server example
- esm.mjs - ESM example with callbacks
- async-await.mjs - ESM example with async/await
- bundle-example.mjs - Working with bundles
- error-handling.mjs - Error handling patterns
Contributions are welcome! Please feel free to submit a Pull Request.
Apache-2.0
Note: This project was relicensed from LGPL-3.0-or-later to Apache-2.0 in December 2025.