osc.js Web Sockets

### Install Dependencies Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Installs all necessary project dependencies using npm. This is a prerequisite for building and testing. ```bash npm install ``` -------------------------------- ### Install osc.js with npm Source: https://github.com/colinbdclark/osc.js/blob/main/README.md This snippet shows how to install the osc.js library using npm, a package manager for Node.js and web projects. It includes a sample package.json configuration file. ```json { "name": "", "version": "", "dependencies": { "osc": "2.4.1" } } ``` ```bash npm install ``` -------------------------------- ### Include osc.js in HTML Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Demonstrates how to include the osc.js library in an HTML page using a script tag. This is the simplest way to get started with osc.js in a browser. ```html osc.js Web Sockets ``` -------------------------------- ### Listen for Incoming OSC Messages Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Provides an example of how to set up a listener for incoming OSC messages on the WebSocket port. The 'message' event handler receives the OSC message object. ```javascript oscPort.on("message", function (oscMsg) { console.log("An OSC message just arrived!", oscMsg); }); ``` -------------------------------- ### OSC to JavaScript Object Mapping Examples Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Illustrates how various OSC messages are converted into plain JavaScript objects by the osc.js library. This includes examples for different data types like floats, arrays, time tags, blobs, colors, and MIDI messages. ```javascript OSC Message: "/carrier/freq" ",f" 440.4 JavaScript Object: { address: "/carrier/freq", args: [ { type: "f", value: 440.4 } ] } ``` ```javascript OSC Message: "/float/andArray" ",f[ff]" 440.4 42 47 JavaScript Object: { address: "/float/andArray", args: [ { type: "f", value: 440.4 }, [ { type: "f", value: 42.0 }, { type: "f", value: 47.0 } ] ] } ``` ```javascript OSC Message: "/aTimeTag" ",t" 3608146800 2147483648 JavaScript Object: { address: "/scheduleAt", args: [ { raw: [3608146800, 2147483648], jsTime: 1399158000500 } ] } ``` ```javascript OSC Message: "/blob" ",b" 0x63 0x61 0x74 0x21 JavaScript Object: { address: "/blob", args: [ { type: "b", value: new Uint8Array([0x63, 0x61, 0x74, 0x21]) } ] } ``` ```javascript OSC Message: "/colour" ",r" "255 255 255 255" JavaScript Object: { address: "/colour", args: [ { type: "r", value: { r: 255, g: 255, b: 255, a: 1.0 } } ] } ``` ```javascript OSC Message: "/midiMessage" ",m" 0x00 0x90 0x45 0x65 JavaScript Object: { address: "/midiMessage", args: [ { type: "m", value: new Uint8Array([0, 144, 69, 101]) // Port ID, Status, Data 1, Data 2 } ] } ``` -------------------------------- ### jQuery Integration in Electron Render Process Source: https://github.com/colinbdclark/osc.js/blob/main/tests/electron-tests/electron-render-process-tests.html This snippet demonstrates how jQuery is required and made available globally within the Electron render process for osc.js. It's a common setup for applications needing jQuery's DOM manipulation capabilities. ```javascript window.$ = window.jQuery = require("jquery"); ``` -------------------------------- ### Source Code Distribution Options Source: https://github.com/colinbdclark/osc.js/blob/main/GPL-LICENSE.txt Outlines the acceptable methods for distributing the Program or works based on it, focusing on providing corresponding source code. ```text 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. ``` -------------------------------- ### Use osc.js with WebPack Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Provides guidance on using osc.js with module bundlers like WebPack. It suggests loading the pre-built `osc-browser.js` package. Community contributions for better WebPack and ES6 module support are encouraged. ```javascript require("osc/dist/osc-browser"); ``` -------------------------------- ### License Acceptance Source: https://github.com/colinbdclark/osc.js/blob/main/GPL-LICENSE.txt Explains that modifying or distributing the Program implies acceptance of the license terms, even without a formal signature. ```text 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and ``` -------------------------------- ### Run All osc.js Tests Source: https://github.com/colinbdclark/osc.js/blob/main/tests/all-tests.html Initializes and runs all defined test suites for the osc.js library using the QUnit testing framework. It specifies the HTML files that contain the individual test cases. ```javascript QUnit.testSuites("osc.js Tests", [ "osc-tests.html", "transport-tests.html", "osc-module-tests.html", "osc-web-tests.html" ]); ``` -------------------------------- ### Use osc.js with Require.js Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Explains how to configure and load osc.js using Require.js, a JavaScript module loader. This involves defining module paths for osc.js and its dependencies. ```javascript // Define your module paths, including osc.js' dependencies. // Note: these paths must resolve to wherever you have placed // osc.js, slip.js, and eventEmitter in your project. require.config({ paths: { slip: "../node_modules/slip.js/dist/slip.min", EventEmitter: "../node_modules/eventEmitter/EventEmitter.min", long: "../node_modules/long/dist/Long.min", osc: "../node_modules/osc.js/osc-module.min" } }); // Load it asynchronously. require(["osc"], function (osc) { // Do something with osc.js when it has fully loaded. }); ``` -------------------------------- ### Build Project Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Lints and generates builds from new source code using Grunt. This command is essential for incorporating code changes. ```bash grunt ``` -------------------------------- ### Open OSC WebSocket Port Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Demonstrates how to open the OSC WebSocket port. This action establishes the connection to the Web Socket server, allowing for OSC message transmission. ```javascript oscPort.open(); ``` -------------------------------- ### Run Automated Unit Tests Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Executes the fully automated unit tests for osc.js using npm. This is the primary method for verifying code correctness. ```bash npm test ``` -------------------------------- ### Send OSC Messages Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Illustrates how to send an OSC message using the osc.WebSocketPort. It's recommended to send messages only after the 'ready' event has fired, ensuring the port is open and ready for communication. ```javascript // For most Ports, send() should only be called after the "ready" event fires. osPort.on("ready", function () { oscPort.send({ address: "/carrier/frequency", args: [ { type: "f", value: 440 } ] }); }); ``` -------------------------------- ### Run Electron Tests Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Executes tests specifically for the Electron environment. This is useful for testing features that rely on Electron integration. ```bash npm run electron-test ``` -------------------------------- ### WebSocket Server with osc.js Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Sets up an Express server and a WebSocket server to handle incoming OSC messages over WebSockets. It listens for connections and logs any received OSC messages. ```javascript var osc = require("osc"), http = require("http"), WebSocket = require("ws"); // Create an Express server app // and serve up a directory of static files. var app = require("express").express(), server = app.listen(8081); app.use("/", express.static(__dirname + "/static")); // Listen for Web Socket requests. var wss = new WebSocket.Server({ server: server }); // Listen for Web Socket connections. wss.on("connection", function (socket) { var socketPort = new osc.WebSocketPort({ socket: socket, metadata: true }); socketPort.on("message", function (oscMsg) { console.log("An OSC Message was received!", oscMsg); }); }); ``` -------------------------------- ### osc.js Options Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Configuration options for osc.js Transport objects, including ports, addresses, broadcast settings, and multicast configurations. ```APIDOC localPort: Description: The port to listen on Default Value: 57121 localAddress: Description: The local address to bind to Default Value: "127.0.0.1" remotePort: Description: The remote port to send messages to (optional) Default Value: none remoteAddress: Description: The remote address to send messages to (optional) Default Value: none broadcast: Description: A flag specifying if messages should be sent via UDP broadcast Default Value: false multicastTTL: Description: The time to live (number of hops) for a multicast connection (optional) Default Value: none multicastMembership: Description: An array of multicast addresses to join when listening for multicast messages (optional) Default Value: none socketId: Description: The id of an existing socket to use instead of osc.js creating one for you; if supplied, it is your job to configure and bind it appropriately Default Value: none ``` -------------------------------- ### UDP Port in Node.js Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Demonstrates how to create and use an osc.UDPPort in Node.js to send and receive OSC messages. It includes opening the port, handling incoming messages, and sending a message to SuperCollider. ```javascript // Create an osc.js UDP Port listening on port 57121. var udpPort = new osc.UDPPort({ localAddress: "0.0.0.0", localPort: 57121, metadata: true }); // Listen for incoming OSC messages. udpPort.on("message", function (oscMsg, timeTag, info) { console.log("An OSC message just arrived!", oscMsg); console.log("Remote info is: ", info); }); // Open the socket. udpPort.open(); // When the port is read, send an OSC message to, say, SuperCollider udpPort.on("ready", function () { udpPort.send({ address: "/s_new", args: [ { type: "s", value: "default" }, { type: "i", value: 100 } ] }, "127.0.0.1", 57110); }); ``` -------------------------------- ### UDP Port Configuration Options Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Details the configuration options available for the osc.UDPPort object, including local and remote addresses/ports, broadcast, multicast TTL, multicast membership, and using a pre-existing dgram.Socket. ```APIDOC UDP Port Options: localPort: The port to listen on (Default: 57121) localAddress: The local address to bind to (Default: "127.0.0.1") remotePort: The remote port to send messages to (optional) remoteAddress: The remote address to send messages to (optional) broadcast: A flag specifying if messages should be sent via UDP broadcast (Default: false) multicastTTL: The time to live (number of hops) for a multicast connection (optional) multicastMembership: An array of multicast addresses to join when listening for multicast messages (optional) socket: A raw dgram.Socket to use instead of osc.js creating one for you; if supplied, it is your job to configure and bind it appropriately (Default: none) ``` -------------------------------- ### Send OSC Bundles Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Shows how to send an OSC bundle, which is a collection of OSC messages with an optional time tag. This allows for scheduling messages to be processed at a specific time by the receiver. ```javascript oscPort.on("ready", function () { oscPort.send({ // Tags this bundle with a timestamp that is 60 seconds from now. // Note that the message will be sent immediately; // the receiver should use the time tag to determine // when to act upon the received message. timeTag: osc.timeTag(60), packets: [ { address: "/carrier/frequency", args: [ { type: "f", value: 440 } ] }, { address: "/carrier/amplitude", args: [ { type: "f", value: 0.5 } ] } ] }); }); ``` -------------------------------- ### License Distribution Requirements Source: https://github.com/colinbdclark/osc.js/blob/main/GPL-LICENSE.txt Details the obligations for distributing works derived from the osc.js project, including licensing terms and source code provisions. ```text b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. ``` -------------------------------- ### Create OSC WebSocket Port Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Shows how to instantiate an osc.WebSocketPort object. This port is used for sending and receiving OSC messages over Web Sockets. It requires a URL for client connections and can optionally take metadata. ```javascript var oscPort = new osc.WebSocketPort({ url: "ws://localhost:8081", // URL to your Web Socket server. metadata: true }); ``` -------------------------------- ### osc.js API Documentation Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Provides detailed information on the functions for reading and writing OSC data, including their parameters, return values, and usage. ```APIDOC osc.readPacket(data, options, offsetState, length) Decodes binary OSC message into a tree of JavaScript objects containing the messages or bundles that were read. Parameters: data: A Uint8Array containing the raw data of the OSC packet. options: (optional) An options object. offsetState: (optional) An offset state object containing an idx property that specifies the offset index into data. length: The length (in bytes) to read from data. Returns: An osc.js message or bundle object. osc.writePacket(packet, options) Writes an OSC message or bundle object to a binary array. Parameters: packet: An osc.js message or bundle object. options: (optional) An options object. Returns: A Uint8Array. ``` -------------------------------- ### Error Handling with osc.js Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Demonstrates how to handle errors emitted by osc.js Transport objects and errors thrown by the low-level API. ```javascript var port = osc.UDPPort(); port.on("error", function (error) { console.log("An error occurred: ", error.message); }); ``` ```javascript var msg; try { msg = osc.readPacket(rawPacket); } catch (error) { console.log("An error occurred: ", error.message); } ``` -------------------------------- ### osc.js Options Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Details the configurable options for osc.js functions and Port objects. These options allow customization of behavior, such as including OSC type metadata or automatically unpacking single-argument messages. ```APIDOC osc.js Options: metadata: boolean Specifies if OSC type metadata should be included. Defaults to false. When true, type metadata is included when reading packets and inferred when writing. Useful for greater precision in OSC message arguments. unpackSingleArgs: boolean Specifies if osc.js should automatically unpack single-argument messages. If true, the 'args' property will not be wrapped in an array for single-argument messages. Defaults to true. ``` -------------------------------- ### License Restrictions Source: https://github.com/colinbdclark/osc.js/blob/main/GPL-LICENSE.txt Specifies the limitations on copying, modifying, sublicensing, and distributing the Program, and the consequences of violating these terms. ```text 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. ``` -------------------------------- ### Electron Configuration (.npmrc) Source: https://github.com/colinbdclark/osc.js/blob/main/README.md This configuration file is used to override npm's default compile target and runtime settings for Electron applications, ensuring native Node.js modules are compiled correctly for the Electron environment. The `target` property must match the Electron version being used. ```json target=23.1.3 disturl=https://electronjs.org/headers runtime=electron build_from_source=true ``` -------------------------------- ### osc.js Port API Documentation Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Documentation for the osc.js Port API, detailing methods for sending OSC packets and events for receiving messages and handling port status. This API provides an EventEmitter-style interface for various transports like UDP and Web Sockets. ```APIDOC osc.Port: Methods: send(packet) Description: Sends an OSC package (either a message or a bundle) on this Port. Arguments: packet: the OSC message or bundle to send Events: ready Description: Fires when a Port is ready to send or receive messages. Arguments: _none message(message, timeTag, info) Description: Fires whenever an OSC message is received by the Port. Arguments: message: the OSC message received timeTag: the time tag specified by the sender (may be undefined for non-bundle messages) info: an implementation-specific remote information object bundle(bundle, timeTag, info) Description: Fires whenever an OSC bundle is received. Subsequent bundle and/or message events will be fired for each sub-packet in the bundle. Arguments: bundle: the OSC bundle received timeTag: the time tag specified by the sender info: an implementation-specific remote information object osc(packet, info) Description: Fires whenever any type of OSC packet is recieved by this Port. Arguments: packet: the OSC message or bundle received info: an implementation-specific remote information object raw(data, info) Description: Fires whenever any data is recieved by this Port. Arguments: data: an Uint8Array containing the raw data received info: an implementation-specific remote information object error(error) Description: Fires whenever an error occurs. Arguments: error: the Error object that was raised ``` -------------------------------- ### Including osc.js in Chrome App Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Shows how to include the osc.js library in a Chrome App's HTML file using a script tag. ```html ``` -------------------------------- ### Chrome App Manifest Permissions Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Specifies the necessary permissions in a Chrome App's manifest.json file, specifically the 'serial' permission required for using osc.SerialPort. ```json { "name": "OSC.js Chrome App Demo", "version": "1", "manifest_version": 2, "permissions": [ "serial" ], "app": { "background": { "scripts": ["js/launch.js"], "transient": true } } } ``` -------------------------------- ### Type-Annotated OSC Arguments Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Describes the structure of type-annotated OSC argument objects, containing 'type' and 'value'. ```APIDOC Type-Annotated Argument Object: type: OSC type tag string (e.g., "i", "f", "t") value: The raw argument value ``` -------------------------------- ### Serial Port Communication in Chrome App Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Demonstrates how to instantiate and use osc.SerialPort in a Chrome App to listen for OSC messages received over a serial connection. It includes opening the port and logging received messages. ```javascript // Instantiate a new OSC Serial Port. var serialPort = new osc.SerialPort({ devicePath: "/dev/cu.usbmodem22131", metadata: true }); // Listen for the message event and map the OSC message to the synth. serialPort.on("message", function (oscMsg) { console.log("An OSC message was received!", oscMsg); }); // Open the port. serialPort.open(); ``` -------------------------------- ### OSC Message Structure Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Defines the structure of OSC Message objects, including the 'address' and 'args' properties. ```APIDOC OSC Message Object: address: URL-style address path (string) args: Array of raw argument values or type-annotated Argument objects ``` -------------------------------- ### OSC Bundle Structure Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Defines the structure of OSC Bundle objects, including 'timeTag' and 'packets'. ```APIDOC OSC Bundle Object: timeTag: OSC Time Tag object packets: Array of nested OSC bundle and message objects ``` -------------------------------- ### OSC Colour Normalization Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Details how OSC colour values are normalized to CSS 3 rgba format. ```APIDOC OSC Colour Object (normalized): r: Red component (0-255) g: Green component (0-255) b: Blue component (0-255) a: Alpha channel (0.0-1.0) ``` -------------------------------- ### OSC Time Tag Representation Source: https://github.com/colinbdclark/osc.js/blob/main/README.md Explains the structure of OSC Time Tag objects, including raw NTP time and native JavaScript timestamp representations. ```APIDOC OSC Time Tag Object: raw: Array containing seconds and fractions of a second since January 1, 1900 (NTP format) - raw[0]: Seconds since January 1, 1900 - raw[1]: Fractions of a second (Uint32) native: Milliseconds since January 1, 1970 (JavaScript timestamp) ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.