Content to Video

Produce a finished, high-quality MP4 video from arbitrary source content. This skill is the router and orchestrator: classify -> plan -> produce -> QA. It bundles the full promo-film machinery (three.js/HTML scene contract, render commands, ffmpeg assembly, TTS, i18n) and adds per-content-type presets, adaptations (screen capture, data-viz, vertical format), an optional HyperFrames rendering backend, and stricter quality gates.

Pipeline

0. CLASSIFY - Read references/classification.md. Run node scripts/classify.mjs <source> for a fast first pass. Confirm content_type, format, duration, pacing, and visual strategy (intent beats signals; follow confidence rules in classification.md).
1. PLAN - Write the one-line message, audience, distribution, CTA. Design the storyboard with image-gen (planning reference only - panels are never final frames). Structure the film per the chosen pipeline in references/pipelines.md. For EVERY storyboard panel, decide and record the shot's tech stack - primary technique + layers - using references/tech-stack.md ("shot 3: three.js core + GSAP title + sprite embers"). A panel with no tech stack is a Q1 failure. Pass gate Q1.
2. SCRIPT + NARRATION - Narration-first, one line per shot, into a narration JSON. Synthesize with TTS, measure real durations, write them back. PAD > FADE so speech is never cut (see references/pipeline.md).
3. SCENES + ASSETS - Build scenes per the pipeline's visual strategy and the chosen rendering backend (below). Follow the identity rules in references/methodology.md: labeled real UI + 3D forms + text; image-gen only for atmosphere and planning panels.
4. SOUND - After picture locks: pick BGM per sound-design.md (audition inside the cut, bed ~0.34), pin SFX with a declarative relative-frame table (genre vocabulary: whoosh/impact/riser/sparkle/transition; no game-pack timbres). If the user chose a strong-beat BGM, cut the timeline in beatF(n) per beat-sync.md and verify <= 3f error after render.
5. RENDER + ASSEMBLE + QA - Preview 3 frames per scene, render clips, assemble with ffmpeg (Ken Burns, crossfades, audio mix with loudnorm, ASS subs) or render a HyperFrames composition, deliver BGM + no-BGM versions, then run Q2 per-shot vision checks and Q3 watch-through. Repeat per language from one parameterized builder.

Classification quick matrix

Full decision tree, presets, and overrides: references/classification.md. Per-pipeline structures and visual strategies: references/pipelines.md.

Choose a rendering backend

Two scene-authoring backends; pick per pipeline and content:

• Bundled machinery (default): three.js/HTML scenes with a deterministic frame(t) contract + build_film.py assembly. Best for cinematic 3D, real-UI heroes, particles. Promo/explainer/story/tutorial/slides default here.
• HyperFrames: HTML + GSAP timelines rendered by the hyperframes CLI. Best for kinetic motion graphics, vertical social, data charts, and caption/overlay-heavy pieces. See references/hyperframes.md (verified commands, composition contract, --variables/--batch for language variants). The official HyperFrames skills are installed locally (hyperframes, hyperframes-core, hyperframes-animation, hyperframes-cli, ...) - delegate composition authoring to them via references/hyperframes.md.

Both share the same upstream (classification, narration JSON with measured durations, Q1-Q3 gates) - only scene authoring and the render command change.

Bundled machinery (read these first)

• references/methodology.md - the full method: decisions, failure modes, asset sourcing, checklists. Read it before starting any film.
• references/pipeline.md - scene contract, render/build commands, timing math (FADE/PAD/TAIL), ffmpeg filtergraph, TTS, i18n.
• references/tech-stack.md - per-shot tech-stack catalog and decision rule; read it at storyboard time, panel by panel.
• references/sprites.md - image-gen sprite playbook (chroma-key, slicing, atlases, manifests, frame-sequence puppets); read before any sprite layer.
• references/sound-design.md - BGM + SFX + mix: genre-based vocabulary, declarative relative-frame SFX table, volume math, two-version delivery. Read at sound stage; picture locks before sound.
• references/beat-sync.md - when the user picks a strong-beat BGM: analyze the grid first (librosa), write the timeline in beatF(n), verify cut errors <= 3f on the rendered cut.

Scene contract: every scene is a standalone HTML page at 1920x1080 exposing window.__modeldock = { frame(t), duration, frameAsync?(t) } and __ready. Render environment: headless MS Edge via Playwright (SwiftShader flags), local static server with HTTP Range (206). Scripts (adapt config, do not edit the engine):

• scripts/classify.mjs - classify source content -> production recommendation.
• scripts/build_film.py - ffmpeg assembly (Ken Burns, xfade, audio mix, ASS subs, --lang).
• scripts/render-clip.mjs - render an animated scene to an mp4 clip at 25 fps.
• scripts/preview-scenes.mjs - sample 0.3/0.55/0.8 frames per scene, capture page/console errors, write 3-up strips.
• scripts/qa-frames.mjs - extract per-shot and mid-fade frames for QA.
• scripts/static-server-range.mjs - minimal static server with Range support.

Non-negotiable rules

• Narration drives the timeline; measure real TTS durations, never guess.
• PAD > FADE (e.g. 1.5s vs 1.0s) so speech finishes before the next shot.
• Never let image-gen carry product identity: no "device" heroes. Identity = labeled real UI + clear 3D forms + text sprites. image-gen is for atmosphere backgrounds, concept stills, validated hub layouts, and transparent-background decorative sprites (smoke, embers, glow orbs, sparkles, dust, generic non-brand icons). Sprites are powerful in animation, but they never carry identity.
• Plan-stage image-gen designs the OUTLINE and STORYBOARD (one panel per planned shot, plus 2-3 style anchors when shots share a look). Panels are planning references, never final frames.
• Composite image layers with heavy blur + radial feather mask; never hard crop edges (they read as panels/windows).
• Vision-QA one image per call, never contact strips (cross-frame misreads).
• Real UI footage: object-fit contain so controls are never cropped.
• Keep the builder parameterized by language (--lang).
• Windows: never pass non-ASCII text through a PowerShell pipe; read UTF-8 files from disk or write with Node fs utf8 + unicode escapes.
• A static server used for video scenes must support HTTP Range (206).
• Add a data: favicon link to every scene so console-error checks stay clean.

Quality gates (the "better" in better video)

Three gates; do not proceed past a failing gate. QA on single frames only.

• Q1 - Plan: one-line message is a sentence, audience + distribution stated, CTA defined, every claim has a visible proof point, storyboard reviewed, voice sample signed off.
• Q2 - Production (per shot, single frames): labeled identity, no modem/router reading, text readable and in safe margins, no hard edges / double exposure, clean transition midpoints, footage shows all key controls.
• Q3 - Final (watch with audio): no cut speech, audio clean, subtitles fit and match, correct aspect/fps/duration, h264 yuv420p +faststart.

Full checklists and failure handling: references/quality.md.

Language variants

One builder, per-language narration JSON and audio, shared language-neutral scenes, translated text stills and subs. With HyperFrames, per-language text can live in --variables/--batch instead of duplicated compositions. Never pass non-ASCII text through a PowerShell pipe.

QA loop

1. Q1 before production; fix the flow while a panel costs one generation.
2. Preview every scene: zero page/console errors (HyperFrames: check + --strict render).
3. Q2 per shot on single frames; check transition midpoints.
4. Q3 watch-through with audio; only then deliver.