StreamBridge

StreamBridge

Your Minecraft server drives OBS. Die on stream and the scene cuts itself.

You get killed by a creeper. Before you have finished saying anything about it, OBS
has already clipped the replay buffer, put "Kiosk01 died: creeper" on the overlay,
cut to your death scene, and cut back six seconds later.

Nobody touched a hotkey. The server did it.

StreamBridge connects a Minecraft server to OBS Studio over obs-websocket v5 and
turns what happens in game into scene switches, source and filter toggles,
replay-buffer saves, recording control and text overlays.

How it works

Three things, and only one of them is a file you edit:

1. Something happens in the world. A player dies, a boss goes down, an
   advancement pops, someone drops below three hearts, someone walks into the Nether.
2. A rule matches it. Rules live in config/streambridge.json: which event, an
   optional condition, a cooldown, and what to do.
3. OBS does it. The action becomes an obs-websocket request. Scene switch, source
   toggle, replay save, caption — whatever you listed.

/streambridge reload applies changes without restarting anything.

What can trigger a rule

• Deaths — with the cause, the killer and where it happened
• Boss kills — ender dragon, wither
• Advancements — recipe unlocks filtered out, so it does not spam
• Low health — fires once when you drop below the threshold, re-arms when you heal
• Dimension changes — Nether, End, back again
• Join and leave
• Chat messages — including operator-only chat commands
• Server start and stop

Every one of them is decided on the server. No player can trigger anything except
through the events above, and every manual control checks your permission level
first.

What a rule can do in OBS

• Switch the program scene or the studio-mode preview scene, and trigger the
  transition between them
• Toggle a source on or off inside a scene, by name — no scene-item ids to look up
• Toggle a filter on a source
• Save the replay buffer — the clip of the thing that just happened
• Set the text of a text source, with values from the event:
  {player} died: {cause}
• Start, stop or pause recording, start or stop the stream
• Trigger any OBS hotkey by name
• Send any raw obs-websocket request the protocol accepts, for anything not in the
  list above

Actions can be delayed: cut to a death scene now, cut back six seconds later, from one
rule.

The dashboard

/streambridge dashboard, or right-click a Scene Remote that is not bound to
anything yet.

It lists the scenes OBS actually reports — not a list you had to type into a
config first. Click one to switch to it. The scene that is live is marked. Next to
each scene is a bind button, which writes that scene onto the Scene Remote in
your hand.

On the right it lists your rules, each with the number of times it has fired,
a click to test-fire it, and an on/off toggle for when a rule is being annoying
mid-session. Toggles last until the next reload; the file stays the source of truth.

Along the bottom: reload the config, save a replay clip, start or stop recording.

The Scene Remote

One item, one scene. Bind one to Intro, one to Just Chatting, one to
Death, put them in your hotbar — and switching scenes is a right-click, without
alt-tabbing and without a Stream Deck.

The bound scene is part of the item’s name, so a hotbar full of remotes reads at a
glance. Sneak + right-click reopens the dashboard to re-bind.

Every action is checked on the server against your permission level. Handing
someone a remote does not hand them your stream.

Chat commands

A condition can be a regex, and the regex hands its capture to the action. That means
one rule covers every scene you own:

{
  "on": "chat.message",
  "when": { "op": "true", "message": "regex:^!scene (?<scene>.+)$" },
  "do": [ { "type": "scene", "scene": "{scene}" } ]
}

Type !scene Just Chatting in game and OBS switches. The "op": "true" condition is
there for a reason — without it, anyone on your server could drive your stream.

Things people set this up for

• A death cam that clips and cuts itself, so highlights are not a post-session chore
• A "BRB" scene that appears the moment you log out and disappears when you come back
• A red border overlay while you are below three hearts
• A Nether colour-grade filter that switches on when you go through the portal
• An intro scene when the server starts, before anyone joins
• Boss fights that record themselves

Built to sit on a live server

• Nothing blocks the server thread. Rule matching is a map lookup; the OBS socket
  runs on its own thread.
• Requests are dropped, not queued, while OBS is closed. A scene switch that
  arrives forty seconds late is worse than none.
• A global rate limit (5 actions/second, burst 10) means a mob farm cannot turn a
  thousand deaths into a thousand scene switches.
• Per-rule cooldowns survive a reload, so reloading is not a way around them.
• A broken config never takes the server down. Invalid rules are skipped and listed
  in /streambridge status.
• A wrong OBS password stops the reconnect loop instead of hammering OBS forever.

Requirements

• Minecraft 1.21.11
• NeoForge 21.11 or newer
• OBS Studio 28 or newer, with the WebSocket server enabled
  (Tools → WebSocket Server Settings)
• Install on the client as well as the server — the dashboard and the Scene
  Remote are registered content

OBS and the Minecraft server have to be able to reach each other. For a remote server
that means a tunnel; do not expose obs-websocket to the open internet.

Honest limitations

This is version 0.1.0. The protocol layer, rule engine and rate limiting are
covered by 51 automated tests, including a full handshake against a stand-in OBS
server. What has not had months of use is the game side.

The chat back-channel is one-way for now. Events go from the game to OBS. Twitch
and YouTube chat driving the game is planned, not shipped.

No client-side triggers. Nothing reacts to what you see, only to what the server
knows. That is a deliberate boundary, not an oversight.

The dashboard and the remote have not been through a real session yet. They
compile against 1.21.11 and the logic behind them is tested, but the first live run
is still ahead.

Where it is going

• Twitch and YouTube chat as an input, with a per-command whitelist and hard limits on
  what chat is allowed to touch
• A Fabric build
• Stream Deck via OBS hotkeys
• Per-player rule scoping for servers with several streamers on at once