osc-min
v2.1.1
Published
Simple utilities for open sound control in node.js
Downloads
2,922
Maintainers
Readme
osc-min
simple utilities for open sound control in node.js
This package provides some node.js utilities for working with
OSC, a format for sound and systems control.
Here we implement the OSC 1.1 specification. OSC is a transport-independent
protocol, so we don't provide any server objects, as you should be able to
use OSC over any transport you like. The most common is probably udp, but tcp
is not unheard of.
Examples
Further examples available in the examples
folder.
A simple OSC server that prints any received messages
const sock = udp.createSocket("udp4", (msg) => {
try {
console.log(osc.fromBuffer(msg));
} catch (e) {
console.log("invalid OSC packet", e);
}
});
sock.bind(inport);
Send a message containing multiple arguments every 2 seconds
const sendHeartbeat = () => {
const buf = toBuffer({
address: "/heartbeat",
args: [
12,
"sttttring",
new TextEncoder().encode("beat"),
{
type: "integer",
value: 7,
},
],
});
return udp.send(buf, 0, buf.byteLength, outport, "localhost");
};
setInterval(sendHeartbeat, 2000);
A simple OSC re-director
const sock = dgram.createSocket("udp4", (msg) => {
try {
const redirected = osc.applyAddressTransform(
msg,
(address) => `/redirect${address}`
);
return sock.send(
redirected,
0,
redirected.byteLength,
outport,
"localhost"
);
} catch (e) {
return console.log(`error redirecting: ${e}`);
}
});
sock.bind(inport);
Javascript representations of the OSC types.
See the [spec][spec] for more information on the OSC types.
An OSC Packet is an OSC Message or an OSC Bundle.
An OSC Message:
{ oscType : "message" address : "/address/pattern/might/have/wildcards" args : [arg1,arg2] }
Where args is an array of OSC Arguments. oscType
is optional.
args
can be a single element.
An OSC Argument is represented as a javascript object with the following layout:
{ type : "string" value : "value" }
Where the type
is one of the following:
string
- string valuefloat
- numeric valueinteger
- numeric valuecolor
- JS object containingred
,green
,blue
,alpha
in range 0-255midi
- four-element array of numbers representing a midi packet of datasymbol
- string valuecharacter
- a single-character stringdouble
- numeric valuebigint
- 64-bitbigint
value (watch out, this will be truncated to 64 bits!)blob
-ArrayBuffer
,DataView
,TypedArray
or node.jsBuffer
true
- value is boolean truefalse
- value is boolean falsenull
- no valuebang
- no value (this is theI
type tag)timetag
- JavascriptDate
array
- array of OSC Arguments
Note that type
is always a string - i.e. "true"
rather than true
.
The following non-standard types are also supported:
double
- numeric value (encodes to a float64 value)
For messages sent to the toBuffer
function, type
is optional.
If the argument is not an object, it will be interpreted as either
string
, float
, array
or blob
, depending on its javascript type
(String, Number, Array, Buffer, respectively)
An OSC Bundle is represented as a javascript object with the following fields:
{ oscType : "bundle" timetag : 7 elements : [element1, element] }
oscType
"bundle"
timetag
is one of:
Date
- a JavaScript Date objectArray
-[numberOfSecondsSince1900, fractionalSeconds]
Both values arenumber
s. This gives full timing accuracy of 1/(2^32) seconds.
elements
is an Array
of either OSC Message or OSC Bundle
[spec]: http://opensoundcontrol.org/spec-1_0
Migrating from 1.0
There have been a few breaking changes from the 1.0 version:
- We now provide type declarations for typescript compatibility
- We always enable the previously optional "strict" errors
- Many explicit error messages for passing in data of the wrong type have been removed. We encourage you to use typescript to prevent these sorts of errors.
- Functions that used to return
Buffer
now returnDataView
- TimeTags must be specified as
Date
s or[number, number]
arrays, and are always returned as[number, number]
arrays. To convert between arrays andDate
s, usedateToTimetag
andtimetagToDate
. - The two-argument version of
toBuffer
has been removed.
License
Licensed under the terms found in COPYING (zlib license)