video-to-template

Reference video → template

This is the process that produced brutalist-product-promo, devtool-launch-video and narrated-collage-explainer, packaged so the next reference goes faster. Work in phases, and don't skip a phase's gate.

Tools (all in scripts/):

Tool	Does
analyze.py <url-or-file> [--transcribe]	downloads; format, shot cuts (scene score ∪ changed-pixel peaks), pacing, palette, audio type, optional Whisper transcript; timestamped contact sheets, a keyframe per shot, report.md with a storyboard skeleton
scaffold.py <name> --analysis …/analysis.json	new template skill whose brief has one animatic shot per detected cut (the reference keyframe, dimmed), so timing matches from minute one
grab.mjs <url> <out> '<specs>' (node 22)	capture real product UI from a live site: scroll so animations fire, hide fixed bars, clip by selector or rect, isolate pinned layers
compare.py ref.mp4 ours.mp4	side-by-side video (reference audio) and paired-frame sheets at the same timestamps

Phase 0: Intake

Get: the reference, the target brand or product, and its real logo plus real product material (README demos, screenshots, docs). Also the format, if it differs from the reference. Ask only for what you can't find yourself; for a public product, read its repo or site first. Gate: you can say in one sentence what the new video is about, and you have the real logo.

Phase 1: Analyse

1. Run python3 scripts/analyze.py <ref> --out analysis/<name>, adding --transcribe if the audio looks like speech.
2. Look at every contact sheet and several keyframes. Open the images; the numbers alone aren't enough. The detector is a first draft: merge shots split by in-shot animation, and split any a dissolve merged.
3. Fill in the storyboard table in report.md: layout and subject, type (face, size, colour), motion in and out, transition, copy.
4. Write a short style spec:
   • palette (confirm by eye; coverage ranking under-weights small accent text)
   • type roles mapped to bundled faces (sans Inter Display, mono Geist Mono for code only, pixel Departure Mono)
   • the recurring visual grammar (the 5–8 object or treatment types the video is built from)
   • transition types
   • pacing (average shot length, and whether cuts follow beats or narration)
   • audio

Gate: storyboard filled for every shot, and a style spec written.

Phase 2: Map to the engine

• For each grammar item, pick an engine primitive (references/engine-map.md) or plan a new scene type.
• Check the router (skills/framesmith/SKILL.md). If an existing template already covers most of the grammar, extend it instead of forking.
• Decide the asset list, using real material first (see Phase 4).

Phase 3: Scaffold and time

1. Run python3 scripts/scaffold.py <kebab-name> --analysis analysis/<name>/analysis.json (inside the framesmith repo it lands in skills/).
2. Render the animatic and run compare.py against the reference. The timing should already line up.
3. If the reference is narrated: write the script to the reference's words-per-second, generate the voice (framesmith.narration.tts + transcribe_words), and re-time beats to spoken cues instead of fixed durations. narrated-collage-explainer shows the pattern.

Phase 4: Content and assets

• Copy: run every line through the no-ai-slop skill and its eval (references/no-ai-slop/) before building scenes; on-screen text has no trailing periods. Every claim comes from the product's own docs. Never invent testimonials, quotes or posts from real people; show real artefacts instead.
• Real material first: the logo (never generated or reinterpreted), product screenshots, and terminal transcripts retyped as native text (not GIF crops).
• Brand icons: use the brand-icons skill (thesvg.org), with the light or dark variant to match the background, licences checked, and credits kept.
• Generated scenery (gpt-image-2, low/medium):
  • Write full-sentence prompts that name material, lighting, lens and an explicit background: pure black or white, transparent, or a flat #00FF00 screen for devices you'll key.
  • Use a sprite sheet (a grid of the same subject, with one part changing) for looping motion.

Phase 5: Build scenes

Replace animatic shots one at a time with real scene types, in order. After each: still at 2–3 moments, then look at them. Design rules are in references/design-rules.md; they're hard requirements.

Phase 6: Review loop

• check must pass: no overflow, and no copy shrunk below 80%.
• Look at sheet, then compare.py against the reference. Fix the biggest mismatch first: layout, then type, then colour, then motion.
• Prove it generalises: render a second brief with a different brand, a light accent and a long name.

Phase 7: Render and ship

• Render with a unique output filename, and poll the log rather than pgrep (references/lessons.md).
• Make the preview GIF (docs/media/<name>.gif) and a contact sheet. Finish SKILL.md (the description is the trigger), add a row to the router table, then run tools/catalog.py, tools/sync_core.py --check, tools/validate.py, the changelog and the version bump.
• Commit. Push only if the user asked; check whether the repo is public first.

Read references/lessons.md before starting. Every item in it cost a re-render once.