NewsDesk 📰 — a broadcast-news stream package for OBS

A complete, production-deployed OBS graphics package that makes a Twitch stream look like a cable news broadcast: an alpha-channel stinger transition, seamless screen loops, and a six-tier alert system where follows are wire blips and big donations are BREAKING NEWS.

Built as code, not video files: alerts render live in one browser source with real usernames and amounts, the video assets are generated by deterministic render pipelines in this repo, and the whole package deploys dev → production with one script. Running nightly on twitch.tv/CodingWithPak.

What's in the package

Piece	What it does	Tech
Alert overlay	Follows, bits, donations, subs, gift bombs, and raids — routed through a news-urgency ladder with escalating visuals + stings	Single HTML browser source, zero dependencies
Stinger transition	Skewed panel wipe with light streaks for scene changes	1080p60 VP9 WebM with alpha
Screen loops	"Be Right Back" / "Starting Soon" monitor loops with a mathematically seamless loop point	H.264 MP4, hardware-decoded
Scene overlays	Chat rail, camera frame, lower-third live brief	Static HTML/CSS
Render pipelines	Re-generate any video asset from its animation source code	Node + headless Chrome + ffmpeg

The alert ladder

Broadcast news already solved "how do we signal this story matters more than that one" — this maps stream events onto that hierarchy:

Event	Treatment	Duration
Follow	JUST IN — small lower-third chip, quick in/out	~3s
Bits / dono < $10 · 1–4 subs	VIEWER DISPATCH — lower third with red kicker	~4.5s
$10–49 · 5–49 gift subs	DEVELOPING STORY — skewed panel + light streak	~5.5s
$50+	BREAKING NEWS — red full takeover, flash, streaks	~7.5s
50+ gift subs	SPECIAL REPORT — gold takeover, reserved for the rarest event	~7.5s
Raid	INCOMING BROADCAST — blue takeover (panel-size under 10 viewers) + teletype sting	~7.5s

Color = meaning at a glance: red is money, gold is subs, blue is a raid. Gift bombs collapse into one alert (nobody wants 50 individual popups).

Engineering decisions

Alerts are pure functions of time. Every alert is render(t) — given seconds since it started, position everything. No CSS keyframe state, no tweening library. Why: the same code drives live playback (rAF clock), the demo reel, and frame-by-frame video rendering in headless Chrome (manual clock). The preview videos in demo/ are literally the production overlay, screenshotted 30 times per second.

One browser source instead of pre-rendered alert videos. Rendered videos can't show usernames or amounts; a browser overlay renders them as crisp live text, and adding a tier is an edit, not a re-render. CSS transforms are GPU-composited, so idle cost is near zero.

VP9-with-alpha for the stinger, H.264 for the loops. Stingers need transparency, and WebM/VP9 (yuva420p) is the only format OBS stingers read alpha from — worth the CPU decode for a 2-second clip. Loops are opaque and play for minutes, so they use H.264 and the GPU's dedicated decode block (check "hardware decoding" on the media source). Choosing per-asset instead of one-format-fits-all keeps stream overhead minimal.

Seamless loops by construction, not by eye. Loop frames are sampled at i/N with the endpoint excluded, so the frame after the last is the first. Every motion in the loop source is periodic over the duration. Verified by rendering the p = 1.0 frame and asserting it's byte-identical to frame 0.

Sounds ship as a manifest, not files. The stings are licensed from Epidemic Sound and can't be redistributed. sounds.manifest.json maps each alert tier to a track ID; tools/fetch-sounds.js downloads them under your subscription via Epidemic's MCP API. Licensing compliance as a feature.

Dev/production split. Working copy lives in this repo; OBS reads a deployed copy (in Program Files, which needs elevation). tools/deploy.ps1 self-elevates and syncs one-way. Iterate freely, ship deliberately, and git is the backup and the changelog.

Quick start

1. Clone anywhere, e.g. F:\Stream\obs-newsdesk.
2. Sounds (optional, needs an Epidemic Sound subscription): generate an API key at Account → API keys, copy it, run tools/set-epidemic-key.ps1, then node tools/fetch-sounds.js. No subscription? The overlay runs silent with ?sounds=off, or swap in your own MP3s using the same filenames.
3. Alerts: add a Browser source in OBS → Local file → media/Effects/alerts.html, 1920×1080. Check "Control audio via OBS" to get a mixer fader. Preview the reel by opening media/Effects/alerts-demo-c.html in a browser.
4. Stinger: Settings → Scene Transitions → add Stinger → media/video/News Stinger Alpha.webm, transition point 1000 ms.
5. Loops: Media source → Be Right Back Loop 540p.mp4 → check Loop + hardware decoding.
6. Test events from any console on the overlay page:

window.newsAlert({ type: 'donation', user: 'TestViewer', amount: 100 });
window.newsAlert({ type: 'raid', user: 'FriendlyChannel', viewers: 47 });
window.newsAlert({ type: 'giftbomb', user: 'GenerousOne', count: 50 });

Event feed integration (Streamer.bot → WebSocket → window.newsAlert) is the active roadmap item; the overlay API is stable and any event source that can POST a WebSocket message can drive it.

Repo layout

media/            The deployable package (what OBS reads)
  Effects/          alerts.html + demo launchers
  video/            stinger + loops (generated by src/ pipelines)
  images/ layers/   scene artwork (AI-generated)
  overlays/         static scene overlays
  Sounds/alerts/    stings — fetched via manifest, not committed
src/              Animation sources + render pipelines (Node + headless Chrome + ffmpeg)
tools/            fetch-sounds.js · es-mcp.js (Epidemic MCP client) · deploy.ps1 · key setup
docs/ai-skills/   Process documentation for AI-assisted maintenance (see below)
sounds.manifest.json   Tier → Epidemic Sound track mapping
demo/             Rendered previews (made by the pipelines in src/)

Customizing

• Branding: wordmark, kicker, accent color are props/config in the animation sources (src/news-stinger/stinger.jsx, media/Effects/alerts.html).
• Tier thresholds: moneyTier() / subTier() in alerts.html.
• Volumes: per-tier VOLUMES map × master gain (?vol=0..1, default 0.55). Stings auto-fade when their alert exits.
• Re-render videos: each src/*/render-pipeline/README.md documents its pipeline (roughly: drive the animation deterministically in headless Chrome, screenshot frames, encode with ffmpeg).

How this was built

Designed, directed, and QA'd by CodingWithPak; implemented in pair-programming sessions with Claude (Anthropic), which also co-authored the commits. The interesting part isn't that AI wrote code — it's the workflow: every visual change was verified by rendering frames in headless Chrome before committing, sound candidates were auditioned via A/B/C demo pages, and the recurring workflows were codified into reusable AI skills (docs/ai-skills/) so future maintenance sessions start with full context instead of archaeology.

License

Code and docs: MIT. Alert stings: licensed from Epidemic Sound, fetched per-user, never redistributed. Scene artwork and demo footage: AI-generated for this project.