OBS Control with Social Stream Ninja

Control OBS directly from Event Flow—no Streamer.bot required. This guide covers setup, every OBS trigger and action, practical recipes, and the older dock/browser-source controls.

1. Connect Flow Actions to OBS

OBS WebSocket v5 is built into OBS 28 and newer. Social Stream Ninja uses it for full OBS control and media events.

  1. In OBS, open Tools → WebSocket Server Settings.
  2. Enable the WebSocket server. Keep the default port 4455; set a password if wanted.
  3. In Social Stream Ninja, open the Flow Actions section and set the OBS WebSocket URL and optional password.
  4. Copy the Flow Actions URL and keep it open. An OBS Browser Source is recommended for overlay/audio actions.
  5. Use the OBS WebSocket Tester to confirm the connection before building a flow.
Direct URL example
https://socialstream.ninja/actions.html?session=YOUR_SESSION&obsws=ws://127.0.0.1:4455

Add &obspw=YOUR_PASSWORD only when OBS requires authentication. Add &obsdebug=1 to show a small connection-status badge while diagnosing problems.
Keep the Flow Actions page running. It is the bridge that receives Event Flow actions and sends OBS WebSocket requests. If it is an OBS Browser Source, turn off Shutdown source when not visible when the source must keep controlling OBS while hidden.
Chat / stream event │ ▼ Social Stream Ninja Event Flow │ same session ID ▼ Flow Actions page (actions.html) │ OBS WebSocket v5 · ws://127.0.0.1:4455 ▼ OBS Studio

Two OBS connection modes

ModeWhat it supportsRequirement
OBS WebSocket v5Every trigger and action in this guide.OBS 28+, WebSocket server enabled, Flow Actions page open.
OBS Browser Source APIFallback for scene changes, start/stop streaming, start/stop recording, and saving replay buffer.Flow Actions loaded inside OBS with Advanced Access Level. Source, filter, text, volume, media, refresh, and media-ended features still require WebSocket.

2. Add OBS nodes to a flow

  1. Open the Event Flow Editor and create or edit a flow.
  2. Drag a trigger onto the canvas.
  3. Expand OBS Studio in the Actions list and drag in the OBS action you need.
  4. Connect the trigger to the action, configure the exact OBS scene/source names, save, and enable the flow.
OBS Studio action list in the Social Stream Ninja Event Flow Editor
The OBS Studio group contains scene, source, text, media, audio, filter, output, and replay-buffer controls.
OBS names must match exactly, including spaces and punctuation. Source actions target the OBS input name, not the scene-item label if it was renamed independently.

3. OBS triggers

These start a flow when OBS reports a matching event. They arrive as type: "obs"; OBS-specific details are under meta.

TriggerWhen it firesUseful data
OBS Stream StartedStreaming reaches the started state.meta.outputState, meta.outputActive
OBS Stream StoppedStreaming reaches the stopped state.meta.outputState, meta.outputActive
OBS Recording StartedRecording starts.meta.outputState
OBS Recording StoppedRecording stops.meta.outputState
OBS Scene ChangedThe active program scene changes.meta.sceneName
OBS Media Ended WebSocketA media input finishes playback. Optionally filter by exact Media Source Name.meta.inputName, meta.inputUuid
OBS Replay Buffer SavedOBS finishes saving a replay.meta.savedReplayPath

4. OBS actions

ActionConfiguration and behaviorConnection
Change SceneSwitches the active program scene by exact scene name.WebSocket or Browser Source API fallback
Toggle SourceShow, hide, or toggle a scene item. Scene and Group are optional targeting fields.WebSocket
Set Text SourceUpdates Text (GDI+) or Text (FreeType 2), with template placeholders.WebSocket
Control Media SourcePlay/resume, pause, restart, stop, next, or previous.WebSocket
Set Source VolumeSets an input from -100 to +26 dB.WebSocket
Refresh Browser SourceReloads a Browser Source without cache.WebSocket
Toggle FilterEnable, disable, or toggle a named source filter.WebSocket
Mute/Unmute AudioMute, unmute, or toggle an input.WebSocket
Start RecordingStarts OBS recording.WebSocket or Browser Source API fallback
Stop RecordingStops OBS recording.WebSocket or Browser Source API fallback
Start StreamingStarts the configured OBS stream output.WebSocket or Browser Source API fallback
Stop StreamingStops the OBS stream output.WebSocket or Browser Source API fallback
Control Replay BufferStart, stop, or toggle the replay buffer.WebSocket
Save Replay BufferSaves the currently running replay buffer.WebSocket or Browser Source API fallback

Set Text Source and flow variables

The text field supports normal message placeholders such as {username}, {message}, {source}, and {donation}, plus values added by earlier flow nodes such as {counterValue}, {counterTarget}, and {counterRemaining}.

{username}: now {counterValue}, need {counterTarget}
Set Text Source properties with counter template variables
Set Text Source writes the resolved value straight into the named OBS text input.
For a Text (GDI+) or Text (FreeType 2) source, turn off Read from file. Otherwise OBS may continue displaying the file contents instead of the text sent by Event Flow.

Media Source controls

Play / Pause

Play resumes paused media. Pause holds its current position.

Restart / Stop

Restart starts from the beginning. Stop ends playback and resets the input.

Next / Previous

Moves through playlist-capable inputs, such as VLC Video Source. A single-file Media Source may ignore these actions.

Volume, mute, and filters

Set Source Volume uses dB, matching the OBS mixer scale: 0 dB is unchanged gain, negative values are quieter, and -100 dB is effectively silent. Mute is a separate state. Toggle Filter changes only the enabled state of an existing filter; it does not edit filter settings.

Replay Buffer

First enable Replay Buffer in OBS Settings → Output. Use Control Replay Buffer to start/stop it, then Save Replay Buffer to write the recent buffered segment to disk.

Live-output warning: Start/Stop Streaming and Start/Stop Recording act immediately. Use restrictive triggers, permissions, and cooldowns so ordinary chat messages cannot fire them accidentally.

5. Useful recipes

Counter text in OBS

Place Set Text Source after the counter/check path and use:

{username}: now {counterValue}, need {counterTarget}

Run something after a video

OBS Media Ended (filter to Intro Video) → Change Scene to Main.

Chat-controlled media restart

Message Equals !replayintro → permission condition → Control Media Source: Restart.

Refresh an alert page

Message Equals !refreshalerts → moderator condition → Refresh Browser Source.

Duck music for an alert

Set Source Volume to -24 dB → alert action → Delay → restore to 0 dB.

Replay workflow

OBS Stream Started → Control Replay Buffer: Start; a separate trusted command runs Save Replay Buffer.

6. Other built-in OBS controls

Social Stream Ninja also has older OBS Browser Source controls in the Streaming Chat dock. These do not use the Flow Actions WebSocket bridge.

OptionWhat it doesRequirement
Current OBS scene indicatorShows the active scene in the Streaming Chat dock.Dock loaded inside OBS with read permission.
Guests can use !cycleCycles to the next OBS scene, rate-limited to once per 10 seconds.Enable the popup option; dock loaded inside OBS with Advanced access.
Privileged users can use !start / !stopStarts or stops streaming from trusted chat users.Enable the popup option; dock loaded inside OBS with Full/Advanced control permission.
Remote OBS control panelDisplays scenes and can switch scenes or toggle streaming/recording when the target OBS dock grants the required control level.Streaming Chat dock paired to a dock running inside OBS.
OBS WebSocket TesterChecks version, connection, scenes, and individual requests before using Event Flow.Open tester

7. Troubleshooting

ProblemCheck
Nothing happensFlow is saved and enabled; Flow Actions is open; both use the same session ID.
OBS will not connectWebSocket server is enabled, URL is ws://127.0.0.1:4455, and password matches. Port 4444 is the obsolete v4 default.
Scene/source/filter is not foundCopy the exact OBS name. For visibility, set Scene or Group when the item is nested or outside the current scene.
Text does not changeUse Text (GDI+) or Text (FreeType 2), confirm the input name, and disable Read from file.
Media Ended never firesUse OBS WebSocket v5 and a real media input. Looping media does not reach an ended state.
Next/Previous does nothingUse a playlist-capable source such as VLC Video Source.
Replay save failsEnable Replay Buffer in OBS Output settings and start it before saving.
Actions stop when a scene changesDisable Shutdown source when not visible on the Flow Actions Browser Source, or keep the page open elsewhere.
Diagnostic order: open the tester → confirm GetVersion → confirm scenes/inputs → test the individual request → test the full Event Flow.