SRT-Driven Explainer

SRT-Driven Video (SRT-Driven Video Pipeline)

Turn a voiceover script into a code-generated visual explainer video. Uses SRT as the sole time reference, progressing through five stages, pausing at each stage for user confirmation.

Environment & Dependencies

• Windows: Playwright (channel="msedge", uses local Edge to avoid Chromium download) + imageio-ffmpeg (provides ffmpeg; does not include ffprobe, uses ffmpeg -i stderr to parse specs).
• Install dependencies: pip install playwright imageio-ffmpeg (scripts handle ffmpeg path resolution).
• This skill's scripts/ directory is tested and adapted for Windows; on Linux/macOS, remove channel="msedge" and use the system ffmpeg.

Five-Stage Overview

Stage	Output	Confirmation Gate
0 Outline	outline.md + decision table	User confirms outline & decisions
1 Script+SRT	script.md / subtitles.srt / speaker-notes.md	User confirms script
2 Storyboard	storyboard.json (must pass check_timeline.py)	User confirms storyboard
3a First scene + component library	assets/shared/ + scene-001 low-res sample	User approves style before batch rendering
3b Per-scene batch rendering	scenes/scene-NNN/scene.mp4 × N	User reviews key shots
4 Assembly & delivery	output/final.mp4 + cover.png	User confirms final video

For detailed flow, decision table fields, and common pitfalls (imageio-ffmpeg no filter_complex_script, alimiter level trap, etc.), see references/pipeline.md.

Three Core Contracts (Non-Negotiable)

1. SRT Time Base: Scene boundaries align with subtitle boundaries, total span error ≤0.1s; python scripts/check_timeline.py <project_dir> rechecks at each stage.
2. WORKLOG Handoff: Create WORKLOG.md at the project root (template in references/worklog-template.md), which is the sole state carrier across sessions; decision table cannot be modified after lock; baseline files (outline/script/SRT/speaker-notes/storyboard/assets/shared/scenes) are frozen from stages 3/4 onward.
3. Stage Confirmation Gates: After each stage report, pause and wait for explicit user confirmation before proceeding to the next stage.

Scene Rendering (Stage 3)

Each scene is an independent HTML page implementing window.setTime(t) deterministic rendering (all animations are pure functions of t); subtitle burn-in uses the unified contract element div#subtitle. For full development contract, QA process (check_frames.py keyframe mosaic), and design redlines, see references/visual-authoring.md.

Starting template: assets/neon-theme/ (already approved tech-neon style with theme.css + components.js, including particles/character fly-in/data cards/comparison bars/risk color coding/transitions/subtitle components) — if the user wants the same style, copy it directly to the project's assets/shared/; for other styles, use it as a structural blueprint.

python scripts/render_scene.py scenes/scene-001 --duration 10.5 --fps 30 --size 960x540   # low-res sample
python scripts/check_frames.py scenes/scene-NNN --times 0.5,3,6,9.2                        # pre-render QA
python scripts/render_all.py .                                                             # batch full render
python scripts/render_all.py . --no-subtitle --outdir output/nosub                         # subtitle-free variant
python scripts/concat_final.py .                                                           # concatenation + cover

Optional Sound Effects Module (Off by Default)

Only enable if the user explicitly requests beat-synced sound effects, and lock the decision in stage 0. Source assets via Freesound CC0 (verify license per track), drop timeline into assets/sfx/mix_timeline.json, and preview with the user before finalizing; deliver via one of two paths: FFmpeg auto-mix (mix_sfx.py), or export a CapCut alignment checklist (make_cue_sheet.py) for manual editing — the latter is more stable in practice. See full flow in references/sound.md.

Referenced External Skill/Tool

• vibe-motion/sound (GitHub, clone into project tools/sound/): Freesound search/download CLI. Repository has no LICENSE, used only as an internal download tool; licensing is per the individual Freesound CC0 declaration.

Delivery Specifications

final.mp4: 1920×1080 / 30fps / h264 / yuv420p, duration exactly matching total SRT span; cover.png captures a peak frame (determined by sampling); verify duration, frame count, specs, and audio level, then update WORKLOG before reporting.