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.

Format of the values:

• Identifiers are integer.
• Color components are integer (0-255)
• Boolean values are integer (0,1)

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} Request reporting of this puck.
• /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.
• /distance {fid1} {fid2} Request reporting of the distance and angle between two pucks.
• /distance {fid1} {fid2} draw {value} (de-)Activate the drawing of a line between two pucks.
• /distance {fid1} {fid2} rm Deactivate reporting of the distance and angle between two pucks.

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.
• `/distance/on {fid1} {fid2} twe two pucks are on the surface and distance and angle can be reported.
• `/distance/off {fid1} {fid2} twe two pucks are on the surface and distance and angle cannot be reported.
• /distance {fid1} {fid2} {distance} {angle} Reports the distance and angle between two pucks.

Finger-related messages

When interacting with fingers the front-end generates messages. sid is the Session id of the cursor.

• /finger in {sid} {x} {y} [{pressure}] Report a new finger in the surface, its position and optionally its pressure (pressure in mMTCF Only).
• /finger out {sid} {x} {y} [{pressure}] Report a finger leaving the surface, its position and optionally its pressure (pressure in mMTCF Only).
• /finger move {sid} {x} {y} [{pressure}] Report a new finger in the surface, its position and optionally its pressure (pressure in mMTCF Only).

Graphical Objects

The front-end can draw graphical objects, defined by the client. Three types of graphical objects exist: Waves, Text and Polygons.

Waves are optimized graphical ojects to draw signals:

• /wave {id} p1 {x} {y} Set the first point where to draw the wave between.
• /wave {id} p2 {x} {y} Set the second point where to draw the wave between.
• /wave {id} wav {v0 v1 v2 ... v99} Update the data of the wave with values [0-1000]
• /wave {id} rm Remove the wave object.

Text and Polygons share some commands:

• /... {id} color {r} {g} {b} [{a}] Define color and transparency.
• /... {id} hidden {value} Define if the object is visible.
• /... {id} layer {value} Define layer (default = 100).
• /... {id} bring_top Bring top of the current layer.
• /... {id} rm Remove the graphical object.

Position and transformation The position and transformation of an object (Text or Polygon) is defined by 2 matrices:

• transform_matrix
• translate_matrix

And they combine together this way:

total_matrix = translate_matrix * transform_matrix;

Commands to modify the matrices

• /... {id} position {x} {y} {angle} Sets the translate_matrix to be a translate(x,y) and then a rotate(angle).
• /... {id} transform {command1} [{command2}] [...] Calculates transform_matrix from a series of commands:
• t {x} {y} Translate(x,y).
• r {angle} Rotate(angle).
• s {sx} {sy} Scale(sx,sy).
• S {s} Scale(s,s).
• /... {id} matrix {v00 v01 ... v33} Loads a 4x4 Matrix into transform_matrix and resets translate_matrix.

Text messages:

• /text {id} write {text} Set the caption of the Text element (please substitute spaces with %20).
• /text {id} clear Set the caption to an emty string.

Polygon messages Polygons are defined by vertices, and those vertices shoud be created around (0,0), being (0,0) the center of the figure. All transformations are applied from there.

• /figure {id} addrectangle {x} {y} {h} {w} [{r}] Creates a Rectangle in the position (x,y) with the dimensions (h,w) and optional round corner radius r.
• /figure {id} addcircle {x} {y} {r} Creates a circle in (x,y) with radius r.
• /figure {id} addvertex {x0} {y0} [{x1} {y1} ...] Add vertices.
• /figure {id} clearvertex Clear vertices.
• /figure {id} texture {path} Define a texture for the polygon. Path must be local to the front-end and absoluto or relative to data/ folder.
• /figure {id} drawpolygon {value} Wether or not to draw the Polygon.
• /figure {id} drawstroke {value} Wether or not to draw a stroke.
• /figure {id} strokecolor {r} {g} {b} Color of the stroke.
• /figure {id} strokewidth {value} Define the width (in pixels) of the stroke.
• /figure {id} touchable {value} Wether or not the Polygon can consume interaction events such as touch or pucks colliding with it.

To the client

Polygons report finger and puck interaction just as the whole interface, when occurring in its area:

• /figure/addfinger {id} {sid} Reports new finger on the Polygon.
• /figure/finger {id} {sid} {x} {y} Reports finger movement.
• /figure/rmfinger {id} {sid} {x} {y} Reports the finger leaving the Polygon.
• /figure/addobject {id} {fid} Reports new puck on the Polygon.
• /figure/object {id} {fid} {x} {y} Reports puck movement.
• /figure/rmobject {id} {fid} {x} {y} Reports the puck leaving the Polygon.

Every time a Polygon updates its total_matrix it sends it to the client:

• /figure/matrix {id} {v00 v01 ... v33} Reports the current total transformation of Polygon.

Sensor-related messages

Only mMTCF has sensor reporting.

To the front-end

• /sensors/enable {value} Enable or disable sensor reporting.

To the client

• /sensors rotationvector {yaw} {pitch} {roll}
• /sensors linearacceleration {ax} {ay} {az}
• /sensors gravity {gx} {gy} {gz}
• /sensors proximity {value}
• /sensors light {value}
• /sensors gyroscope {x} {y} {z}
• /sensors accelerometer {ax} {ay} {az}
• /sensors magneticfield {vx} {vy} {vz}
• /sensors tilt {x} {z} {y}