{"id":18275125,"url":"https://github.com/adzialocha/osc-js","last_synced_at":"2025-04-04T10:03:57.430Z","repository":{"id":14553026,"uuid":"17268487","full_name":"adzialocha/osc-js","owner":"adzialocha","description":"OSC library for Node.js, Electron, Chrome Apps, Webpages or any other JS application. It comes with a customizable Plugin API for WebSocket, UDP or bridge networking","archived":false,"fork":false,"pushed_at":"2024-04-21T18:46:03.000Z","size":4062,"stargazers_count":267,"open_issues_count":11,"forks_count":32,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-28T09:06:11.800Z","etag":null,"topics":["electron","javascript","music","osc","osc-applications","osc-js","udp","websocket-client","websockets"],"latest_commit_sha":null,"homepage":"https://adzialocha.github.io/osc-js","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adzialocha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-02-27T23:20:03.000Z","updated_at":"2025-03-22T19:58:04.000Z","dependencies_parsed_at":"2024-04-03T09:45:53.560Z","dependency_job_id":"b9a4eb07-b414-451a-b293-a6e789300270","html_url":"https://github.com/adzialocha/osc-js","commit_stats":{"total_commits":216,"total_committers":10,"mean_commits":21.6,"dds":0.5555555555555556,"last_synced_commit":"a6a102bd11ee58b262db9e191ab9ec4ac75952aa"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fosc-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fosc-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fosc-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fosc-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adzialocha","download_url":"https://codeload.github.com/adzialocha/osc-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157081,"owners_count":20893202,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","javascript","music","osc","osc-applications","osc-js","udp","websocket-client","websockets"],"created_at":"2024-11-05T12:11:56.633Z","updated_at":"2025-04-04T10:03:57.387Z","avatar_url":"https://github.com/adzialocha.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"osc-js\n======\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/adzialocha/osc-js/actions\"\u003e\n    \u003cimg src=\"https://github.com/adzialocha/osc-js/workflows/Node.js%20CI/badge.svg\" alt=\"Build status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.org/package/osc-js\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/osc-js.svg?style=flat-square\" alt=\"npm version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"http://spdx.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/osc-js.svg?style=flat-square\" alt=\"npm licence\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://adzialocha.github.io/osc-js\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/adzialocha/osc-js/gh-pages/badge.svg\" alt=\"ESDoc status\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nosc-js is an [Open Sound Control](http://opensoundcontrol.org/) library for JavaScript applications (UMD module for Node, Browser etc.) with address pattern matching and timetag handling. Sends messages via *UDP*, *WebSocket* or both (bridge mode) and offers a customizable Plugin API for network protocols.\n\n[Wiki](https://github.com/adzialocha/osc-js/wiki) | [Basic Usage](https://github.com/adzialocha/osc-js/wiki/Basic-Usage) | [Documentation](https://adzialocha.github.io/osc-js) | [Plugin API](https://github.com/adzialocha/osc-js/wiki/Plugin-API)\n\n## Features\n\n- UMD Module running in Node.js, Electron, Chrome Apps, browser or any other JS environment\n- Can be used with Webpack and Browserify\n- TypeScript definitions\n- No dependencies (except of `ws` in Node.js or similar environments)\n- Receive sender information from incoming messages\n- Built-in *UDP*, *WebSocket* networking support as plugins\n- Special bridge plugin for easy communication between *UDP*- and *WebSocket* clients\n- Plugin API for custom network protocols\n- Featuring all [OSC 1.0 specifications](http://opensoundcontrol.org/spec-1_0)\n- OSC Address pattern matching\n- Time-critical OSC Bundles with Timetags\n- Extended (nonstandard) argument types\n\n## Documentation\n\nRead more about osc-js and how to use it in the [Wiki](https://github.com/adzialocha/osc-js/wiki) and [Documentation](https://adzialocha.github.io/osc-js).\n\n## Example\n\n```js\nconst osc = new OSC()\n\nosc.on('/param/density', (message, rinfo) =\u003e {\n  console.log(message.args)\n  console.log(rinfo)\n})\n\nosc.on('*', message =\u003e {\n  console.log(message.args)\n})\n\nosc.on('/{foo,bar}/*/param', message =\u003e {\n  console.log(message.args)\n})\n\nosc.on('open', () =\u003e {\n  const message = new OSC.Message('/test', 12.221, 'hello')\n  osc.send(message)\n})\n\nosc.open({ port: 9000 })\n```\n\n## Installation and Usage\n\nRecommended installation via npm: `npm i osc-js` or `yarn add osc-js`.\n\nImport the library `const OSC = require('osc-js')` or add the script `lib/osc.js` or `lib/osc.min.js` (minified version) for usage in a browser.\n\n## Plugins\n\nosc-js offers a plugin architecture for extending it's networking capabilities. The library comes with four built-in plugins. This is propably all you need for an OSC application:\n\n- `WebsocketClientPlugin` (default)\n- `WebsocketServerPlugin`\n- `DatagramPlugin` for UDP network messaging\n- `BridgePlugin` useful Bridge between WebSocket- and UDP Clients\n\nConfiguration and examples of every plugin can be read here: [Wiki](https://github.com/adzialocha/osc-js/wiki).\n\n### Example: WebSocket Server\n\nRegister the plugin when creating the OSC instance:\n\n```js\nconst osc = new OSC({ plugin: new OSC.WebsocketServerPlugin() })\nosc.open() // listening on 'ws://localhost:8080'\n```\n\n### Example: OSC between MaxMSP/PD/SC etc. and your browser\n\n1. Write a simple webpage. The library will use a WebSocket client\nby default.\n\n  ```html\n  \u003cbutton id=\"send\"\u003eSend Message\u003c/button\u003e\n  \u003cscript type=\"text/javascript\" src=\"lib/osc.min.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\"\u003e\n    var osc = new OSC();\n    osc.open(); // connect by default to ws://localhost:8080\n\n    document.getElementById('send').addEventListener('click', () =\u003e {\n      var message = new OSC.Message('/test/random', Math.random());\n      osc.send(message);\n    });\n  \u003c/script\u003e\n  ```\n\n2. Write a Node app (the \"bridge\" between your UDP and WebSocket clients).\n\n  ```js\n  const OSC = require('osc-js')\n\n  const config = { udpClient: { port: 9129 } }\n  const osc = new OSC({ plugin: new OSC.BridgePlugin(config) })\n\n  osc.open() // start a WebSocket server on port 8080\n  ```\n\n3. Create your Max/MSP patch (or PD, SuperCollider etc.).\n\n  ```\n  [udpreceive 9129] // incoming '/test/random' messages with random number\n  ```\n\n### Custom solutions with Plugin API\n\nIt is possible to write more sophisticated solutions for OSC applications without loosing the osc-js interface (including its message handling etc.). Read the [Plugin API documentation](https://github.com/adzialocha/osc-js/wiki/Plugin-API) for further information.\n\n```js\nclass MyCustomPlugin {\n  // ... read docs for implementation details\n}\n\nconst osc = new OSC({ plugin: MyCustomPlugin() })\nosc.open()\n\nosc.on('/test', message =\u003e {\n  // use event listener with your plugin\n})\n```\n\n### Usage without plugins\n\nThe library can be used without the mentioned features in case you need to write and read binary OSC data. See this example below for using the [Low-Level API](https://github.com/adzialocha/osc-js/wiki/Low-Level-API) (even though the library already has a solution for handling UDP like in this example):\n\n```js\nconst dgram = require('dgram')\nconst OSC = require('osc-js')\n\nconst socket = dgram.createSocket('udp4')\n\n// send a messsage via udp\nconst message = new OSC.Message('/some/path', 21)\nconst binary = message.pack()\nsocket.send(new Buffer(binary), 0, binary.byteLength, 41234, 'localhost')\n\n// receive a message via UDP\nsocket.on('message', data =\u003e {\n  const msg = new OSC.Message()\n  msg.unpack(data)\n  console.log(msg.args)\n})\n```\n\n## Development\n\nosc-js uses [Babel](http://babeljs.io) for ES6 support, [ESDoc](https://esdoc.org) for documentation, [Mocha](https://mochajs.org/) + [Chai](http://chaijs.com/) for testing and [Rollup](https://rollupjs.org) for generating the UMD module.\n\nClone the repository and install all dependencies:\n\n```\ngit clone git@github.com:adzialocha/osc-js.git\ncd osc-js\nnpm install\n```\n\n### Testing\n\n`npm run test` for running the tests.\n`npm run test:watch` for running specs during development. Check code style with `npm run lint`.\n\n### Deployment\n\n`npm run build` for exporting UMD module in `lib` folder.\n\n### Contributors\n\n* [@adzialocha](https://github.com/adzialocha)\n* [@davidgranstrom](https://github.com/davidgranstrom)\n* [@elgiano](https://github.com/elgiano)\n* [@eliot-akira](https://github.com/eliot-akira)\n* [@JacobMuchow](https://github.com/JacobMuchow)\n* [@PeterKey](https://github.com/PeterKey)\n* [@yaxu](https://github.com/yaxu)\n* [@yojeek](https://github.com/yojeek)\n\n### ESDocs\n\n`npm run docs` for generating a `docs` folder with HTML files documenting the library. Read them online here: [https://adzialocha.github.io/osc-js](https://adzialocha.github.io/osc-js)\n\n## License\n\nMIT License `MIT`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzialocha%2Fosc-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadzialocha%2Fosc-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzialocha%2Fosc-js/lists"}