Loading...
Controls LivePlay audio playout software over its REST + WebSocket external-control API.
| Setting | Description |
|---|---|
| Server IP / hostname | The machine running the LivePlay server. |
| Port | The LivePlay REST/WebSocket port. Default 4480. |
| API token | Only needed when LivePlay requires a login. Paste an API token (starts with lpk1_) here. |
| Per-cue name variables | Off by default. Adds two name variables for every cue in the open project (see Variables). |
LivePlay can optionally require a login. When it does, have an administrator issue an API token from LivePlay's Users settings and paste it into API token. Use a token, not a user account: tokens don't expire, and revoking one only disconnects Companion. If the token is missing, wrong or revoked, the connection status says so.
When LivePlay's login is off, its API is open to anyone on the network — only run it that way on a trusted network.
Most item-level actions take the item's UUID from the LivePlay project. UUIDs are stable across playlist edits, so prefer them for fixed buttons.
Actions that take an index path use comma-separated, 0-based child indices descending into groups — 1,11 means the 2nd top-level item's 12th child, matching what the LivePlay client shows. Index paths shift when the playlist is edited; they suit "play position 1"-style workflows.
Cart slots are numbered 1–64 here, matching the LivePlay UI. The cart wall itself has 16 slots, and those get ready-made presets and variables.
The module mirrors LivePlay's own operator state, so a Stream Deck can drive a whole show without touching the screen:
Selection and Show Mode are held by the server, not by each client, so Companion, a touch tablet and the operator's laptop always agree.
Transport
Selection & Show Mode
Master & project
Mixer
Every bus picker lists the buses in the open show, plus Master and Preview entries that follow whichever bus holds that role. PFL and Preview mono are session-only and are not saved in the show.
Boolean (apply a style when true)
Values (for layered buttons and gauges; see Progress bars below)
LivePlay operators read cues by color first and name second, so these report the color authored in the project, with black or white text for whatever color that turns out to be. Point a button local variable at one and use $(local:…) in a gauge or text element.
0–255), color and legible text color as numbers, and its name. They take a UUID, an index path, or a variable such as $(local:index).playing while the cue sounds, paused while it is held, blank otherwise. Use it in an expression, e.g. a fill that turns green while the cue plays.The Up Next, selected and now-playing items have module variables for the same purpose (next_*, selected_*, current_*), and current_flash_rgb carries the end-of-cue flash: yellow / orange / red at 30 s / 10 s / 5 s remaining, blinking at 2 s / 1 s / 0.5 s to match the client. Paused cues do not flash.
| Variable | Description |
|---|---|
project_name, item_count | Open project info |
current_item, current_item_uuid, current_color | Most recently triggered on-air item |
current_state | Its transport state, in LivePlay's language |
elapsed, remaining, duration | Current item times (mm:ss, updated 4 Hz) |
warn_level | yellow / orange / red, blank when clear |
next_name, next_uuid, next_color, next_index | Effective Up Next (armed override or derived) |
next_source | override or auto |
selected_* | Name, UUID, color and index of the selected item |
show_mode, locale | Shared operator UI state |
master_gain, limiter | Master section state |
lufs_m, lufs_s | Master K-weighted momentary/short-term loudness |
playing_count, server_version | Misc status |
cart_<n>_name, cart_<n>_uuid, cart_<n>_color | Cart slots 1–16 |
<x>_progress | Playback progress, 0 (start) to 255 (end) |
<x>_color_rgb | Item color as a number, for gauge color stops |
<x>_text_rgb | Black or white, whichever reads over that color |
current_flash_rgb, current_flash_text_rgb | Current item color with the end-of-cue flash |
bus_<id>_name, _gain, _mute, _pfl | Every mixer bus in the open show |
preview_mono | Preview mono audition (On/Off) |
advance_in | Seconds until a waiting cue fires (blank if none) |
item_name_<uuid> | Name of a specific item, by UUID |
item_name_at_<index> | Name of a specific item, by index path |
For the gauge variables, <x> is cart_<n> (slots 1–16), current (Now Playing), next (Up Next) or selected. Progress is 0 whenever the item is not on air.
With Per-cue name variables switched on in the connection config, a pair of name variables is created for every item in the open project, so any button can show an item's name whether you address it by UUID or by position. They are off by default because a large show makes hundreds of them; the Trigger Cue presets and the Cue name value feedback do not need them. For example $(liveplay:item_name_at_0) is the name of the first top-level item, $(liveplay:item_name_at_1_11) the name at index path 1,11, and $(liveplay:item_name_e8eaa079-...) the name of that specific item wherever it moves. These update automatically when the playlist is edited. (Cart-only items get a UUID variable but no index variable.)
The Trigger Cue preset section lists one button per cue in the open project, grouped by top-level LivePlay group (2,35 appears under Group 2). Each is the by UUID button below with its uuid local variable already set: it fires its cue by UUID and shows the cue's live name over a progress bar (see below). The list refreshes as the playlist is edited; renaming a cue relabels buttons already on a page too.
The Manual group has two buttons you point at a cue yourself: by index path and by UUID. Each keeps its target in a button local variable (index or uuid) that both the press action and the button's cue values read. Set that one value (e.g. 2,35) and the button fires that cue, shows its name, color and progress. An index path that points at nothing shows the path itself on the button. An index button follows whatever currently sits at that position, so it retargets when the playlist is reordered.
Every preset that fires or shows a cue — the cart pads, GO, Up Next display, Now playing, Set As Next, Play selected, Selected item display and every Trigger Cue button — is a Companion 5 layered button drawn the same way: the whole button is a gauge in the cue's own color, dimmed while the cue waits, with a full-color bar sweeping left to right as it plays, under the name. GO shows the Up Next item, so its bar stays empty until that item is itself on air. Now playing also flashes yellow / orange / red near the end of the cue, blended into the bar's color.
To build one yourself, add a gauge element (horizontal, full size) with:
$(liveplay:cart_<n>_progress), Minimum 0, Maximum 2550, color set as an expression to $(liveplay:cart_<n>_color_rgb)60then a text element on top with color $(liveplay:cart_<n>_text_rgb). Swap cart_<n> for current, next or selected, or use the Cue / Cart slot value feedbacks through local variables for any other cue or slot. Use the _color_rgb variables for gauges, not _color: gauge colors must be numbers, and Companion 5.0.0 draws a #RRGGBB text value as black.
A cue that is a group shows no progress: LivePlay reports playback per audio cue, not per group.
Preset button labels are written in whatever language LivePlay is currently displaying. The strings come from LivePlay's own translation files, so a Companion button and the on-screen control it mirrors are worded identically. Changing the language in LivePlay re-publishes the presets in the new language.
GO, PANIC and LIMITER stay in English deliberately — they are the terms operators look for, and they fit a button in a way the translated phrases do not.
Buttons you have already placed on a page keep the text you gave them; only the presets in the sidebar are relabelled. Re-drag a preset to pick up the new wording.
To regenerate the label table after LivePlay adds a locale:
python tools/gen-locale.py <path-to>/liveplay/client/locales