pro-motion – Design & UI skill for AI agents

Pro Motion — MG film, audio first (launch · brand · TVC · promo)

A method for making motion-graphics films that read as designed, not templated — in code, fast, locked to music.

It was distilled from a real project that went through ~10 rounds: early cuts were rejected as "PPT", "ugly material", "text floating on top", "pop art when I asked for stylized"; later cuts were accepted. The difference was the method, not the tooling. Follow the steps in order; each one exists because skipping it failed once.

When to Use This Skill

• the user wants a launch video, brand film, TVC or app promo made as motion graphics
• the user wants a film re-cut to music, restyled, or localized into several languages
• the user needs a music plan or Suno/Udio prompts for a promo

0 · Setup (once per project folder)

Needs Node 18+, Python 3 with numpy / scipy / matplotlib, and a Chrome / Chromium install (auto-detected; set CHROME=/path to override). Subject cutouts need macOS 14+.

Runtime prerequisite

Pinned upstream reference: [jack-reson8/pro-motion at 50db3957004a086c24575897c0b97a2a975624a1](https://github.com/jack-reson8/pro-motion/tree/50db3957004a086c24575897c0b97a2a975624a1).

This catalog entry bundles documentation, assets/template/audio-plan.md, references/*.md, and LICENSE only; the runtime template (film.html, film.js, motion-lib.js, OFL font binaries) and scripts/ helpers (setup.sh, analyze_music.py, audio_post.py, render-fast.js, contact_sheet.sh, ref_frames.sh, cutout.swift, faces.swift) are not bundled. Before executing any rendering or setup step, obtain user consent to fetch the pinned upstream commit above, inspect all scripts and dependencies, and verify their contents.

1 · Brief intake (decide, don't interrogate)

Write down in one block, filling gaps with sensible defaults and saying so: product / brand and what the film must make people feel · audience and markets (→ languages) · music file (if there is none, make one in step 1b — never start the picture without a locked track) · duration · aspect ratios (default 9:16 master, 1:1 and 16:9 later) · film type (product launch = show the product's real design language; brand film = story and style first, product optional) · must-have elements (logo, mascot, slogan, features) · what the user has rejected before.

1b · Audio first: plan and generate the track

Copy assets/template/audio-plan.md into the project (setup does this for new folders; copy it by hand into existing ones) and fill it in order — each part feeds the next, and the picture doesn't start until the track is locked:

1. Campaign brain (§1): read references/audio-first.md §1 and pick a mechanism type A–G from references/campaign-cases.md; write the sound that *is* the mechanism. A concept with no mechanism gets rejected as "boring" — fix it here, not later. For "viral / 神级" briefs, search recent Cannes / Spikes winners first.

2. Palette and energy map (§2–3): use the fusion engine, sound-design and voice lists in audio-first.md §3; bars on round seconds.

3. Rails (§4): tick every box; any unticked box means rewrite the map, not the prompt.

4. Prompt (§5): follow audio-first.md §4 (style = identity, tags = placement). Show the user the plan's §1 and §3 plus the prompt. Offer 2–3 directions only while they're still exploring.

5. Post (§6): user generates takes → analyse (step 2) → tools/audio_post.py for tuned SFX on exact beats, glow-up muffle, on-twos stutter, loop, Morse / spectrogram signature; loudness with ffmpeg.

2 · Analyse the music (the edit is the music)

$FF -y -i music.mp3 -ac 1 -ar 22050 music/mono.wav
python3 tools/analyze_music.py music/mono.wav music/   # tempo, grid offset, onsets, low/high hits, RMS → music/analysis.json + music/spec.png

Look at spec.png (spectrogram, envelope, beat grid). Write the music map: lead-in, stabs, builds, the drop, held / half-time sections, silences, the biggest hit, the final hit, the tail — in seconds. A user's description of the track ("drop at 0s, logo at 25s") is a hint; the spectrogram is the truth. Every major move lands on a mapped event; secondary moves on 8ths / 16ths (grid0 + k * 60 / BPM / 4).

3 · Research with real frames (never from memory)

Follow references/sourcing.md:

• find official uploads with web search → bash tools/ref_frames.sh <url> <name> → 24-frame contact sheet (no browser, no permission prompts);
• 6–10 references across countries and media, not one genre — category leaders, motion-design studios, and (for anything "stylized") feature animation, anime OP/ED, art shorts, MV, game cinematics;
• the product's own latest screenshots, icon, mascot and design notes (for launch films the film must speak the product's current design language).

For each reference write a technique sheet (palette rule · line · texture · shape language · depth trick · camera · transition device · timing · signature move). references/research-notes.md has worked examples.

4 · Direction: three style frames before any film

Don't default to the first association or the style that is easiest to code — if a direction can be named by one familiar label ("pop art", "flat", "Y2K", "clean SaaS") it is probably not new enough.

1. Propose 3 clearly different directions, each = 2–3 *named techniques* borrowed from the technique sheets + the material it needs.

2. Render one style frame each (node tools/render-fast.js "film.html?dir=a" stills/ --stills 1.2 — a still at the key moment, or a 2-second loop) and show them side by side.

3. The user picks or mixes. Only then write the shot map.

5 · Story: protagonist + shot map

• One protagonist that transforms through every scene (an object, shape or mascot tied to the brand — e.g. a brand dot that becomes a punch tool, a REC light, a page indicator, and finally the dot of the logo). Narrative beats feature lists.
• Each feature / object performs itself on a music event (a punch is a hit, dots breathe on hi-hats, an outline draws itself, a sticker peels). Material and motion are the same thing.
• Every scene change is designed: match cut, morph, object flies into the next layout, shard / scan / push wipe, metaball convergence, colour-block slam. Plain cuts only as deliberate stutters.
• Text is animation: written on by the protagonist, riding a path, echoing an effect, annotating what it names. No lower-third templates, chips or boxes. Few words.
• The ending grows out of the film: everything converges into the protagonist, which becomes part of the logo.
• Shot map table: time · music event · picture · transition in · words. Save it as shotmap.md.

Run references/aesthetic-checklist.md against the shot map before coding.

6 · Build

• Start from film.js (scene table + render(t)), motion-lib.js (primitives — read its header index) and film.html.
• render(t) must be pure and deterministic: no Math.random at draw time (use rand(seed) / hash), no state between frames — frames are rendered by parallel tabs.
• Material: real, current, licence-safe photos (the user's own > Lorem Picsum / Unsplash licence) or pure drawn graphics. Half-body > big faces. Blank space beats an ugly asset. Cutouts / face boxes: swift tools/cutout.swift in.jpg mask.png, swift tools/faces.swift *.jpg > faces.json (normalized — convert to pixels explicitly).
• Frame-rate language is a style choice: 60 fps smooth for product films; 24 fps with objects on twos (Math.floor(t*12)/12) for hand-made animation; 12 fps line boil for doodle layers.
• Languages: ?lang= parameter → EN master + local cuts that swap only key lines; decorative multilingual text (onomatopoeia, rings, slams) stays in every cut. Handwriting fonts (OFL) are bundled in assets/template/assets/fonts.

7 · Render fast, verify once, deliver

node tools/render-fast.js "film.html?lang=en" out/film-en.mp4 --dur 20.04 --audio music/track.mp3 [--fps 24]   # parallel tabs; ~30 s per 20 s @60fps
bash tools/contact_sheet.sh out/film-en.mp4 stills/check.jpg 0.5,1.0,2.4,...                               # frames at chosen seconds → one image
$FF -i out/film-en.mp4 -map 0:a -f null - 2>&1 | grep -oE 'time=[0-9:.]+' | tail -1                       # audio must run full length

One check pass per render: read the sheet at every mapped event and transition, fix concrete bugs (off-screen, overlaps, backwards text, seams, unreadable contrast), re-render. Don't ask the user to verify what a sheet can show, and don't loop endlessly — the first draft should already be good. Deliver: open the file, clickable links, a side-by-side index.html for several cuts; offer 1:1 / 16:9 re-layouts only after the master is approved.

8 · Iterate by timestamp

Take feedback as "time → problem", fix only that, re-render (seconds, not minutes). When feedback is about taste ("PPT", "ugly", "not stylized enough"), go back t

… (full content is in the download package)