Motion Video Maker

motion-video-maker

A self-contained skill for authoring cinematic HTML animations and rendering them to frame-accurate MP4 video. One composition = one HTML file driven by a tiny deterministic timeline runtime.

Hard Rules — READ FIRST (non-negotiable)

These prevent the bugs we keep seeing in agent-generated videos. scripts/lint.mjs enforces most of them and exits non-zero on violations.

Run node scripts/lint.mjs path/to/index.html before rendering. Add --strict in CI so warnings also fail.

Determinism Contract

Two renders of the same HTML file MUST produce byte-identical MP4 output. The runtime + render pipeline already enforce this — but author code can break it. The rules:

1. Never call Math.random() in inline scripts. Use one of:
   • window.__mvm.random("a-stable-string-seed") → stateful PRNG function
   • window.__mvm.randomSample("seed") → one deterministic value
2. Never call Date.now() / new Date() / performance.now() for anything visible. Time MUST come from the mvm-seek event detail.
3. Never use CSS transition / animation on stage elements — those don't respect the timeline's seek mechanism, so they play in preview but appear "frozen" in the rendered MP4.
4. Never use setTimeout / setInterval to drive visuals. The renderer issues seek(t) at 30 fps step boundaries; any wall-clock-driven code will skip frames.
5. All async resources go through delayRender / continueRender:

   const h = window.__mvm.delayRender('Loading hero image');
   img.onload  = () => window.__mvm.continueRender(h);
   img.onerror = () => window.__mvm.cancelRender(new Error('hero image failed'));
   

   The renderer waits for __mvm.ready === true (i.e. all handles cleared) before screenshotting each frame; failures surface immediately with the pending handle labels printed.

Scene Transitions — non-negotiable rules

Borrowed from Hyperframes. Failing these is the #1 reason a video feels "choppy" or "broken".

1. Every scene boundary must have a <div data-transition>. Pick one of: pixel-dissolve / iris / glitch / wipe-left / wipe-right / wipe-up / wipe-down / flash. The transition straddles the cut.
2. Every text/element must have a data-animation (entrance). Don't appear out of nothing — fade, slide, drop, mask in.
3. Don't add data-animation-out to a non-final scene. The transition IS the exit. Adding an extra fade-out makes the screen go blank for ~0.3s and looks like a bug. scripts/lint.mjs flags this as E005.
4. Only the final scene may fade to opacity 0. Earlier scenes hand off via the transition; the last scene closes the video.

<!-- Scene 1 -->
<div data-background="meta-balls" data-palette="warm-glow"
     data-clip data-start="0" data-duration="5.8"
     data-animation="fadeIn"></div>   <!-- ✅ entrance only -->

<!-- Transition (bridges 5.3s → 6.0s) -->
<div data-transition="pixel-dissolve" data-start="5.3" data-duration="0.7"></div>

<!-- Scene 2 starts at 5.8s -->
<div data-background="liquid-ether" data-palette="cool-deep"
     data-clip data-start="5.8" data-duration="5.5"
     data-animation="fadeIn"></div>   <!-- ✅ no data-animation-out -->

Style Presets — 8 recipes to start from or hybridise

Each preset is a complete vibe: palette + typography + animation pattern + transition + pacing. They're not classes you import; they're templates you copy from when you want a recognisable look. Hybridise freely — use Asian Ink typography with Glitch Tech transitions, etc.

1. Cinematic Trailer

Big serif over warm darkness. Long beats, single ideas per scene. Feels like a film opening.

2. Glitch Tech / Cyberpunk

Hard cuts, electric edges, decrypting text. Reads "future" or "hacker".

3. Asian Ink / 中国风水墨

留白、宋体、行楷。Soft paper background, brushed accents, slow rhythm.

4. Data Story

Hero numbers + supporting cards. Each stat lands with weight.

5. Pop Vibrant

Saturated colors, bouncy springs, candy. Reads "consumer brand" or "playful product".

6. Minimal Editorial

90% empty space. Tiny eyebrow over a giant serif. One movement at a time.

7. Liquid Dreamy

Iridescent shaders, soft text, ethereal pacing. Reads "calm" or "luxury".

8. Documentary

Sepia-ish, slow zoom on stills, somber typography, long holds.

Hybridising — yes, do it

The presets are starting points, not boxes. Real "stand-out" videos cross-pollinate:

• "Cinematic + Glitch" — warm palette + serif type + occasional glitch transition + decrypted-text eyebrow. Hero shot stays cinematic, intro chyrons feel tech.
• "Asian Ink + Data Story" — paper background + ink red stat numbers + cn-brush labels. Annual report visual language.
• "Liquid Dreamy + Pop Vibrant" — iridescent shader + bouncy spring. Reads "beauty / cosmetics brand".

When in doubt: commit to one style for 80% of the runtime, sprinkle the other style on 1 scene as contrast. Pure-blend rarely reads.

motion-video-maker/
├── runtime/        # timeline.js, components.js, spring.js, shaders.js,
│   │               # transitions.js, effects.js, styles.css,
│   │               # contrast-check.js, layout-check.js,
│   │               # gsap-bridge.js   (← determinism bridge for GSAP)
│   └── gsap/       # gsap.min.js + every plugin we ship: CustomEase,
│                   # CustomWiggle, CustomBounce, EasePack,
│                   # DrawSVGPlugin, MorphSVGPlugin, MotionPathPlugin,
│                   # Physics2DPlugin, PhysicsPropsPlugin, Flip,
│                   # SplitText, ScrambleTextPlugin, TextPlugin
├── assets/fonts/   # 12 open-source Chinese fonts (auto-installed)
├── scripts/        # render.mjs, preview.mjs, install-fonts.mjs,
│                   # new-video.mjs, debug.mjs, snap.mjs, lint.mjs
├── templates/      # base.html, diagnostic.html, showcase.html,
│                   # effects-showcase.html (signature effects sampler)
├── examples/       # time-flies/ (30s reference)
│                   # raycast-deep-dive/    (40s v1: canvas only)
│                   # raycast-deep-dive-v2/ (40s v2: + spring + shaders + transitions)
│                   # raycast-deep-dive-v3/ (40s v3: + electric-border / image-trail / odometer)
│                   # gsap-showcase/        (42s GSAP plugin sampler — every plugin in one file)
└── reference/      # components.md, workflow.md

Creative Latitude — these are tools, not training wheels

The Hard Rules above prevent broken videos. They are NOT a recipe for good videos. Many compositions look identical because agents stop at "safe and lint-clean" instead of pushing the medium. Push the medium.

What "push the medium" means in practice:

1. Pick a STYLE first, primitives second. Don't reach for split-text

   • fadeIn + meta-balls by reflex. Decide what the video should feel like (see Style decision tree), then pick primitives that serve that feeling. The same primitive read differently in different styles — split-text at 0.04 stagger feels urgent and confident; the same animation at 0.2 stagger with springGentle easing feels meditative.

2. Combine primitives to invent new effects. Every "signature" effect in this Skill (electric-border, image-trail, odometer flip) is a composition of simpler parts. You can do the same:

   • mask-text + gradient-text on a duplicate layered behind = neon edge title that bleeds color through the negative space.
   • image-trail + a small camera-pan = parallax-feeling depth.
   • Two liquid-ether shaders with different data-palette and opposite data-scale, blended mix-blend-mode: screen = iridescent fluid impossible to get with one shader.
   • wave-text with data-amplitude="3" + springSnap = subtle "breathing" hero title for slow scenes.

3. Bend the timeline. A 30s video doesn't need 6 scenes of 5s each.

   • Cinematic trailers spend 8s on a single hero shot then sprint through 4 quick cuts in 6s.
   • Glitch / tech videos use very short clips (1.2–2s) with hard cuts between shaders + glitch transitions.
   • Editorial / minimalist videos hold one scene for 12s with a slow kenBurnsIn on the background.

4. Custom animations are welcome. If none of the built-in data-animation values fit, you can:

   • Write your own keyframe-like animation by listening to mvm-seek and applying transforms based on event.detail.time. See runtime/components.js for the pattern.
   • Use data-effect="custom" with inline style="--my-anim-progress: ..." to drive your own CSS variables off the timeline.
   • Compose multiple data-animation by nesting elements with independent animations.

5. Camera moves. Wrap a scene in <div class="mvm-cam" data-camera-zoom="1.15" data-camera-pan-x="-40" data-camera-pan-y="20"> and the whole scene slowly zooms / pans across its lifetime. Subtle camera moves are the single biggest "I am watching a film, not a slideshow" cue.

You are encouraged to read users' descriptive cues literally and translate them. "Cinematic", "elegant", "punchy", "ink wash", "data-driven", "playful", "otherworldly", "vintage", "futurist", "documentary" — each maps to a different combination of palette / typography / motion. See Style Presets for 8 ready-made recipes you can adopt or hybridise.

Style decision tree — pick by user intent

When the user describes the feeling but not the parts, use this map:

If the user mixes cues ("中国风但要现代感"), hybridise: take Asian Ink's typography + palette and Cinematic Trailer's camera moves + flash.

You decide. Don't always ask back — read the prompt for tone cues and commit to a style. Variety is the goal.

Every composition MUST include this script chain in this order:

<script src="../../runtime/spring.js"></script>       <!-- physics -->
<script src="../../runtime/timeline.js"></script>     <!-- seekable timeline -->
<script src="../../runtime/components.js"></script>   <!-- text / canvas bg -->
<script src="../../runtime/shaders.js"></script>      <!-- WebGL shader bg  -->
<script src="../../runtime/transitions.js"></script>  <!-- scene transitions -->
<script src="../../runtime/effects.js"></script>      <!-- electric / star / image-trail -->

<!-- GSAP — load any plugins you'll use BEFORE the bridge.
     The bridge tolerates missing plugins; drop ones you don't need. -->
<script src="../../runtime/gsap/gsap.min.js"></script>
<script src="../../runtime/gsap/CustomEase.min.js"></script>
<script src="../../runtime/gsap/EasePack.min.js"></script>
<script src="../../runtime/gsap/SplitText.min.js"></script>
<script src="../../runtime/gsap/DrawSVGPlugin.min.js"></script>
<script src="../../runtime/gsap/MorphSVGPlugin.min.js"></script>
<script src="../../runtime/gsap/MotionPathPlugin.min.js"></script>
<script src="../../runtime/gsap/Physics2DPlugin.min.js"></script>
<script src="../../runtime/gsap/Flip.min.js"></script>
<script src="../../runtime/gsap/ScrambleTextPlugin.min.js"></script>
<script src="../../runtime/gsap-bridge.js"></script>   <!-- MUST come AFTER gsap -->

Quick Start

# 1) One-time setup (installs Chinese fonts; idempotent)
node scripts/install-fonts.mjs

# 2) Scaffold a new composition
node scripts/new-video.mjs my-video --duration 12 --fps 30 --bg aurora

# 3) Live-preview in a browser
node scripts/preview.mjs examples/my-video/index.html
#   → http://localhost:5173/examples/my-video/index.html

# 4) Render to MP4 (frame-accurate, deterministic)
node scripts/render.mjs examples/my-video/index.html examples/my-video/output.mp4

See examples/time-flies/index.html for a complete 30-second reference composition that exercises every component.

How a Composition Works

A composition is one HTML file with three layers:

1. <div id="stage" data-*> — declares pixel size, fps, total duration.
2. [data-background] — full-bleed animated backgrounds (canvas).
3. [data-clip] — any element that appears, moves, or animates.

<div id="stage" data-composition-id="my-video"
     data-width="1920" data-height="1080"
     data-fps="30" data-duration="10">

  <div data-background="aurora"
       data-colors="#3a1c71,#d76d77,#ffaf7b"></div>

  <h1 class="title text-aurora"
      data-clip data-start="0.5" data-duration="9"
      data-text-animation="split-text"
      data-stagger="0.06" data-char-duration="0.9">你好，世界</h1>

  <p class="subtitle"
     data-clip data-start="1.4" data-duration="8"
     data-animation="fadeInUp" data-in-duration="0.8">第一帧</p>
</div>

<script src="../../runtime/timeline.js"></script>
<script src="../../runtime/components.js"></script>

The renderer (render.mjs) launches headless Chromium, sets window.__mvmRenderMode = true to suppress the wall-clock preview loop, then for every frame i calls window.__mvm.seek(i / fps) and screenshots the page. Frames are encoded to H.264 MP4 via FFmpeg.

Composition Attributes Reference

Stage (#stage)

Clip ([data-clip])

Governs visibility window and outer in/out animation of any element.

Available outer-animation presets (for data-animation / data-animation-in / data-animation-out):

Variety tip: when you have N parallel elements (cards, list items, layers), give each one a different preset from a different group — that's exactly what turns a "generic" composition into a polished one.

Text animations ([data-text-animation])

Use on the element whose text you want to animate. Combine with data-clip so the element has a defined visibility window. The text component reads data-anim-duration for its own animation length, falling back to data-duration.

Backgrounds ([data-background])

Absolute-positioned full-stage backgrounds — both Canvas2D and WebGL.

Canvas backgrounds (lighter, no GPU):

WebGL fragment-shader backgrounds (richer, real shaders — require shaders.js):

All shader backgrounds accept data-colors as 4 hex stops (e.g. "#FF6363,#FF8B5E,#FFD400,#0a0a16").

Scene transitions ([data-transition])

Place a <div data-transition="..." data-start="..." data-duration="..."> anywhere inside #stage — it auto-mounts a fullscreen overlay canvas that paints the transition over everything from start to start+duration.

The full transition window is duration; half-way through (p=0.5) the overlay is fully opaque so the underlying scenes can swap invisibly.

Effects ([data-fx])

Element-level effects ([data-effect])

Decorations that attach to an existing element and animate around it. Inspired by react-bits' ElectricBorder / StarBorder / ImageTrail.

<!-- card with electric flowing border, perfect for "chosen" highlights -->
<div class="card chosen"
     data-effect="electric-border"
     data-color="#FF6363" data-color2="#FFD400" data-color3="#5BC0EB"
     data-intensity="1.3" data-speed="1.4" data-padding="22"
     data-border-radius="18"
     data-clip data-start="2" data-duration="6"
     data-animation="pop" data-easing="springBouncy"
     style="opacity:0;">CHOSEN</div>

<!-- title with image-trail during its slide-in -->
<h1 data-effect="image-trail"
    data-trail-count="5" data-trail-stride="0.06" data-trail-decay="0.7"
    data-clip data-start="0" data-duration="4"
    data-animation="fadeInLeft" data-in-duration="0.9"
    data-easing="springSmooth">FLOW</h1>

GSAP integration — every plugin, deterministic, bridged

The runtime now bundles GSAP 3.15 plus every plugin Webflow makes free (see lineage). All of them animate on the same mvm-seek clock as the native runtime — two renders are still byte-identical.

What you get

Deliberately omitted (because they need user interaction that doesn't exist in offline render):

• ScrollTrigger / ScrollSmoother — there is no scroll
• Draggable / Observer / InertiaPlugin — there is no pointer

If you reference these, scripts/lint.mjs raises W006. Replace them with a timeline that you anchor onto gsap.globalTimeline — the bridge will seek into it on every mvm-seek.

How the bridge works (the determinism contract)

1. The bridge calls gsap.ticker.lagSmoothing(0) and removes gsap.updateRoot from gsap.ticker so GSAP's RAF clock never advances anything on its own in render mode.
2. On every mvm-seek event the bridge calls gsap.updateRoot(seekTime) — the official "drive me from a custom clock" API. Every tween, child timeline, and plugin advances to that exact absolute second. (gsap.com/docs)
3. The bridge proxies window.__mvm.easing so any GSAP ease string (e.g. "power2.inOut", "back.out(1.7)", "elastic.out(1, 0.3)") silently resolves through gsap.parseEase(...) and is then available to the native data-animation system too. So you can write data-animation="fadeInUp" data-easing="back.out(1.6)" and the runtime now understands it.
4. Anything you author with data-gsap-from / data-gsap-to / etc. becomes a gsap.fromTo(...) tween anchored at the host element's data-start + data-gsap-delay. The clip's lifecycle still owns visibility — GSAP only handles the tween itself.

Author hard-rules:

• Don't wrap gsap.to() / gsap.from() in setTimeout / setInterval / requestAnimationFrame. Wall-clock timers bypass gsap.updateRoot and produce different output every render. lint.mjs W007 flags this.
• Don't call gsap.utils.random() — it uses Math.random under the hood. Wrap with __mvm.random("seed") or pass a pre-computed deterministic value. lint.mjs W008 flags this.
• Build the timeline at parse-time; don't try to construct new tweens inside an mvm-seek handler (that fires every frame and would create thousands of tweens).

Declarative recipes — copy these

1) Drop-in tween (works on any element with data-clip)

<h1 class="title text-readable"
    data-clip data-start="2.0" data-duration="6"
    data-gsap-from='{"y":120,"opacity":0,"rotationX":-30}'
    data-gsap-to='{"y":0,"opacity":1,"rotationX":0}'
    data-gsap-duration="1.0"
    data-gsap-ease="back.out(1.4)">Hello GSAP</h1>

2) Pro SplitText (line / word / char reveal with mask)

<h1 class="title"
    data-clip data-start="0.6" data-duration="5"
    data-gsap-split="lines,words,chars"
    data-gsap-mask="lines"
    data-gsap-stagger="0.05" data-gsap-duration="0.9"
    data-gsap-y="120" data-gsap-ease="power3.out">动画引擎</h1>

data-gsap-mask="lines" clips each line to its own bounding box — characters that translate up appear "lifted" out of an invisible slot. Combine with a serif font for an editorial feel.

3) DrawSVG — animate a stroke

<svg class="logo" viewBox="0 0 1100 520">
  <path d="M 80 440 L 80 100 L 240 360 L 400 100 L 400 440"
        fill="none" stroke="#FFD400" stroke-width="4"
        data-clip data-start="6.4" data-duration="5"
        data-draw-svg="0% 100%"
        data-gsap-duration="1.6"
        data-gsap-ease="power2.inOut" />
</svg>

The path MUST have a visible stroke (CSS or attribute). Multiple paths can share data-clip data-start to draw simultaneously, or stagger them by 0.2-0.5s for a "logotype building itself" effect.

4) MorphSVG — square → triangle → star

Hide the target shapes (so they don't render their own strokes/fill), keep the visible morphing path, and animate it through targets:

<svg viewBox="0 0 540 540">
  <!-- targets are visibility:hidden so only their `d` matters -->
  <path id="shape-triangle" style="visibility:hidden"
        d="M 270 60 L 480 470 L 60 470 Z" />
  <path id="shape-star" style="visibility:hidden"
        d="M 270 60 L 320 220 L 480 220 L 350 320 L 400 480
           L 270 380 L 140 480 L 190 320 L 60 220 L 220 220 Z" />

  <!-- The visible path morphs through them. First hop is declarative,
       further hops are sequenced on a real GSAP timeline. -->
  <path id="morph"
        d="M 80 80 L 460 80 L 460 460 L 80 460 Z"
        fill="none" stroke="#5BC0EB" stroke-width="6"
        data-clip data-start="12.4" data-duration="5"
        data-morph-to="#shape-triangle"
        data-gsap-duration="1.0" />
</svg>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const tl = window.__mvmGsap.timeline({ at: 13.6 });
    tl.to('#morph', { morphSVG: '#shape-star',   duration: 1, ease: 'power2.inOut' })
      .to('#morph', { morphSVG: '#shape-circle', duration: 1, ease: 'power2.inOut' }, '+=0.4');
  });
</script>

5) MotionPath — anything along an SVG path

<svg class="track" viewBox="0 0 1280 540" style="position:absolute;top:50%;left:50%;
     transform:translate(-50%,-50%); width:1280px; height:540px;">
  <path id="rocket-path" d="M 60 480 C 260 480 360 60 640 270
                            C 920 480 1020 60 1220 60"
        fill="none" stroke="#FFD400" stroke-width="2"
        stroke-dasharray="4 6" />
</svg>

<div style="position:absolute; left:0; top:0; font-size:84px;"
     data-clip data-start="18.6" data-duration="5"
     data-motion-path="#rocke

…(truncated)