node-osc

A no frills Open Sound Control client and server. Heavily inspired by pyOSC.

Installation

Install using npm

npm install node-osc

Features

• 🚀 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

Quick Start

Sending Messages

import { Client } from 'node-osc';
const client = new Client('127.0.0.1', 3333);
await client.send('/oscAddress', 200);
await client.close();

Receiving Messages

import { Server } from 'node-osc';
const server = new Server(3333, '0.0.0.0');
server.on('message', (msg) => {
  console.log(Message: ${msg});
});

Documentation

• 📂 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

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

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 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

CommonJS

Both callback and promise-based APIs work with CommonJS!

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();

Examples

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0

Note: This project was relicensed from LGPL-3.0-or-later to Apache-2.0 in December 2025.