A RNBO runner controlled by OSCQuery.
NOTE there is a separate README for rpi that indicates how to build for rpi.
This currently builds and runs on Linux and Mac. Windows is TBD.
debian instructions also apply to other apt based distros like ubuntu.
- cmake version 3.17 or greater
- macOS:
brew install cmake - debian:
sudo apt-get install cmake - make sure
cmakeis in your path if you install it withbrewor directly from the download
- macOS:
g++orclang++- macOS:
clang++comes with XCode. - debian:
sudo apt-get install build-essential g++
- macOS:
- conan
- via pip3:
- macOS: modern macOS comes with
pip3 - debian:
sudo apt-get install python3-pip pip3 install --break-system-packages --user conan==1.61.0
- macOS: modern macOS comes with
- make sure that
conanis in your PATH, I updated my.bashrcto add~/.local/bin/to my PATH
- via pip3:
ruby2.0+ to run the compile script- macOS: modern macOS comes with
ruby - debian:
sudo apt-get install ruby
- macOS: modern macOS comes with
Build the runner with CMake. You may have to update the RNBO_DIR to reflect the path on your system.
If you're on Mac OS using the bundled RNBO version, your RNBO_DIR should probably be:
~/Documents/Max\ 8/Packages/RNBO/source/rnbo/if you installed RNBO with the package manager/Applications/Max.app/Contents/Resources/C74/packages/RNBO/source/rnboif you're using RNBO bundled with Max.
On Linux you'll likely have to copy the rnbo src dir from a Windows or Mac machine.
mkdir build/
cd build/
cmake .. -DRNBO_DIR=~/Documents/Max\ 8/Packages/RNBO/source/rnbo/
cmake --build .
If you're on a debian based system, you can also build a .deb
cpack
then you can install it with
sudo dpkg -i *.deb`
There is an example runner.json config file in the config directory.
If you want some customizations you can edit that and copy it here:
~/.config/rnbo/runner.json
Here is an example of the contents:
{
"compile_cache_dir": "~/Documents/rnbo/cache/so/",
"save_dir": "~/Documents/rnbo/cache/saves/",
"source_cache_dir": "~/Documents/rnbo/cache/src/",
"datafile_dir": "~/Documents/rnbo/datafiles/",
"instance_auto_start_last": true,
"instance_auto_connect_audio": true,
"instance_auto_connect_midi": true,
"jack": {
"period_frames": 1024,
"sample_rate": 44100.0,
"card_name": "hw:ES8",
"midi_system_name": "raw"
}
}compile_cache_dir: a path to the directory where compiled shared objects are storedsave_dir: a path to the directory where save data is storedsource_cache_dir: a path to the directory where source files are stored before compilingdatafile_dir: a path to the directory where datafiles are stored, to be loaded as data refs- you can put files directly into this directory and load them via the OSCQuery data ref commands
instance_auto_start_last: a boolean that indicates if when the runner starts, if it should attempt to load the last patcher it loaded before restartinstance_auto_connect_audio: a boolean that indicates if the runner should automatically try to connect its audio i/o- disabling this can be useful if you want to have a custom jack signal flow, the commandline
jack_connectcan be useful if you have this set to false
- disabling this can be useful if you want to have a custom jack signal flow, the commandline
instance_auto_connect_midi: a boolean that indicates if the runner should automatically connect to MIDI devices that it sees- you can use
jack_connecton the commandline to connect to specific MIDI devices if you have this set to false
- you can use
The only file that is currently saved in the save_dir is called last.json
Here is an example of that file content:
{
"instances": [
{
"config": {
"datarefs": {
"loop": "jongly.aif"
},
"inports": [
"foo"
],
"outports": [
"bar"
],
"presets": {
"muted": {
"baz": {
"value": 0.0
}
},
"snap1": {
"baz": {
"value": 0.9430000185966492
}
}
}
},
"so_path": "/home/pi/Documents/rnbo/cache/so/libRNBORunnerSO1634332529.0.13.0-dev.44.so"
}
]
}The saves file only supports 1 instance at the time of this writing but eventually might support more.
If you edit this file you can change values for dataref mappings, presets and also identify which so to load on restart.
If you haven't run jack before you probably want to set it up with qjackctl, you can leave that running while running the runner.
Simply run the runner from the build directory ./bin/rnbooscquery
Then start up Max. The RNBO sidebar should list your host as a OSCQuery Runner Export.
You can communicate with the runner via Open Sound Control (OSC) over either websockets or UDP.
If you have sucessfully connected to a runner in Max, the associated target sidebar info should show you the UDP and HTTP/WS host port and, for OSC, transport.
By default the HTTP and websocket port are 5678 and OSC is UDP at 1234 so if you know the ip of your runner, you should be able to load a webpage with the url:
http://<ipoftherunner>:5678 and send OSC messages at osc.udp://<ipoftherunner>:1234
If you have a hostname like c74rpi.local that works, you can also use that http://c74rpi.local:5678 osc.udp://c74rpi.local:1234
The websocket interface is created via an http upgrade from the HTTP host and port.
NOTE the websocket interface is used for more than just OSC, so you'll want to detect the type of the websocket messages and only try to parse the Binary messages.
If you've sent a patch to your runner, you should be able to investigate the
runner's OSCQuery namespace via
HTTP. For instance, if my runner is at c74rpi.local, I might see the
below in my web browser if I load the URL http://c74rpi.local:5678
{
"FULL_PATH":"/",
"CONTENTS":{
"rnbo":{
"FULL_PATH":"/rnbo",
"CONTENTS":{
"info":{
"FULL_PATH":"/rnbo/info",
"DESCRIPTION":"information about RNBO and the running system",
"CONTENTS":{
"version":{
"FULL_PATH":"/rnbo/info/version",
"TYPE":"s",
"VALUE":"0.11.0-dev",
"ACCESS":1,
"CLIPMODE":"none"
},
"system_name":{
"FULL_PATH":"/rnbo/info/system_name",
"TYPE":"s",
"VALUE":"Linux",
"ACCESS":1,
"CLIPMODE":"none"
},
"system_processor":{
"FULL_PATH":"/rnbo/info/system_processor",
"TYPE":"s",
"VALUE":"armv7",
"ACCESS":1,
"CLIPMODE":"none"
},
"system_id":{
"FULL_PATH":"/rnbo/info/system_id",
"TYPE":"s",
"VALUE":"c516613b-449f-49c7-a81b-f4de411f8d1e",
"ACCESS":1,
"CLIPMODE":"none",
"DESCRIPTION":"a unique, one time generated id for this system"
},
"disk_bytes_available":{
"FULL_PATH":"/rnbo/info/disk_bytes_available",
"TYPE":"s",
"VALUE":"11332669440",
"ACCESS":1,
"CLIPMODE":"none"
},
"update":{
"FULL_PATH":"/rnbo/info/update",
"DESCRIPTION":"Self upgrade/downgrade",
"CONTENTS":{
"state":{
"FULL_PATH":"/rnbo/info/update/state",
"TYPE":"s",
"VALUE":"idle",
"RANGE":[
{
"VALS":[
"idle",
"active",
"failed"
]
}
],
"ACCESS":1,
"CLIPMODE":"both",
"DESCRIPTION":"Update state"
},
"status":{
"FULL_PATH":"/rnbo/info/update/status",
"TYPE":"s",
"VALUE":"waiting",
"ACCESS":1,
"CLIPMODE":"none",
"DESCRIPTION":"Latest update status"
},
"supported":{
"FULL_PATH":"/rnbo/info/update/supported",
"TYPE":"T",
"VALUE":null,
"ACCESS":1,
"CLIPMODE":"none",
"DESCRIPTION":"Does this runner support remote upgrade/downgrade"
}
}
}
}
},
"cmd":{
"FULL_PATH":"/rnbo/cmd",
"TYPE":"s",
"VALUE":"",
"ACCESS":2,
"CLIPMODE":"none",
"DESCRIPTION":"command handler"
},
"resp":{
"FULL_PATH":"/rnbo/resp",
"TYPE":"s",
"VALUE":"",
"ACCESS":1,
"CLIPMODE":"none",
"DESCRIPTION":"command response"
},
"jack":{
"FULL_PATH":"/rnbo/jack",
"CONTENTS":{
"info":{
"FULL_PATH":"/rnbo/jack/info",
"CONTENTS":{
"alsa_cards":{
"FULL_PATH":"/rnbo/jack/info/alsa_cards",
"CONTENTS":{
"hw:ES8":{
"FULL_PATH":"/rnbo/jack/info/alsa_cards/hw:ES8",
"TYPE":"s",
"VALUE":"USB-Audio - ES-8\nExpert Sleepers Ltd ES-8 at usb-0000:01:00.0-1.4, high speed",
"ACCESS":1,
"CLIPMODE":"none"
},
"hw:1":{
"FULL_PATH":"/rnbo/jack/info/alsa_cards/hw:1",
"TYPE":"s",
"VALUE":"USB-Audio - ES-8\nExpert Sleepers Ltd ES-8 at usb-0000:01:00.0-1.4, high speed",
"ACCESS":1,
"CLIPMODE":"none"
}
}
},
"is_realtime":{
"FULL_PATH":"/rnbo/jack/info/is_realtime",
"TYPE":"T",
"VALUE":null,
"ACCESS":1,
"CLIPMODE":"none",
"DESCRIPTION":"indicates if jack is running in realtime mode or not"
}
}
},
"config":{
"FULL_PATH":"/rnbo/jack/config",
"DESCRIPTION":"Jack configuration parameters",
"CONTENTS":{
"card":{
"FULL_PATH":"/rnbo/jack/config/card",
"TYPE":"s",
"VALUE":"hw:ES8",
"RANGE":[
{
"VALS":[
"hw:ES8",
"hw:1"
]
}
],
"ACCESS":3,
"CLIPMODE":"both",
"DESCRIPTION":"ALSA device name"
},
"num_periods":{
"FULL_PATH":"/rnbo/jack/config/num_periods",
"TYPE":"i",
"VALUE":2,
"RANGE":[
{
"VALS":[
1,
2,
3,
4
]
}
],
"ACCESS":3,
"CLIPMODE":"both",
"DESCRIPTION":"Number of periods of playback latency"
},
"period_frames":{
"FULL_PATH":"/rnbo/jack/config/period_frames",
"TYPE":"i",
"VALUE":1024,
"RANGE":[
{
"VALS":[
32,
64,
128,
256,
512,
1024
]
}
],
"ACCESS":3,
"CLIPMODE":"both",
"DESCRIPTION":"Frames per period"
},
"sample_rate":{
"FULL_PATH":"/rnbo/jack/config/sample_rate",
"TYPE":"f",
"VALUE":48000.0,
"RANGE":[
{
"MIN":22050.0
}
],
"ACCESS":3,
"CLIPMODE":"both",
"DESCRIPTION":"Sample rate"
}
}
},
"active":{
"FULL_PATH":"/rnbo/jack/active",
"TYPE":"T",
"VALUE":null,
"ACCESS":3,
"CLIPMODE":"none"
},
"transport":{
"FULL_PATH":"/rnbo/jack/transport",
"CONTENTS":{
"bpm":{
"FULL_PATH":"/rnbo/jack/transport/bpm",
"TYPE":"f",
"VALUE":100.0,
"ACCESS":3,
"CLIPMODE":"none"
},
"rolling":{
"FULL_PATH":"/rnbo/jack/transport/rolling",
"TYPE":"F",
"VALUE":null,
"ACCESS":3,
"CLIPMODE":"none"
}
}
}
}
},
"inst":{
"FULL_PATH":"/rnbo/inst",
"DESCRIPTION":"command response",
"CONTENTS":{
"0":{
"FULL_PATH":"/rnbo/inst/0",
"CONTENTS":{
"jack":{
"FULL_PATH":"/rnbo/inst/0/jack",
"CONTENTS":{
"audio_ins":{
"FULL_PATH":"/rnbo/inst/0/jack/audio_ins",
"TYPE":"",
"VALUE":[
],
"ACCESS":1,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list"
},
"audio_outs":{
"FULL_PATH":"/rnbo/inst/0/jack/audio_outs",
"TYPE":"",
"VALUE":[
],
"ACCESS":1,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list"
},
"midi_ins":{
"FULL_PATH":"/rnbo/inst/0/jack/midi_ins",
"TYPE":"s",
"VALUE":[
"rnbo0:midiin1"
],
"ACCESS":1,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list"
},
"midi_outs":{
"FULL_PATH":"/rnbo/inst/0/jack/midi_outs",
"TYPE":"s",
"VALUE":[
"rnbo0:midiout1"
],
"ACCESS":1,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list"
}
}
},
"params":{
"FULL_PATH":"/rnbo/inst/0/params",
"DESCRIPTION":"Parameter get/set",
"CONTENTS":{
"foo":{
"FULL_PATH":"/rnbo/inst/0/params/foo",
"TYPE":"s",
"VALUE":"x",
"RANGE":[
{
"VALS":[
"x",
"y",
"z"
]
}
],
"ACCESS":3,
"CLIPMODE":"both",
"CONTENTS":{
"normalized":{
"FULL_PATH":"/rnbo/inst/0/params/foo/normalized",
"TYPE":"f",
"VALUE":0.20000000298023225,
"RANGE":[
{
"MIN":0.0,
"MAX":1.0
}
],
"ACCESS":3,
"CLIPMODE":"both"
}
}
},
"bar":{
"FULL_PATH":"/rnbo/inst/0/params/bar",
"TYPE":"f",
"VALUE":0.0,
"RANGE":[
{
"MIN":0.0,
"MAX":100.0
}
],
"ACCESS":3,
"CLIPMODE":"both",
"CONTENTS":{
"normalized":{
"FULL_PATH":"/rnbo/inst/0/params/bar/normalized",
"TYPE":"f",
"VALUE":0.0,
"RANGE":[
{
"MIN":0.0,
"MAX":1.0
}
],
"ACCESS":3,
"CLIPMODE":"both"
}
}
}
}
},
"data_refs":{
"FULL_PATH":"/rnbo/inst/0/data_refs"
},
"presets":{
"FULL_PATH":"/rnbo/inst/0/presets",
"CONTENTS":{
"entries":{
"FULL_PATH":"/rnbo/inst/0/presets/entries",
"TYPE":"s",
"VALUE":[
"untitled 1"
],
"ACCESS":1,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list",
"DESCRIPTION":"A list of presets that can be loaded"
},
"save":{
"FULL_PATH":"/rnbo/inst/0/presets/save",
"TYPE":"s",
"VALUE":"",
"ACCESS":2,
"CLIPMODE":"none",
"DESCRIPTION":"Save the current settings as a preset with the given name"
},
"load":{
"FULL_PATH":"/rnbo/inst/0/presets/load",
"TYPE":"s",
"VALUE":"",
"ACCESS":2,
"CLIPMODE":"none",
"DESCRIPTION":"Load a preset with the given name"
},
"initial":{
"FULL_PATH":"/rnbo/inst/0/presets/initial",
"TYPE":"s",
"VALUE":"",
"ACCESS":3,
"CLIPMODE":"none",
"DESCRIPTION":"Indicate a preset, by name, that should be loaded every time this patch is reloaded. Set to an empty string to load the loaded preset instead"
}
}
},
"midi":{
"FULL_PATH":"/rnbo/inst/0/midi",
"CONTENTS":{
"in":{
"FULL_PATH":"/rnbo/inst/0/midi/in",
"TYPE":"",
"VALUE":[
],
"ACCESS":2,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list",
"DESCRIPTION":"midi events in to your RNBO patch"
},
"out":{
"FULL_PATH":"/rnbo/inst/0/midi/out",
"TYPE":"",
"VALUE":[
],
"ACCESS":1,
"CLIPMODE":"none",
"EXTENDED_TYPE":"list",
"DESCRIPTION":"midi events out of your RNBO patch"
}
}
}
}
}
}
}
}
}
}
}Those FULL_PATH entires correspond to OSC addresses, and the TYPE
identifies the OSC type that those parameters expect, if any.
If the ACCESS value is 2 (set only) or 3 (get set) then you can send OSC
messages to that address to alter parameters.
Most of what you'll want to interact with will be below the /rnbo/inst/0
path, this is the path that identifies the running codegen export.
See the OSCQueryProposal for more details on OSCQuery.
const OSC = require("osc");
{
let ws = new WebSocket(YOUR_RUNNER_URL);
ws.on('message', (d) => {
//must be a buffer because there are other non OSC websocket messages as well
if (Buffer.isBuffer(d)) {
try {
const msg = OSC.readPacket(d, {metadata: true});
//process
} catch (e) {
}
}
});
ws.on('open', () => {
//send OSC
const array = OSC.writePacket({
address: "/rnbo/inst/0/params/foo",
args: [
{
type: "f",
value: 1.0
}
]
},
{ metadata: true });
ws.send(array);
});
}Here we use oscsend, which is available in homebrew, to send a normalized
parameter update to c74rpi.local.
oscsend osc.udp://c74rpi.local:1234 /rnbo/inst/0/params/foo/normalized f 0.2If foo is a valid parameter in your loaded patch, and you send that, then
load http://c74rpi.local:5678/rnbo/inst/0/params/ in a webbrowser, you should
see that both foo and foo/normalized have been updated.
Uses a modified jsonRPC for comand communication.
modifications:
idis a uuid.- method calls may have multiple responces indicating progress.
If the runner is running on the same machine as you want to listen on, you can use localhost for the ip.
oscsend osc.udp://localhost:1234 /rnbo/cmd s '{"method": "listener_add", "id": "foo", "params": {"ip": "localhost", "port": 9999}}'
dns-sd can show you available services:
dns-sd -B _oscjson._tcp