OSC API

OSC API

Musical Tabletop Coding Framework (MTCF) uses Open Sound Control (OSC) over UDP as a way of communication between the graphical front-end and the client application (such as the official Pure Data Client). The protocol is composed by OSC/UPD messages sent both from the client to the front-end and the other way around. This means that both programs must implement an OSC server and a client.

The front-end listens to port 1235 and the client to port 1234. The front-end will record the address it receives the messages from and use it to comunicate to the client. This allows the client to be in another device and communicate through the network easily.

Format of the messages

The messages are always composed using this pattern:

/address [id] command [arguments]

In previous versions we used in some places the composed address form (/address/id/command). In later versions (v0.3a and onwards) we use the form above as it is easyer to parse than the previous in many partial implementations of OSC clients, particullarly in Pd-vanilla.

Global messages to the front-end

Messages referring to global properties of the front-end application are in the /mtcf space.

• /mtcf reset Tells the front-end app to remove all virtual elements and start again from scratch.
• /mtcf background {R} {G} {B} Defines the background color of the application.
• /mtcf fingercolor {R} {G} {B} Defines the color of the finger visual feedback.
• /mtcf textsize {size} Changes the scale of all text in the application. MTCF Only

Global messages to the client

Only one message can be considered global :

• /init Notify the client that the front-end is ready to process messages. The front-end send this only once after it has been just initiated.

Puck-related messages

MTCF allows the use of physical objects with fiducial markers (Pucks) on the surface of the device (if the device supports it). The address spaces are /objects and /object. Pucks can have some built-in widget controls: a slider and a rotatory parameter. The slider can be manipulated using the finger by dragging its handle, and the rotatory parameter by rotating the Puck. Both parameters range [0-1].

fid is the identifier of the fiducial marker.

To the front-end

• /objects {fid} fvalue {value} Set the position of the slider control.
• /objects {fid} config {rotatory} [{slider} [{delete}]] Configure the puck to have the slider and/or the rotatory parameter, as well as to delete the puck configuration. Values are (0,1).

To the client

• /object/on {fid} Reports one object entering the surface.
• /object/off {fid} Reports one object leaving the surface.
• /object {fid} {x} {y} {angle} {xspeed} {yspeed} {rspeed} {maccel} {raccel} Reports the object position, orientation, speed and acceleration.
• /object/angle_report {fid} {value} Reports the value of the rotatory control.
• /object/finger_report {fid} {value} Reports the value of the slider control.