---
name: "stream_overlays_design"
description: "Design and build OBS stream overlay systems: lower thirds, event alert widgets, scene layouts, and animated stingers. Triggers on requests to make stream overlays, Twitch/YouTube/Kick alerts, lower third graphics, OBS scene collections, or StreamElements custom widgets."
---

# Stream Overlays Design

## Purpose
Build a complete, working overlay system for a live stream: the scenes, the browser-source graphics, the event alerts, and the transitions between them. Everything this skill produces is meant to be loaded into OBS, not just looked at.

## Workflow
1. **Ask for the essentials if missing**: canvas size (default 1920x1080, or 1080x1920 for vertical), brand colors, channel name. Do not invent branding.
2. **Lay out the scene set.** At minimum: Starting Soon, Main Content, BRB, Ending. Add Just Chatting for talk-heavy streams. Record the source stack per scene (top to bottom): alerts, bars/lower thirds, webcam, gameplay/content, background.
3. **Build the graphics.** Start from the templates in `templates/` and restyle, do not start from a blank page:
   - `lower-third.html`: browser source, transparent, driven by query params.
   - `se-alert-widget.html`: single-file StreamElements custom alert widget (inline style and script). Run `scripts/split_widget_tabs.py` to split it into the HTML/CSS/JS/fields tab files StreamElements expects.
   - `alert-test-harness.html`: local test page. Open it in a browser, fire synthetic events, confirm every alert type looks and sounds right before anything goes near a live stream.
4. **Generate the scene collection.** `scripts/build_scene_collection.py` writes an OBS scene collection JSON with the browser sources pre-wired. The user imports it via OBS Scene Collection menu and adjusts captures to their machine.
5. **Verify.** Open the test harness over local HTTP (`python3 -m http.server` in `templates/`, then `http://localhost:8000/alert-test-harness.html`; browsers block the harness on file:// URLs), fire every alert type, confirm the lower third renders at the target canvas size, validate the generated JSON parses, run py_compile on any touched scripts. No template ships without a visual check.

## Output Contract
- One or more browser-source HTML files (transparent background, sized to the canvas) plus exact OBS wiring instructions: source type, URL or local file path, width/height, and where each source sits in the stack.
- StreamElements widgets as paste-ready tab files plus the field defaults.
- An OBS scene collection JSON from the generator, never hand-edited.
- Timing notes for every animated element: enter duration, hold duration, exit duration. Defaults live in `references/overlay-timing.md`.

## Operating Rules
1. Every factual claim about a platform API (StreamElements event names, OBS source fields) must match `references/se-widget-api.md`. If the reference does not cover it, verify via web search before writing it into a deliverable. Never guess listener names or payload keys.
2. Text stays inside the 90% frame safe zone. Never stack more than 2 overlays at once. Lower thirds outrank alerts.
3. Keep animation snappy: lower third 0.5s in / 0.3s out, 5-8s hold; alerts 2-5s depending on type. Stingers 1-3s, transition point at full canvas coverage.
4. One canonical source per widget. The `se-alert-widget.html` single file is the truth; tab files are generated, never edited separately.
5. Test before shipping: the test harness must fire each alert type at least once and the lower third must render at the target canvas size.
6. Style ban applies to all generated copy: no em dashes, no ChatGPT-speak, plain direct language.