Requests

This page is reference material for building your own control panel. Anything that speaks the obs-websocket protocol can drive the playout with these nine commands — a Stream Deck, a tally system, a script of your own.

How they are sent

Requests go over the connection from the remote connection as a custom vendor request.


Vendor name	`ultimate-playout`
Also registered as	`obs-playout` — the old name; panels built with it keep working

A request that is accepted answers ok: true. When eight requests are already waiting to be carried out, the next one answers ok: false with a reason.

Which playout

Every request takes an optional playout:

Value	Meaning
`1`–`4`	That playout, whatever is on screen
`0`, or left out	The playout being driven at that moment

The nine requests

Request	Parameters	Does
`go`	`playout`	Takes the armed cue to air
`stop`	`playout`	Stops that playout
`arm_next`	`playout`	Moves the green marker one step down
`arm_prev`	`playout`	Moves it one step up
`arm`	`number`, `playout`	Arms the cue with that number, without playing it
`goto`	`number`, `playout`	Arms that cue and plays it
`record`	`on`, `playout`	Starts or stops recording
`stream`	`on`, `playout`	Starts or stops streaming
`status`	—	Reports the playouts, see below

number is the number as it appears in the list: 3, 3.1, 3.1.2.

Recording and streaming

record and stream are the two that begin and end a broadcast, and they work

the same way.

on is optional. Send on: true or on: false to set it; leave the parameter out and it toggles. The reply only confirms the request; read status for the state afterwards.

Toggling is what you want on a physical button, and setting is what you want in a script — a script that toggles twice because a message went missing has stopped the recording it meant to start.

To read the state without changing anything, use status.

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

That is everything a panel needs to build itself and light itself: the names for its labels, the colour for its buttons, the cue list for its drop-downs, and the two markers for its feedbacks. The numbers in live_number and

armed_number are the same n as in cues, so a button can compare them

with its own pick.

The markers lag by up to a second. The program refreshes them on its one-second tick, not on the GO itself. A panel polling every second sees a change within a second or two, which is what a lamp on a button needs; do not build anything on it that needs to be exact to the frame.

Notes for implementers

A request returns as soon as it is accepted, not when the cue is on air. Do not treat the answer as confirmation that the picture changed; read status if you need to know.

A go request and the GO hotkey do the same thing, as do the other pairs.

Numbers move. A cue’s number changes when the list changes shape. A panel that stores numbers should refresh them from status rather than assume last week’s are still right.