Stream Deck and Companion
A control token for panic, alerts, counters and sounds from a Stream Deck or Companion.
A control token lets a Stream Deck, Bitfocus Companion, or anything else that can send an HTTP request, run your overlay live: panic, skip or pause alerts, clear on-screen chat, bump a counter, add subathon time, play a sound, fire a test alert. It cannot open the editor, change the account, see tips, or do anything an admin can. Scenes stay separate links in OBS; a token doesn’t switch them.
Managers create and revoke tokens on Team. The secret is shown once. Layrs stores only a hash of it.
Create a token
- Open Team (you need to be a manager or the owner).
- Under Stream Deck and Companion, name the token (for example “Stream Deck”) and press Create token.
- Copy the secret. You won’t see it again. If you lose it, revoke it and create another.
- Copy the overlay id of the scene OBS is showing. It’s the last part of the editor address,
/app/edit/then the id, and it’s listed under the token too. - Revoke stops that token at once. Sign out everywhere does not revoke tokens.
What you can run
Each request is one live action, the same ones a moderator runs from the editor:
| Action | What it does |
|---|---|
panic | Hide everything on the overlay (on: true) or show it again |
alerts.skip | Skip the alert that’s playing |
alerts.pause | Pause or resume the alert queue |
alerts.replay | Play the latest event again (or a recent one by eventId) |
chat.clear | Clear on-screen chat |
counter | Add to a counter, or set it |
subathon | Start, pause, resume, reset, or add time |
sound / sound.stop | Play one of the channel’s sounds, or stop them |
test | A labelled test alert (it doesn’t change counters) |
media | Skip, pause or clear media requests |
session.reset | Clear session counters and the recent list |
Anything else is refused. A token never edits widgets, and it never receives chat or the overlay document.
The request
POST https://layrs.tv/api/control/<overlay id>
Headers: Authorization: Bearer <token>, Content-Type: application/json, and X-Layr: 1 (the same header the website sends; a form on another site can’t).
{ "action": { "a": "panic", "on": true } }Counters and the subathon also need the widget id: open the overlay the key targets, select the counter or subathon, and press the copy button at the top of its settings. A counter added to a scene is a copy with its own id, so copy it in that scene. A wrong id gets “That counter isn’t on this overlay”. A counter: { "action": { "a": "counter", "widgetId": "<id>", "delta": 1 } }. A subathon: { "action": { "a": "subathon", "widgetId": "<id>", "cmd": "add", "ms": 60000 } }. Answers are { "ok": true }, or an error. Too many presses in a row get “wait a moment”.
Put the token in the header only. Never in the address: addresses end up in logs.
A WebSocket, if you want one
wss://layrs.tv/ws?overlay=<overlay id>&control=1 with the same Authorization header. The first message is { "t": "control-hello", "overlayId": "…" } and nothing else about the overlay. Then send { "t": "action", "seq": 1, "action": { "a": "alerts.skip" } } and read action-result. The Stream Deck and Companion setups below use the HTTP request, which is enough for a button.
Elgato Stream Deck
Needs Stream Deck 7.1 or newer.
- Download the Layrs plugin and double-click it. Stream Deck installs it; the category Layrs appears.
- Drag an action onto a key. Set the Layrs URL (
https://layrs.tv), the token and the overlay id. The URL and token are shared by all your Layrs keys and stay out of profiles you export. Counters and the subathon also need the widget id. - Press the key. A check means Layrs accepted it; an alert means the token, an id or the action needs a look.
Bitfocus Companion
Needs Companion 4.0 or newer.
- Download the Layrs module. In Companion, open Modules, press Import module package and pick the file.
- Add a connection: Layrs. Set the Layrs URL (
https://layrs.tv), the token and the overlay id. - Add a button and pick an action: Panic, Skip alert, Pause alerts, Clear chat, Counter, Subathon, Sound, Test alert.
Keep the token like a password. Anyone who has it can press those buttons until you revoke it on Team.