---

name: motion-design description: Code-only motion design pipeline (no After Effects) for Raphaël / Howseen: launch films, showreels, product promos, LinkedIn/X videos, meme clips. Use when asked to make a motion design video, a promo/launch film, a showreel, "remake this video", a video from a prompt (e.g. "make a 15s motion graphics video…"), to change a video's music/SFX, or to prepare memes for posts. Covers the brief → beat map → stills → seek(t) HTML engine → Playwright render → ffmpeg → music/SFX → QA flow, plus asset sourcing (Mixkit, Pexels, Unsplash, svgl, 21st.dev) and every gotcha hit so far.

Motion design, 100 % code (Howseen pipeline)

Built and battle-tested 25-27/09/2026 on: promo60 (60 s VO ad), loop, launch film, showreel v1/v2, frame. (Apple-keynote prompt), Crave (food-app prompt), reel15 (howseen.ai in 1 prompt + "make it better" pass), Baguette Pro (Apple framework parody), Howseen LinkedIn v1→v5 (4:5). Workdir: ~/Desktop/Howseen AI/howseen-video/ (one folder per film). Every film folder = <name>.html + render.py + audio.py + out/.

Our stack vs the "AI motion" stack people post (Opus + Higgsfield + Blender + After Effects + Suno + Soundly): we replace Blender/After Effects with a deterministic HTML engine rendered frame by frame, Higgsfield with real stock (Pexels/Unsplash) or coded visuals, Suno with Mixkit music, Soundly with Mixkit SFX. 0 € and fully reproducible. Suno/Envato/Higgsfield only if Raphaël asks and has credits.

00. Start from the library (fastest path)

• Read howseen-video/INDEX.md first: every film we made, its final file and what to reuse. Copy the closest folder instead of starting from zero.
• Brief given as frame tables (f0–fN, hard cuts, per-frame px lists, "motion law p(n)=…"): copy launch20/ (02/10/2026). It has the frame-number engine (core.js: T/L/kf registered tables, law(), settleT/exitT/joinT, scanTables() that blocks one-frame outliers, makeField colour field, makeBadge, macOS cursor), fictional Mac apps in em units (ui.js: chat, call, notes, files, board, dock icons, lineIcon set, tx helper), shot registry split in files so 3 agents build shot groups in parallel (one file each), render.py (deviceScaleFactor 2 = 4K, PROBE=<dir> per agent, frames a b in 3 parallel processes, encode with frame count check, no -shortest), audio.py (music + SFX 100 % synthesized on exact frames, two-pass −14 LUFS / TP −1.3).
• Workflow that worked on launch20 (≈2 h brief → v2): inputs (AskUserQuestion) → 4 stills → BRIEF.md in the folder → 3 build agents + 1 side task in parallel → scan → parallel render → encode → motion critic + design critic as separate read-only agents (default reject) → FIXES file split per agent → v2.
• Lessons from the critics (apply from the first pass): never key settles in 3-frame steps (per-frame law, fastest step first), exits geometric ×1.5, no frozen frame anywhere except the final hold (keep a micro settle/drift alive, also on still end cards), the next shot enters already moving in the exit's direction, real icons (no empty placeholder squares), one face per name everywhere, grade photos to remove banned hues with a continuous per-pixel formula (hue thresholds blotch JPEG blocks), traffic lights/details sized in the component's em units.
• People in fictional UIs: AI-generated faces (thispersondoesnotexist.com/random-person.jpeg, crop centre 76 % to drop the watermark), names chosen to match each face, never a real person. Photos: picsum (Unsplash licence) when Unsplash napi returns 401; build a contact sheet and pick by eye (an agent can do it).

0. Non-negotiables

• Zero fabrication on screen: real data is sourced on screen (e.g. "12 logged-out ChatGPT answers · 25 Sep 2026"); anything illustrative is labelled "Example data" / "Example answer" / "Illustration". Never claim product features that don't exist (check the app code). Native CMS = WordPress, Shopify, Ghost, BigCommerce; others "via webhook".
• Captions must stay true: no "made in 10 minutes" if it wasn't, no "0 external tools" if Cartesia/Mixkit were used, no "one shot" after iterations. Mixkit SFX are placed by code, not generated.
• Illustrations/covers: no Howseen name/logo in AI-generated images (rule 25/09). Howseen can appear in our own coded promo films.
• No em/en dashes in any copy we write.

1. Flow (always in this order)

1. Inputs: if the brief has an <inputs> block, ask for them (AskUserQuestion, recommended defaults first). Otherwise pick sensible defaults and say so.
2. Beat map (BEATMAP.md): BPM → beat length, every scene on a beat, the music drop on the key visual moment (flood, logo, big reveal). Nothing still for > 1 s.
3. 4 stills (or a one-frame-per-beat sheet) → look at them (Read) → fix → only then the full render.
4. Full render → pops scan → audio → mux → open -R the file and give the path + a true caption.

2. The engine (one HTML file)

• Everything computed from time inside window.seek = async (t) => {…}; no CSS transitions, no timers, no state between frames. Declare all constants before the first seek(). Set window.ready = true after fonts/images load.
• Springs = closed-form step response step(tau, f, z); a value with many targets = sum of one spring per change. Easings: io (cubic in-out), out, in, o5, expo. Linear motion = cheap, never.
• Camera = one transform on a container, keys [t, zoom, x, y], eased segments, zoom interpolated in log space, never zoom in/out back-to-back. Beat punches: +0.012 per beat, +0.03 per bar after the drop, exp decay.
• Shared elements for every handoff (the bubble carries its words into the flood, the button carries its label into the page). Text that swaps inside a morphing shape gets its own mask.
• Masked text rise (translateY 105% inside overflow:hidden), word-by-word stagger (55 ms) with a small rotation; accent words with a moving gradient (background-clip:text).
• Floods: circle from the source object, must clear the farthest corner (hypot to the 4 corners ×1.05) in ~0.3-0.35 s, then contract into the next object.
• Glass / goo / iris / variable-font squeeze / 3D cube / equalizer / blob mask / animated beam / border beam: reference implementations in frame/frame.html (liquid glass via canvas displacement, goo, 6-blade iris, Archivo wdth squeeze), reel2/reel2.html (morph shapes, cube, EQ, blob), h20/h28.html (21st.dev Animated Beam + Border Beam ported to seek(t), dotted grid, drifting blobs, sheen sweep, sparkles).
• z-index on every layer. visibility:inherit (not visible) on children of hidden parents.
• Look: warm off-white #f5f5f2/#f7f7f5 or ink #0b0b0c; Howseen sky #38bdf8, ink #0f172a, lime #cdf24f, orange #ff6a2a, violet #a78bfa. Fonts in crave/fonts/geist-latin.woff2, frame/fonts/archivo-var.woff2 (wdth 62-125), crave/fonts/instrument-serif.woff2.

3. Render (scripts/render_template.py)

• Serve the folder over HTTP (python -m http.server 876x --directory …, background), Playwright Chromium, viewport = video size (1920×1080, 1080×1350 for LinkedIn 4:5, 1440×1440 square).
• probe t1 t2… → probe/sheet.png; beats → one frame per beat; draft → 30 fps, 1 capture/frame, 960×540, crf 23 veryfast (always before the master: judge rhythm, not sharpness); full → N subframes per frame blended with tmix (6-8 for fast moves, 4 = ghosting) spread over SHUTTER = 0.5 of the frame (180° film shutter; 1.0 = smeary), 60 fps; pops → frame-diff spikes > 3× neighbours (intentional beat cuts show up too: say so, don't hide); loop → seam check in position (last vs frame 0) AND velocity (motion into vs out of frame 0).
• Capture hygiene (built into the template): wait document.fonts.ready, pause document.getAnimations() and kill CSS transitions after load, and wait 2 requestAnimationFrame after every seek(t) before the screenshot. WEBGL=1 launches Chromium with SwiftShader/ANGLE flags (headless WebGL otherwise renders black).
• Every film page also gets preview controls for Raphaël: Space = play/pause, ←/→ = previous/next frame, R = replay, a time readout. Playback calls the same seek(t) from a rAF loop (the only place a clock is allowed); the render never touches it.
• Films > 25 s: always render in 3 parallel chunks (h20/lm55/render_par.py chunk <html> <T> k 3 x3 in background, then concat): ~20 min for 55 s instead of ~55 min sequential. Raphaël expects fast turnarounds; never launch a long single-process full render. Re-render only the changed seconds when possible (part).
• Use a separate sub*/ folder per version so parallel renders don't clash. ~1-1.5 min of wall time per second of film at 8 subframes; run long renders in the background.
• Final encode: scale=in_range=pc:out_range=tv:out_color_matrix=bt709,format=yuv420p, -color_range tv -colorspace bt709, libx264 crf 16, AAC 256k, +faststart.

4. Music & SFX (scripts/audio_template.py, analyze_song.py)

• Music = Mixkit (free commercial). Direct file: https://assets.mixkit.co/music/<id>/<id>.mp3. IDs: grep music/[0-9]+/[0-9]+\.mp3 in the listing page HTML (page order = WebFetch list order).
• Used & measured: audio/mixkit-207.mp3 120 BPM (drop song 31.97 s), mixkit-190 120 BPM (drop bar 8 = 16.01 s), mixkit-129 120 BPM (drop 16.09 s), minimal-techno-01 119.99 BPM (true drop 39.98 s, auto grid is 2 beats off), Cat Walk (Arulo #371) 130 BPM drop 14.769 s (crave/assets/audio/cat-walk.mp3), Waka Floka Type (Arulo #364, trap/US rap) drop 14.75 s (reel2/assets/m364.mp3), Driving Ambition (#32, piano uplifting ~99 BPM) hit 37.66 s, Classical vibes 4 (#684, Apple-ish classical ~94 BPM) lift ~7.95 s, Head Bang (#357, hip-hop half-time 74 BPM, 4-bar quiet intro, drop 12.96 s = beat 16; used by the viral "STOP PAYING FOR MOTION DESIGN SOFTWARE" loop prompt). Mixkit search ignores ?q=: crawl genre pages (/free-stock-music/<genre>/) and match item-grid-card__title to music/<id>/<id>.mp3. Leo's framework: 60-80 BPM regal, 90-110 smooth, 115-123 elite/sophisticated, > 125 hype.
• Find the drop by energy, never trust an auto grid: per-bar low/full band energy, then 20-50 ms windows around the jump. Start the song at drop_in_song - drop_in_film.
• SFX = Mixkit, downloaded to howseen-video/sfx/ (https://assets.mixkit.co/active_storage/sfx/<id>/<id>-preview.mp3); search with scripts/mixkit_sfx_search.py <tag>. Map so far: click 1125, key 2568, soft tick 1117, check 1113, toggle 1120, toast 2573, pop 2364 / bubble 2357 / soap 2925, whoosh w1490, rise w1489, flip w1485, impact 1143, shutter 1430 / lens 1433, sparkle 3083, success 2865, bread crunch 118.
• Place every SFX by its measured peak (argmax of |s|), gain 0.04-0.3, keystrokes follow the same per-character rhythm as the typing animation. Fade the tail, two-pass loudnorm to −14 LUFS. Voice-over: Cartesia (Katie) with word timestamps → cues.json (promo60), music ducked ~9 dB under the voice.
• Minimal sound design for "premium/Apple" films: a handful of soft hits, remove anything that feels loud or out of place.

5. Assets

• Photos: Unsplash https://unsplash.com/napi/search/photos?query=…&per_page=30 (curl ok) → urls.raw + &w=2600&q=85&fm=jpg; Pexels CDN https://images.pexels.com/photos/<ID>/pexels-photo-<ID>.jpeg?auto=compress&cs=tinysrgb&w=1600 (search pages block curl: use WebFetch/WebSearch for IDs). Always build a contact sheet and look at it before using. Cutouts from dark backgrounds: luminance+warmth alpha, largest component, trim 5 px (see baguette/assets/hero_cut_3k.png).
• Video: Mixkit assets.mixkit.co/videos/<ID>/<ID>-1080.mp4, Pexels pexels.com/download/video/<id>/. Re-encode all-intra (-g 1), load as blob URL, await seeked.
• Logos: scripts/svgl_logos.py (svgl.ap