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, 100= normal size, transparent, 101= normal size, transparent, touch produces highlight, 200= small size, transparent, 201= small size, transparent, touch produces highlight, 1000= variable size, transparent, 1001= variable size, transparent, touch produces highlight) 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 |
|
| 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 and 10 are the supported style codes, with 10 being transparent) 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.
