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

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

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.