Open Sound Control (OSC)

MagicQ supports sending and receiving of Open Sound Control (OSC) messages.

OSC is a network protocol commonly used to send messages between audio visual programs, such as show control, sound effect and tablet applications. The protocol is free to implement which makes it increasingly popular; the specification can be found at http://opensoundcontrol.org/introduction-osc

OSC is supported on MagicQ consoles (except MQ40 and MQ40N) and PCs when fully unlocked (Unlocked Mode).

MagicQ can interact with OSC in the following ways:

Receive messages controlling the first 10 playbacks
Receive messages controlling buttons, faders and encoders in the Execute Window
Convert messages to ChamSys Remote Ethernet Protocol commands>> and <<midi,midi messages
Respond to message by using the Autom Window
Send messages using the macro field of cue stacks
Patch a special OSC head that sends messages when the value of the channel changes

An OSC message consists of two parts:

Address: a forward slash followed by the name of the message. Can be separated by slashes, similar to file paths. e.g. /myosc/method/address or /triggercue
Arguments: zero or more values, each with a specific type. Common types are:
- integer
- float: number with a decimal place
- string: line of text
- midi: MIDI message

Setup

To enable OSC on MagicQ you need to set the mode, and the transmit and/or receive port numbers in Setup, View Settings, Network.

Setting a port to 0 disables transmitting/receiving of OSC.

Optionally, a transmit IP address can be specified or set to 0.0.0.0 to broadcast to all computers on the lighting network. Note that if you wish to transmit on the control net then you must set a transmit IP address which is on the control net.

MagicQ automatically receives OSC on the main lighting network. MagicQ will receive OSC on the control net when the control net firewall is disabled.

Port number needs to be higher than 1024 on most systems. A good default is 9000 transmit and 8000 receive.

Receiving messages

MagicQ OSC addresses

The following table lists the built-in OSC messages that MagicQ will respond to. Only the first 10 playbacks and first 10 execute grids can be controlled with the built-in addresses.

You can use the AUTOM window to extend control to other parts of the MagicQ system.

Table 1. OSC Addresses
Address	Arguments	Behaviour
/pb/<playback>	float between 0.0 and 1.0 or int between 0 and 100	Set playback fader level
/pb/<playback>/go	(optional) non-zero value	Go on playback
/pb/<playback>/flash	0 sets to 0% non-zero sets to 100%	Set playback level to 100%
/pb/<playback>/pause	(optional) non-zero value	Pause playback
/pb/<playback>/release	(optional) non-zero value	Release playback
/pb/<playback>/<cue>	(optional) non-zero value	Jump to cue
/dbo	0 turns on non-zero turns off	Blackout
/swap	0 = add non-zero = swap	Set swap mode
/exec/<page>/<item> /exec/<item>	(optional) one of following no arguments = activate button/fader 0 = relase button/fader; lower encoder 1 = activate button/fader; raise encoder float between 0.0 and 1.0 = set fader level int between 0 and 100 = set fader level	Control button, fader or encoder in execute window
/10Scene/<item>/<zone> /10Scene/<item>	(optional) one of following no arguments = activate button 0 = release button 1 = activate button float between 0.0 and 1.0 = set fader level	Control 10Scene buttons
/rpc	string with commands	Send remote ethernet command
/rpc/<commands>	None	Send remote ethernet command
/midi	MIDI bytes	Send MIDI message - processed as if received from MagicQ or USB MIDI device (timecode messages are ignored)
/feedback/off	None	Turns feedback off
/feedback/pb /feedback/exec /feedback/pb+exec	None	Turns feedback on and transmits state of playbacks and executes (see TouchOSC)

If unspecified, as an argument either a float or an int is accepted.

<playback> := number between 1 and 10

<cue> := number with optional decimal, e.g. 2.5

<page> := number between 1 and 10 for execute grid, or name of execute grid

<item> := number of box in execute grid, or grid reference e.g. 4x3 for row 4 col 4, or name of execute item

The receipt of OSC messages from the keyboard by typing testosc followed by the command - for example to GO on Playback 1:

testosc /pb/1/go

This is supported on MagicQ consoles and on MagicQ PC sytems unlocked with a MagicQ Wing or Interface.

Automation

MagicQ can respond to user-defined OSC messages by adding rows to the MACRO - VIEW AUTOM window. After seting the type to OSC Message, set the OSC address in the P1 column.

Depending on the trigger type, an argument may be expected, e.g to set a fader level. This can either be an integer between 0 and 100 or float between 0.0 and 1.0.

Sending messages

Cue stack macros

OSC messages can be sent by using the macro field of a cues inside the Cue Stack window.

OSC addresses should be entered into the macro field, preceeded by the letter K and must be the last macro command in a macro.

The address can be followed by an optional comma separated list of arguments.

Specifying commas and backslashes in string arguments should be escaped with a backslash, e.g. \,, and \\.

Patching OSC heads

A generic 1-channel personality can be patched that will send OSC messages whenever the value of the channel changes. This personality can be found in the CHOOSE HEAD window under Generic - mqosc. You can choose between three modes depending on the type of argument you want sent in the OSC message.

The channel value can be set using encoder Y in the INTENSITY window.

You will need to change the name of the head to the address of the OSC message, followed by an optional comma separated list of arguments that will be added before the value being transmitted (see Cue stack macros above).

TouchOSC

TouchOSC is a free iOS and Android application that can be used to create custom layouts of buttons, faders and encoders, and attach these controls to OSC messages.

There is an example TouchOSC file and show file in the MagicQ show folder called magicqdemo.touchosc and MQTouchOSCDemo.shw. You can load the TouchOSC file onto the app and edit the layout with the editor tool provided at http://hexler.net/software/touchosc#downloads

In the demo, the Load vals button sends a /feedback/pb+exec message which transmits the current state of playbacks and execute controls to the TouchOSC app. This also enables automatic sending of any changes to playbacks and executes to keep the TouchOSC controls in sync with MagicQ.

The Load vals button can be used to reload the state of MagicQ if the app gets closed or after network loss.

Troubleshooting

Transmit or receive not working

Make sure transmit and receive ports are set opposite to the device you are communicating with.

If there are multiple networks cards on the PC, make sure the IP address in MagicQ setup is set to the IP address of the interface you want OSC to transmit on.

Make sure the OSC address starts with a forward slash.

Make sure the address does not contain any characters that are disallowed in the OSC specification.

If specifying arguments after the address in a cue stack macro or patched head, ensure the address is followed by a comma, and that there are no unusual characters. Backslashes in string arguments can also cause issues, only use a double backslash \\ or to escape a comma \,

Ensure MagicQ is unlocked.

Check transmit and receive port numbers are set to values larger than 1024.

Check for any firewalls (e.g. Windows firewall) that may stop messages from being received.

Messages getting lost

Be careful not to flood the network with large amounts of OSC traffic, particularly if using OSC heads.

Large amount of broadcast Art-Net universes may case delayed or lost OSC messages.

Notes

MagicQ only supports OSC over UDP. Receiving OSC bundles is supported, although MagicQ does not currently transmit bundles.

OSC patched head names are restricted to 15 characters.

In the Execute Window, select an item, type // and press ENTER to display the OSC address that is associated with the button. This is also the address that gets sent when feedback is enabled.