Ossia library reference for SuperCollider

Extension

libossia is a modern C++, cross-environment distributed object model for creative coding and interaction scoring. It allows to expose the parameters of your creative coding application over the network, and score them in time.

It handles various protocols such as OSC, MIDI, Minuit and OSCQuery. It offers bindings for many environments (PureData, Max/MSP, Python, Unity3D, QML, Faust, SuperCollider).

Basic Networking

Local OSCQuery device

A device represents a tree of parameters.

Local devices map to real parameters on the executable libossia is used with. For instance the frequency of a filter, etc.

Remote devices are mirror images of local devices on other applications : remote controls, mobile apps, etc. Every parameter in a local device will be synchronized with the remote devices connected to it.

Devices can be mapped to different protocols : Minuit, OSCQuery, etc. For the sake of simplicity, some bindings tie together device and protocol implementation.

We use OSCQuery as an example of protocol here. Once a device has been created, it is possible to check what's in it by going to http://localhost:5678.

For more information on the OSCQuery protocol, please refer to the proposal.~some_device = OSSIA_Device('supersoftware'); ~some_device.exposeOSCQueryServer(1234, 5678); // equivalent to ~some_device = OSSIA_Device.newOSCQueryServer('supersoftware', 1234, 5678);

Creating nodes

The nodes in the device are simply called "nodes" in the API. Nodes are identified with the OSC parameter syntax: /foo/bar.

Nodes per se don't carry any value; they have to be extended with parameters to be able to send and receive messages.~some_device = OSSIA_Device('supersoftware'); ~some_device.exposeOSCQueryServer(1234, 5678); ~node = OSSIA_Node(parent: ~some_device, name: "/foo/bar")

Creating parameters

Each node can only have a single parameter. Parameters can have the following types:

• Integer - 32-bit int.
• Float - 32-bit float.
• Boolean - true/false.
• Impulse or Signal - no value; just a message.
• Char - 'a', '0', '!' or $s, $_...
• String or Symbol - "a string" or 'symbol'
• Array or List- a generic list of values: [3, 'a', 2.68, ["foo", "bar"]]

As an optimisation, specific types for 2, 3, and 4 floats are provided; they are referred to as OSSIA_vec2f, OSSIA_vec3f, OSSIA_vec4f through the code.

Values can be written to a parameter, and fetched from it.

This example shows how to create a node, a parameter, and send a value to the parameter:

~param = OSSIA_Parameter(~some_device, 'int_test', Integer); ~sigparam = OSSIA_Parameter(~some_device, 'signal_test', Signal);

~param.value = 347; ~param.v = 347; // 1st shortcut ~param.sv(347); // 2nd shortcut

~param.value.postln; ~param.v.postln;

Parameter callbacks

Parameter callbacks will inform you every time a parameter receives a message. On environments that support this, this will enable listening on the remote end. That is, if a remote device has no callbacks, network messages won't be sent upon modification.~param.callback = { |value| format("value received: %", value).postln; }

Property binding

This show how, for environments that support it, ossia objects can integrate with existing property environments. In SuperCollider, parameters can easily be integrated with a SynthDef using the .snapshot, .ar and .kr methods.~freq = OSSIA_Parameter(~some_device, 'freq', Float, [440, 880], 440); // bind the frequency parameter to the synthdef, becoming an argument d = SynthDef('sinosc', { Out.ar(0, SinOsc.ar(~freq.kr, 0, 0.25)); }).add; // the snapshot convenience method returns an array with children parameter's name and current values x = Synth('sinosc', ~some_device.snapshot); // changing the value of the parameter will automatically update the synth argument's value ~freq.value = 660;

Device callbacks

The example below shows how to automatically wait for the device to be instantiated and exposed before creating your own tree of nodes & parameters, necessary if you want to build all in a single code region, because the protocols' instantiation is asynchronous :( ~some_device = OSSIA_Device.newOSCQueryServer('supersoftware', 1234, 5678, { ~foo = OSSIA_Node(~some_device, 'foo'); ~bar = OSSIA_Parameter(~foo, 'bar', Float) }) )

Remote OSCQuery Device

This shows how to connect to an existing OSCQuery device, and refresh the image that we have of it.// create a local device in any application, for this example, we'll do this directly in SuperCollider ( d = OSSIA_Device('my_device').exposeOSCQueryServer(1234, 5678, { p = OSSIA_Parameter(d, 'my_parameter', Float).value_(22.5); }); ) // create a remote mirror image of the device m = OSSIA_Device('my_remote'); m.exposeOSCQueryMirror("ws://localhost:5678"); // get the root node's direct children m.children; // posts [ my_parameter ] // create a mirror image of a parameter and query its value q = OSSIA_MirrorParameter(m, '/my_parameter'); q.value; // posts 22.5 // remotely modify the value of the original parameter q.value = 25.0; p.value; // posts 25

Node attributes

This part presents the attributes that can be set on nodes and parameters.

When using OSCQuery, all attribute changes will propagate across the network, except mute which is local. The "disabled" attribute has the same effect but does propagate.

Access mode

Access mode is a metadata that categorizes parameters between:

• GET: read-only
• SET: write-only
• BI: read-write

For instance:

• The value of a vu-meter should be GET
• A "play" button should be SET.
• The cutoff of a filter or a controllable color should be BI.

Domain (min/max)

Domains allow to set a range of accepted values for a given parameter. Only meaningful for nodes with parameters.

// Set domain either at parameter creation, or later on... ~param_1 = OSSIA_Parameter(~some_device, 'floatparam', Float, [-5.0, 5.0]); ~param_2 = OSSIA_Parameter(~some_device, 'intparam', Integer, nil); ~param_2.domain = [-5, 5];

~param = OSSIA_Parameter(~some_device, 'my_param', Integer, OSSIA.domain(values: [1, 3, 5]), 3);

Bounding mode

The bounding mode tells what happens when a value is outside of the min / max:

• FREE : no clipping; domain is only indicative.
• CLIP : clipped to the closest value in the range.
• LOW : only clips values lower than the min.
• HIGH : only clips values higher than the max.
• WRAP : wraps values around the range
• FOLD : folds back values into the range

The default is FREE.// same as domain: ~param = OSSIA_Parameter(~some_device, 'param', Float, [0, 2017], bounding_mode: 'clip'); ~param.bounding_mode = OSSIA_bounding_mode.high; ~param.bounding_mode = 'high'; // equivalent;

Repetition filter

When the repetition filter is enabled, if the same value is sent twice, the second time will be filtered.p = OSSIA_Parameter(~some_device, 'p', Float, [0, 1], repetition_filter: true); p.repetition_filter = false;

Units

Units give a semantic meaning to the value of a parameter.

Position

• cart2D
• cart3D
• spherical
• polar
• opengl
• cylindrical

Orientation

• quaternion:
• euler:
• axis:

Color

• argb: all between 0 - 1
• rgba:
• rgb:
• bgr:
• argb8: all between 0 - 255
• hsv:
• cmy8:
• todo: css? (rgb in 0, 1 and alpha in 0, 255)

Angle

• degree
• radian

Distance

• meter
• kilometer
• decimeter
• centimeter
• millimeter
• micrometer
• nanometer
• picometer
• inch
• foot
• mile

Time

• second
• bark
• bpm
• cent
• frequency
• mel
• midi_pitch
• millisecond
• playback_speed

Gain

• linear
• midigain
• decibel
• decibel_raw

Speed

• meter_per_second
• miles_per_hour
• kilometer_per_hour
• knot
• foot_per_second
• foot_per_hour

Extended type

Extended types, just like units, are here to give an indicative meaning to a parameter. They can also be used to enable some optimizations.

libossia proposes the following types:

• File path : used for when a string is a filesystem path, like /home/self/sound.wav or c:\document.txt
• Generic buffer : when a string should be interpreted as a a raw binary blob.
• Float array : when a parameter has a fixed number of floating point values, like vec2f.
• Float list : when a tuple consists exclusively of values of type float.
• Same for int list and string list.
• Dynamic array : when a tuple's size may change during execution.

Description

An optional textual description.n = OSSIA_Node(~some_device, 'pretty_node'); n.description = "a pretty node";

Tags

An optional array of tags for nodes.n = OSSIA_Node(~some_device, 'synth_1'); n.tags = ['physical_model', "awesome"];

Priority

Nodes with the highest priority should execute first.n = OSSIA_Node(~some_device, 'super_important_node'); n.priority = 10;

Refresh rate

An optional value that says how often a value should be updated. Currently does nothing.n = OSSIA_Node(~some_device, 'laggy_node'); n.refresh_rate = 500;

Step size

An optional value that says by which increment a value should change, for instance in a value editor.

Default value

A default value for a given node. Useful for resetting to a default state.p = OSSIA_Parameter(~some_device, 'foo', Float, [0, 1], default_value: 0.5);

Zombie

This is a read-only attribute: it informs of whether a node is in a zombie state. A zombie node is an node in a remote device, whose source has been removed. It is kept in the mirrors but marked as such.

Critical

This attribute informs the network protocol that the value has a particular importance and should if possible use a protocol not subject to message loss, eg TCP instead of UDP. This is useful for instance for "play" messages.p = OSSIA_Parameter(~some_device, 'foo', Signal, critical: true); p.critical = false;

Enabled/Disabled

This attribute will disable a node: it will stop sending messages to the network.n = OSSIA_Node(~some_device, 'some_node'); n.disabled = true;

Hidden

This attribute is to use for nodes that are not to be exposed to the network.n = OSSIA_Node(~some_device, 'hidden_node').hidden_(true);

Muted

This attribute will disable a node: it will stop sending messages to the network. Unlike the "enabled/disabled" attribute, it won't propagate to other computers.n = OSSIA_Node(~some_device, 'muted_node').muted_(true); n.muted = false;

Preset support

Loading and saving presets

Ossia provides preset handling. Files can be loaded and save to the disk to set the state of the device tree.

d = OSSIA_Device('my_device'); d.exposeOSCQueryServer(1234, 5678, { p = OSSIA_Parameter(d, 'param_1', Float, [0.0, 1.0], 0.5); q = OSSIA_Parameter(d, 'param_2', Integer); g = OSSIA_Parameter(d, 'param_3', String, nil, "hello"); }); d.save_preset(); // if no path is explicitly specified, this will open a dialog

p.value = 0.75; q.value = 127; g.value = "something else"; // reload the original state preset d.load_preset();