Mrmr Interface Protocol

Mrmr's interface builder will support standard OSC over UDP, as well as a hybridized OSC over TCP, for instances when potential UDP packet-loss is unacceptable. The syntax is identical, enabling a Mrmr server to generate one set of messages and then decide over which protocol to distribute them to clients.

When sending any messages to a Mrmr client, remember to prepend the mrmr IB (interface builder) namespace to any packets that you want Mrmr to consider. By default, this namespace prefix is /mrmrIB. So, to send a pushbutton to mrmr via TCP, the full command might be: /mrmrIB pushbutton nil .1 4 4 1 1 1 1 test

In addition to commands for the creation of UI widgets, version .3 of the Mrmr interface protocol also supports some event management commands. These are used to push alert or informational messages to Mrmr clients outside of the Mrmr control context (e.g., a notice that the event will begin/end/change etc), and to prompt the user to accept or reject incoming interface or configuration changes.

If you are not on a Mac, then you will have to use your own TCP sockets to communicate with the Mrmr client. We recommend using the cross-platform tool NETCAT. Here's some basic netcat instructions.

For instance, the choice of whether to use UDP or TCP could be determined by parsing a Mrmr client's bonjour/mdns service to see which they support.

Available Interface Widgets:

Buttons & Switches pushbutton s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
i (style: 1=normal fixed size 80 px, 2=small fixed size 40 px, 10=variable size, 11=normal size but with a quicktime badge on the button)

example: pushbutton password .1 4 6 3 5 1 1 my_button 1
togglebutton s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
i (style - same as above)

example: togglebutton password .1 4 6 3 5 1 1 my_toggle
Sliders slider s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)

example: slider password .1 4 6 3 5 1 1 my_slider_label
Text textview s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
example: textview password .1 4 6 3 5 1 1 my_textview_text_uses_underscores_to_create_spaces_when_viewed_in_the_client
titleview s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
i (style, where 1 = 36 point text, 2 = 24 points, 3 = 18 points)

example: titleview password .1 4 6 3 5 1 1 my_title
a titleview is a centered string of text, usually used to provide a centered title to an interface bank
textinputview s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (placeholder text)
example: textinputview password .1 4 6 3 5 1 1 placeholder_text_for_textinput_field
*this widget provides a means of letting the client contribute text to a performance - it brings up the standard keyboard control and as such you should place this widget high enough in the interface to still be visible on devices that only have a virtual keyboard (e.g., iPhone)
webview s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (url)

example: webview password .1 4 6 3 5 1 1 http://google.com
Touch tactilezone s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
i (style: allows for different background colors, 1,2,3,4,5,6 are the supported style codes)

example: tactilezone password .1 4 6 3 5 1 1 my_tactilezone_label_text
tactile3D s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
i (style: allows for different background colors, 1,2,3,4,5,6 are the supported style codes)

example: tactile3D password .1 4 6 3 5 1 1 my_3d_controller_label
Accelerometers accelerometer s f (authentication string, minimum supported protocol version)
i i (grid size columns, grid size rows)
i i (grid position column, row)
i i (colspan, rowspan)
s (label)
i (style: 1=full XYZ, 2=rotation only, 3=up/down/left/right - mimics an oldskool digital joystick control)

example: accelerometer password .1 4 6 3 5 1 1 my_accelerometer_label 1

NOTES:

How to read the above chart: the first column is merely the category of the controller.  The second column is the actual string to use in your mrmr command (see examples below).  The third column contains descriptions of the parameters that are required to configure the widget.  's' means a string is expected; 'i' means an integer is expected; 'f' means a float is expected.

Using text: for all labels, use an underscore ( _ ) to indicate an empty space, e.g., to print the string "two words", use two_words.  If you do not wish to have a label, simply use a single underscore.

Here is an example of a complete Mrmr interface (to send this to an actual Mrmr client over the network, remember to prepend the namespace string to each packet, i.e., /mrmrIB):

pushbutton nil .1 4 4 1 1 1 1 test

pushbutton nil .1 4 4 1 4 1 1 test2

pushbutton nil .1 4 3 2 2 1 1 test3

pushbutton nil .1 4 3 3 2 1 1 test4

pushbutton nil .1 4 4 4 1 1 1 test5

pushbutton nil .1 4 4 4 4 1 1 test6

slider nil .1 4 8 1 3 4 1 test_slider

textview nil .1 4 8 1 6 4 1 This_is_an_example_of_text_in_mrmr.