Project Overview and Architecture
Vincentwei1021/mg-styles-15 publishes 15 motion-design (MG) short films, style notes, complete prompts, and full source code (verified at commit 49052d80bfaf9fa8412cc9710530e5e95a3b8d8c). All 15 10-second (10.000 s) films are produced by Claude Opus 5.5 writing code from prompts—covering visuals, easing choreography, musical arrangement, and sound-effect sync without calling image or video generation models.
Each film is a web page with a deterministic time function window.renderAt(t) (demos/<slug>/index.html) that draws the frame for any time t in seconds; 04-3d-render is the sole exception, where Blender 5.1 (Cycles) renders the frame sequence and the web page composites typography and grain. Soundtracks are synthesized by each film's audio.py using the lib/audio (mgaudio) toolkit and 103 CC0 VCSL instrument samples, while harness/render.mjs captures frames in headless Google Chrome and muxes them via ffmpeg into -14 LUFS H.264 MP4 files.
Stage 1 · Style Prompts and Timeline Definition: prompts/*.md & cues.json
- Fixed output spec: 1920x1080 or 1080x1920, 30 fps, 10.000 s, -14 LUFS
- Creative seed story beats and Signature features visual constraints
- Shared timing sheet cues.json synchronizing visual hits and audio triggers
Stage 2 · Deterministic Picture and Audio Code Synthesis: demos/<slug>/
- Web page implements time render function and ready flag: SVG, Canvas, WebGL, Three.js
- 04-3d-render renders frame sequences via Blender scripts before web type and grain compositing
- audio.py loads the mgaudio toolkit and 103 VCSL samples to export 24-bit audio.wav
Stage 3 · Headless Frame Rendering and Independent AI Jury: harness/ & rubric.md
- harness/render.mjs captures frames via Puppeteer and headless Chrome with tmix motion blur
- ffmpeg encodes libx264, CRF 14, bt709, and AAC 320k into video.mp4
- Independent AI session scores 7 dimensions via rubric.md across 2 revision rounds
Starting from a style prompt, both picture and soundtrack operate as deterministic functions of time t, enabling exact frame reproduction and automated review iterations.
Overview of the 15 Motion Design Styles and Technical Routes
The repository includes 15 style prompts (prompts/*.md) and matching source directories (demos/*). Every film went through 2 rounds of independent AI review and revision under rubric.md, scoring between 7.57 and 8.21 out of 10:
| Order | Directory Slug | Style Name | Demo Film Subject | Core Visual and Motion Characteristics |
|---|---|---|---|---|
01 | 05-cel-boil | Frame-by-Frame / Line Boil | Handcrafted HAND MADE | Hand-drawn texture, boiling line contours (Line Boil), and cel-animated pacing |
02 | 03-isometric | Isometric 2.5D | ISOPOLIS | Isometric projection view, modular building growth, and spatial layering |
03 | 01-flat-vector | Flat Vector | popwise — One Dot | Solid geometric color blocks, limb rig rotations, elastic overshoot, and shape wipes |
04 | 02-line-art | Line Art | ATELIER LINEA | Continuous stroke path drawing, variable line weight, and unbroken line composition |
05 | 04-3d-render | 3D Render | soft. — Soft Landing | Blender Cycles inflated letter meshes, collision simulation, and soft studio lighting |
06 | 08-morph | Shape Morph | morphe. | Smooth cross-object path interpolation (Shape Morph) and continuous subject transitions |
07 | 19-paperclip | Sticker Explainer MG | Smartphone chemical elements explainer | Bold-outlined sticker characters, high-density infographics, and explainer pacing |
08 | 22-hud | Cyberpunk HUD / FUI | KESTREL-9 · Target Acquired | Tactical interface overlays, Natural Earth map data, scanlines, and target lock telemetry |
09 | 06-collage | Collage / Cut-out | NOGGIN Quarterly | Magazine paper cut-outs, segmented photos, stop-motion stepped timing, and paper grain |
10 | 12-aurora-glass | Aurora & Glassmorphism | Aurora | Custom GLSL shaders, diffused aurora gradients, frosted glass refraction, and clean type |
11 | 09-bauhaus | Geometric Bauhaus | KONSTRUKTION · 20 Beats | Primary-color geometric construction, strict grid alignment, and 20-beat mechanical sync |
12 | 10-synthwave | Retro 80s Synthwave / VHS | NEON DRIVE · 1986 | Neon perspective grid, segmented sun scanlines, VHS tape noise, and synthwave drive |
13 | 20-pixel | Pixel Art | PIXEL QUEST | Integer-scaled pixel grid, 8-bit chiptune audio synthesis, and retro game transitions |
14 | 07-liquid | Liquid Motion | drop. | Surface-tension metaball fusion, droplet splash physics, and fluid wipe transitions |
15 | 18-hanazi | Variety Captions | Miaowu Diary EP.07 · 9:16 Vertical | 9:16 vertical framing, multi-stroke variety show captions, bouncy SFX, and rapid cuts |
Environment Requirements and Installation
Running the source renderer and soundtrack synthesizer locally requires Node.js 22.12 (or later), Python 3.11 (or later), Google Chrome, and ffmpeg. Re-rendering the 3D frame sequence for 04-3d-render additionally requires Blender 5.1.
Step 1: Clone the Repository and Install Node.js and Python Dependencies
Run the commands below in your terminal to install frontend and rendering packages (puppeteer-core, three, d3, opentype.js, simplex-noise, topojson-client) alongside audio and asset-preparation packages (numpy, scipy, soundfile, numba, pedalboard, pyloudnorm, librosa):
git clone https://github.com/Vincentwei1021/mg-styles-15.git
cd mg-styles-15
npm install
pip install -r requirements.txtStep 2: Verify Headless Chrome and ffmpeg Availability
On macOS, harness/render.mjs defaults to /Applications/Google Chrome.app/Contents/MacOS/Google Chrome. On other operating systems or custom install paths, export the MG_CHROME environment variable:
export MG_CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
ffmpeg -versionStep 3: Populate Local Font Files (Optional for Exact Lettering Parity)
Because font licenses vary and CJK font files are large, font binaries are omitted from the repository. To match the lettering of the published films, place Alibaba PuHuiTi, HarmonyOS Sans SC, Inter, DM Sans, JetBrains Mono, and the remaining listed fonts into assets/fonts/cjk/ and assets/fonts/latin/ per assets/fonts/README.md (03-isometric, 07-liquid, 08-morph, and 10-synthwave also load static font weights inside their own directories).
Core Skills and Toolchain
The project includes tools for prompt authoring, audio synthesis, timeline scrubbing, headless frame rendering, and AI jury evaluation.
Phase 01 · Prompt Reuse
prompts/<slug>.md
15 structured director prompts ready for AI coding agents
Each prompt defines the fixed Output spec, Suggested technical route, second-by-second Creative seed beats, and testable Signature features so you can swap in custom brands and copy while preserving style recognition.
Phase 02 · New Style Authoring
template.md
4-section prompt template for defining new motion-design styles
Separates shared production rules (How to work, Rules, Craft checklist, Deliver) from style-specific blocks; fill in Style, Output, Suggested technical route, Creative seed, and Signature features to specify a new style.
Phase 03 · Deterministic Audio
python3 demos/<slug>/audio.py
Programmatic music and SFX synthesis built on mgaudio and 103 recorded samples
Includes 15 genre recipes (synthwave, darksynth, chiptune, techno, pop, future_bass, lofi, ambient, variety, explainer, and more) and 12 SFX families, mastering output to -14 LUFS integrated and <= -1 dBTP.
Phase 04 · Interactive Scrubbing
harness/preview.html?demo=<slug>
Browser timeline scrubber and frame inspector
Loads any target demo over a local HTTP server and invokes window.renderAt(t) as you drag the timeline, letting you inspect composition, kerning, and safe margins before launching a full render.
Phase 05 · Headless Frame Renderer
node harness/render.mjs demos/<slug>
Puppeteer headless Chrome frame capturer and ffmpeg muxer
Waits for window.__ready === true and document.fonts.ready, supporting multi-worker parallel segment rendering, tmix sub-frame motion blur, PNG still extraction (--stills), and Fritsch-Carlson time-warp curves (--tmap).
Phase 06 · AI Jury Loop
rubric.md
7-dimension scoring rubric and 2-round revision prompts
Instructs an independent AI session to extract 0.5-second contact sheets and full-resolution key frames, score 7 dimensions from 1 to 10 (style_fidelity, concept_wow, motion_craft, and others), and return 5 to 10 timecoded fixes.
Common harness/render.mjs CLI Flags
| Flag | Default | Description |
|---|---|---|
--w / --h | 1920 / 1080 (or window.DEMO) | Output frame width and height in pixels |
--fps / --duration | 30 / 10 | Output frame rate and duration in seconds |
--mb / --shutter | 1 / 0.5 | Sub-frame motion-blur sample count (for example --mb 4) and shutter angle fraction |
--workers | 1 | Number of independent headless Chrome instances rendering frame chunks in parallel |
--stills | None | Comma-separated timestamps in seconds (for example 0.5,2,4.25) to export out/stills/*.png stills |
--scale | 1 | Overrides deviceScaleFactor (for example --scale 0.5 for fast low-resolution previews) |
--crf | 14 | libx264 constant rate factor quality setting |
--noaudio / --audio | Auto-detects out/audio.wav | Disables audio muxing or specifies a custom WAV file path |
--mkv | None | Outputs lossless ffv1 MKV video without x264 encoding or audio muxing |
Power Tips
The practices below are distilled from README.zh-CN.md, template.md, rubric.md, and lib/audio/README.md.
Keep Signature features Intact When Customizing Creative seed
In every prompts/*.md file, only Creative seed describes the specific story, brand name, copy, and palette. When substituting your own content or switching Output to 1080x1920 vertical format, keep the Signature features block intact—explicit easing curves such as cubic-bezier(0.34,1.56,0.64,1) and 2–4 frame stagger rules are what make the style recognizable.
Inspect 6 to 10 Poster-Grade Stills with --stills Before Animating
Step 2 of the prompt workflow mandates Key frames before motion. Run node harness/render.mjs demos/<slug> --stills 0.5,1.8,3.5,5.0,6.8,8.5 to inspect kerning, line-height, 5% safe margins, and negative space as static PNGs before refining motion curves.
Pass Visual Event Timestamps Directly to mgaudio Sync Points
Every sfx function in lib/audio embeds a perceptual sync point: impacts align on the initial transient, whoosh aligns on the center pass-by peak, and riser or reverse_cymbal aligns on the final hit. Pass visual timestamps from cues.json directly to at=t in audio.py without manually subtracting lead-in offsets.
Run the 2-Round rubric.md Review in a Separate AI Session
Initial renders typically score between 5 and 7 (student to template level). Hand the rendered video.mp4 to an independent AI session with rubric.md to inspect 0.5-second contact sheets and key frames, generate 5 to 10 timecoded fixes with concrete parameters, and iterate for 2 rounds.
Worked Example
This walkthrough synthesizes the soundtrack for 01-flat-vector (popwise — One Dot), extracts key still frames, renders the 10-second MP4 film, and launches the browser timeline scrubber locally.
Step 1: Synthesize Deterministic Music and Sound Effects (audio.py)
Run demos/01-flat-vector/audio.py from the repository root; the script reads frame cues from demos/01-flat-vector/cues.json and exports a 24-bit WAV file via lib/audio:
python3 demos/01-flat-vector/audio.py
ls -lh demos/01-flat-vector/out/audio.wavStep 2: Extract Key PNG Stills and Render the Full MP4 Film
Use --stills to inspect key timestamps and confirm layout and font loading, then render 300 frames (1920x1080, 30 fps, 10.000 s) and mux out/audio.wav:
node harness/render.mjs demos/01-flat-vector --stills 0.5,2.0,4.5,6.5,8.8
node harness/render.mjs demos/01-flat-vectorStep 3: Start a Root HTTP Server and Open the Timeline Previewer
Because asset paths inside each demo (/assets/... and /node_modules/...) resolve relative to the repository root, start the static HTTP server from the root directory and open harness/preview.html:
python3 -m http.server 8000
# Open http://localhost:8000/harness/preview.html?demo=01-flat-vectorStep 4: Run mgaudio Audio Quality and Hit-Alignment Checks
Run the mgaudio CLI module to generate a spectrogram PNG and verify integrated loudness (-14 LUFS), true peak (<= -1 dBTP), and onset alignment against visual hit timestamps:
PYTHONPATH=lib/audio python3 -m mgaudio demos/01-flat-vector/out/audio.wav --png demos/01-flat-vector/out/spec.png --hits 0.5,0.8,1.33,5.0,8.0Gotchas & Warnings
Next Path
After exploring mg-styles-15 local rendering and prompt structure, continue with these manuals to extend motion-design workflows into AI storyboard generation, interactive art-motion web experiences, or automated video pipelines:
HuaShu AI Art and Motion Design Skills (
skills-atlas-huashu-art-motion): Covers 53 art style recipe cards, 9 explainer animation grammars, and 17 Canvas/SVG visual libraries rendered with Playwright that pair with the code-driven rendering pipeline inmg-styles-15.AI Pose Gallery Prompt Library (
skills-atlas-ai-pose-gallery-zh): Provides structured character pose and camera-framing prompts useful as visual storyboards for character-driven MG or collage animations.Digital Human Talking-Head Pipeline (
skills-atlas-digital-human-koubo): Combines Renoise MCP talking-head generation,whisper.cppword-level timestamp alignment, and Remotion 4 visual packaging (5 templates and 48 packaging components) so 10-second title sequences frommg-styles-15can be embedded into talking-head videos.