render-video-overlay-track

name	render-video-overlay-track
description	Render premium, reusable video overlay components from declarative JSON specs for social videos, ads, product videos, UI callouts, notifications, proof cards, charts, product screenshots, iMessages, stickers, and animated text overlays. Use when Codex needs crisp designed overlays that can be composited over existing footage and whose text/content can be changed without redesigning the component.

render-video-overlay-track

Render reusable overlay components as standalone HTML previews or PNG frames. The component system is designed for overlays that sit on top of existing video footage: product proof cards, fitness/stat HUDs, streak cards, giant title overlays, native notifications, glass stacks, browser chrome, and title/play overlays.

Quick Start

cd skills/atoms/overlays/render-video-overlay-track
npm install
npx playwright install chromium
npm test
npm run render:previews

Outputs land in previews/ by default, one PNG per registered component.

Workflow

1. Start from an overlay plan shaped like references/overlay-plan-schema.md.
2. Pick component types from references/component-registry.md.
3. Fill props with editable text, asset paths, brand colors, metrics, or list data.
4. Render previews with scripts/render-previews.js.
5. Visually inspect the PNGs before compositing into a video.
6. When using in a final video pipeline, render transparent overlay tracks or per-frame PNGs from the same component registry, then composite with FFmpeg.

Current Components

• product-proof-card — editorial cream product card with image well, review badge, and product pill.
• fitness-metric-hud — runner/watch-style metric overlay with headline, mini map, and stat rows.
• streak-progress-card — dark product streak card with bottle, label pill, and weekly progress rings.
• giant-kinetic-title — oversized bold title over dimmed cinematic footage.
• social-notification — soft native notification pill with avatar, context line, and timestamp.
• stacked-glass-list — layered translucent checklist rows with an active focused item.
• browser-chrome — stylized browser tab and secure URL bar.
• video-title-play — paused-video title overlay with play button.

Scripts

node scripts/render-previews.js --out previews --width 1080 --height 1920 --html
node scripts/render-previews.js --out previews-transparent --width 1080 --height 1920 --transparent
node scripts/render-previews.js --plan path/to/overlay-plan.json --out custom-overlays --transparent

Flags:

Flag	Purpose
--out <dir>	Directory for PNG and optional HTML outputs.
--width <px>	Canvas width. Default 1080.
--height <px>	Canvas height. Default 1920.
--dpr <n>	Playwright device scale factor. Default 1.
--html	Also write standalone HTML files for debugging.
--transparent	Render alpha-friendly PNG overlays by hiding mock scene backgrounds and using Playwright omitBackground.
--plan <path>	Render a custom overlay plan instead of the default sample plan. Output filenames use overlay.id.

Failure Modes

Symptom	Likely cause	Fix
PNG overlay invisible despite enable='between(t,A,B)' being set on the FFmpeg overlay filter	FFmpeg treats a -i image.png input as a single frame; fade=in:st=A:d=...:alpha=1 operates on the PNG's t=0 timeline only and silently degenerates	Add -loop 1 -framerate 30 -t <base_duration + 1> BEFORE each PNG input so it becomes a long video stream and temporal filters work. Always required when mixing static PNG + temporal filters. (LEARNINGS — 11-walking-felt-goose, L2)
Overlay appears as a hard pop instead of fading	fade=alpha filter requires format=yuva420p upstream so the alpha channel is preserved through the filter chain	Insert format=yuva420p between the scale and fade filters in the per-overlay sub-chain.
Overlay appears partially black or with white halo	Composited a chroma-keyed PNG (white background stripped via PIL) — anti-alias edge pixels were partially keyed	Replace with a PNG that has true alpha (PIL pill design with Lucide SVG icons via cairosvg), or generate with an explicit dark plate built into the design.

Design Rules

• Treat every component as a premium design recipe, not a generic card.
• Keep all visible copy in props; do not hard-code campaign text inside component markup.
• Keep layouts stable at 9:16 and 1:1 preview sizes.
• Use real text rendering through HTML/CSS, not AI-generated text in image assets.
• Preserve safe area for future caption tracks: avoid placing critical text in the bottom 14% unless the overlay is intentionally a lower-third.
• Use visual review after rendering. Code tests catch registry regressions; screenshots catch taste problems.
• Remember that CSS backdrop-filter cannot blur the underlying video once an overlay is pre-rendered to transparent PNG. For glass components on busy footage, either bake a stronger translucent surface into the overlay or add a video-side blur/dim treatment during FFmpeg compositing.

References

• references/overlay-plan-schema.md — data contract.
• references/component-registry.md — component props and design intent.
• references/animation-presets.md — planned motion vocabulary for video overlay tracks.