OSC Dictionary

The Open Sound Control protocol, or OSC, is a flexible language designed for communication between media applications and devices. Go Button has an extensive API (application program interface) for OSC which allows you to control Go Button from any device or software which can broadcast OSC messages. What follows here is a complete dictionary of Go Button’s OSC implementation.



Transport Layer

The Go Button OSC API can be used over both UDP and TCP transport layers.

When talking to Go Button via UDP, each OSC message corresponds to one UDP datagram. When talking to Go Button via TCP, messages are framed using the double END SLIP protocol (RFC 1055) as required by the OSC 1.1 specification.

The OSC API behaves almost identically when using both UDP and TCP. Exceptions are noted below, such as cases where a reply may be larger than the maximum size of a UDP datagram.

TCP/UDP Port Numbers

Go Button listens for incoming OSC messages and sends replies on the ports specified in the Sidebar > OSC Control Settings > Network section. In Go Button 3.2.0 and later, the default listening port for TCP and UDP is 53100. Replies to OSC via UDP are sent by default on port 53101.

Go Button also listens for plain text on UDP port 53535, and attempts to interpret it as OSC. For example, sending the string “/cue/1/start” to Go Button on UDP port 53535 will have the same result as sending the actual OSC command /cue/1/start to the current TCP port (e.g. 53100).

  • Note that Go Button 3.1.5 and earlier used hardcoded port values that were different from the new defaults. When updating to Go Button 3.2.x, those previous default port numbers (53000 and 53001) are migrated to OSC Control Settings to avoid a breaking change with any controllers that still expect those values. You can change the settings to use the new default ports 53100 and 53101 if desired.

To view reply messages in the QLab Workspace Status > Logs window, set the Go Button UDP Reply Port to 53000.

For convenience, the Sidebar > OSC Control Settings > Network also lists the IP address(es) for your current device. On iOS devices, the primary network interface is typically the Wi-Fi connection, which is reported to the system as “en1”. Newer versions of macOS can also set up a local TCP connection with an iOS device over a USB-to-Lightning cable. When that or any other connection is active, the IP addresses of those networks are also listed. You can send OSC messages to Go Button using any of these IP addresses.

Reply Format

All replies from Go Button take the form:

/reply/{/invoked/osc/method} json_string

The reply is sent to the IP address from which the original message was received.

The address of the reply starts with /reply/ and ends with the address of the invoked method.

json_string takes the form:

{
    "show_id" : string,
    "address": "/invoked/osc/method",
    "status": string,
    "data": value
}

show_id is optional, and only specified if the reply is specifically from the given show.

status is either ok or error.

data is the JSON-encoded result of invoking the method at address.



Update Format

When a client has requested updates from Go Button, it will receive a push notification when the client needs to update state for a cue, hit, or show. The client may receive the following messages at any time:

/update/show/{id}

This message is sent if you need to reload the cue lists for the show.


/update/show/{id}/cue_id/{cue_id}

This message is sent if you need to reload the state for the given cue or hit. If the cue is a group cue or cue list, you should also reload the children of the cue. (Note that despite using the term cue_id, this update message is sent for both cues and hits.)


/update/show/{id}/playbackPosition {cue_id}

This message is sent when the playback position changes to {cue_id}. If there is no current playback position, there will be no {cue_id} argument.


/update/show/{id}/volume {decibels}

/update/show/{id}/volumePercent {percent}

Both of these messages are sent initially when a show first opens and subsequently any time the Master Volume level of a show changes. The valid range for decibels is -96.0 to 0.0, and the valid range for percent is 0.0 to 1.0.


/update/show/{id}/disconnect

This message is sent if you need to disconnect from the given show (because it is closing).



Application Methods

Go Button will respond to the following general commands:

/connect {passcode_string}

Connect to Go Button with an optional passcode string. If the OSC Control Settings has a passcode set, you MUST supply this command before any other commands will be accepted. If the OSC Control Settings does not have a passcode, the /connect method is optional.

Returns ok if there is no passcode, or the passcode matches.

Returns badpass if the passcode does not match.


/disconnect

Disconnect from Go Button. You should invoke this method when you will no longer be sending messages to Go Button.

If you are communicating to Go Button via UDP, Go Button will automatically disconnect your client if it has not heard any messages from it in the last 61 seconds. Any message (e.g. /thump) will serve to keep the client connected. If you are disconnected and OSC Control Settings has a passcode set, you will need to reconnect with that passcode before further commands will be accepted.

If you are communicating with Go Button via TCP, Go Button will not automatically disconnect your client. The client will remain connected until the client sends the /disconnect message or the TCP connection itself is disconnected.


/version

Returns Go Button’s current application version number.


/alwaysReply {number}

By default, Go Button will only send a reply if the invoked method generates a reply to send.

However, if alwaysReply is set to any non-zero number, Go Button will send a reply for every OSC message it receives. Messages that would not normally generate a reply will generate one with a JSON string argument that contains:

{
    "show_id" : string,
    "address": "/invoked/osc/method",
    "status": string
}

The status string will be either ok or error.

Note that the data field does not exist in this reply.


/shows

Returns an array of available shows. Each array contains a dictionary of uniqueID and displayName values for each show.


/thump

A simple heartbeat method to verify Go Button is responding to OSC messages. Returns the data thump. (Thump-thump. Thump-thump.)


/updates {number}

number is interpreted as a boolean; 0 equals false, any other number equals true. If true, your client wants push notifications of changes. If false, your client no longer wants push notifications of changes.



Show Methods

These messages can be sent to a show that’s currently open in Go Button. The commands can optionally include the prefix /show/{id} or /show/{displayName} but, since only one show can be open at a time, using the prefix is a matter of semantics and is not necessary.


/show/{id}/open

Opens a Go Button show. This method, obviously, requires the /show/{id} or /show/{displayName} prefix.


/close

Closes the currently open show.


/go


/stop

/hardStop

At present, /stop and /hardstop are synonymous. Both stop all cues and hits in a show immediately.


/pause


/resume


/reset


/panic

Panic fades out and stops all cues and hits over the Panic duration set in the show Settings.


/panicInTime {time}

time is interpreted as a number of seconds over which to execute a Panic, overriding the Panic duration set in the show Settings.


/oops

Stops and re-selects the most recently played cue. This command can be sent multiple times to “undo” the playback of currently playing cues in reverse order.


/playhead/{next|previous|cue_number}

/playbackPosition/{next|previous|cue_number}

playhead and playbackPosition are synonymous. In Go Button, this is also referred to as the selected cue.


/cueLists

/runningCues

/runningOrPausedCues

All return an array of cue dictionaries:

[
    {
        "uniqueID": string,
        "number": string
        "name": string
        "listName": string
        "type": string
        "colorName": string
        "armed": number
    }
]

If the cue is a group, the dictionary will include an array of cue dictionaries for all children in the group:

[
    {
        "uniqueID": string,
        "number": string
        "name": string
        "listName": string
        "type": string
        "colorName": string
        "armed": number
        "cues": [ { }, { }, { } ]
    }
]

colorName may be: none, red, orange, green, blue, or purple.

Note: Methods that reply with an array of cue dictionaries may generate large OSC messages. These messages can easily grow larger than the maximum size supported by UDP datagrams. If you need to access these methods you should communicate to Go Button over a TCP connection rather than a UDP connection.


/toggleFullScreen

/fullScreen {number}

When Go Button is running on iPad, enter or exit full screen mode. When Go Button is running on iPhone or iPod touch, this command has no effect.

number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided for /fullScreen, return whether or not full screen mode is currently active.


/toggleMasterVolumeVisible

/masterVolumeVisible {number}

Reveals or hides the visibility of the master volume fader.

number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided for /masterVolumeVisible, return the current visibility of the master volume fader.


/volume {decibels}

The master volume of a show represented in decibels. The valid range for decibels is -96.0 to 0.0.


/volumePercent {percent}

The master volume of a show represented on a linear scale as a percentage. The valid range for percent is 0.0 to 1.0.


/volumeStepUp

/volumeStepDown

Fades the master volume level of a show up or down by 6 dB. Equivalent to the remote control actions “Step Up Master Volume” and “Step Down Master Volume”.


/toggleDim

/dim {number} {time}

Engages or releases the “DIM” setting in the master volume fader. When engaged, the master volume is faded down by the value set in Show Settings > Master Volume Dim (dB). Releasing fades the master volume back up to its undimmed level.

number is interpreted as a boolean; 0 equals false, any other number equals true.

time is an optional whole or decimal number. If provided, the master volume will be faded from its current value over that many seconds. If time is omitted, the Show Settings > Master Volume Dim Duration is used. If no arguments are provided for /dim, return whether or not DIM is currently engaged.


/toggleMute

/mute {number}

Mutes or unmutes the master volume of a show.

number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided for /mute, return whether or not the master volume is currently muted.


/timer/toggleRunning

/timer/start

/timer/stop


/timer {number}

If given a number, sets the Elapsed Show Timer to that time in seconds. If no number is given, this command returns the current value of the Elapsed Show Timer in seconds.


/timer/reset

Resets the Elapsed Show Timer the value set in Show Settings > Elapsed Timer Start Time. The running state of the timer is not affected by a reset.



Cue Methods

Cue Methods are addressed to individual cues with the structure /cue/{number}/{method}. Alternately, you can substitute the structure /cue_id/{id}/{method}.

Actions:

/cue/{number}/start

If this cue is already playing, the cue will restart from the beginning.


/cue/{number}/togglePause


/cue/{number}/pause


/cue/{number}/resume


/cue/{number}/reset


/cue/{number}/load


/cue/{number}/loadAt {number}

If given a number, load the cue at that time in seconds. If no number is given, this command is equivalent to /load.


/cue/{number}/panic

Panic fades out and stops a cue over the Panic duration set in the Show Settings.


/cue/{number}/stop

/cue/{number}/hardStop

At present, /stop and /hardstop are synonymous. Both stop a cue immediately.


Read-Only Properties:

These methods will return information about the specified cue.

/cue/{number}/name


/cue/{number}/preWait


/cue/{number}/duration


/cue/{number}/uniqueID


/cue/{number}/isLoaded


/cue/{number}/isRunning


/cue/{number}/isPaused


/cue/{number}/isBroken


/cue/{number}/preWaitElapsed


/cue/{number}/actionElapsed


/cue/{number}/percentPreWaitElapsed


/cue/{number}/percentActionElapsed


/cue/{number}/goButtonText

Returns the string that will be displayed on the GO button when this cue becomes selected in the cue list. Use this method with the special /cue/playhead/* prefix to fetch the current GO button text.



Hit Methods

Hit Methods are addressed to individual hits with the structure /hit/{number}/{method}. Alternately, you can substitute the structure /hit_id/{id}/{method}.

Hits are numbered in their display order, starting from the top left of the hits panel and going left to right, then top to bottom.

Actions:

/hit/{number}/start

If this hit is already playing, the hit will restart from the beginning.


/hit/{number}/pause


/hit/{number}/resume


/hit/{number}/togglePause


/hit/{number}/reset


/hit/{number}/load


/hit/{number}/loadAt {number}

If given a number, load the hit at that time in seconds. If no number is given, this command is equivalent to /load.


/hit/{number}/panic

Panic fades out and stops a hit over the Panic duration set in the Show Settings.


/hit/{number}/stop

/hit/{number}/hardStop

At present, /stop and /hardstop are synonymous. Both stop a hit immediately.


Read-Only Properties:

These methods will return information about the specified hit.

/hit/{number}/name


/hit/{number}/preWait


/hit/{number}/duration


/hit/{number}/uniqueID


/hit/{number}/isLoaded


/hit/{number}/isRunning


/hit/{number}/isPaused


/hit/{number}/isBroken


/hit/{number}/preWaitElapsed


/hit/{number}/actionElapsed


/hit/{number}/percentPreWaitElapsed


/hit/{number}/percentActionElapsed

Still have a question?

Our support team is always happy to help.

Business Hours
9–5 PM (ET)
Current time at our headquarters — 09:59 AM