risingjerry/motion-skill

Code-Driven Motion Graphics Shorts (motion)

The video is written in code: every frame is computed from the time variable t, so "make this section slower" is just changing one number and re-rendering — no need to reshoot. No AI image or video generation models are used; everything on screen comes from real assets or code.

Choose Your Production Tier

All three tiers follow the same workflow, but each progressively mimics real-life shooting and takes longer. Pick the one that fits your video; you can mix tiers.

Tier	What You See	Best For	Starting Point
1. 2D Motion	Real logos, real screenshots, shapes morphing	App, software, brand intros	templates/2d.html
2. Browser 3D	Interface cards in 3D space, camera fly-throughs; silhouette-to-live footage	Multi-screen UI showcases, videos with live footage	templates/3d.html, scripts/silhouette.py
3. Blender Studio	Physical product model, one light, realistic materials	Physical products like headphones, phones, cups	scripts/blender/studio.py

Detailed explanation: references/layers.md.

Workflow (in order, no skipping)

1. Clarify requirements; gather real assets. What is the product? Who is the audience? How long? Which platform? What should viewers do at the end? Always use genuine materials: Official logo files, real device screenshots (first remove notifications, avatars, phone numbers), brand colors and fonts. Do not use app store promo images as UI; do not draw logos from memory. For physical products, ask for multiple photos from different angles — preferably photos the user took themselves — to later compare with the model.
2. Define the ending. The ending should only show the icon and wordmark (or cut to live footage). No "Download Now" or "Open XX" slogans, and no "concept piece" disclaimers (include those in the description instead).
3. Produce a numbered storyboard; get client approval. 5–10 shots, each describing: time range, visuals, action, how it transitions to the next shot, and on-screen text. Write shots.json, run node scripts/render.mjs board shots.json board.png to generate a visual board. Do not proceed to final production until approved — changes are cheapest here. Format in references/storyboard.md.
4. Build the page. Copy the template and templates/motion-kit.js into the assets folder. All beats are defined in the BEATS array at the top of the page; to change pacing, edit only this array. Page conventions in references/html-engine.md.
5. Frame-by-frame self-review before sharing. Use render.mjs still to extract key moments (3–4 frames per transition, not just the resting state), then scripts/sheet.py to compile them into an image and review yourself. Then run the checking scripts:
   • render.mjs probe + scripts/layout_check.py probe: text must be at least 40 px from the subject (4K); subject near the center.
   • 3D: scripts/blender/motion_check.py (clipping, max 6° rotation per frame, no sudden speed changes), scripts/seam_check.py (seam gap ≤ 1 px). Full checklist in references/checklist.md.
6. Export only 4K. node scripts/render.mjs video page.html film-name-4K.mp4 --scale 2 (1920x1080 page → 3840x2160). Only one 4K render or Blender render at a time per computer. Extract frames for review from the 4K final: python3 scripts/sheet.py video ....
7. Add sound only after picture is locked. Any picture change shifts all beats. Both music and sound effects are required; the music's strongest beat must align with the key visual moment; overall -14 LUFS, true peak max -1 dBTP; video stream copied without re-encoding. See references/sound.md.
8. Revisions. Back up before each round, re-check frames after changes, explain changes in plain language. Save as new version; do not overwrite or delete the client's files. Be honest about what was checked: stills are not playback, viewing images is not listening to the mix.

Rules for Good-Looking Videos

Full explanation in references/transitions.md and references/blender-3d.md. These are must-remembers:

• Each shot emerges from the previous one. No fades, no cross dissolves. The same object morphs, flips, unfolds, or retracts — the viewer's eyes never have to search for a new focal point.
• Action stays in the center. Imagine a crosshair at the center of the frame; the main subject is always near it.
• The frame is always moving. Even stationary shots have a very slow push-in or drift.
• One motion follows one curve. Push in all the way; don't push then pull. Rotate in one direction; don't rotate partway then reverse. Start fast, end slow; give the slowdown ample time.
• Text should be concise, fade in from blurry to clear — no bouncing, no sudden enlargement. Text must not overlap the subject.
• 3D uses only one light with a black background. This is the main reason it looks like a studio shot.
• 3D must be physically plausible: lid closes seamlessly; objects do not clip through each other; two objects swap positions via 3D orbit, not straight-line intersection; rotation speed is smooth, no jumps.
• Compare the model with real product photos — if proportions, corner radii, or port positions are wrong, fix the model.
• Silhouette transition starts from an extreme close-up, then pulls back before a hard cut to live footage. See references/silhouette.md.
• Audio and video shift together globally; no speed or pitch changes.

Rules to Follow

• Branding: Only work on brands that the client owns or has permission to use. Other brands are for practice only — do not impersonate official accounts, run ads, or mimic their real campaigns.
• Assets: Use only assets, fonts, music, and models that the client created or has a license for; confirm the license covers this usage.
• Claims: Every number and claim in the video must be truthful and sourced; do not fabricate data or reviews.
• Privacy: Remove personal information from screenshots and live footage; obtain consent from people appearing on camera.
• Paid services (voiceover, AI music, etc.) will use the client's credits — use them only when requested.

Script Overview

Script	Purpose
scripts/render.mjs	HTML page → stills / 4K mp4 / position records (probe) / storyboard (board)
scripts/sheet.py	Extract frames at time intervals from stills or final video → a single time-stamped check image (extracted from original resolution)
scripts/layout_check.py	Check text-to-subject distance and subject centering
scripts/seam_check.py	Seam misalignment (in pixels) between two parts as seen from the actual camera angle
scripts/blender/studio.py	Single-light studio scene + EEVEE/Cycles rendering; accepts GLB/glTF/USDZ/OBJ/FBX; --demo includes a sample model
scripts/blender/motion_check.py	Per-frame clipping, angular velocity, and sudden speed changes
scripts/silhouette.py	Person masking (macOS Vision, optional) → smooth vector silhouette, can pull back from close-up
scripts/audio/synth.py	Code-synthesized sound effects and backing track (royalty-free)
scripts/audio/mix.py	Align music to key moments, place sound effects on beats, sidechain ducking, loudness normalization, final mix into video
scripts/encode.py	PNG frame sequence → mp4
scripts/doctor.py	Check dependencies — what's missing and how to install it

Which File to Read When

You are…	Read
Choosing a tier or estimating effort	references/layers.md
Writing a storyboard	references/storyboard.md
Writing an HTML page and rendering	references/html-engine.md
Designing transitions between shots	references/transitions.md
Making 3D for a physical product	references/blender-3d.md
Making silhouettes and cutting to live footage	references/silhouette.md
Adding music and sound effects	references/sound.md
Final self-check before delivery	references/checklist.md
Something looks wrong	references/pitfalls.md

Environment

Node.js 20+, Python 3.9+ (numpy, Pillow, opencv-python-headless), ffmpeg, Google Chrome or Chromium. Tier 3 requires Blender (free); automatic silhouette masking requires macOS 14+; other systems can use external tools to generate masks. Before starting, run python3 scripts/doctor.py and inform the client about any missing dependencies and how to install them. If the skill directory contains a .venv, run Python scripts with .venv/bin/python (Windows: .venv\Scripts\python); on Windows, replace python3 with python.