REF / Music API / OSC

OSC refers to the Open Sound Control network protocol. You can use it to collaborate with other programs on your machine or within your local network. There are a number of slick apps for iPad and desktop for designing control surfaces and these should readily communicate to your programs.

OSC is more expressive than MIDI since you can design your own messaging patterns. Because of this blank page you may find it a little daunting. The good news is: easy things are easy!

OSCIn API

Use the OSCIn class to install one or more listeners for OSC activity. As a listener you need only specifiy the OSC port. The port represents a meeting point between sender and listener. By default Hz's OSC listening port is port 22000, but you can initialize your OSCIn instance to listen on any legal and available port.

let oin = new OSCIn();

Example

let oin = new OSCIn(); 
let err = await oin.Connect(); // listen on default port (22000)
if(!err)
{
    console.info("oin connected");
    for(let i=0;i<30;i++)
    {
        let msg = await oin.Recv();
        console.log(`${i} OSC msg: ` + JSON.stringify(msg));
    }
    console.info("oin done after 30 messages");
    oin.Disconnect();
}
else
    console.warn("Problem listening on default OSC port.");

Here's a portion of the output:

15:25 info oin connected
15:25 info 0 OSC msg: {"addr":"/foo/notes","types":"if","origin":"192.168.1.113","data":[47,0.445024]}
15:25 info 1 OSC msg: {"addr":"/foo/notes","types":"if","origin":"192.168.1.113","data":[42,0.399837]}
15:25 info 2 OSC msg: {"addr":"/foo/notes","types":"if","origin":"192.168.1.113","data":[34,0.392982]}

OSCOut API

let oout = new OSCOut(hostip, port);

Example

// This script sends dota from Hz to separate
// processes on the desired host(s) listening on specified port. 
// If no process is listening or the host is invalid, the script 
// still runs but has no effect other than network pollution.
// Here we "spawn" three separate fibers and communicate differently
// with each target.

let scene = await Ascene.BeginFiber(this);

let sDefaultCfg = {host:"localhost", port:10000, loops:10, notedur:.25};

async function go(cfg = {})
{
    let lcfg = Object.assign({}, sDefaultCfg, cfg);
    let {host, port, loops, notedur} = lcfg;
    let ipaddress;
    if(host.match(/[a-zA-z]/) && host != "localhost")
    {
        // DNS lookups can take some time
        ipaddress = await OSCUtil.GetHostAddr(host, port);
        console.log(`${host} -> ${ipaddress}`);
    }
    else
        ipaddress = host;
    let oout = new OSCOut(ipaddress, port);
    let tgt = `${host}:${port}`;
    let dur = scene.Seconds(notedur);
    for(let i=0;i<loops;i++)
    {
        oout.StartMsg("/foo/note")
        oout.AddValue(40+i); // the MIDI key
        oout.AddValue(.33 * i); // the velocity
        oout.AddValue(tgt);
        oout.SendMsg();
        console.info(`send ${tgt} ${i}/${loops}`);
        await scene.Wait(dur)
    }
}

let promises = [];
// promises.push(Async.Run(go, {host:"255.255.255.255", notedur:1})); // permission denied
promises.push(Async.Run(go, {host:"limpet.local", notedur:1}));
promises.push(Async.Run(go, {host:"localhost", notedur:.1}));
promises.push(Async.Run(go, {host:"192.168.1.113", notedur:.5}));
await Promise.all(promises);
console.log("done");

OSCUtil API

This module collections functions that may be useful in your OSC endeavors.

OSC Lua API

Recv methods

Send methods

Produce OSC packets for consumption by another coroutine, process or computer.