Repository navigation
Stream Deck
English · Deutsch · Español · Languages
Rivulet implements the OBS WebSocket v5 protocol (JSON), the same wire protocol the Stream Deck ecosystem's OBS plugins speak. Point a plugin at Rivulet's port and password and your deck controls scenes, recording, streaming, and mute — no extra bridge software.
Which plugin? Install a Stream Deck plugin that speaks obs-websocket v5 (obs-websocket-js based, e.g. "OBS Tools" by BarRaider, or Bitfocus Companion / Touch Portal integrations). The official Elgato "OBS Studio" plugins are internal OBS plugins and do not connect over obs-websocket.
Open Settings → OBS WebSocket (Stream Deck):
- Tick Enable remote control.
- Note the port — default
4455, OBS-compatible. - Optionally set a password. Empty disables authentication.
The server binds to 127.0.0.1 only: it is reachable from this machine (and the Stream Deck software running on it), not from other machines. To control Rivulet from a phone or another computer instead, use the Remote companion — a LAN bind there requires a password and, for stream start/stop, an explicit permission.
In the plugin's OBS WebSocket settings (Stream Deck app → action → Connection):
| Field | Value |
|---|---|
| Host | 127.0.0.1 |
| Port |
4455 (the port you configured) |
| Password | the password you set in Rivulet, or empty if authentication is off |
| Protocol version | 5 (some plugins ask explicitly; choose 5, not 4) |
The plugin then performs the v5 handshake on its own: Hello → Identify (with the SHA-256 auth response when a password is set) → Identified, and subscribes to the events it needs. Scene dropdowns populate from GetSceneList; if a list stays empty, press Refresh in the action settings while Rivulet is running.
| Deck action | Request sent | Notes |
|---|---|---|
| Switch scene | SetCurrentProgramScene |
scene names come from GetSceneList
|
| Record start/stop |
StartRecord / StopRecord
|
or ToggleRecord as a single toggle button |
| Record pause/unpause |
PauseRecord / UnpauseRecord
|
button state follows RecordStateChanged
|
| Stream start/stop |
StartStream / StopStream
|
or ToggleStream as a single toggle button |
| Mute | ToggleInputMute |
needs the input name from GetInputList
|
| Replay Save | SaveReplayBuffer |
saves the buffered clip (optionally with an explicit path) |
| Replay On/Off | ToggleReplayBuffer |
enable/disable the replay buffer |
| Studio Mode | SetStudioModeEnabled |
independent preview/program scenes |
| Status icons |
GetRecordStatus / GetStreamStatus / GetReplayBufferStatus
|
read on connect and on every state event |
Buttons reflect reality: state changes you make in the Rivulet window (record button, mixer mute, scene switch) are broadcast as v5 events to every connected deck, so the icons stay current without touching the deck. Requests that cannot succeed answer honestly — e.g. starting a stream without an ingest configured returns status 501 with a comment instead of pretending success.
- Set a password on shared machines: without one, any local process can switch scenes or start/stop recording/streaming.
- The server never binds beyond loopback on its own; LAN access goes through the Remote companion's explicit gates.
- Remote stream start/stop from surfaces beyond loopback requires the explicit permission flag (Settings → Remote companion).
| Symptom | Likely cause |
|---|---|
| "Waiting for OBS" / connect loop | Server not enabled in Rivulet, or wrong port |
| Authentication error | Password differs between plugin and Rivulet (or password set in one but not the other) |
| Scene dropdown empty | Press Refresh in the action settings; check Rivulet has scenes |
| Record button does nothing, plugin shows a 204/UnknownRequest error | The plugin is using v4 request names or protocol version 4 — switch the plugin/connection to version 5 |
| Stream start fails with 501 | No ingest configured in Rivulet's Stream view |
| Mute does nothing | Input name mismatch — pick the input from GetInputList (Rivulet publishes its sources there) |
Rivulet's server speaks the v5 wire names exactly (StartRecord, ToggleStream, ToggleInputMute) and rejects the old v4 spellings, like real obs-websocket. A CI compatibility test drives the full connect-then-control sequence the plugins use. Details and raw payload examples: the obs-websocket documentation.
Last reviewed: 2026-09-22
Related: Streaming — set up live streaming · Troubleshooting and FAQ