Local OBS overlay server with code-based widget definitions.

# Install dependencies
uv sync

# Run the server (hot-reload enabled by default)
uv run observe

Open http://localhost:8000 to see available widgets and layouts.

Edit widgets.py to define your overlays:

from server import Widget, Layout, LayoutWidget

WIDGETS = {
    "live-indicator": Widget(
        type="text",
        content="LIVE",
        css_class="hud pulse",
        style={"color": "#ff0000"},
    ),
    "logo": Widget(
        type="image",
        content="/static/images/logo.png",
    ),
}

LAYOUTS = {
    "stream-overlay": Layout(
        width=1920,
        height=1080,
        widgets=[
            LayoutWidget(widget_id="live-indicator", css_class="top-right"),
            LayoutWidget(widget_id="logo", css_class="bottom-left"),
        ],
    ),
}

Changes hot-reload automatically.

Add a Browser Source with one of these URLs:

• Single widget: http://localhost:8000/widgets/live-indicator
• Full layout: http://localhost:8000/layouts/stream-overlay

Set the browser source dimensions to match your layout (e.g., 1920x1080).

Positions: top-left, top-right, bottom-left, bottom-right, center

Styles: hud, log-line, alert-box

Animations: fade-in, fade-out, slide-in-left, slide-in-right, slide-in-top, slide-in-bottom, pop-in, bounce-in, pulse, glow, shake

uv run observe [options]

  -p, --port PORT   Port (default: 8000)
  --host HOST       Host (default: 127.0.0.1)
  --no-reload       Disable hot-reload