OBS FrameBridge — a plugin that gives your Lua scripts eyes inside OBS.
You've spent hours setting up your OBS scenes. The gameplay scene. The loading
screen. The pause menu overlay. Everything is pixel-perfect — and switching
between them manually has become second nature. But deep down, you know it
shouldn't be manual at all.
OBS is smart enough to do this automatically. Except it can't — because OBS
has no way to see what's happening inside a scene that isn't currently live.
It's a blind spot that's been there since the beginning. And it's why streamers
end up either hitting hotkeys at the wrong moment, or cobbling together
workarounds that involve hidden projector windows, external screen-capture hacks,
and scripts that break whenever a window gets resized.
There had to be a better way. So I spent a weekend building one.
See the difference
Same stream. Same game. Same OBS setup. The only difference is whether
FrameBridge is running.
❌ Without FrameBridge — manual switching, late, easy to miss:
✅ With FrameBridge — automatic, instant, zero effort:
No hotkeys. No manual triggers. No external tools. The script reads the game's
pixel output in real time and switches scenes automatically — exactly when it should.
How it actually works
Every frame, OBS renders your sources to the GPU. Normally that output goes
straight to your stream encoder — nothing else can touch it. FrameBridge hooks
into that render pipeline and copies the pixel data to a CPU-side buffer that
your Lua scripts can query — from any scene, even if it's not on-air.
OBS Scene ──GPU──▶ FrameBridge ──CPU──▶ Lua Script ──▶ Switch Scene ✓
What you can do with it
Auto scene switching based on game state — FrameBridge reads average
luminance or color from a probe region every 250ms. Your script switches
scenes without you touching a thing.
Detect UI elements via template matching — store a reference image once,
get a similarity score (0.0–1.0) in real time. Detect death screens, score
reveals, menus — whatever you need.
Render off-air scenes to PNG on demand — useful for automated thumbnails
or assets your viewers never see directly.
A real working example
obs.timer_add(function()
local lum = avg_luminance()
if not lum then return end
if lum > 42.5 then switch_to("MenuScene")
elseif lum > 34.0 then switch_to("PlayingScene")
else switch_to("PauseScene")
end
end, 250)
No external dependencies. Uses OBS's standard proc_handler — works with
any existing Lua script setup, no native module loading required.
No hacks. Seriously.
Every previous solution involved trickery: hidden projector windows tied to
your desktop resolution, external screen-capture APIs, abusing Studio Mode
transitions. They worked — barely — and broke with any monitor change.
FrameBridge hooks directly into OBS's internal render loop. No external
windows. No desktop capture. No undocumented internals.
→ Download latest · View on GitHub
OBS 32.0+ · Windows & Linux · MIT License
Have questions about the implementation or ideas for use cases? Drop them in the comments!
Top comments (0)