StreamSync OBS Integration — Reference

🍼 ELI5

This lets a trigger control OBS directly — switch scenes, show/hide sources, mute the mic — without you touching OBS. It talks to OBS's own built-in remote-control feature (obs-websocket), which you just need to switch on once.

Requirements

• OBS Studio 28.0 or newer
• The built-in obs-websocket plugin enabled (bundled with OBS 28+)
• StreamSync running with the Triggers & Actions module active

---

Enabling the OBS WebSocket server

1. Open OBS Studio
2. Go to Tools → obs-websocket Settings
3. Check Enable WebSocket server
4. Note the Server Port (default: 4455)
5. Set a Server Password (recommended) or leave it blank to disable auth
6. Click OK

---

Connecting StreamSync to OBS

1. Open StreamSync → Triggers → Integrations tab → OBS Studio
2. Enter the host (localhost unless OBS is on another machine), port, and password
3. Click Save settings, then Connect
4. The status badge will change to connected when the handshake succeeds

The connection is held open for the duration of the session. StreamSync also tries to reconnect automatically the moment your stream goes live on any connected platform — a reliable signal that OBS (or whatever's encoding locally) is now running, even if it wasn't yet when StreamSync started. This is a single attempt per stream start, not a persistent retry loop: if OBS is still unreachable at that point (or the connection drops mid-stream), click Disconnect then Connect again.

---

What StreamSync can do via OBS

Scene control

• Switch Scene — set the current program scene (what viewers see on stream). Requires the exact scene name as it appears in OBS.

Source / scene-item control

• Show / Hide Source — show or hide any source item within a named scene. Requires both the scene name and the source name.

Filter control

• Enable / Disable Filter — toggle any filter applied to any source. Useful for turning a blur, chroma key, color correction, or noise-suppression filter on or off in response to events.

Audio control

• Mute / Unmute Input — mutes or unmutes any audio input by name (e.g. Mic/Aux, Desktop Audio).
• Set Input Volume — sets an input's volume as a percentage. 100 % = unity (0 dB). Values above 100 % (up to 200 %) apply a gain boost.

Text sources

• Set Text Source Content — writes new text into a Text (GDI+) or FreeType 2 source at runtime. The {user} variable is supported. Common use: a "Latest Follower" or "Latest Sub" overlay that updates automatically.

Media sources

• Control Media Source — sends a play, pause, stop, or restart command to a media source (video file, audio clip, GIF, etc.). Useful for triggering alert sounds or videos.

Stream & recording

• Start / Stop Stream — starts or stops the OBS stream output programmatically.
• Start / Stop / Pause / Resume Recording — controls the OBS recording.

Hotkeys

• Trigger OBS Hotkey — fires any named hotkey inside OBS. This is a catch-all for anything not covered by the actions above (e.g. replay buffer, transition overrides, plugin-specific commands).

  To find hotkey names: in OBS go to Profile → Export, open the exported .json file, and look inside "OBSBasic.Hotkeys". The keys are the hotkey names (e.g. "OBSBasic.StartRecording", "OBSBasic.ReplayBuffer").

---

Troubleshooting

Symptom	Likely cause	Fix
Connection times out	OBS WebSocket server not running	Enable it in Tools → obs-websocket Settings
Auth failed	Wrong password	Double-check password matches what's set in OBS
Scene switch fails	Scene name mismatch	Names are case-sensitive — copy them exactly from OBS
Source visibility fails	Source name mismatch or source not in scene	Check both the scene name and source name are exact
Action shows failed in queue	OBS disconnected at rule-fire time	Reconnect OBS before going live
Text source not updating	Wrong source type	Only works with Text (GDI+) and FreeType 2 sources, not browser sources