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. OSC messages are sorted more or less alphabetically in each section, which is to say they’re alphabetically sorted, but messages which are closely related to each other are sometimes grouped together even if they are not alphabetically adjacent if that makes it easier to understand their relationship.

Getting Started

The Go Button OSC API can be used over both UDP and TCP transport layers. Go Button listens for incoming OSC messages and sends replies on the ports specified in the Sidebar > OSC Control Settings > Network section. The default listening port for TCP and UDP is 53100.

When a client talks to Go Button via UDP, each OSC message corresponds to one UDP datagram. Replies to OSC messages received via UDP are sent on the port specified in the Sidebar > OSC Control Settings > Network > UDP Reply Port. The default UDP reply port is 53101.

When a client talks to Go Button via TCP, messages are framed using the double end SLIP protocol (RFC 1055) as required by the OSC 1.1 specification.

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 as text to Go Button on UDP port 53535 will have the same result as sending an actual OSC message /cue/1/start to the current TCP/UDP Listening Port (e.g. 53100).

When sending message to Go Button from QLab, set the Go Button UDP Reply Port to 53000 to be able to view Go Button reply messages in the QLab Workspace Status > Logs window.

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.

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.

Legacy Note: Starting in v3.2.0, Go Button uses different default port numbers than earlier versions of Go Button 3. When updating from Go Button 3.1.5 and earlier, OSC Control Settings will keep the previous port numbers (53000 and 53001) to avoid a breaking change with any controllers that still expect those values. You can manually update the settings to the new default port numbers 53100 and 53101 if desired.

Two Ways To Use OSC With Go Button

OSC can be used in essentially two ways with Go Button: as a relatively simple “remote control” protocol, in the spirit of MIDI, or as a robust two-way protocol for tight integration with other systems.

Those readers interested in using OSC for simple remote control can skip ahead to OSC Booleans in Go Button. For those who are interested in using OSC to talk to Go Button and getting answers back, and then doing things with those answers, read on here.

Getting status updates from Go Button

When a client has requested status updates, that client will receive messages from Go Button whenever the client needs to update its knowledge of a cue, hit, or show.

Clients who have requested status updates might receive the following messages at any time:

• /update/show/{show_id} - the client needs to reload the cue lists for the show. This message is also sent whenever various other aspects of a show are updated.
• /update/show/{show_id}/cue_id/{cue_id} - the client needs to reload the state for the specified cue or hit. If the cue is a Group cue or cue list, the client should also reload the children of that cue. (Note that despite using the term cue_id, this update message is sent for both cues and hits.)
• /update/show/{show_id}/playbackPosition {cue_id} - the playback position has changed to cue_id. If there is no current playback position, there will be no cue_id argument.
• /update/show/{show_id}/volume {decibels} - both of these messages are sent initially when a show first opens and subsequently any time the Main 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/{show_id}/disconnect - the client must disconnect from the current show (e.g. because it is closing.)

To receive status updates from Go Button, send the following OSC command:

/updates 1

To stop receiving updates, send:

/updates 0

The /updates message can be used by clients with any level of access permission.

Replies from Go Button

Most, but not all, OSC messages sent to Go Button will result in a reply being sent back to the client who sent the message. This is separate from the idea of updates, as discussed above, which are sent proactively by Go Button. Replies are only sent in response to incoming OSC messages.

Messages which perform discrete actions in Go Button, like /go and /panic, do not generate replies by default, although you can request a reply for every message using the /alwaysReply command, discussed below.

Replies from Go Button take the form:

/reply/{/invoked/osc/message} json_string

json_string takes the form:

{
    "show_id" : string,
    "address": "/osc/message/that/was/sent",
    "status": string,
    "data": value
}

show_id is optional, and only present if the reply is specifically from the current show, rather than from Go Button as a whole.

status can be:

• ok - the OSC message was received and everything is good.
• error - the OSC message was malformed, invalid, or something else has gone wrong.

data is the JSON-encoded result of the OSC message that was sent.

Example

Sending a show the volumePercent message:

/show/34200B51-835A-4918-A137-B6511784B6CA/volumePercent

would cause Go Button to respond with:

/reply/show_id/34200B51-835A-4918-A137-B6511784B6CA/volumePercent {json_string}

where {json_string} would be a payload object with the show’s current volume as a percent for the "data" key.

OSC Booleans in Go Button

Many OSC messages in Go Button require an argument which sets a value to either true or false. Go Button allows several different data types for these arguments. All of the following are valid:

• Booleans. OSC 1.1 has a boolean data type, allowing you to send True or False as an argument. (Requires Go Button 3.3.0 and later.)
• Integers or Floats. If Go Button receives any number as an argument where it’s expecting a true or false value, 0 will be interpreted as false, and any other number (including, for example, 0.5) will be interpreted as true.
• Strings. If Go Button receives a text string as an argument where it’s expecting a true or false value, any string which begins with N, n, F, f, or the digit 0 will be interpreted as false. Any string which begins with Y, y, T, t, or any digit 1 through 9 will be be interpreted as true.

Examples

The following messages will all show the Main Volume fader:

• /mainVolumeVisible Yes
• /mainVolumeVisible yippee
• /mainVolumeVisible "you betcha"
• /mainVolumeVisible 1
• /mainVolumeVisible 1.0
• /mainVolumeVisible true

The following messages will all hide the Main Volume fader:

• /mainVolumeVisible No
• /mainVolumeVisible never
• /mainVolumeVisible "forget it"
• /mainVolumeVisible 0
• /mainVolumeVisible 00
• /mainVolumeVisible false

How To Read This Dictionary

Every OSC message that Go Button will respond to is listed in this dictionary. Each definition starts with a horizontal separator followed by the OSC message itself written out like so:

/cue/{cue_number}/preWait {number}

The parts that are enclosed in {braces} are the parts which you have to fill in to make the message work, and the dictionary tries to give you clues about what sort of thing you’ll need to fill it with. For example, in the message above, you need to replace {cue_number} with the cue number of the cue you want to talk to, and you need to replace {number} with a number of some kind. This OSC message uses the number you fill in to set the pre-wait of the cue that you specify.

Next comes a table which looks like this:

The first column in this table describes the type of message.

• Read means that a client can send the message without arguments and get data back from Go Button. For example, /cue/10/preWait will return the pre-wait of cue 10.
• Read/write means that a client can read data from Go Button, and can also send data to Go Button to make changes. For example, /cue/10/preWait 5 will set the pre-wait of cue 10 to 5 seconds.
• Read only means that this message can only be used to read; there is no “write” form.
• means that a client can send this message. This is used only for messages which are “actions” such as /go and /panic, which neither read nor write data.
• means that a client cannot send this message (well, it can send it, but Go Button will ignore it.)

The second column is only present for OSC messages which are directed at cues and hits, and it shows whether or not the message can be used with Go Button’s increment/decrement syntax.

After the table comes a description of the behavior of the OSC message, including separate explanations for read and write usage if applicable.

Finally, some OSC messages come with examples showing how to use them. Readers are heartily encouraged to request that specific additional examples be added by emailing the Go Button support team.

Application Messages

The following OSC messages pertain to Go Button as a whole, not to a specific show. For security, a client must connect to Go Button with the OSC passcode before any application messages will be accepted.

There are two exceptions to this rule: /version and /shows will always be accepted, even without a passcode.

/alwaysReply {boolean}

By default, Go Button will only reply to an incoming OSC message if that message generates a reply to send. For example, /go does not generate a reply.

Read: If no argument is given, return true if alwaysReply is enabled for the sending client, and false if it is not.

Write: If boolean is true, send a reply for every OSC message received from the client. Messages that would not normally generate a reply will generate one with a JSON string argument that contains:

{
  "show_id" : {string},
  "address": "/osc/message/that/was/sent",
  "status": {"ok" or "error"}
}

If boolean is false, stop sending replies to messages that do not generate replies.

/connect {string}

Connect to Go Button with an optional passcode string. If the Sidebar > OSC Control Settings has a passcode set, you MUST supply this command before any other commands will be accepted. If OSC Control Settings does not have a passcode, the /connect message 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. Clients should send this message when they will no longer be sending messages to Go Button.

If you are communicating with 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, you will need to reconnect before further commands will be accepted. If you are using a connection with a passcode, the passcode needs to be sent again, just as though you were connecting for the first time.

If you are communicating with Go Button via TCP, Go Button will not automatically disconnect your client, because TCP is nice like that. Clients will remain connected until they send /disconnect or until the TCP connection itself is disconnected.

/forgetMeNot {boolean}

/udpKeepAlive {boolean}

Sending /forgetMeNot or /udpKeepAlive with a true argument will cause Go Button to remember the client and all its settings (such as /alwaysReply) until Go Button quits or until the client sends /forgetMeNot or /udpKeepAlive with a false argument. This allows a client to send a passcode, ask for specific replies, etc. only once at the beginning of a session, and not worry about being disconnected after 61 seconds of inactivity.

It is best practice to always send /forgetMeNot or /udpKeepAlive with a false argument when you’re done, to allow Go Button to clear its record of the now-inactive client.

/replyFormat {string}

Set the format of Go Button’s reply messages to suit your needs. format_string is a string containing your desired reply format. The string can optionally contain the following tokens that will be replaced when sending the reply:

• #show_id# - the show ID
• #address# - the OSC address of the reply
• #status# - ok / error
• #data# - the data of the reply

Go Button will do its best to create a reply OSC message using the format you specify.

Sending an empty string will reset Go Button’s reply format to its default form.

Example

Let’s say you set Go Button’s reply format with the following message:

/replyFormat #data#

Then, if you sent /hit/1/colorName, you would get the reply:

/green

The #data# token resolves to green, assuming the color of hit 1 is in fact green.

/shows

Return an array of dictionaries for each available show. Each dictionary looks like this:

[
    {
        "uniqueID": string,
        "displayName": string,
        "port": number,
        "udpReplyPort": number,
        "version": string
    }
]

Go Button will always reply to this message, even with clients that have not yet sent a /connect message when an OSC passcode is set.

/thump

Returns a string thump. This is a simple “heartbeat” message (thump-thump, thump-thump) which you can use to verify a connection, keep a session active, etc.

/version

Return Go Button’s version number.

Go Button will always reply to this message, even with clients that have not yet sent a /connect message when an OSC passcode is set.

Show messages

Show OSC messages can be sent to the show that is currently open in Go Button. With the exception of the /open command, all other 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}/close

Closes the currently open show.

/show/{id}/cueLists

/show/{id}/runningCues

/show/{id}/runningOrPausedCues

Return an array of cue dictionaries listing the following information about all cues and hits that fall within the scope of the message:

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

The scope of each message is as follows:

• cueLists are the main cue list and the hits list.
• runningCues are all cues and hits which are currently running (and with an elapsing duration.)
• runningOrPausedCues are all cues and hits which are currently running, whether or not their duration is elapsing.

If any of the included cues are Group cues, 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": true|false
        "cues": [ {a cue dictionary}, {another dictionary}, {and another} ],
    }
]

Note: These messages may generate large replies, which can easily be larger than the maximum size supported by UDP datagrams. You should communicate with Go Button via a TCP connection if you wish to use these messages.

Starting with Go Button 3.3.0, versions of these commands are available which return smaller amounts of data.

The following messages are identical to the similar messages above, except they do not include any data for the children of Group cues:

/cueLists/shallow

/runningCues/shallow

/runningOrPausedCues/shallow

The following messages return only the cue IDs of the cues in question, and not all the other information about them. Cue IDs of children of Group cues are included.

/cueLists/uniqueIDs

/runningCues/uniqueIDs

/runningOrPausedCues/uniqueIDs

The following messages return only the cue IDs of the cues in question, and do not include children of Group cues.

/cueLists/uniqueIDs/shallow

/runningCues/uniqueIDs/shallow

/runningOrPausedCues/uniqueIDs/shallow

/show/{id}/dim {boolean}

/show/{id}/dim {boolean} {number}

Read: If no argument is provided, return true if the “DIM” setting of the main volume slider is currently engaged, and false if it is not.

Write: If boolean is true, engage the “DIM” setting of the main volume slider in the current show. If boolean is false, disengage DIM. number is an optional whole or decimal number. If provided, the main volume will be faded from its current value over that many seconds. If number is omitted, the show Settings > Main Volume Dim Duration is used.

/show/{id}/toggleDim

Engage or disengage the “DIM” setting of the main volume slider in the current show.

/show/{id}/fullScreen {boolean}

This command only applies when Go Button is running on iPad. When Go Button is running on iPhone or iPod touch, this command has no effect.

Read: If no argument is provided, return the current full screen mode status of the show.

Write: Set the full screen mode status of the current show. true will enter full screen mode; false will dismiss full screen mode.

/show/{id}/toggleFullScreen

Enter or dismiss full screen mode in the current show.

/show/{id}/go

Tell the cue list of the current show to GO. The cue list in the current show will GO on whatever cue is currently standing by.

/show/{id}/mainVolumeVisible {boolean}

Read: If no argument is provided, return the current visibility of the main volume slider in the current show.

Write: Set the visibility of the main volume slider. true will show the fader; false will hide the slider.

/show/{id}/toggleMainVolumeVisible

Reveal or hide the main volume slider in the current show.

/show/{id}/mute {boolean}

Read: If no argument is provided, return true if main volume is currently muted in the current show, or false if it is not muted.

Write: Set whether the main volume in the current show is muted. true will mute the volume; false will unmute.

/show/{id}/toggleMute

Mute or unmute the main volume in the current show.

/show/{id}/oops

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

/show/{id}/open

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

/show/{id}/panic

Tell the show to panic. A panic is a brief gradual fade out leading into a hard stop. Sending a second instruction to panic during that gradual fade out will cause an immediate hard stop. Panic fades out and stops all cues and hits over the duration set in the show Settings > Panic Duration.

/show/{id}/panicInTime {number}

Panic over the specified number of seconds, rather than over the panic time defined in the show Settings. {number} can be any number 0 or greater, decimals allowed.

/show/{id}/pause

Pause all currently running cues and hits in the show.

/show/{id}/playhead/{cue_number}

/show/{id}/playbackPosition/{cue_number}

Set the selected cue of the cue list (also called the playhead or the playback position) to the given cue.

/show/{id}/playhead/next

/show/{id}/playbackPosition/next

Move the selected cue to the next cue.

/show/{id}/playhead/previous

/show/{id}/playbackPosition/previous

Move the selected cue to the previous cue.

/show/{id}/reset

Reset the show. Resetting stops all cues and hits, returns the playhead to the top of the cue list, and stops & resets the elapsed show timer.

/show/{id}/resume

Un-pause a paused show and all paused cues & hits in the show.

/show/{id}/stop

/show/{id}/hardStop

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

/show/{id}/timer {number}

Read: If no argument is given, return the elapsed time of the Elapsed Show Timer in seconds.

Write: If number is given, set the elapsed time of the Elapsed Show Timer in seconds.

Removed in Go Button 3.3.0. Use /timer/elapsed {number} instead.

/show/{id}/timer/duration {number}

Read: If no argument is given, return the current duration (“Starting Time”) of the Elapsed Show Timer in seconds.

Write: If number is given and is a positive number, set the duration of the Elapsed Show Timer in seconds. Negative numbers are not accepted. A timer with a non-zero duration counts down from that number when started. A timer with a duration of 0 counts up from “00:00”.

Available in Go Button 3.3.0 and later.

/show/{id}/timer/elapsed {number}

Read: If no argument is given, return the current elapsed time of the Elapsed Show Timer in seconds.

Write: If number is given, set the elapsed time of the Elapsed Show Timer in seconds.

Available in Go Button 3.3.0 and later.

/show/{id}/timer/start

Start the Elapsed Show Timer.

/show/{id}/timer/stop

Stop the Elapsed Show Timer.

/show/{id}/timer/toggleRunning

Start or stop the Elapsed Show Timer.

/show/{id}/timer/reset

Reset the elapsed time of the Elapsed Show Timer to 0, and reset the current duration of the timer to the show Settings > Elapsed Timer Starting Time. The running state of the timer does not change.

/show/{id}/timer/reset/duration

Reset the current duration (“Starting Time”) of the Elapsed Show Timer to 0. The elapsed time and the running state of the timer do not change.

/show/{id}/timer/reset/elapsed

Reset the elapsed time of the Elapsed Show Timer to 0. The current duration (“Starting Time”) and the running state of the timer do not change.

/show/{id}/volume {number}

Read: If no argument is given, return the main volume of the current show in decibels.

Write: If number is given, set the main volume of the current show in decibels. The valid range is -96.0 to 0.0.

/show/{id}/volumePercent {number}

Read: If no argument is given, return the main volume of the current show on a linear scale as a percentage.

Write: If number is given, set the main volume of the current show as a percentage. The valid range is 0.0 to 1.0.

/show/{id}/volumeStepUp

/show/{id}/volumeStepDown

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

Cue and Hit messages

All of the messages below can be sent to cues and hits interchangeably, unless noted otherwise.

Addressing Cues

Cues can be addressed either by their cue number or their unique ID.

For all cue OSC messages, any instance of the address pattern /cue/{cue_number} can be replaced by the equivalent unique ID address pattern /cue_id/{id}.

Additionally, Go Button supports a few special addresses for cues:

• /cue/selected addresses the currently selected cue or cues.
• /cue/playhead addresses the cue that’s currently standing by at the playhead.
• /cue/playbackPosition is the same as /cue/playhead.

Addressing Hits

Hits can be addressed either by their number or their unique ID. 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.

For all hit OSC messages, any instance of the address pattern /hit/{hit_number} can be replaced by the equivalent unique ID address pattern /hit_id/{id}.

Wildcards

Finally, because Go Button supports OSC address patterns, you may use an asterisk * and a question mark as wildcards within {cue_number} or {id}.

Important: Spaces are not permitted inside OSC addresses, so cue numbers with spaces in them will not work properly with OSC. If you are using OSC to control your show, avoid using spaces in cue numbers.

Increment/Decrement Syntax

Simple numerical properties of cues and hits can be incremented or decremented with the following syntax:

• /cue/1/property/+ {delta} adds {delta} to the current value.
• /cue/1/property/- {delta} subtracts {delta} from the current value.

Example

• /cue/10/preWait/+ 1 would increase the preWait of cue 10 by one second.

Messages which support the increment/decrement syntax are noted with a under the +/-? heading.

/cue/{cue_number}/actionElapsed

Return the elapsed action (in seconds) of the specified cue.

/cue/{cue_number}/percentActionElapsed

Return the elapsed action (as a percentage of the total action) of the specified cue.

/cue/{cue_number}/colorName {string}

This command only applies to hits. When sent to a cue list cue, this command has no effect.

Read: If no argument is given, return the color of the specified cue.

Write: If string is given, set the color of the specified cue to string. Valid colors are none, red, orange, green, blue, and purple.

/cue/{cue_number}/defaultName

Return the default name of the specified cue.

/cue/{cue_number}/displayName

Return the display name of the specified cue.

/cue/{cue_number}/duration

Return the duration of the specified cue.

/cue/{number}/goButtonText

This command only applies to cue list cues. When sent to a hit, this command has no effect.

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

/cue/{cue_number}/isBroken

Return true if the specified cue is broken.

/cue/{cue_number}/isLoaded

Return true if the specified cue is loaded.

/cue/{cue_number}/isPaused

Return true if the specified cue is paused.

/cue/{cue_number}/isRunning

Return true if the specified cue is running.

/cue/{cue_number}/load

Load the specified cue.

/cue/{cue_number}/loadAt {number}

If argument number is given and is a positive number, load the specified cue to number seconds. If the cue has a pre-wait, that time is counted as part of the load time.

If no argument is given, this command is equivalent to load.

/cue/{cue_number}/name {string}

Read: If no argument is given, return the name of the specified cue.

Write: If string is given, set the name of the specified cue to string.

/cue/{cue_number}/number {string}

Read: If no argument is given, return the cue number of the specified cue.

Write: If string is given, set the cue number of the specified cue to string.

/cue/{cue_number}/panic

Panic the specified cue. Panicked cues fade out and stop over the panic duration specified in the show Settings.

/cue/{cue_number}/panicInTime {number}

Panic the specified cue, using number for the panic duration instead of the panic duration specified in show Settings.

/cue/{cue_number}/pause

Pause the specified cue. If the specified cue is not playing, this message has no effect.

/cue/{cue_number}/togglePause

If the specified cue is playing, pause it. If the specified cue is paused, resume it. If the specified cue is not playing and not paused, this message has no effect.

/cue/{cue_number}/preWait {number}

Read: If no argument is given, return the pre-wait of the specified cue.

Write: If number is given, set the pre-wait of the specified cue to number.

/cue/{cue_number}/preWaitElapsed

Return the elapsed pre-wait time (in seconds) of the specified cue.

/cue/{cue_number}/percentPreWaitElapsed

Return the elapsed pre-wait time (as a percentage of the total pre-wait time) of the specified cue.

/cue/{cue_number}/reset

Reset the specified cue. Resetting a cue or hit returns any temporary changes to be reverted.

/cue/{cue_number}/resume

Resume the specified cue. If the specified cue is not paused, this message has no effect.

/cue/{cue_number}/start

Start the specified cue. This does not move the playhead.

/cue/{number}/stop

/cue/{number}/hardStop

Stop the specified cue. If the specified cue is not playing, this message has no effect. At present, /stop and /hardstop are synonymous.

/cue/{cue_number}/uniqueID

Return the uniqueID of the specified cue.