Working With OSC

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. Go Button listens for incoming OSC messages on port 53000.

When talking to Go Button via UDP, each OSC message corresponds to one UDP datagram. Replies to OSC via UDP are sent on port 53001.

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. Replies to OSC via TCP are sent on port 53000.

Go Button also listens for plain text on UDP port 53535, and attempts to interpret it as OSC. For example, sending the text /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 port 53000.

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.

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 push notifications when the client needs to update state for a Cue 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. If the cue is a group cue or cue list, you should also reload the children of the cue.

/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}/disconnect

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

Application Methods

/connect {passcode_string}

Connect to Go Button with an optional passcode string. If the OSC Settings has a passcode set, you MUST supply it before any other commands will be accepted. If the OSC 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 31 seconds. Any message (e.g. "thump") will serve to keep the client connected. If you are disconnected and OSC Settings has a password, you will need to reconnect with that password 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 version number.

/alwaysReply {boolean}

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.

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 Go Button Show.

/thump

A simple heartbeat method for this Show. Returns the data "thump". (Thump-thump. Thump-thump.)

/updates {number}

number is interpreted as a boolean. If yes, your client wants push notifications of Cue changes. If no, your client no longer wants push notifications of Cue changes.

/go

/stop

/hardStop

/panic

/panicInTime {time}

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

/pause

/resume

/reset

/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

When Go Button is running on iPad, this toggles in and out of full screen mode. When Go Button is running on iPhone or iPod touch, this command has no effect.

/fullScreen {true/false}

/toggleMasterVolumeVisible

/masterVolumeVisible {true/false}

/volume {decibel}

The master volume of a Show. The valid range for decibel is -96.0 to 0.0.

/dim {true/false}

/toggleDim

/mute {true/false}

/toggleMute

/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/start

/timer/stop

/timer/toggleRunning

/timer/reset

Resets the Elapsed Show Timer to "0:00". 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

/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.

/cue/{number}/pause

/cue/{number}/resume

/cue/{number}/togglePause

/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.

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

Hit methods

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.

/hit/{number}/start

/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.

/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.

← Working With Remote Controls Importing and Exporting Shows →