osc js

osc-js

osc-js ist eine Open Sound Control-Bibliothek für JavaScript-Anwendungen (UMD-Modul für Node, Browser usw.) mit Adressmusterabgleich und Timetag-Verarbeitung. Sendet Nachrichten über UDP , WebSocket oder beides (Bridge-Modus) und bietet eine anpassbare Plugin-API für Netzwerkprotokolle.

Wiki | Grundlegende Verwendung | Dokumentation | Plugin-API

Merkmale

• UMD-Modul läuft in Node.js, Electron, Chrome Apps, Browser oder einer anderen JS-Umgebung
• Kann mit Webpack und Browserify verwendet werden
• TypeScript-Definitionen
• Keine Abhängigkeiten (außer von ws in Node.js oder ähnlichen Umgebungen)
• Erhalten Sie Absenderinformationen aus eingehenden Nachrichten
• Integrierte UDP- und WebSocket- Netzwerkunterstützung als Plugins
• Spezielles Bridge-Plugin zur einfachen Kommunikation zwischen UDP- und WebSocket- Clients
• Plugin-API für benutzerdefinierte Netzwerkprotokolle
• Mit allen OSC 1.0-Spezifikationen
• OSC-Adressmusterabgleich
• Zeitkritische OSC-Bundles mit Timetags
• Erweiterte (nicht standardmäßige) Argumenttypen

Dokumentation

Weitere Informationen zu osc-js und seiner Verwendung finden Sie im Wiki und in der Dokumentation.

Beispiel

 const osc = new OSC ( )

osc . on ( '/param/density' , ( message , rinfo ) => {
  console . log ( message . args )
  console . log ( rinfo )
} )

osc . on ( '*' , message => {
  console . log ( message . args )
} )

osc . on ( '/{foo,bar}/*/param' , message => {
  console . log ( message . args )
} )

osc . on ( 'open' , ( ) => {
  const message = new OSC . Message ( '/test' , 12.221 , 'hello' )
  osc . send ( message )
} )

osc . open ( { port : 9000 } ) 

Installation und Nutzung

Empfohlene Installation über npm: npm i osc-js oder yarn add osc-js .

Importieren Sie die Bibliothek const OSC = require('osc-js') oder fügen Sie das Skript lib/osc.js oder lib/osc.min.js (minimierte Version) zur Verwendung in einem Browser hinzu.

Plugins

osc-js bietet eine Plugin-Architektur zur Erweiterung seiner Netzwerkfunktionen. Die Bibliothek verfügt über vier integrierte Plugins. Das ist wahrscheinlich alles, was Sie für eine OSC-Anwendung benötigen:

• WebsocketClientPlugin (Standard)
• WebsocketServerPlugin
• DatagramPlugin für UDP-Netzwerknachrichten
• BridgePlugin nützliche Brücke zwischen WebSocket- und UDP-Clients

Konfiguration und Beispiele jedes Plugins können hier gelesen werden: Wiki.

Beispiel: WebSocket-Server

Registrieren Sie das Plugin beim Erstellen der OSC-Instanz:

 const osc = new OSC ( { plugin : new OSC . WebsocketServerPlugin ( ) } )
osc . open ( ) // listening on 'ws://localhost:8080'

Beispiel: OSC zwischen MaxMSP/PD/SC etc. und Ihrem Browser

1. Schreiben Sie eine einfache Webseite. Die Bibliothek verwendet standardmäßig einen WebSocket-Client.

 < button id =" send " > Send Message </ button >
< script type =" text/javascript " src =" lib/osc.min.js " > </ script >
< script type =" text/javascript " >
  var osc = new OSC ( ) ;
  osc . open ( ) ; // connect by default to ws://localhost:8080

  document . getElementById ( 'send' ) . addEventListener ( 'click' , ( ) => {
    var message = new OSC . Message ( '/test/random' , Math . random ( ) ) ;
    osc . send ( message ) ;
  } ) ;
</ script >

2. Schreiben Sie eine Node-App (die „Brücke“ zwischen Ihren UDP- und WebSocket-Clients).

 const OSC = require ( 'osc-js' )

const config = { udpClient : { port : 9129 } }
const osc = new OSC ( { plugin : new OSC . BridgePlugin ( config ) } )

osc . open ( ) // start a WebSocket server on port 8080

3. Erstellen Sie Ihren Max/MSP-Patch (oder PD, SuperCollider usw.).

 [udpreceive 9129] // incoming '/test/random' messages with random number

Individuelle Lösungen mit Plugin-API

Es ist möglich, anspruchsvollere Lösungen für OSC-Anwendungen zu schreiben, ohne die osc-js-Schnittstelle (einschließlich ihrer Nachrichtenverarbeitung usw.) zu verlieren. Weitere Informationen finden Sie in der Dokumentation zur Plugin-API.

 class MyCustomPlugin {
  // ... read docs for implementation details
}

const osc = new OSC ( { plugin : MyCustomPlugin ( ) } )
osc . open ( )

osc . on ( '/test' , message => {
  // use event listener with your plugin
} )

Nutzung ohne Plugins

Die Bibliothek kann ohne die genannten Funktionen verwendet werden, falls Sie binäre OSC-Daten schreiben und lesen müssen. Sehen Sie sich dieses Beispiel unten für die Verwendung der Low-Level-API an (obwohl die Bibliothek bereits über eine Lösung für die Handhabung von UDP wie in diesem Beispiel verfügt):

 const dgram = require ( 'dgram' )
const OSC = require ( 'osc-js' )

const socket = dgram . createSocket ( 'udp4' )

// send a messsage via udp
const message = new OSC . Message ( '/some/path' , 21 )
const binary = message . pack ( )
socket . send ( new Buffer ( binary ) , 0 , binary . byteLength , 41234 , 'localhost' )

// receive a message via UDP
socket . on ( 'message' , data => {
  const msg = new OSC . Message ( )
  msg . unpack ( data )
  console . log ( msg . args )
} ) 

Entwicklung

osc-js verwendet Babel für die ES6-Unterstützung, ESDoc für die Dokumentation, Mocha + Chai für Tests und Rollup für die Generierung des UMD-Moduls.

Klonen Sie das Repository und installieren Sie alle Abhängigkeiten:

 git clone [email protected]:adzialocha/osc-js.git
cd osc-js
npm install

Testen

npm run test zum Ausführen der Tests. npm run test:watch während der Entwicklung auf Laufspezifikationen. Überprüfen Sie den Codestil mit npm run lint .

Einsatz

npm run build zum Exportieren des UMD-Moduls in lib -Ordner.

Mitwirkende

• @adzialocha
• @davidgranstrom
• @elgiano
• @eliot-akira
• @JacobMuchow
• @PeterKey
• @yaxu
• @yojeek

ESDocs

npm run docs um einen docs -Ordner mit HTML-Dateien zu generieren, die die Bibliothek dokumentieren. Lesen Sie sie hier online: https://adzialocha.github.io/osc-js

Lizenz

MIT-Lizenz MIT