Communitygithub.com

Beat Motion Graphics

Generate a 15- or 30-second beat-locked motion-graphics short from code: procedural Canvas pictures, headless Chrome frames, and a synthesized soundtrack, with no stock assets.

What is Beat Motion Graphics?

A code-only motion-graphics pipeline for promo, explainer, launch, or showcase spots at 1080p60. Visuals are procedural HTML5 Canvas, frames are captured headlessly, and the soundtrack is synthesized to the beat instead of imported. Nothing depends on a stock library or a timeline editor.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/cccPhoenix/beat-motion-graphics/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:

  1. ffmpeg / ffprobe (with libx264 and aac encoders).
  2. Headless Chrome / Chromium binary (Google Chrome on macOS, chromium / google-chrome on Linux).
  3. 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 === true after fonts, offscreen sprites, morph shapes, and particle targets finish initializing.
  • window.TOTAL (integer total frame count, e.g., 900 or 1800).
  • window.MB (configurable motion-blur sub-sample count, default 10 for final render, 1 for 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 difference blend 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 / BPM exactly.
  • 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

  1. Render all frames at 60 fps with MB=10 motion blur:
    python3 scripts/render.py --html ./index.html --out video.mp4 --mb 10
    
  2. 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
    
  3. Run a final ffprobe + 6-frame contact sheet check on final.mp4 to confirm 1920x1080, 60 fps, h264 + aac, exact duration, and clean output.

Hard Constraints & Engineering Rules

  1. Single Beat Clock: Both index.html and make_audio.py must derive time strictly from beat = t / (60 / BPM). Never hardcode magic millisecond offsets that can drift from the music.
  2. Deterministic Rendering: Use a seeded PRNG (e.g., mulberry32) keyed on frame/element index—never Math.random() inside the render loop—so 10× motion-blur sub-samples stay coherent without chaotic flickering.
  3. 10× Shutter Motion Blur: Average 10 sub-frames across a 0.75-frame shutter window (alpha = 1 / (k + 1) accumulation). Fewer than 8 samples creates stepped ghosting on fast kinetic typography.
  4. Zero-Dependency Python: render.py and make_audio.py must use Python standard library only (os, json, subprocess, base64, math, random, wave, array) so they run anywhere without pip install or numpy.
  5. Pre-bake Expensive Glows: Avoid calling ctx.shadowBlur per frame across 10 motion-blur passes on complex text/cards. Pre-render glowing hero sprites onto offscreen canvases during init() or use stacked low-alpha strokes (glowStroke).
  6. Pre-Drop Silence: Insert ~0.10 s of total visual blackout and total audio silence immediately before the climax drop beat to maximize perceived impact.
  7. 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).

Related Skills