Requests

This page is a reference for people who build their own control panel. Any tool that supports the obs-websocket protocol can control the playout with these nine commands, for example a Stream Deck, a tally system or your own script.

How to send them

Send requests over the connection described in the remote connection, as a custom vendor request.

Vendor name	ultimate-playout
Also registered as	obs-playout. This is the old name. Panels that use it continue to work

The program answers an accepted request with ok: true. When eight requests are already waiting, it answers the next request with ok: false and a reason.

Which playout

Every request accepts an optional playout parameter:

Value	Meaning
1–4	That playout, whichever playout is on screen
0, or omitted	The playout that is active at that moment

The nine requests

Request	Parameters	What it does
go	playout	Puts the armed cue on air
stop	playout	Stops the playout
arm_next	playout	Moves the green marker one step down
arm_prev	playout	Moves the green marker one step up
arm	number, playout	Arms the cue with that number, without playing it
goto	number, playout	Arms the cue and plays it
record	on, playout	Starts or stops the recording
stream	on, playout	Starts or stops the stream
status	—	Returns the state of the playouts. See below

number is the number as shown in the list, for example 3, 3.1 or 3.1.2.

Recording and streaming

The requests record and stream start and end a broadcast, and they work in the same way.

The parameter on is optional. Send on: true or on: false to set the state. If you omit the parameter, the request toggles the state. The reply only confirms the request, so use status to read the state afterwards.

Use toggling for a physical button, and use on in a script. The reason is that a script that toggles twice, because a message was lost, stops the recording that it should start.

status also lets you read the state without changing anything.

What status returns

count     how many playouts are switched on
active    which playout is being driven at that moment, 1..4 — what
          `playout: 0` resolves to
playouts  one entry per playout:
            slot          1..4
            name          the output name
            color         that playout's accent colour
            cues          [ { n: "3.1", t: "Announcement 1" }, … ]
            recording     true while that playout records
            streaming     true while it streams
            live          true while something is on screen
            live_number   number of the cue on screen, "" when nothing is
            live_title    its title
            armed_number  number of the cue that will go on the next GO
            armed_title   its title

This is everything a panel needs: the names for its labels, the colour for its buttons, the cue list for its selection lists, and the two markers for its feedback. The numbers in live_number and armed_number are the same n as in cues, so a button can compare them with its own cue.

The markers can be up to one second behind. The program updates them once a second, and not at the moment of the GO. A panel that requests the status every second therefore sees a change within one or two seconds. This is enough for a lamp on a button, but do not use it for anything that must be accurate to the frame.

Notes for developers

A request returns when it is accepted, and not when the cue is on air. The answer therefore does not confirm that the picture has changed. To confirm this, read status.

A go request and the GO hotkey do the same thing, and this also applies to the other pairs.

Numbers change. The number of a cue changes when the structure of the list changes, so a panel that stores numbers must read them again from status.