obs-framebridge is a powerful OBS Studio plugin designed to facilitate real-time pixel analysis and automation within OBS scripts. This plugin directly addresses a common limitation of OBS Studio: the inability to inspect the internal state of scenes that are not actively being streamed. By integrating deeply with OBS's render pipeline, obs-framebridge provides a robust solution for developers who want to automate scene switching based on in-game states or other dynamic inputs.

Key Features

• Per-Pixel Queries: Access the exact RGBA color values at specified coordinates within a scene.
• Region Average Color: Calculate the average color of a defined rectangular region, enabling nuanced decisions based on visual content.
• Color Matching: Assess whether a specific region matches a target color within a defined tolerance.
• Template Matching: Compare regions against reference images using Mean Absolute Error (MAE) for advanced detection tasks.
• On-Demand Screenshots: Capture and save a rendered scene to a PNG file, even if it's not the active scene.
• Thread Safety: Ensured protection of the pixel buffer, making it safe to query from any thread.
• Pure Lua Integration: Utilizes OBS’s standard proc_handler, allowing seamless integration into existing Lua scripts.

Example Usage

A common use case is automated scene switching based on the observed luminance of a game capture. For instance:

local PROBE = { x=1280, y=810, w=320, h=270 }

local function avg_luminance() {
    -- Code to fetch average luminance
g}

local function switch_to(scene_name) {
    -- Code to switch scene
g}

local g_timer = nil

function script_load(settings) {
    g_timer = obs.timer_add(function() {
        local lum = avg_luminance()
        -- Logic to determine which scene to switch to
g    end, 250)
end

function script_unload() {
    if g_timer then obs.timer_remove(g_timer) end
end

This concise code snippet illustrates the capability to automatically switch between scenes based on the game's visual state.

For developers and streamers looking to enhance their OBS Studio setup, obs-framebridge serves as a critical tool for building dynamic, responsive streaming environments.