agentforge-promo-video

name	agentforge-promo-video
description	Build and iterate technical product promo videos with Remotion and Playwright using frame-accurate timelines, automated screenshot/clip capture, macOS say voiceover generation, bilingual subtitle sync, and production QA gates. Use when creating a new promo video, refreshing existing promo assets, fixing audio/subtitle timing, or upgrading visual quality (QHD/4K) for stakeholder demos.

AgentForge Promo Video

Overview

Create repeatable product promo videos for technical decision makers with deterministic timing and verifiable capture quality.

Follow This Workflow

1. Define the narrative contract.

• Lock audience, tone, language, duration target, and 3-4 core messages.
• Keep one timing source of truth in a dedicated timeline file (*Timeline.ts).

2. Build a sentence-level script.

• Write short English lines for narration (10-18 words each).
• Write paired Chinese lines only for subtitle overlay.
• Prefer sentence boundaries that map cleanly to scene switches.

3. Capture assets with Playwright.

• Force English locale and light theme before every capture.
• Capture both static PNG screenshots and WebM operation clips.
• Reject captures that include non-content Chinese in UI chrome.

4. Compose in Remotion.

• Register composition in Root.tsx with explicit width/height/fps.
• Organize scenes with Sequence and shared containers (for consistent spacing/background).
• Use click highlight overlays only; avoid fake cursor trails.

5. Generate voiceover and timings.

• Use scripts/build_voiceover.py for line-level macOS say synthesis.
• Produce merged audio (.wav) plus line-level timings.json.
• Map timing JSON to frame ranges in the timeline file.

6. Sync and polish.

• Hold scene transitions until the sentence end; do not cut mid-sentence.
• Keep 0.2-0.6s visual breathing room after key statements.
• Tune subtitle box width/font size to avoid line wrapping spikes.

7. Render and QA.

• Render draft with placeholders, then final with real media.
• Confirm resolution, subtitle sync, voice rate, and key-message coverage.

Reusable Principles

1. Drive all motion and subtitles by frame math, not by best-effort runtime events.
2. Keep one timeline data file for durations and subtitle ranges.
3. Separate capture tooling (Playwright) from composition logic (Remotion).
4. Standardize outputs so assets can be replaced without code rewrites.
5. Preserve realism: show real UI states and true interaction intent.

Resource Map

• Voiceover script: scripts/build_voiceover.py
• Workflow details and command templates: references/workflow-checklist.md
• Stack and architecture patterns: references/tech-stack.md
• QA acceptance gates: references/quality-gates.md
• Optimization and extension roadmap: references/optimization-roadmap.md

Load only the reference file needed for the current task.

TODO (Maintenance Backlog)

• Add one-command pipeline script for capture + voiceover + render.
• Add 4K composition profile and corresponding safe-area subtitle preset.
• Add pronunciation dictionary for product/domain terms (Team, Workflow, SKILL.md, Invocation).
• Add automated checks for timeline/audio mismatch (frame drift > 6 frames).
• Add asset freshness checks to catch stale screenshots after major UI updates.
• Add versioned release template (vN) for script/timing/changelog packaging.