OSC (Open Sound Control)

OSC is a client and server system that defines a message address pattern used to address elements in the receiving server.

The grandMA3 software supports OSC 1.1. For more information about how to format OSC packets, see https://ccrma.stanford.edu/groups/osc/spec-1_0.html.

Open Sound Control, or OSC, is a networking protocol used to allow devices of various types to control other devices of other types. OSC messages are human-readable (unlike, for example, MIDI Show Control, or MSC), and follow this general pattern:

"(/prefix)/[OSC Address],[OSC Type],[Value]"

prefix - this is optional, depending on your system setup. It can be used in a more complex OSC network to differentiate messages meant for one set of devices (e.g. lighting consoles) and not others (e.g. sound consoles).

OSC Address - this is the target you are controlling on the receiving device(s), for example /Fader201 would be the address to move the fader for executor 201 in grandMA3. Sometimes the address will be more complex, for example /Page1/Fader201 would be the address to move the fader for executor 201 on page 1 in grandMA3.

OSC Type - this is the type of value you're sending, for example:

i = integer

f = float

s = string

t = true

f = false

Value - this is the value you are actually sending for the target.

An example OSC command to set the fader for executor 201 to 100 might be:

• "/Page1/Fader201,i,100"
• or with a prefix to specify only, e.g. grandMA3 devices: "/gma3/Page1/Fader201,i,100"

For more information about the OSC address, OSC type, and OSC structure, see SendOSC keyword.

• To adjust the settings of OSC, tap OSC in the In & Out window.
  The OSC settings window opens.

  

The most important OSC setting is the correct network configuration.

Make sure that the IP address, the network protocol (UDP, TCP), and the port are set correctly.

When receiving OSC messages, Input will highlight its title bar. When sending OSC messages, the title bar of Output will be highlighted.

Each configuration line for OSC can be used for input and/or output.

These properties can be configured:

• Name: Sets the name for this configuration.
• Destination IP: Sets the IP address for sending OSC data. A specific IP address or a broadcast IP can be set.
• Mode: OSC packets can be sent via UDP or TCP.
• Port: Specifies the network port of the incoming and/or outgoing OSC packets.
• Prefix: A prefix can be set by the user if he needs to. A prefix can be used for example as a criterion for limiting the range of possible receivers, e.g. /lighting would only take packets with /lighting into account, and discard OSC packets with the /sound-prefix.
• Page: Specifies which OSC Address of incoming OSC messages is routed to pages.
• Fader: Specifies which OSC Address of incoming OSC messages is routed to faders.
• ExecutorKnob: Specifies which OSC Address of incoming OSC messages is routed to the mini encoders.
• Key: Specifies which OSC Address of incoming OSC messages is routed to keys.
• FaderRange: Specifies which OSC value range is used for the fader, e.g. FaderRange 255 sets OSC 0-255 to 100%.
• Receive: Specifies if OSC data (but no commands) shall be received.
• Send: Specifies if this OSC configuration sends OSC data (but no commands).
• Receive Command: Specifies if commands for the command line will be received via OSC. This setting is independent of the general receive setting.
• Send Command: Specifies if commands of the command line will be sent via OSC. This setting is independent of the general send setting.
• EchoInput: Specifies if the input data shall be displayed in the system monitor.
• EchoOutput: Specifies if the output data shall be displayed in the system monitor.

With the buttons ReceiveAll, ReceiveNone, SendAll, SendNone, Receive CommandAll, Receive CommandNone,Send CommandAll, and Send CommandNone all OSC configuration lines can be modified together for the properties Receive, Send, Receive Command and Send Command.

In addition to the example OSC strings mentioned above, the entirety of the grandMA3 command line can be accessed via OSC, using the "/cmd" OSC Address and the string 's' OSC Type. Note - this requires "Receive Command" to be set to Yes. For example:

• "/cmd,s,FaderMaster Page 1.201 At 100"
  • Bring fader 201 on page 1 to 100% (same as the examples above but using gMA3 command line syntax instead)
• "/cmd,s,Fixture 1 At 75"
  • Use gMA3 command line syntax to execute the command "Fixture 1 At 75" in the command line
• "/cmd,s,Go+ Exec 402"
  • Trigger whatever is assigned to exec 402
• "/cmd,s,Patch Fixture 1 3.42"
  • Patch fixture 1 to address 42 in universe 3

Examples for Using OSC

Common programs to trigger grandMA3:

TouchOSC

TouchOSC is a modular OSC and MIDI control surface for Windows, macOS, and Android by hexler.net.

It supports sending and receiving Open Sound Control and MIDI messages over Wi-Fi and CoreMIDI inter-app communication and compatible hardware.

Fader

This example will control the fader on Executor 230 of Page 1:

Notes:

• Assumes the OSCData line on the console has a prefix of "gma3" configured. If the prefix is empty, this would just be /Page1/Fader230.
• Assumes the "Page" and "Fader" cells in the OSCData line on the console are set to "Page" and "Fader" respectively (this is the default).

Executor button

This example will press the button for Executor 230 of Page 1:

Notes:

• Assumes the OSCData line on the console has a prefix of "gma3" configured. If the prefix is empty, this would just be /Page1/Key230.
• Assumes the "Page" and "Key" cells in the OSCData line on the console are set to "Page" and "Key" respectively (this is the default).
• The {Send on Press} and {Send on Release} settings (not pictured above) should both be enabled/checked.

QLab

QLab is sound, video, and lighting control for macOS by qlab.app.

QLab is fairly simple to use with OSC. These are the QLab network settings in our example:

• Name = something to identify this particular configuration
• Network = the network interface on your computer connected to the grandMA3 system
• Destination
  • IP address of the grandMA3 console
  • Port set in the OSCData line configuration in the console (8000 is default)

And then we have our cue setup in QLab:

• Destination = configuration as set in the "Network Cue Destination Patches" above
• Type = OSC message
• Enter the desired OSC message
  • OSCAddress - in this example we are sending a command syntax string directly, so the address is: /gma3/cmd
    • This assumes the OSCData line on the console has a prefix of "gma3" configured! If the prefix is empty, this would just be /cmd
    • Requires "Receive Command" to be enabled for that OSCData line on the console!
  • Argument - enter the command syntax in quotes, e.g. "Go Sequence 2" (advancing to the next cue in Sequence 2)

Open Stage Control

Open Stage Control is a free program you can use to build a simple OSC interface. When you first open it, you'll be prompted for some network configuration settings. Besides telling it which network interface to use on the computer, the only thing to fill in here is the port:

This needs to match the port you've set in the corresponding OSCData line in the console. Port 8000 is the default. Then you can start your Open Stage Control session.

Fader

This example will control the fader for Executor 230 on Page 1:

Notes:

• Assumes the OSCData line on the console has a prefix of "gma3" configured. If the prefix is empty, this would just be /Page1/Fader230.
• Assumes the "Page" and "Fader" cells on the OSCData line in the console are set to "Page" and "Fader" respectively (this is the default).
• All of the settings in the picture above are at their defaults except for:
  • Fader settings: Range: change the 'max' to 100 instead of 1
  • OSC settings: Address

 

Executor button

This example will press the button for Executor 229 on Page 1:

Notes:

• Assumes the OSCData line on the console has a prefix of "gma3" configured. If the prefix is empty, this would just be /Page1/Key229.
• Assumes the "Page" and "Key" cells in the OSCData line on the console are set to "Page" and "Key" respectively (this is the default).
• All of the settings in the picture above are at their defaults except for the address in the OSC settings
• Open Stage Control buttons default to functioning as 'toggle' - you may wish to change this to 'tap'

 

Command Line Syntax

Here we have a button that will execute command line syntax on the console, in this case triggering the Selected Sequence:

Notes:

• Assumes the OSCData line on the console has a prefix of "gma3" configured. If the prefix is empty, this would just be /cmd.
• Requires "Receive Command" to be enabled for that OSCData line on the console!
• All of the settings in the picture above are at their defaults except for:
  • button mode set to "momentary"
  • address
  • preArgs - this is where you enter the syntax string you wish to execute