stream_overlays_design v1.0.0

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.

1. 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.
2. 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.