Beat-Driven Procedural Motion Graphics
Produce studio-style kinetic typography and procedural motion-graphics videos using a four-stage code pipeline:
index.html (HTML5 Canvas beat-driven renderer)
↓ frame-by-frame capture (10× shutter motion blur)
scripts/render.py (Headless Chrome CDP → ffmpeg H.264)
↓
make_audio.py (Procedural waveform & EDM synthesis on the exact same beat grid)
↓
ffmpeg mux → final.mp4 (1920×1080, 60 fps, AAC stereo)
Everything—visuals, transitions, camera shake, glitch hits, drums, chords, and risers—is scheduled by beat numbers on a single shared tempo grid (default 128 BPM). Zero manual timeline alignment, zero external stock footage, zero third-party Python packages.
Workflow
Step 1 — Environment Check
Before authoring files, verify local prerequisites:
ffmpeg/ffprobe(withlibx264andaacencoders).- Headless Chrome / Chromium binary (
Google Chromeon macOS,chromium/google-chromeon Linux). - Available system fonts matching the target script (e.g., bold geometric sans for Latin, PingFang / Hiragino / Noto Sans for CJK, monospace for HUD/code).
Step 2 — Beat-Mapped Storyboard
Convert the user's topic into a beat sheet before writing any rendering code.
- Choose duration: 15 s = 32 beats or 30 s = 64 beats at
128 BPM(SPB = 60 / 128 = 0.46875 s/beat). - Follow the narrative arc in storyboard-prompt-template.md: Hook → Tension / Contrast → Concept Visuals (Graph / Tunnel / Morph / 3D) → Rapid Build + Countdown → 0.1 s Silence Blackout → Particle Drop Finale.
- Keep on-screen copy ultra-punchy: 1–3 English hero words (200–400 px) paired with at most one short subtitle line (36–70 px). Never write paragraphs.
Step 3 — Build index.html (Visual Engine)
Create a self-contained single-file HTML5 Canvas renderer (1920×1080) that exposes:
window.READY === trueafter fonts, offscreen sprites, morph shapes, and particle targets finish initializing.window.TOTAL(integer total frame count, e.g.,900or1800).window.MB(configurable motion-blur sub-sample count, default10for final render,1for fast preview).window.frameData(frameIndex, quality)returning a JPEG Data URL for that exact frame.
Follow the visual primitives and post-processing pipeline in visual-style-guide.md.
Step 4 — Visual Still-Frame Inspection (Mandatory Gate)
Never run a full 900–1800 frame render blindly. Always capture 12–16 representative key frames first and inspect them as a contact sheet:
python3 scripts/render.py --html ./index.html --stills 60,200,330,420,560,780,920,1110,1280,1450,1560,1650,1760
ffmpeg -y -loglevel error -pattern_type glob -i 'preview/f*.jpg' -vf "scale=640:360,tile=4x4" -frames:v 1 preview/sheet.jpg
Inspect preview/sheet.jpg and verify:
- No text collides with the corner HUD (keep main content inside
y ∈ [100, 980],x ∈ [100, 1820]). - All fonts loaded properly (no tofu / fallback serif glitches).
- Contrast is legible across light and dark scenes; HUD
differenceblend stays readable. - Motion blur, glow, and particle convergence look clean and centered. Fix any layout issues and re-verify before full rendering.
Step 5 — Generate Procedural Soundtrack (make_audio.py)
Adapt make_audio_template.py to match the exact BPM, BEATS, SCENE_TRANSITIONS, and DROP_BEAT used in index.html. See audio-synthesis-guide.md for synthesis rules.
Verify the generated music.wav before muxing:
- Duration matches
BEATS * 60 / BPMexactly. - Render a spectrogram (
showspectrumpic) or per-second RMS check to confirm clean dynamics, clear beat structure, and the ~0.1 s pre-drop silence gap.
Step 6 — Full Render & Mux
- Render all frames at 60 fps with
MB=10motion blur:python3 scripts/render.py --html ./index.html --out video.mp4 --mb 10 - Mux video and audio with stream copy on video:
ffmpeg -y -loglevel error -i video.mp4 -i music.wav \ -c:v copy -c:a aac -b:a 256k -shortest final.mp4 - Run a final
ffprobe+ 6-frame contact sheet check onfinal.mp4to confirm1920x1080,60 fps,h264 + aac, exact duration, and clean output.
Hard Constraints & Engineering Rules
- Single Beat Clock: Both
index.htmlandmake_audio.pymust derive time strictly frombeat = t / (60 / BPM). Never hardcode magic millisecond offsets that can drift from the music. - Deterministic Rendering: Use a seeded PRNG (e.g.,
mulberry32) keyed on frame/element index—neverMath.random()inside the render loop—so 10× motion-blur sub-samples stay coherent without chaotic flickering. - 10× Shutter Motion Blur: Average
10sub-frames across a0.75-frame shutter window (alpha = 1 / (k + 1)accumulation). Fewer than 8 samples creates stepped ghosting on fast kinetic typography. - Zero-Dependency Python:
render.pyandmake_audio.pymust use Python standard library only (os,json,subprocess,base64,math,random,wave,array) so they run anywhere withoutpip installornumpy. - Pre-bake Expensive Glows: Avoid calling
ctx.shadowBlurper frame across 10 motion-blur passes on complex text/cards. Pre-render glowing hero sprites onto offscreen canvases duringinit()or use stacked low-alpha strokes (glowStroke). - Pre-Drop Silence: Insert ~
0.10 sof total visual blackout and total audio silence immediately before the climax drop beat to maximize perceived impact. - Factual Discipline: If the video presents real-world product/technical claims, verify facts first and omit unconfirmed numbers (such as conflicting pricing or unverified benchmark percentages).