create-motion-graphic-video

name

create-motion-graphic-video

description

orchestrate a high-quality motion graphic video end to end. picks a style pack from the catalogue, composes scenes from named archetype molecules, grounds every effect in pack-specific params via an implementation brief, then renders via remotion (or hyperframes per scene). 5 explicit human gates; ≤3 review loops; state recovery via .motion-graphics-state.json. use when the user wants kinetic typography, snappy transitions, data viz reveals, ui-demo product spots, editorial brand films, or any motion graphic where text crispness, timing precision, and matching a specific aesthetic system matter more than photoreal video.

create-motion-graphic-video

Purpose

Produce a motion-graphic video that matches a chosen aesthetic system (style pack) rather than converging on a generic default look. The molecule sequences ~10 atoms with 5 explicit human gates and state recovery, so the user can resume after any interruption and so each gate catches direction errors at the cheapest possible step.

This is the v2 of the motion-graphics molecule. v1 (the previous flat 9-step workflow) is preserved in git history at commit d5fc3ba1. v2 changes:

• Style packs as first-class objects. Gate 1 picks a pack from skills/atoms/motion-graphics/style-packs/. The pack drives palette, fonts, motion params, transitions, container, micro-imperfection.
• Implementation brief as gate 3. New atom create-motion-graphics-implementation-brief bridges storyboard → render with style-pack-grounded params, computed safe-area math, sharedLayer keyframe expansion, music-beat snapping, and per-scene renderer choice.
• Scene archetype molecules. Storyboard scenes name an archetype (A1..A19) from skills/molecules/motion-graphics/scene-archetypes/. Archetypes encode parent layout + effect composition + two-tier choreography.
• Effects as atoms. Each primitive lives in skills/atoms/motion-graphics/effects/<effect-id>/. The Remotion renderer imports effects dynamically based on the impl brief.
• State machine + recovery. .motion-graphics-state.json in the run folder lets the molecule resume after any state.

Use when the user asks for: kinetic typography sizzle, animated infographic, app demo with overlay text, data-viz pop, ad-style motion graphic, brand film, scrolling editorial archive, AI product demo. Do not use for photoreal product video (use create-video-veo3 or create-product-sizzle-reel) or single-shot HTML/GSAP frames (use create-motion-graphics-hyperframes directly).

Inputs

• A free-form user brief: what the motion graphic should communicate, audience, platform, target length, aspect ratio.
• (Optional) 2–5 sample reference images that capture the user's preferred aesthetic. Used in gate 1 style-pack pick.
• (Optional) Brand assets: logo, brand colors, font preferences.
• Output directory or test-run directory.

Composed Atoms

Planning:

• create-brand-design-board — derives palette+typography mockup from the chosen style pack (no longer free-floating).
• create-video-concept-brief — concept, hook, scene beats, CTA.
• create-motion-graphics-storyboard — frame-by-frame plan, scene archetypes, continuity element.
• create-motion-graphics-implementation-brief — NEW gate-3 bridge. Grounds every effect param in the pack's motion-recipes; computes safe-area math; expands sharedLayer keyframes; picks renderer per scene.

Render:

• create-motion-graphics-remotion — render scenes via Remotion (the default).
• create-motion-graphics-hyperframes — render scenes via HTML/GSAP (for A14/A15/A10 archetypes).

Audio:

• find-music — pick a real music track matching the pack's music.vibe and the spot's duration.
• add-music-track — mix music (and VO if any) under the silent video master.

Assembly:

• stitch-videos-ffmpeg — concat per-scene clips into a silent master.

Review:

• review-motion-graphic — final gate with DNA-level checks (continuity present, palette discipline held, two-tier choreography detectable, micro-imperfection layer applied per pack).

Reference data (read-only):

• skills/atoms/motion-graphics/style-packs/ — the 7 packs.
• skills/molecules/motion-graphics/scene-archetypes/ — the 19 archetypes.
• skills/atoms/motion-graphics/effects/ — the 30+ primitives.

State machine

The molecule advances through 11 states. At each state, check whether the prerequisite artifact exists; if it does, skip ahead. Always write the result of each state to its deterministic path so resume works.

┌────────────────┐    ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
│ S0 INTAKE      │ -> │ S1 STYLE PACK  │ -> │ S2 BRAND BOARD │ -> │ S3 CONCEPT     │
│ intake-brief   │    │ style-pack.md  │    │ brand-board    │    │ concept-brief  │
│                │    │ [GATE 1]       │    │                │    │                │
└────────────────┘    └────────────────┘    └────────────────┘    └────────────────┘
                                                                            │
                                                                            ▼
┌────────────────┐    ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
│ S7 RENDER      │ <- │ S6 MUSIC LOCK  │ <- │ S5 IMPL BRIEF  │ <- │ S4 STORYBOARD  │
│ clips/*.mp4    │    │ audio/music    │    │ impl-brief     │    │ storyboard     │
│                │    │ beats.json     │    │ [GATE 3]       │    │ [GATE 2]       │
└────────────────┘    └────────────────┘    └────────────────┘    └────────────────┘
       │
       ▼
┌────────────────┐    ┌────────────────┐    ┌────────────────┐
│ S8 ASSEMBLE+MIX│ -> │ S9 REVIEW      │ -> │ S10 DELIVER    │
│ master-final   │    │ review.md      │    │ manifest.json  │
│                │    │ [GATE 4]       │    │ [GATE 5]       │
└────────────────┘    └────────────────┘    └────────────────┘
                              │ (NEEDS REVISION)
                              └──> back to S5, S6, or S7

Workflow

S0 — Intake

If <run>/intake-brief.md exists, skip to S1.

Read the user brief. If the user has not provided sample images, ask for 2–5 references that capture the desired aesthetic. Capture: target platform, aspect ratio (default 9:16 social, 16:9 landing, 1:1 square), total duration target, audio mode (music | silent | vo+music), and any brand constraints.

Write intake-brief.md and .motion-graphics-state.json (state: S1).

S1 — Style pack pick (GATE 1)

If <run>/style-pack.md exists, skip to S2.

1. Read all style packs in skills/atoms/motion-graphics/style-packs/. (Each pack's reference.md describes its DNA + when-to-pick.)
2. Score each pack against the intake: vibe match, archetype fit, audience fit, platform fit.
3. Present the top 2–3 packs to the user with one-paragraph reasoning each. Recommend one.
4. HUMAN GATE 1: wait for explicit user pick. Capture the chosen pack id.
5. Copy the pack reference into the run folder: style-pack.md = <run>/style-pack.md containing the slug + a copy of the pack's reference.md + motion-recipes.md.

Write .motion-graphics-state.json (state: S2, locked_pack: SP-X).

S2 — Brand board

If <run>/brand-board.html exists, skip to S3.

Call create-brand-design-board with intake + sample images + the locked style pack. The brand board now DERIVES from the pack:

• Palette = pack.palette.primary, secondary, ink, background_set. (User can request 1–2 brand-specific overrides — e.g. replace pack's primary with their brand pink — but the structure of the palette stays.)
• Fonts = pack.type.display_family, body_family. (Same — user can override family but not the weight scale.)
• Mockups = single direction in the chosen pack's style (no longer 2–3 directions, since the pack already encodes direction).

No gate by default — board is mechanical from pack + brand overrides. If user requests changes, regenerate.

S3 — Concept brief

If <run>/concept-brief.md exists, skip to S4.

Call a concept-brief generator (create-video-concept-brief or motion-graphics-specific equivalent). Concept brief produces:

• Core message + hook (first 1–2s)
• Scene-by-scene beat list, with proposed archetype IDs (A1..A19) per scene, picked from the pack's supported_archetypes.
• Continuity element decision: if pack transitions.continuity_required = true, what physical element will travel through (chip / ball / aurora-blob / corner-ticker).
• Music vibe (pulled from pack defaults, adjustable).
• CTA.

No gate by default — concept-brief is iterable but doesn't burn cost yet. Optional pause if <auto>: false.

S4 — Storyboard (GATE 2)

If <run>/storyboard.html exists and post-dates concept-brief, skip to S5.

Call create-motion-graphics-storyboard with the concept brief + style pack. The atom emits:

• storyboard.html — single-page mockup of every scene at 9:16, using pack's palette + fonts + container.
• storyboard.json — machine-readable: scenes[], each with archetype, copy, on-screen-text, background, duration_seconds, music_cue, plus optional decoration_x_min and a top-level continuity_element block.

Per the user's "storyboard is the single review surface" rule, this is the user's primary review artifact.

HUMAN GATE 2: open storyboard.html. Wait for explicit approval. If the user requests changes, regenerate the affected scenes (don't rerun the whole atom).

S5 — Implementation brief (GATE 3)

If <run>/implementation-brief.json exists and post-dates storyboard, skip to S6.

Call create-motion-graphics-implementation-brief with the approved storyboard + locked pack. The atom emits:

• implementation-brief.md — human-readable per-scene table.
• implementation-brief.json — machine-readable spec the renderer consumes (frame-accurate timeline, sharedLayer keyframes, per-effect params from pack motion-recipes, computed safe-area math, per-scene renderer choice).
• Optional: appended ## Implementation section to storyboard.html so the user reviews both at the same surface.

The atom validates pack-archetype compatibility, palette discipline, safe-area math, continuity-element wiring, music-beat alignment. Halts on hard violations, surfaces warnings on soft.

HUMAN GATE 3: review implementation-brief.md (or the augmented storyboard.html). Approve or request brief-level changes (e.g. "scene 1 fontSize too small, accept overflow risk", "switch s4 renderer to hyperframe"). Brief-level changes do not regenerate the storyboard.

S6 — Music + beat lock

If <run>/audio/music.mp3 exists, skip to S7.

Asset-reuse fork: if the brief recreates a concept from a sibling project, scan that project's audio/ first. Reuse if VO/music exist and match duration ±1s. Record source in manifest.

Otherwise: call find-music with the pack's music.vibe and the spot's total duration. Save to audio/music.mp3.

If pack's music.beat_locked = true, run beat detection (librosa or aubio) to produce audio/beats.json with timestamps. The impl brief's music_beat_anchor fields snap to these.

If audio mode is silent, skip music entirely; assemble step delivers silent master.

Music provenance must be recorded as real (with source) or silent (intentional). Never placeholder.

S7 — Render

For each scene in implementation-brief.json:

• If scene.renderer == "remotion": call create-motion-graphics-remotion --scene <id> which reads the brief and renders clips/scene-NN.mp4.
• If scene.renderer == "hyperframe-gsap": call create-motion-graphics-hyperframes --scene <id> which builds the scene's HTML composition and renders via Playwright.

Re-roll individual scenes (not the whole comp) when iterating. The Remotion project persists at <run>/remotion/ and the Hyperframes project at <run>/hyperframes/.

S8 — Assemble + mix

1. If multiple scene clips: stitch-videos-ffmpeg → clips/master-silent.mp4.
2. Call add-music-track to mix music (+ VO) under the silent master. Enforce true-peak ≤ −1.0 dBTP via two-pass loudnorm or alimiter. Verify with ffmpeg -af loudnorm=print_format=json -f null -.
3. Write master-final.mp4.

S9 — Review (GATE 4)

Call review-motion-graphic against master-final.mp4 + the storyboard + impl brief + pack manifest. The atom checks:

• Safe-area at animation peaks (springs overshoot 1.15x by default)
• Decoration-on-text occlusion
• Music provenance + true-peak compliance
• Font fidelity (no system fallback)
• VO/copy alignment
• Scene duration drift
• Brand fidelity
• NEW DNA-level checks (from Phase 8 extension):
  • Continuity element present and tracks through scenes as declared
  • Color discipline held (no off-pack bg colors)
  • Two-tier choreography detectable (tier-2 elements arrive ≥4 frames after tier-1)
  • Micro-imperfection layer present if pack required one (grain / doodle / wobble)

Branch on verdict:

• pass → continue to S10.
• warning → user accepts or requests fix → loop to S5/S6/S7 as needed.
• blocked → loop to S5/S6/S7. Loop guard: max 3 iterations.

S10 — Deliver (GATE 5)

If review verdict is pass (or warning with explicit accept), write manifest.json listing every atom invoked, gate outcomes, render times, and final artifact paths. Write verification.md.

HUMAN GATE 5: show the user master-final.mp4. Wait for "ship it." Do not push to any external service automatically.

Decision Rules

• Halt at gates 1, 2, 3, 4, 5. Never auto-advance through a human gate. If the user is unreachable, mark needs human review and stop.
• State recovery is real. Always read .motion-graphics-state.json first; only run states whose artifact is missing or stale.
• Re-render at scene granularity. Never rebuild the whole composition for a single-scene fix.
• Placeholder/synthesized audio is never acceptable for delivery. If find-music cannot return a real track, the run is blocked, not pass. The only exception is when intake audio mode is silent.
• Style pack locks at S1. Cannot switch packs mid-run. To switch, archive the run and start a new one (the storyboard.json + concept-brief.md can be reused as inputs).
• Storyboard is the single review surface. Per user feedback, every video-project artifact lands in storyboard.html (with the impl-brief layer optionally augmenting it), not separate chat messages.
• Implementation brief is the renderer's only source of truth. The Remotion/Hyperframe atoms must not read the storyboard directly — they read the impl brief.
• Beat-snap only when pack requires. Beat-locking is opt-in via pack manifest. Default off — most spots don't need beat-locked cuts.

Output

motion-graphic-NN-<slug>/
├── intake-brief.md                  # S0
├── style-pack.md                    # S1 (gate 1)
├── brand-board.html                 # S2
├── concept-brief.md                 # S3
├── storyboard.html                  # S4 (gate 2)
├── storyboard.json
├── implementation-brief.md          # S5 (gate 3)
├── implementation-brief.json
├── audio/
│   ├── music.mp3                    # S6
│   └── beats.json                   # if beat-locked
├── remotion/                        # S7 (Remotion scenes)
├── hyperframes/                     # S7 (HF scenes, if any)
├── clips/
│   ├── scene-NN.mp4
│   └── master-silent.mp4
├── master-final.mp4                 # S8
├── review.md                        # S9 (gate 4)
├── manifest.json                    # S10 (gate 5)
├── verification.md
└── .motion-graphics-state.json      # state recovery

.motion-graphics-state.json shape:

{
  "current_state": "S5",
  "completed_states": ["S0", "S1", "S2", "S3", "S4"],
  "locked_pack": "SP-A-marshmallow",
  "review_iterations": 0,
  "last_human_gate": "S4",
  "blockers": []
}

Quality Checks

• All 5 gates either passed or were explicitly accepted with documented reason.
• Locked style pack matches every artifact: brand-board's palette, storyboard's archetype list, impl brief's effect params.
• Implementation brief's safe-area math passes at spring peaks for every text element.
• Music is real (or intentionally silent), true-peak ≤ −1.0 dBTP.
• Continuity element (if required by pack) is wired through every relevant scene as a sharedLayer.
• Review verdict is pass (or warning with explicit accept).
• manifest.json lists every atom call, gate outcome, render time, artifact path.

Failure Modes

• Pack-archetype incompatibility at S5. Impl brief halts. Either change scene's archetype in storyboard (rerun S4) or pick a different pack (re-start at S1).
• Safe-area still overflows at min fontSize. Impl brief surfaces a recommendation to break the copy onto multiple lines or shorten. User decides at gate 3.
• find-music returns no track. Block. Do not substitute a synthesized tone.
• Review verdict stuck blocked after 3 iterations. Escalate to user with summary; ask whether to ship as-is, hard-pivot a scene, or pause.
• Scene render fails (Remotion install or render error). Re-roll only that scene with --scene <id>.
• State file missing or corrupted. Re-derive state by checking which artifacts exist. The orchestrator is idempotent at every step.
• User wants a different pack mid-run. Cannot switch in place. Archive current run, start new one with intake + concept-brief reused.
• DNA-level review check fails (no continuity element when pack required one). Treat as blocked. Add the continuity element to the storyboard (S4) and regenerate the brief (S5).

Reference run

When the new system is first validated, the reference run will be skills/test-runs/<timestamp>-create-motion-graphic-video-v2/. It will reproduce the Marshmallow-style test from v1 (skills/test-runs/20260510-230705-create-motion-graphic-video/) using the new style-pack + impl-brief pipeline. Visually equivalent output is the acceptance criterion for the framework.