# Ultimate Motion Design — full documentation (v0.10.0)

> Claude Code plugin to make and audit high-end motion design. Source: https://github.com/1AngelMicka/ultimate-motion-design. Site: https://1angelmicka.github.io/ultimate-motion-design/

# AGENTS.md — Ultimate Motion Design

Instructions for an AI agent asked to install, set up or use this plugin for a user. Humans: see [README.md](README.md) (French) or [README.en.md](README.en.md).

## What it is

A Claude Code plugin (`umd`) that makes and audits motion design: promo, presentation, explainer and social videos, logo animations, animated short films, animated web pages, 3D shots. It renders HTML animations to video deterministically, scores the result out of 10 on 64 checks, with evidence, guards licences and reports token use. One command drives everything: `/umd:go`.

- Repository: https://github.com/1AngelMicka/ultimate-motion-design
- Documentation: https://1angelmicka.github.io/ultimate-motion-design/ (English at `/en/`)
- Full docs in one file: https://1angelmicka.github.io/ultimate-motion-design/llms-full.txt

## Install for the user (Claude Code)

Slash commands can only be typed by the user. Pick one path:

**A. Ask the user to type these two commands** in Claude Code, then restart Claude Code (or type `/reload-plugins`):

```
/plugin marketplace add 1AngelMicka/ultimate-motion-design
/plugin install umd@ultimate-motion-design
```

**B. Project install, done by you** (no slash command): add this to the project's `.claude/settings.json` (merge with existing keys, do not overwrite the file), then ask the user to restart Claude Code in that folder and trust it when asked:

```json
{
  "extraKnownMarketplaces": {
    "ultimate-motion-design": { "source": { "source": "github", "repo": "1AngelMicka/ultimate-motion-design" } }
  },
  "enabledPlugins": { "umd@ultimate-motion-design": true }
}
```

Do not run `claude plugin …` from inside a running Claude Code session: nested sessions are refused. For every project of the user, the same block goes in `~/.claude/settings.json` (ask first: it is their global configuration). The plugin loads at the next start; until then use the CLI directly (below): `npx github:1AngelMicka/ultimate-motion-design <command>` or `node <clone>/plugins/umd/scripts/umd.mjs <command>`.

## Prerequisites and check

- Node.js 18+, git, FFmpeg (with the `ebur128`, `loudnorm`, `freezedetect`, `signalstats` filters; full builds have them).
- Playwright + Chromium: installed by the plugin into `~/.umd/runtime`, nothing goes into the user's project.
- After install, ask the user to run `/umd:doctor`. It lists what is missing with the exact command for their OS, and installs Playwright, Chromium and FFmpeg (winget on Windows, Homebrew on macOS) after the user agrees. On Linux, give the user the `sudo apt install ffmpeg` command; never run `sudo` yourself.
- Ask before installing anything system-wide.

## Guide the user

1. First project: the user types `/umd:go <what they want to make>`, for example `/umd:go a 30-second launch video for our app, 16:9`. It asks a few questions (what, format, length, look, commercial use), then writes `BRIEF.md` and `.motion/project.json`.
2. From then on the user types `/umd:go` to continue. It runs the next step (storyboard, build, render, audit, fix, deliver) and stops at decisions that belong to the user: approving the key stills, accepting a licence exception, delivering.
3. Results: the audit report is `.motion/AUDIT.md` (score out of 10, blockers, fixes); renders and their contact sheets are in `.motion/renders/<id>/`; deliverables in `deliverables/`.
4. Token use: `/umd:tokens`. Cheapest audit: `/umd:audit quick` (automatic checks only, no agent).
5. Resources, at no token cost: `umd styles match` (ranks 1 323 styles, prompts and blocks against the brief), `umd styles <words> [--project logo --tier 2 …]` (previews at https://1angelmicka.github.io/ultimate-motion-design/library/), `umd moves <words>` (120 named techniques), `umd commons <words>` (free images, recorded in the assets lock), `umd sounds <words> [--music]` (free effects and music, CC0/CC BY, recorded with their credit line), `umd sfx <kind>` (effects synthesised on the spot), `umd characters <words>` (free characters, rigs, motion clips and 2D kits for commercial work; `get` records the licence), `umd lipsync <voice.wav>` (mouth shapes for `templates/blender/character.py` and the 2D puppet). Every link the project used is in `SOURCES.md`.

## Use without Claude Code (other agents)

**The skill alone:** `skills/motion-design/` is a standalone skill (SKILL.md plus 55 reference guides, generated from the plugin by `tools/build.mjs`). Copy it into the agent's skills folder, or `npx skills add 1AngelMicka/ultimate-motion-design` and pick `motion-design`. It carries the method and the craft; the CLI below adds rendering, measures and the audit.

The engine is a zero-dependency Node CLI usable by any agent:

```bash
git clone https://github.com/1AngelMicka/ultimate-motion-design
node ultimate-motion-design/plugins/umd/scripts/umd.mjs            # help
node ultimate-motion-design/plugins/umd/scripts/umd.mjs doctor --fix
node ultimate-motion-design/plugins/umd/scripts/umd.mjs capture page.html --out out.mp4 --duration 6
node ultimate-motion-design/plugins/umd/scripts/umd.mjs analyze out.mp4
```

The method lives in plain Markdown: `plugins/umd/skills/*/SKILL.md` (the steps; `$ARGUMENTS` = the user's words, `${CLAUDE_PLUGIN_ROOT}` = `plugins/umd`), `plugins/umd/references/` (routes, recipes, engines, audio, craft, licences) and `plugins/umd/referential/` (the checks and scoring, JSON).

## Rules to respect when helping

- Use the whole method even when the project has its own pipeline: put its render command in `render.command` (so `umd render` runs it) or run `umd adopt <video>` after each render, and never show a result before the key stills were measured (`umd still --hero … --seek-check`), critiqued, and the render analysed and audited. Writing a parallel renderer that skips these gates is the failure seen on a real project.
- Before deciding a look, run `umd styles match` (it ranks the style library against BRIEF.md and project.json) and start from one of its picks; never invent a look from a blank page.
- Never mark a check as passed without evidence (a frame at a time, a measure, a file and line).
- Never add a licence exception (`license_policy.allow`) or lower a threshold on your own: it is the user's decision.
- Do not copy someone else's video or site look; describe references in words (see `plugins/umd/references/recipes/match-reference.md`).
- Record every asset in `.motion/assets.lock.json` with its source and licence.
- Recommend only free, reusable resources: nothing paid, nothing that may not be redistributed.


# Home

A plugin for [Claude Code](https://claude.com/claude-code) that makes Claude produce high-end motion design, then checks it frame by frame before delivering it. It covers:

- promo videos and product launches;
- presentation videos and explainers;
- vertical shorts for social media;
- logo animations;
- animated short films;
- animated web pages and 3D shots.

What it brings:

- **Every technology, one method.**
  - Engines: HTML/CSS, GSAP, Motion, Remotion, HyperFrames, Revideo, three.js and WebGPU, shaders, Lottie, Rive, SVG, canvas, Manim, Blender, Mermaid, Code Hike, VHS.
  - Sound and text: voice-over, music, sound effects and captions.
  - Claude picks the right route for each project.
- **Built-in deterministic rendering.** `umd capture` turns any animated HTML page into a video, frame by frame, with no Remotion licence. Two renders give identical frames.
- **Real quality control.**
  - 12 domains and 64 checks, from narrative to licences.
  - Every passed check has evidence: a frame at t = 2.40 s, a LUFS measure, a line of code.
  - Score out of 10. An open blocker caps the score and locks delivery.
  - A critic agent scores every draft like a jury (7 = professional, 8 = agency, 9 = festival selection) and sends it back until it reaches the target. A fresh critic every round, which never sees the builder's reasoning and checks the previous round's fixes item by item.
  - Craft counts in the score: the idea and hero moment, typography, colour and sound design are judged against the project's target level (8 by default).
  - Sound is measured against picture: each effect lands on its event within ±45 ms (`umd sync`), and the music's real ending lands on the end card (`umd mix --backtime`).
- **Measured, not just looked at.** The hero's size in every key still (`umd still --hero`), frames that do not depend on the render order (`--seek-check`), loops without a jump (`umd analyze --loop`), motion blur by sub-frames (`umd capture --subframes`) and one clock for every event and sound (`timing.json`).
- **Real characters.** No more stiff faces drawn in code: `umd characters` searches film rigs (full face), a generator from baby to senior, anime, low-poly, animals and creatures, 4,000 avatars, 2D kits, motion libraries and tools, all free and usable in advertising, with licence and credit recorded. One layer (`templates/blender/character.py`) animates any humanoid the same way: look, blink, breathe, speak (`umd lipsync`), play an action, take a captured motion. In 2D, an HTML puppet does the same.
- **A real sound department.** Twelve effects made on the spot with no licence to manage (`umd sfx whoosh`, `riser`, `impact`…), free effects and music searched and credited automatically (`umd sounds`, CC0 and CC BY only), and a guide that says which sound goes on which picture event, per project type. Listen on the [Sound and music](https://1angelmicka.github.io/ultimate-motion-design/en/son.html) page.
  - Cuts happen on motion, never between two parked shots, and no more than one second of near-still picture per 30 s: two measured checks, calibrated with zero false alarm on 15 reference films scored 7 to 8 by an AI jury.
- **The grammar of professional launch films.** Six rules and 16 mechanisms drawn from the analysis of 28 launch films: one persistent actor, every action producing a result, the foreground carrying the transition.
- **Proven starting points, at no token cost.**
  - 1 323 styles, prompts and ready-made blocks, sorted by project type, mood, look and format, with a preview of the result in the [online library](https://1angelmicka.github.io/ultimate-motion-design/library/?lang=en). Your agent picks what fits your brief on its own (`umd styles match`), or offers you three options.
  - 120 named techniques, from match cut to split-flap, so you and the critic speak the same language (`umd moves`).
  - Free images from Wikimedia Commons, recorded automatically with their author and licence (`umd commons`).
- **A real motion design skill, usable anywhere.** [`skills/motion-design`](skills/motion-design/SKILL.md) condenses the craft: the ten-step loop with three gates, twelve rules that separate craft from slop, the numbers that matter, type, colour, sound, camera, how to judge a piece. In Claude Code it triggers by itself as soon as you animate; it also installs in Codex, Cursor or any agent that reads skills, with its 55 guides.
- **Token-frugal and transparent.**
  - About 270 tokens loaded at all times.
  - Measurable checks are done in code, without an agent.
  - A contact sheet replaces dozens of frames.
  - `/umd:tokens` shows what each command used. See [Token economy](#token-economy).
- **Licences under control.**
  - A guard refuses to install a non-commercial model in a commercial project, a Tencent model in Europe, or AGPL code in a web page.
  - Every asset is inventoried with its licence.
  - Only free, reusable resources are recommended: nothing paid, nothing you may not redistribute.
- **Easy to install.** Two commands, then `/umd:doctor` installs whatever is missing.
- **Free, open source, no telemetry**, in French and English.

## How it works

**One command to remember: `/umd:go`.** It looks at where your project stands and runs the next step, then chains on its own until the next decision that is yours: approving the look, accepting a licence exception, delivering.

```
/umd:go a 30-second launch video for our app, 16:9
```

Under the hood it follows these steps, which you can also run one by one:

```
/umd:kickoff → /umd:storyboard → /umd:build → /umd:render → /umd:audit → /umd:fix → /umd:deliver
```

| Step | What happens | What it produces |
| --- | --- | --- |
| `/umd:kickoff` | Claude looks at the folder and asks a few questions: what, format, length, look, commercial use. It picks the profile, route and engine, checks the tools and writes the brief. | `BRIEF.md`, `.motion/project.json` |
| `/umd:storyboard` | Picks a proven style, writes the script, then timed beats with one intent per beat. Product actions are written as events numbered to the frame, and important sounds as cues. Before anything moves, the **key stills** are rendered, compared with the reference and corrected over up to 3 rounds by an "art director" agent. | `.motion/storyboard.md`, `.motion/stills/` |
| `/umd:build` | Builds beat by beat with motion tokens, assets, voice, music (timed so its real ending lands on the end card) and captions. Fast drafts (half size, 15 fps) are reviewed every round by a fresh critic, who scores like a jury and checks the previous round's fixes. | the piece's sources, `.motion/assets.lock.json`, `.motion/LEDGER.md` |
| While you work | The `motion` skill applies the craft rules by itself. Time comes from the frame, never the clock. Durations and curves come from the tokens, and every motion has a job. No AI motion tells, nothing frozen. The licence guard watches installs. | |
| `/umd:render` | Final render, done twice to prove it is reproducible, then analysed: cuts and motion around each cut, dead air, near-still time, black frames, flashes, loudness, contact sheet. | `.motion/renders/<id>/` |
| `/umd:audit` | Automatic measures are done in code. Then one auditor per group judges, in parallel, whatever needs eyes. Result: the overall score, each domain's score, the trend and prioritised fixes. | `.motion/AUDIT.md` |
| `/umd:fix` | Fixes issues in order, blockers first. Each fix is verified, then the render and audit are redone. | |
| `/umd:deliver` | Copies the audited render to `deliverables/` with a manifest and credits. Refused while a blocker is open or if the render changed since the audit. | `deliverables/` |

# Install

**You need:** [Claude Code](https://claude.com/claude-code), [Node.js](https://nodejs.org) 18 or newer, `git` and [FFmpeg](https://ffmpeg.org). On Windows and macOS, `/umd:doctor` installs FFmpeg for you.

**1. Add the marketplace and install the plugin.** In Claude Code, type:

```
/plugin marketplace add 1AngelMicka/ultimate-motion-design
```
```
/plugin install umd@ultimate-motion-design
```

**2. Restart Claude Code** (or type `/reload-plugins`), open your project folder and run:

```
/umd:doctor
```

It checks Node, FFmpeg and the filters it needs, Playwright and Chromium, and your route's tools (Blender, Manim, Python…). With your approval it installs what is missing:

- **Playwright and Chromium** go to `~/.umd/runtime`, shared by all your projects; nothing is added to your project;
- **FFmpeg** comes through winget (Windows) or Homebrew (macOS). On Linux it gives you the `apt` command.

**3. Start your first project:**

```
/umd:go a 30-second launch video for our app, 16:9
```

Then just type `/umd:go` each time to carry on.

**4. Optional, depending on your route:** the useful official skills and MCP servers. See [Companion tools](#companion-tools); `/umd:kickoff` suggests the ones that fit your project.

### Have your AI agent install the plugin

The `/plugin …` commands are typed by hand: an agent cannot run them, and `claude plugin …` is refused from inside a running Claude Code session. Your agent can instead add this block to `~/.claude/settings.json` (all your projects) or to the project's `.claude/settings.json`, merged with what is already there:

```json
{
  "extraKnownMarketplaces": {
    "ultimate-motion-design": { "source": { "source": "github", "repo": "1AngelMicka/ultimate-motion-design" } }
  },
  "enabledPlugins": { "umd@ultimate-motion-design": true }
}
```

The plugin loads at the **next start** of Claude Code (trust the folder if asked). Until then, the CLI below already works.

### Use the CLI without the plugin

Everything `umd` does (rendering, analysis, style library, automatic audit) also works without the plugin, before a restart or from another agent (Codex, Cursor…):

```bash
npx github:1AngelMicka/ultimate-motion-design doctor
```
```bash
git clone https://github.com/1AngelMicka/ultimate-motion-design && node ultimate-motion-design/plugins/umd/scripts/umd.mjs styles match
```

Without arguments the CLI prints its help. In a clone, `npm link` puts the `umd` command on your PATH.

### Install for a whole team

In the project folder, run once in your terminal, then commit `.claude/settings.json`:

```bash
claude plugin marketplace add 1AngelMicka/ultimate-motion-design --scope project
```
```bash
claude plugin install umd@ultimate-motion-design --scope project
```

Your teammates get the plugin when they open the project in Claude Code and trust the folder. Each of them runs `/umd:doctor` once on their machine.

### Update

Type `/plugin marketplace update ultimate-motion-design` in Claude Code. For automatic updates: `/plugin` → **Marketplaces** → **ultimate-motion-design** → **Enable auto-update**.

### Uninstall

```
/plugin uninstall umd@ultimate-motion-design
```
```
/plugin marketplace remove ultimate-motion-design
```

Your project keeps its `.motion/` folder and deliverables; delete them if you no longer want them. The shared Playwright runtime lives in `~/.umd/runtime`.

# First project

From install to a delivered video, with a single command: `/umd:go`. Allow five minutes to get started, then the render time.

## 1. Install

In Claude Code:

```
/plugin marketplace add 1AngelMicka/ultimate-motion-design
```
```
/plugin install umd@ultimate-motion-design
```

Restart Claude Code (or type `/reload-plugins`), then open an empty folder for your project. The details, team install included, are on the [Install](site:installation) page.

## 2. Say what you want

```
/umd:go a 30-second launch video for our notes app, 16:9, understated tone
```

`/umd:go` sees there is no project yet and starts with the **kickoff**:

- it asks a few questions: audience, platforms, look described in words, voice-over and music, commercial use;
- it picks the profile (here `promo`), the route (`html-video`) and the engine, and says why;
- it checks the tools (FFmpeg, Playwright, Chromium) and offers to install what is missing;
- it writes `BRIEF.md` and `.motion/project.json`.

## 3. Approve the look before anything moves

Type `/umd:go` again. It writes the **storyboard**: timed beats, one intent per beat, text that stays on screen long enough. Then it renders the **key stills** and has an "art director" agent review them, correcting over up to three rounds.

It then stops to show you the stills. If you like them, say so: it records the approval in the storyboard. Otherwise, say what is wrong.

## 4. Let it build, render and check

`/umd:go` again. This time it chains on its own:

1. **build**: the piece beat by beat, with voice, music and captions if the brief asks for them, and quick drafts reviewed;
2. **render**: the final render, done twice to prove it is reproducible, then analysed;
3. **audit**: the automatic measures, then the auditors in parallel, and a score out of 10 in `.motion/AUDIT.md`;
4. **fix** if a blocker is still open, then a new render and a new audit.

It stops when only minor or major issues are left for you to decide on, or when everything is ready.

## 5. Deliver

`/umd:go` offers delivery: the audited video goes to `deliverables/` with its manifest and the required credits. Ask for platform versions if you need them (vertical, GIF, WebM for the web).

## Where to look

| What | Where |
| --- | --- |
| The brief and storyboard | `BRIEF.md`, `.motion/storyboard.md` |
| The latest render and its contact sheet | `.motion/renders/<id>/video.mp4`, `sheet.jpg` |
| The score, blockers and fixes | `.motion/AUDIT.md` |
| The deliverables | `deliverables/` |
| Tokens used per step | `/umd:tokens` |

## Come back later

Close Claude Code whenever you like. When you come back, `/umd:go` reads the project's state and resumes at the right step. For a long break, `/umd:handoff` leaves a note that the next session reads first.

# Tips and prompts

What separates a decent video from one people share: a precise brief, a proven style, stills approved before anything moves, and a few rounds of demanding critique. It is all here, ready to copy.

## The recipe for a good brief

One sentence per point is enough. `/umd:go` asks what is missing, but the more you say up front, the fewer questions it asks.

| Point | Example |
| --- | --- |
| What | A launch video for Notio, our notes app |
| For whom, where | Freelancers scrolling LinkedIn, sound off by default |
| Format | 30 s, 16:9 plus a 9:16 version |
| What to remember | "Your notes file themselves" and the trial link |
| Mood, in words | Dark and precise, like a software keynote; short shots, the interface is the star |
| Constraints | Logo at `brand/logo.svg`, colour #3D5AFE, Inter font, no faces |
| Ambition | Agency level (target score 8) |

Describe references in your own words: shot length, camera position, how things enter the frame. Never ask to copy someone's video.

## Prompts ready to copy

Replace what is in brackets.

**Product launch**

```
/umd:go a 30-second launch video for [product], [what it does in one sentence]. Audience: [who]. Mood: dark and precise, the interface is the star, one hero moment when [the key feature] appears. End on the logo and [the call to action]. 16:9 and 9:16. Music, no voice.
```

**Company presentation video**

```
/umd:go a 60-second presentation video for [company]. Message: [the promise in one sentence]. Three parts: the problem, what we do, the proof ([real figures]). Calm English voice-over, burned-in captions, discreet music. Brand: [colours, font, logo].
```

**Explainer**

```
/umd:go a 45-second explainer of [the concept] for [audience]. One idea per shot, diagrams that build in front of the viewer, no on-screen text longer than 6 words. Voice-over and word-by-word captions.
```

**Vertical short for social media**

```
/umd:go a 20-second 9:16 short for [platform] about [topic]. Hook in the first second, new information every 2 seconds, karaoke captions inside the safe area, a looping end. Rhythmic music, cuts on the beats.
```

**Logo animation**

```
/umd:go a 4-second logo animation from [path to the SVG logo]. The logo builds from [a shape or idea tied to the brand], one gesture, a clean end, a short sound logo. Light and dark background versions, plus a transparent WebM.
```

**Data story**

```
/umd:go a 40-second video telling these figures: [data or CSV file]. A chart that draws itself, counting numbers, a handwritten note on the key figure. Data-journalism style.
```

**Animated web page or 3D hero**

```
/umd:go the animated hero section of [site] in [framework]. References: [2 or 3 sites described in words]. A subtle shader background, the title revealed word by word, 60 fps on mobile, prefers-reduced-motion respected.
```

**Short film**

```
/umd:go a 45-second animated short: [character] wants [something small], tries, [something unexpected happens], and ends looking at the camera. Style [chosen style]. Music and sound effects, no dialogue.
```

## Choose a style

Starting from a proven style is the shortest path to a high-end result. `/umd:storyboard` offers you three. To choose by eye, browse the [Style library](site:bibliotheque): each style has a preview of the result and its prompt. You can also search in a terminal, at no token cost:

```
node <plugin>/scripts/umd.mjs styles luxury dark launch
```

| Mood | Styles to try |
| --- | --- |
| Tech, software, keynote | `lemo:dark-keynote`, `mg:22-hud`, `lemo:swiss-motion` |
| Luxury, premium | `lemo:art-deco`, `lemo:glass-product` |
| Explaining, teaching | `lemo:whiteboard`, `lemo:dataviz`, `lemo:iso-infographic` |
| Playful, warm | `lemo:paper-popup`, `lemo:rubber-hose`, `mg:05-cel-boil` |
| Retro | `mg:10-synthwave`, `lemo:risograph`, `lemo:silent-film` |
| Organic, artistic | `mg:07-liquid`, `lemo:watercolor`, `lemo:ink-wash` |

Previews are in the [lemo-opuscar](https://lemomo-ai.github.io/lemo-opuscar/) and [mg-styles-15](https://vincentwei1021.github.io/mg-styles-15/) galleries. More than 700 other prompts are in [awesome-opus5-5-videos](https://github.com/yihui-dev/awesome-opus5-5-videos).

## During production: what to say

When `/umd:go` shows you stills or a draft, be precise: a moment, a problem, what you want.

- "At 2.4 s the title arrives with the image: bring the image in first, the title 8 frames later."
- "The hero moment is missing: I want a real high point when [X] appears."
- "Too tame: keep the style but push the contrast and the title size."
- "The accent colour is everywhere: keep it for the product."
- "One more round of critique, target 9."
- "It looks like a template: change style, show me three others."

For a precise correction, give four things: **where** (a moment or a frame), **what you see**, **the change**, **what must not move**. Claude then changes one thing and checks the frames around it.

```
At 7 s (frame 210) the cursor covers the file label.
Change only the cursor's path after the click: stop 24 px away from the label.
Keep the click at 6.5 s, the file reveal and the copy as they are.
```

## Beat the template look

What separates a launch film people share from a run of animated slides. The "Motion grammar" reference has the detail; the essentials:

- **One persistent actor**: a cursor, a card or a shape leads the eye from shot to shot.
- **Every action produces a result**: the start state, the cursor on the button, the press, the result, then time to read it.
- **The foreground carries the transition**: the title or logo travels through the camera while the next scene is already in place.
- **Speed changes**: an arrival that slows so you can read, a quick exit. Never a constant drift.
- **The subject fills 60 to 85 % of the frame** in product shots, and frame 0 is already a finished composition.
- **The music ends with the film**: its real ending lands on the end card (`umd mix --backtime`) instead of a fade or a cut.

## Sell a video

The plugin is enough to offer a small service. The simplest format to sell: a 20 s **launch clip** for one feature.

- **One** feature, **one** approved script, **one** square video (1080 × 1080), **one** cover image taken from the film, **one** revision round (timing, copy, sound).
- Make a complete sample first, with your own product or one whose owner agrees. Show it with its three key frames (opening, result, ending).
- Time the real job (preparation, feedback, rendering, delivery) before setting a price. Public anchors gathered in September 2026 by motion-video-kit: AI tools around $30, reels around $150, a 15 to 30 s product video around $455. Generic clips compete with AI tools; what sells is accuracy to the client's real product and quality control. Check your market.
- Before starting, agree in writing on: script, supplied files, date, payment, number of revisions, where the client may use the video and whether you may show it in your portfolio.
- During production: the three key frames to approve the direction, then the draft, then the final render. Feedback is given by moment ("at 7 s…"), which keeps the revision round clear.
- `.motion/LEDGER.md` (each critique round, what changed, the measures) and the audit report show the care taken: attach them to the delivery if the client values it.
- Another format that sells: a **series** with the same character and a short episode every day or week, sold monthly to an app or a brand (pilot of 3 to 5 episodes, then a subscription). The method is in the "A recurring animated series" reference: series bible, locked hero, episodes drawn from the product's reviews and releases, human approval before each post.
- Remotion, if you use it, needs a paid licence above 3 people in the company: `umd capture` and HyperFrames have no such limit.

## What gives away an AI-made video

| Tell | Instead |
| --- | --- |
| Everything fades in moving up 20 px | Varied entrances, tied to what each element is |
| Pulsing dots, things floating forever | Discreet life: breathing, light gliding |
| Bouncy springs everywhere | Springs only when something is thrown or caught |
| A blur on every entrance | Motion blur only on what moves fast |
| Purple gradient, glass cards, centred layout | The palette and grid of the chosen style |
| "Revolutionary", "effortless", "unlock your potential" | Concrete facts, plain verbs |

The automatic checks catch a good part of this (motion tells and hollow wording); the critic agent catches the rest.

## Spend fewer tokens

- Approve the look on stills before animating: one more round on stills costs far less than one on the video.
- While iterating, `/umd:render draft`: half resolution, 15 fps.
- `/umd:audit quick` between iterations; the full audit before delivery.
- Set `"audit_model": "sonnet"` in `.motion/project.json` for the auditors.
- Target 7 for everyday content, 8 for an ad, 9 only if it is worth the extra rounds.
- Check `/umd:tokens` after each big step.
- `/umd:go` states the cost of each step before running it and waits for your go-ahead on the expensive ones. Set a `token_budget` in `.motion/project.json` if you want a ceiling.

## A 20-minute real test

To check that everything works on your machine, end to end:

1. In a **new** folder, open a **new** Claude Code session and install the plugin (see [Install](site:installation)).
2. `/umd:doctor`: everything should be ready; otherwise accept the proposed install.
3. `/umd:go a 4-second logo animation for a made-up coffee roaster called Brûlerie, warm mood, with a sound logo`.
4. At the stills step, look at them and approve them.
5. Let `/umd:go` chain through to the audit, then read `.motion/AUDIT.md`.
6. `/umd:tokens` to see what each step cost.

If a step gets stuck, copy the error message and the output of `node <plugin>/scripts/umd.mjs next`, and open an issue on [GitHub](https://github.com/1AngelMicka/ultimate-motion-design/issues).

# Style library

https://1angelmicka.github.io/ultimate-motion-design/library/

# Sound and music

A motion piece is judged by ear as much as by eye. The plugin treats sound like picture: written in the storyboard, timed on picture events, measured, and with a licence for every file.

## The four layers

- **Voice** carries the message; the mix aims at −16 to −14 LUFS, voice in front.
- **Music** gives energy and the cut rhythm; it ducks about 9 dB under the voice and ends on the end card (`umd mix --backtime`).
- **Effects** make events physical: an arrival, a click, a reveal. Two to five marked moments per 30 s, not one sound per move.
- **Room tone** is a very low air bed, so a pause never sounds like a dropout.

## Listen to the palette

`umd sfx <kind>` makes these sounds with FFmpeg: nothing to download, no licence to track, the same file for the same settings. Vary `--dur`, `--seed` and `--gain` so a repeated sound does not read as stock.

@@SFX@@

## Which sound on which event

| On screen | Sound | Timing |
| --- | --- | --- |
| An element slides or enters | `swipe` or `whoosh` | Starts 2 to 4 frames before, peaks on the arrival |
| Build-up to a reveal | `riser` | Ends exactly on the reveal frame |
| Hero moment, logo landing | `impact` + `subdrop` | Attack 0 to 1 frame after the picture |
| Tail after the reveal | `shimmer` or `chime` | Starts with the impact, rings over the hold |
| Cursor press, toggle | `click` | On the press frame |
| Icon or badge appears | `pop` | On the first visible frame |
| Counter stepping | `tick` | One per step, up to 12 per second |
| Digital cut | `glitch` | Over the cut |

Each sound goes in the storyboard's `## Sound cues` with its time; `umd sync` checks it lands within ±45 ms of its picture.

## Find free sounds and music

```bash
umd sounds whoosh --cc0 --max 3
```
```bash
umd sounds get <id>
```
```bash
umd sounds ambient --music --limit 5
```

`umd sounds` searches Freesound and Wikimedia Commons (effects) or Jamendo (music) through Openverse, keeping only CC0, CC BY and public domain. `get` downloads the file as 48 kHz WAV and records the author, licence and credit line in `.motion/assets.lock.json`. For CC BY music the credit line goes in the description or the end credits: `umd licenses` lists them.

For tailored music: ACE-Step 1.5 (MIT) locally, or a MIDI score written by Claude and rendered with FluidSynth. Never chart music, tracks ripped from video platforms, or a non-commercial licence.

## By project type

| Project | Music | Effects |
| --- | --- | --- |
| Promo, launch | Leads the edit, cuts on beats | Impacts on reveals, one riser into the hero moment |
| Presentation, explainer | A calm bed under the voice | Few: clicks, pops, ticks on step changes |
| Vertical short | A hook in the first half-second | Few and punchy; captions carry the message when muted |
| Logo animation | A 2 to 8 s sting | Riser, impact, a tail ringing over the held logo |
| Short film | Score with silences | Foley and ambiences per place |
| Web page | None by default | Short UI sounds, off until the user turns them on |
| 3D shot | Supports the material | Foley that matches the material: glass, metal, plastic |

The full guide, for the agent: `references/audio/sound-design.md`.

# Commands

`/umd:go` is all you need day to day. The other commands drive one specific step.

| Command | For |
| --- | --- |
| `/umd:go [what you want to make]` | **The command to remember.** Runs the next step and chains until the next decision. `/umd:go audit`, `/umd:go deliver`… forces a step |
| `/umd:kickoff [what you want to make]` | Set up or update the project: brief, profile, format, route, engine, licence policy, tools |
| `/umd:storyboard [notes]` | Write the beats and validate the look on stills before animating |
| `/umd:build [beats or notes]` | Build the piece, with drafts reviewed over up to 3 rounds |
| `/umd:render` · `/umd:render draft` | Final render, done twice to prove determinism, then analysed · quick draft |
| `/umd:audit` | Incremental audit: only what a change can affect is re-checked. It runs in full on the first audit, after a plugin update, or when the last full audit is older than 30 days |
| `/umd:audit quick` | Automatic checks only, no agent: the cheapest |
| `/umd:audit full` | Re-check everything from scratch |
| `/umd:audit story` | One group: `story`, `motion`, `sound` or `delivery` |
| `/umd:audit TXT` · `/umd:audit TXT-01 SAF-01` · `/umd:audit blockers` | One domain, specific checks, or blockers only |
| `/umd:fix` · `/umd:fix blockers` · `/umd:fix AUD-01` | Fix by priority (blockers then majors), blockers only, or one issue |
| `/umd:deliver [name]` | Deliver the audited render, then the platform versions you ask for |
| `/umd:tokens [days]` | Token use per command, and the one change that would save the most |
| `/umd:doctor` · `/umd:doctor fix` | Check or install the tools |
| `/umd:handoff` | Write `.motion/handoff.md` to resume in another session |

All these commands rely on a zero-dependency CLI that you can also run yourself: `node <plugin>/scripts/umd.mjs` (with no argument it prints its help). It includes:

- **rendering:** `capture`, `still`, `render`;
- **analysis:** `analyze` (cuts, motion, dead air, flashes, loudness, contact sheet), `frames` (`--cuts`: 12 frames around each cut), `compare`, `vmaf`, `webperf`, `lint`, `licenses`;
- **sound:** `mix` (ducking, loudness, `--backtime` to land the music's ending on the end card), `hits` (a track's final hits), `sync` (each sound against its picture), `normalize`, `loudness`, `captions`, `burn`;
- **resources:** `styles` (1 323 styles, prompts and blocks; `styles match` picks from the brief), `moves` (120 named techniques), `commons` (free images from Wikimedia Commons), `sounds` (free effects and music), `sfx` (effects made on the spot), `characters` (free characters, rigs, motion and 2D kits), `lipsync` (mouth shapes from a voice);
- **tracking:** `next`, `status`, `tokens`, `estimate` (render time from one test frame), `adopt` (runs a video rendered by your own pipeline through analysis, audit and delivery).

## What it creates in your project

```
BRIEF.md                         the brief (written by /umd:kickoff)
.motion/
  project.json                   profile, route, engine, format, render, licence policy, thresholds
  storyboard.md                  the beats, events, sound cues and the dated "Stills validated" line
  motion-tokens.json             durations and curves (DTCG format)
  assets.lock.json               every asset with its source and licence
  styles/                        the chosen style's prompt, with its credit line
  LEDGER.md                      every critique round: what was found, changed and measured
  stills/                        the key stills
  renders/<id>/                  video, render.json, analysis.json, sheet.jpg, determinism.json, logs
  renders/latest.json            the latest render
  AUDIT.md                       the latest audit report
  audits/<date>.json             every audit, to track the score over time
  audits/<date>/                 evidence.json, plan.json, parts/ (auditor results)
  token-savings.json             tokens saved by compact output
  handoff.md                     the handoff between sessions
assets/commons/                  images downloaded by umd commons
deliverables/                    deliverables, with their manifest and credits.txt
```

Commit `BRIEF.md` and `.motion/`, except the renders, to keep the score history. `LEDGER.md` and the audit report show the care taken: you can attach them to a client delivery. `/umd:kickoff` adds the renders, audit logs and token counter to your `.gitignore`.

## The `umd` CLI

Every command relies on `node <plugin>/scripts/umd.mjs`, with no dependency. You can run it yourself; it is also what the agents use.

```text
Setup
  next                                The next step for this project (what /umd:go runs), from local files only
  doctor [--fix] [--blender] [--rhubarb]         Check FFmpeg, Playwright, Chromium and the route's tools (--blender: Blender and the GPU Cycles sees); --fix installs what it safely can
  detect                              Guess engine, route and profile from the current folder
  init [--force]                      Create .motion/ (project.json, storyboard, tokens, assets lock) and BRIEF.md from templates
  rules [domain|group...]             Build rules of the domains that apply to this project (compact)
Make
  styles match [words] [--project p] [--limit 6]    Rank the library against BRIEF.md and project.json: looks and blocks, with reasons
  styles <words> [--project promo|presentation|explainer|social|logo|film|web|3d] [--mood m] [--medium m] [--format 9:16]
         [--tier 2] [--kind style|prompt|block|component] [--source lemo|oscar|mg|opus|hf]   Search 1323 styles, prompts and blocks (no tokens)
  styles get <id>                                   Copy that style prompt (or block card) into .motion/styles/
  moves <words> [--family transitions|camera|type|...]   120 named motion techniques (match cut, whip pan, split-flap…)
  commons <words> [--allow-sa] [--limit 12]         Wikimedia Commons media under PD, CC0 or CC BY (BY-SA on request)
  commons get "File:Name.jpg" [--dir assets/commons] [--width 1920]   Download it and record it in assets.lock.json
  still <html|url> --at 0,1.5 [--out dir] [--width W --height H] [--hero "#tv"] [--hero-min 170] [--seek-check]
        Key stills on virtual time; measures the hero's width (an element, or window.umdHero(t) for canvas/WebGL) and
        checks that each frame drawn cold equals the same frame drawn in sequence
  capture <html|url> --out f.mp4 [--fps 30] [--duration s] [--width 1920 --height 1080] [--from s]
          [--draft] [--transparent] [--format mp4|webm|mov|gif|png] [--audio f] [--seed n] [--subframes 16 --shutter 0.5]
          Deterministic HTML → video; --subframes averages that many sub-frames per frame over the shutter (motion blur)
  adopt <video> [--draft]                         Make a video rendered by your own pipeline the latest render (analysis, audit, deliver apply)
  render [--draft] [--twice] [--no-analyze] [--engine eevee|cycles]  Render the project (project.json "render"), then analyze; --engine reaches a
          Blender command as UMD_ENGINE (default: render.engine)
  mix --voice v.wav --music m.wav [--sfx a.wav@1.2 ...] --out mix.wav [--duck 9] [--lufs -14] [--length s]  (length defaults to duration_s)
      [--backtime | --hit s --card s | --music-start s]   Back-time the music: its own ending lands on the end card, one continuous piece
  hits <music>                                    Strong attacks near the end of a track (candidates for its final hit)
  sounds <words> [--music] [--max 8] [--cc0]      Free sound effects (Freesound, Wikimedia) or music (Jamendo) via Openverse: CC0, CC BY, public domain only
  sounds get <id> [--dir assets/audio]            Download as 48 kHz WAV, record author, licence and credit line in assets.lock.json
  characters [words] [--dims 3d|2d] [--style anime|film|low-poly|flat…] [--age child|senior…] [--face visemes|full] [--kind pack|avatars|generator|rig|motion|kit2d|code|tool] [--route blender|threejs|html]
             Free characters, rigs, animation clips and 2D kits for commercial work (catalogue + live lists: Mesh2Motion, KayKit, Open Source Avatars)
  characters get <id> | info <id> | add <file> --id <entry> [--licence --author --url]   Download (or record a manual download) with its licence in assets.lock.json
  lipsync <voice.wav> [--text script.txt] [--fps 30]   Mouth shapes A–H, X per frame (Rhubarb, MIT) for character.py and the 2D puppet
  sfx [<kind>] [--dur s] [--seed n] [--gain dB]   Synthesise an effect (whoosh, swipe, riser, impact, subdrop, click, tick, pop, chime, shimmer, glitch, roomtone)
  normalize <in> <out> [--lufs -14] [--tp -1]      loudness <file>
  captions <words.json> --out subs.ass|srt|vtt [--style karaoke|pop|line] [--max-chars 32] [--width --height --font --color --highlight]
  burn <video> <subs.ass> --out f.mp4             Burn captions in (libass)
Check
  analyze <video> [--out dir] [--loop]            Probe, cuts, freezes, dead air, black, flashes, loudness, contact sheet; --loop checks the seam
  frames <video> --at 1,2.5 | --every 2 | --cuts | --sheet [--out dir] [--width 960]   (--cuts: 12 frames around each cut)
  sync <video> [--timing timing.json | --cues storyboard.md] [--tolerance-ms 45]   Do the sound hits land on their visual events?
       (.motion/timing.json, the master clock, when it exists; else the storyboard's "## Sound cues")
  compare <a> <b>                                 Frame-hash equality + SSIM       vmaf <encode> <master>
  lint [dir]   licenses   webperf <url>   captions-check <subs> <words.json>
  evidence [--date D]                             All automatic checks for the audit + statuses of auto criteria
  plan [scope...] [--incremental]                 Criteria left for the auditors      assemble [--date D]      status
Deliver and account
  deliver [--name n]                              Copy the audited render to deliverables/ (refused while a blocker is open)
  tokens [--days 30] [--session id] [--json]      Token use per /umd:* command, from the session transcripts
  run <label> "<command>"                         Run a command, keep the log on disk, print a compact summary
  estimate --frames N [--parallel P] -- <command rendering one frame>   Time one frame, multiply: render time before committing
  version                                         Plugin version
a path to show: relative inside the project, absolute outside it (never ......AppData…)
everything after a lone "--" is a command line for umd estimate, never parsed as options
boolean flags never take a value, so `umd capture --draft page.html` keeps page.html as the input
"music" is a switch only for `umd sounds --music`; `umd mix --music file.wav` takes a file
Compact output for large results: full JSON on disk, summary on stdout.
the per-second motion timeline stays in analysis.json; stdout gets its shape
---------- audit pipeline ----------
A film rendered outside umd (the project's own scripts, Blender, After Effects…) becomes the project's latest render,
so analyze, the audit and deliver judge it like any other. It never replaces the checks: it lets them run.
```

# Routes and tech

At kickoff, Claude picks a route based on what you are making. Each route has its own step-by-step guide, loaded only when needed.

| Route | For | Engines |
| --- | --- | --- |
| `html-video` (default) | Promo, presentation, graphic explainer, short, logo, kinetic type | HTML/CSS, GSAP, canvas rendered by `umd capture`; HyperFrames; Remotion; Revideo |
| `threejs-film` | A character or an object in a small 3D world | three.js or WebGPU in a single HTML file, corrected shot by shot |
| `blender` | Real materials, rigged characters, product renders | Blender driven through Python and its MCP server, BlenderKit |
| `director` | Narrated story, many scenes, generated images and voices | Claude directs, other models draw and speak, under a strict licence registry |
| `explainer` | Maths, diagrams, code, terminal | Manim, Mermaid, D2, Code Hike, VHS |
| `web-page` | Website, landing page, UI | GSAP, Motion, CSS, View Transitions, Lenis, animated shadcn registries |

On top of that:

- **15 proven recipes:** product launch, product demo, presentation video, explainer, logo sting, kinetic typography, vertical short, data story, hero section, page transitions, scrollytelling, micro-interactions, narrative short, recurring animated series, and matching a reference animation (broken down shot by shot);
- **17 engine guides,** including a sorted list of 60 effect, 3D, physics, sound and editing libraries with their licence and what to watch for a reproducible render;
- **craft guides:** launch-film grammar, animation principles, motion tokens, composition and safe areas, on-screen text (and copy a stranger understands in 3 s), anti "AI slop";
- **audio guides:** sound design (which sound on which picture event), commercial-safe voices, music and sound effects, mixing, captions;
- **practical guides:** assets, platform specs, licences.

**1 323 proven styles, prompts and blocks** serve as starting points:

- 66 film styles and the 98 OPUSCAR styles (one per Best Picture winner) from [lemo-opuscar](https://github.com/lemomo-ai/lemo-opuscar);
- 15 scored motion-design styles from [mg-styles-15](https://github.com/Vincentwei1021/mg-styles-15);
- 703 creator prompts from [awesome-opus5-5-videos](https://github.com/yihui-dev/awesome-opus5-5-videos);
- 441 ready-made blocks and components from the [HyperFrames](https://github.com/heygen-com/hyperframes) registry.

Every entry is tagged by project type (promo, presentation, explainer, vertical short, logo, animated short, web page, 3D shot), mood, look, format and quality tier. **Your agent picks from the library on its own**: before fixing a look, the storyboard runs `umd styles match`, which ranks the whole library against your brief, then shows you the best three, or takes the first if you leave the choice to it. To choose by eye: the [Library](https://1angelmicka.github.io/ultimate-motion-design/library/?lang=en) filters everything by project type and style, with a preview of each result and its prompt to copy. Ready-to-copy prompts and advice: the [Tips and prompts](https://1angelmicka.github.io/ultimate-motion-design/en/astuces.html) page.

Two files keep the trace of the research:

- [catalogue_motion_design_claude_codex_2026.md](catalogue_motion_design_claude_codex_2026.md) lists **1,113 GitHub repositories**, checked on 9 and 10 November 2026, with licence warnings;
- [SOURCES.md](SOURCES.md) lists **every link** shared, tested or used since the project started (315), with what was done with it and why some were set aside.

### Deterministic rendering

`umd capture` opens your page in Chromium (through Playwright) on a small local server. Before any of the page's scripts runs, it replaces these with **virtual time**:

- the clock (`Date`, `performance.now`);
- `requestAnimationFrame` and timers;
- `Math.random`, made reproducible with a seed.

On every frame it pauses every CSS and Web Animations animation and every `<video>` element, and sets each to the right time. Libraries driven by `requestAnimationFrame` (GSAP, three.js, Lottie, p5…) advance one step per frame. FFmpeg then encodes the screenshots. You can also define `window.umdRender(t)` to control everything yourself. Tested on a GSAP and three.js scene: two renders give byte-identical frames.

## Every guide

Claude reads each guide only when it needs it. They are in English, the most token-efficient language.

### Routes

| Guide | In one line |
| --- | --- |
| [Route R2 — Claude writes Python, Blender renders](plugins/umd/references/routes/blender.md) | Claude scripts the scene in `bpy` as files, Blender renders frames headless, FFmpeg encodes. The Blender MCP is optional: it helps to explore a scene live, nothing in this route needs it. Pick it for real objects, physic |
| [Route R4 — Claude directs, other models draw, speak and move](plugins/umd/references/routes/director.md) | Claude writes the script, shot list and prompts, calls image, voice, music and video models, then assembles the film in code. Pick it for narrated stories with many illustrated scenes, when drawing every frame in code wo |
| [Route — Technical explainer (Manim, diagrams, code, terminal)](plugins/umd/references/routes/explainer.md) | A sub-route of R1 (or R4 when imagery is generated) for teaching: maths, algorithms, architecture, code walkthroughs and CLI demos, cut to a voice-over. Structure comes from text sources (Python scenes, diagram code, cod |
| [Route R1 — HTML video drawn by code](plugins/umd/references/routes/html-video.md) | Every frame is HTML/CSS/SVG/Canvas computed from time, then captured to MP4. The cheapest and fastest route: pick it for flat or graphic styles, promos, launch films, explainers, kinetic type, data and shorts. |
| [Route R3 — One three.js scene, fixed shot by shot](plugins/umd/references/routes/threejs-film.md) | One HTML file holds one three.js world; the film is a list of shots (camera + events) over that world, captured frame by frame. Pick it for a character or object living in a small stylised 3D world. |
| [Route — Animated web page (no video output)](plugins/umd/references/routes/web-page.md) | The deliverable is a live site, landing page or UI whose motion runs in the visitor's browser. Same craft as R1, different proof: frames dropped, layout shift and reduced-motion behaviour replace the render audit. |

### Recipes

| Guide | In one line |
| --- | --- |
| [Recipe — Concepts before style](plugins/umd/references/recipes/concepts.md) | Three film concepts in the same format, compared side by side, before any style or beat. A style gives a look; it does not give an idea. When the brief asks for something "more evolved", "less template", or only says wha |
| [Recipe — Data story (animated charts and numbers)](plugins/umd/references/recipes/data-story.md) | Numbers and charts that build in the order the story needs them: a count-up, a bar that wins, a line that breaks its trend. For video (report films, social stats, launch proof beats) and pages (dashboards, landing stats) |
| [Recipe — Explainer video](plugins/umd/references/recipes/explainer-video.md) | Makes one idea understood in 60–180 s: a problem the viewer recognises, a mechanism shown step by step, a takeaway. Routes: ../routes/html-video.md for product and concept explainers, ../routes/explainer.md for maths, co |
| [Recipe — Animated hero section](plugins/umd/references/recipes/hero-section.md) | The first viewport of a site: headline, value line, call to action, and one living visual (shader, 3D object, product UI, type reveal) that loads fast and never blocks reading. Route: ../routes/web-page.md. |
| [Recipe — Kinetic typography](plugins/umd/references/recipes/kinetic-typography.md) | Text is the image: words enter, transform and exit in rhythm with a voice or a track. Works as a video (quotes, lyric-style promos, manifestos, shorts) or on a page (headlines, scroll type). Routes: ../routes/html-video. |
| [Recipe — Product launch film](plugins/umd/references/recipes/launch-video.md) | A 20–60 s film in the Apple/Linear register: the product's own interface becomes the hero, cut to music, every state change driven by a cursor or a morph. Default route: ../routes/html-video.md. |
| [Recipe — Logo sting / ident (2–6 s)](plugins/umd/references/recipes/logo-sting.md) | A short reveal that ends on the exact logo lockup, used as intro, outro, bumper or loading moment. Built from the logo's own vector geometry, with an optional sound logo. Route: ../routes/html-video.md (SVG); 3D variants |
| [Match a reference animation](plugins/umd/references/recipes/match-reference.md) | Measure how a reference moves (a live site, a screen recording, an mp4/gif, a Lottie, a WebGL scene) and turn it into a motion spec, motion tokens and, when allowed, a verified rebuild. Companion skill: **reanimate** (Ni |
| [Recipe — Micro-interactions](plugins/umd/references/recipes/micro-interactions.md) | Small, fast feedback on a single control: press, toggle, hover, focus, loading, success, error. Duration 100–300 ms, purpose always "the system heard you" or "here is what changed". Route: ../routes/web-page.md. |
| [Recipe — Narrative short with a character](plugins/umd/references/recipes/narrative-short.md) | A 30–120 s animated short where a character wants something small, tries, meets a surprise, and looks at the camera. Acting carries it: eyes first, body after, never fully still. Routes: ../routes/threejs-film.md (charac |
| [Recipe — Page transitions](plugins/umd/references/recipes/page-transitions.md) | Motion between routes or pages that keeps the user oriented: what stays, what leaves, where the new content comes from. Native View Transitions first, a library only when the site needs it. Route: ../routes/web-page.md. |
| [Recipe — Presentation video (company, product, project)](plugins/umd/references/recipes/presentation-video.md) | A 1–3 min narrated video built from a deck or a script: a voice leads, each slide becomes a designed scene with purposeful motion, captions on. Route: ../routes/html-video.md; voice from ../audio/voice.md. |
| [Recipe — Product demo video](plugins/umd/references/recipes/product-demo.md) | Shows how a product is used: a task from start to result, cursor-led, with zooms on what matters. Two ways to get the pixels: **recode the UI** as animation, or **film the real app** with Playwright. Route: ../routes/htm |
| [Recipe — Scrollytelling](plugins/umd/references/recipes/scrollytelling.md) | A story told as the reader scrolls: a sticky visual changes state at each text step, or a pinned scene scrubs with scroll. The reader controls the pace; motion follows scroll, never fights it. Route: ../routes/web-page.m |
| [A recurring animated series](plugins/umd/references/recipes/series.md) | A series with the same hero, the same world and a new short episode on a schedule, for a brand or an app. One clip gets a view; a recurring character builds an audience, which is what a business pays for every month. Met |
| [Recipe — Social short (9:16 Shorts, Reels, TikTok)](plugins/umd/references/recipes/social-short.md) | A 15–60 s vertical video that must stop the scroll in the first 1–2 s, read with sound off, and survive the platform's overlay UI. Route: ../routes/html-video.md (fast), ../routes/director.md for narrated faceless format |

### Engines

| Guide | In one line |
| --- | --- |
| [Blender (bpy, MCP, headless render)](plugins/umd/references/engines/blender.md) | Full 3D DCC driven from Python: modelling, materials, lights, keyframes, Geometry Nodes, physics, EEVEE/Cycles rendering, all scriptable with `bpy` and renderable headless. Pick it when the piece needs real materials, ri |
| [Canvas 2D and generative: p5.js, PixiJS, two.js, paper.js, canvas-sketch](plugins/umd/references/engines/canvas-2d.md) | Immediate-mode drawing for particles, generative patterns, data art, hand-drawn looks and many-object scenes. Pick canvas when SVG/DOM would need thousands of nodes or when the look is procedural; draw every frame as a p |
| [CSS animations, WAAPI, View Transitions, scroll-driven animations](plugins/umd/references/engines/css-waapi.md) | Native platform motion: no dependency, compositor-friendly, seekable by `umd capture`. Pick it first for hover/focus/enter states, page transitions, scroll-linked progress and simple loops; reach for GSAP or Motion only  |
| [Diagrams, code and terminal: Mermaid, D2, Excalidraw, Code Hike, VHS, asciinema](plugins/umd/references/engines/diagrams-code.md) | Text-first tools that produce structure (diagrams), code steps and terminal sessions an agent can generate reliably, then animate. Pick them for technical explainers, product architecture, dev-tool demos and docs videos. |
| [Effect and engine libraries](plugins/umd/references/engines/effect-libraries.md) | The open-source libraries that keep coming back in "free motion studio" lists, sorted by job, with their licence and what to watch in a deterministic render. Licences checked on GitHub on 2026-11-10. Read the row you nee |
| [GSAP](plugins/umd/references/engines/gsap.md) | Timeline-based JavaScript animation for DOM, SVG, canvas and any object. All plugins (SplitText, ScrollTrigger, Flip, MorphSVG, CustomEase…) are free, including commercial use. The default engine for HTML video captured  |
| [HyperFrames](plugins/umd/references/engines/hyperframes.md) | HeyGen's HTML→video engine for agents (Apache-2.0): scenes are HTML files driven by paused GSAP timelines, rendered frame by frame by its own CLI. Pick it for multi-scene films that benefit from its `check` audits, Studi |
| [Lottie and dotLottie](plugins/umd/references/engines/lottie.md) | Vector animation as JSON (Lottie) or zipped JSON + assets + state machines (`.lottie`). Players: dotlottie-web (ThorVG, canvas/WASM, recommended) and lottie-web (SVG/canvas, classic). Pick it for icons, illustrations and |
| [Manim (Community Edition)](plugins/umd/references/engines/manim.md) | Python engine for mathematical and technical explainers: shapes, equations (LaTeX), graphs and transforms rendered to video. Pick Manim CE for maths, physics, algorithms and any "show the idea transform" explainer; add m |
| [Motion (ex Framer Motion)](plugins/umd/references/engines/motion.md) | Declarative animation for React (`motion/react`), vanilla JS (`motion`) and Vue (`motion-v`): springs, layout animations, enter/exit presence, gestures and scroll. Pick it for component-level UI motion in apps and market |
| [Remotion](plugins/umd/references/engines/remotion.md) | React components rendered to video frame by frame: every visual is a function of `useCurrentFrame()`. Pick it for React teams, data-driven or templated videos, word-timed captions and the official templates. |
| [Revideo and Motion Canvas](plugins/umd/references/engines/revideo.md) | TypeScript scene graphs animated by generator functions (`yield*`). Motion Canvas is the editor-first original; Revideo (MIT fork by Midrender) adds a headless `renderVideo()` API, audio/video export and parallel renderi |
| [Rive](plugins/umd/references/engines/rive.md) | Interactive vector animation authored in the Rive editor and played by small runtimes (web canvas/WebGL2, React, iOS, Android, Flutter, C++). State machines and data binding make animations react to inputs and data. Pick |
| [Scroll animation: Lenis, ScrollTrigger, scroll-driven CSS, Scrollama](plugins/umd/references/engines/scroll.md) | Scroll-linked motion for landing pages, product stories and data scrollytelling. Pick the lightest layer that works: CSS scroll timelines → Scrollama steps → GSAP ScrollTrigger; add Lenis only when native scroll feels wr |
| [Shaders and procedural backgrounds](plugins/umd/references/engines/shaders.md) | GPU fragment shaders for animated backgrounds, textures, logo effects and transitions: Paper Shaders (ready presets), tsl-textures (three.js TSL presets), noise libraries for custom GLSL, glslViewer for headless shader r |
| [SVG animation](plugins/umd/references/engines/svg.md) | Vector shapes in the DOM: line drawing, shape morphs, logo reveals, icons, diagrams. Clean the file with svgo first, then animate with CSS/WAAPI or GSAP; flubber, MorphSVG or KUTE.js for morphs; SVG.js, Vivus or lazy-lin |
| [three.js, WebGPU/TSL and react-three-fiber](plugins/umd/references/engines/threejs.md) | The standard web 3D stack: three.js (WebGL or WebGPU renderer, TSL node shaders), react-three-fiber + drei + postprocessing for React, `@pmndrs/vanilla` (drei-vanilla) for plain HTML, three-gpu-pathtracer for offline pho |

### Craft

| Guide | In one line |
| --- | --- |
| [Anti-slop: AI motion and script tells](plugins/umd/references/craft/anti-slop.md) | The patterns that make a video or page read as "made by AI", and what to do instead. Read before storyboarding and before every audit. |
| [Composition and camera language](plugins/umd/references/craft/composition.md) | Frame sizes, safe areas, platform overlay zones, grids, and the shot and cut vocabulary to write storyboards with. |
| [Directing by numbers: brief, clock, springs and the model itself](plugins/umd/references/craft/direction.md) | A precise model given a vague brief returns a precise default. This guide turns intentions into numbers, puts one clock in charge of every event, and says how to direct the agent so it finishes the film instead of stoppi |
| [Motion grammar of premium launch films](plugins/umd/references/craft/motion-grammar.md) | What separates a launch film people share from a sequence of nicely animated slides. Rules adapted from echris6/motion-video-kit (MIT), whose author analysed 28 professional SaaS launch films and ran dozens of independen |
| [Animation principles for motion design and UI](plugins/umd/references/craft/principles.md) | The 12 principles (Thomas and Johnston, *The Illusion of Life*, 1981) translated into rules Claude can apply and check, with timing tables and easing choices. |
| [Text on screen](plugins/umd/references/craft/text-on-screen.md) | Titles, callouts, kinetic type and captions that can actually be read at the size and speed people watch: on a phone, often muted, often once. |
| [Motion tokens](plugins/umd/references/craft/tokens.md) | Every duration, easing and transition in a umd project comes from `.motion/motion-tokens.json`, written in the DTCG 2025.10 format. No hard-coded `300ms` or `ease-in-out` in scene code (MOT). |

### Audio

| Guide | In one line |
| --- | --- |
| [Captions](plugins/umd/references/audio/captions.md) | Word-timed captions from a known script (forced alignment) or from audio (ASR), styled for reading, burned in or shipped as a sidecar. |
| [Mix and loudness](plugins/umd/references/audio/mix.md) | Voice, music and SFX into one 48 kHz track at the destination's loudness. `umd mix` does the default job; this file explains the numbers and the manual route. |
| [Music and sound effects](plugins/umd/references/audio/music-sfx.md) | Music beds, stingers, UI sounds and SFX with a licence you can prove, plus beat markers to cut on. Pick generated music (ACE-Step 1.5) or a library track; never a track you cannot trace. |
| [Sound design: from picture events to a finished soundtrack](plugins/umd/references/audio/sound-design.md) | How to give a motion piece its sound: what each kind of project needs, which sound goes on which picture event, where to get the files with a clean licence, and how to place, mix and check them. The detailed guides stay  |
| [Voice-over](plugins/umd/references/audio/voice.md) | Script → spoken track. Use a local, commercially licensed TTS. |

### Practical

| Guide | In one line |
| --- | --- |
| [Assets](plugins/umd/references/assets.md) | Images, icons, logos, fonts, emojis, stock media and AI-processed assets, each with a recorded licence. Prefer assets built in code (SVG, CSS, shaders) over downloaded ones; when you download, record it. |
| [Characters: where they come from, how to animate them](plugins/umd/references/characters.md) | A character that acts badly ruins a good film faster than any other flaw. Characters drawn in code (primitives, hand-made SVG faces) often look stiff. This guide gives the agent real characters, free and usable in commer |
| [Companion skills, plugins and MCP servers](plugins/umd/references/companions.md) | Optional official or well-maintained add-ons that deepen one route. umd works without any of them. Install commands are copied from each project's README (checked 2026-11-10). |
| [Licence policy](plugins/umd/references/licenses.md) | How umd classifies every dependency, model and asset, what each class means for a commercial deliverable, and how `umd licenses` and the install guard enforce `.motion/project.json`. This is engineering guidance, not leg |
| [Platform export specs](plugins/umd/references/platforms.md) | What to render and encode for each destination. Figures checked 2026-11-10 from the sources listed; platforms change limits often, so re-check a limit that decides the brief (duration, file size). Loudness targets: `audi |
| [Styles, prompts and references: start from proven work](plugins/umd/references/styles.md) | The films people share as "agency level" rarely start from a blank page. They start from a **proven style prompt** (a look with named signature features, materials, colour logic and motion rules), get adapted to the brie |

# Quality checks

| Group | Domains |
| --- | --- |
| Story | NAR brief and narrative · TIM rhythm and timing · LIF life and density · ART art direction |
| Motion | MOT easing and choreography · TXT on-screen text · SAF motion safety · WEB animated web pages |
| Sound | AUD audio · CAP captions |
| Delivery | REN render and encoding · LIC licences and rights |

Every rule and check is detailed in [docs/en/REFERENTIAL.md](docs/en/REFERENTIAL.md).

29 of the 64 checks are measured in code, without an agent (which ones apply depends on the profile):

- output length and format;
- cuts made on motion, never between two parked shots;
- frozen frames, dead air and total near-still time (under 1 s per 30 s, end card excluded);
- sounds landing on their picture, when the storyboard lists sound cues (`umd sync`);
- black frames;
- flashes, as a full-frame approximation of WCAG 2.3.1;
- loudness and true peak;
- silences and abrupt audio cuts;
- render reproducibility, and how faithful the delivered encode is to the master (VMAF);
- caption coverage, sync and reading speed;
- for pages: smoothness, CLS and `prefers-reduced-motion`;
- in the code: hard-coded durations, AI motion tells, remote fonts and assets, hollow wording;
- asset inventory and licences.

The other checks are judged by the auditors, from the contact sheet and a few targeted frames.

### Scoring

- Each check is a **blocker** (5 points), **major** (3) or **minor** (1). Passed = all points, partial = half, failed or not checked = none.
- A failed blocker caps its domain at 3/10 and the overall score at 5.9/10. Examples:
  - a dangerous flash;
  - text too short to read;
  - a render that is not reproducible;
  - stills not validated before animation;
  - a non-commercial asset in an ad.
- The overall score weights the domains by profile: `promo`, `presentation`, `explainer`, `social`, `film`, `logo` or `web`. Domains that do not apply are ignored, such as captions for a logo or audio for a web page.
- Thresholds can be tuned per project in the `thresholds` of `.motion/project.json`: −14 LUFS, 3 flashes per second, 3 s of dead air, VMAF 93… The dead-air, frozen-picture, near-still, cuts-on-motion, flash and loudness thresholds were checked with zero false alarm on 15 reference films scored 7 to 8 by an AI jury ([docs/CALIBRATION.md](docs/CALIBRATION.md)). A rule that would have wrongly flagged 7 of these films (music dynamics) was dropped. The VMAF, caption and web ones remain conventions.

## The full referential

### Profiles and weights

| | NAR | TIM | LIF | ART | MOT | TXT | SAF | WEB | AUD | CAP | REN | LIC |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `promo` Promo or product launch | 3 | 3 | 2 | 3 | 3 | 3 | 2 | · | 2 | 2 | 3 | 3 |
| `presentation` Presentation video (company, product, project) | 3 | 2 | 1 | 3 | 2 | 3 | 2 | · | 3 | 3 | 2 | 3 |
| `explainer` Explainer or educational video | 3 | 2 | 1 | 2 | 2 | 3 | 2 | · | 3 | 3 | 2 | 2 |
| `social` Vertical short for social media | 3 | 3 | 2 | 2 | 2 | 3 | 2 | · | 2 | 3 | 2 | 2 |
| `film` Narrative animated short | 3 | 3 | 3 | 3 | 2 | 1 | 2 | · | 3 | 1 | 2 | 2 |
| `logo` Logo animation or ident (2 to 8 s) | 1 | 2 | 1 | 3 | 3 | 1 | 2 | · | 1 | · | 3 | 2 |
| `web` Animated web page or UI | 1 | 1 | 1 | 3 | 3 | 2 | 3 | 3 | · | · | · | 2 |

### Default thresholds

| | |
| --- | --- |
| `loudness_lufs` | -14 |
| `loudness_tolerance_lu` | 1 |
| `true_peak_dbtp` | -1 |
| `freeze_s` | 1 |
| `hero_min_px` | 170 |
| `dead_air_s` | 3 |
| `motion_floor` | 0.4 |
| `flashes_per_s` | 3 |
| `flash_delta` | 0.1 |
| `duration_tolerance` | 0.1 |
| `vmaf_min` | 93 |
| `caption_offset_ms` | 100 |
| `caption_cps_max` | 17 |
| `caption_coverage_min` | 0.98 |
| `caption_lines_max` | 2 |
| `text_min_s` | 1.2 |
| `text_words_per_s` | 3 |
| `web_smooth_frames_min` | 0.95 |
| `web_cls_max` | 0.1 |
| `hardcoded_motion_max` | 3 |
| `ai_tells_max` | 0 |
| `fonts_max` | 2 |
| `black_frames_max_s` | 0.1 |
| `silence_edge_max_s` | 0.5 |
| `still_per_30s_max` | 1 |
| `end_card_s` | 2 |
| `sync_tolerance_ms` | 45 |

### NAR · Brief and narrative

One goal, one audience, a structure that holds and a script without AI phrasing.

**Build rules**

- Write the goal, the audience and the expected action in BRIEF.md before any shot.
- Structure: hook, development, payoff (or call to action). In film: the character wants something small, tries, something unexpected happens, it looks at the camera.
- Every storyboard beat has a duration and a single intent, written at the end of the line.
- Key information must be understood with the sound off: it is also on screen.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| NAR-01 | A written goal and audience, served by every scene | major | auditor | BRIEF.md states goal, audience and expected action; every beat in storyboard.md maps to it. |
| NAR-02 | Complete structure: hook, development, payoff | major | auditor | Contact sheet and storyboard: the hook lands within the first 2 seconds (promo, social), the end resolves (CTA, punchline or look at camera). |
| NAR-03 | Every beat has a duration and an intent | minor | automatic | umd lint: storyboard.beats_missing_duration and beats_missing_intent are 0. |
| NAR-04 | Understandable with the sound off | major | auditor | Contact sheet without audio: the main message and the call to action are readable on screen. |
| NAR-05 | Script, on-screen text and voice-over without AI phrasing | minor | automatic | umd lint: slop.count is 0 in BRIEF.md, storyboard.md, the script and captions. |

### TIM · Rhythm and timing

No dead air, regular events, a duration that fits the format.

**Build rules**

- Something new happens about every 2 seconds; never more than 3 seconds without meaningful motion.
- Target duration set in the brief (social 15–60 s, promo 30–90 s, logo 2–8 s) and met within ±10%.
- Key shots hold long enough to be read; no shot under 0.5 s unless a deliberate rapid montage.
- With music: cut on the beats.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| TIM-01 | No dead air longer than 3 s | major | automatic | umd analyze: dead_air has no segment longer than thresholds.dead_air_s (except intended holds noted in the storyboard). |
| TIM-02 | Something new about every 2 s | major | auditor | umd analyze motion timeline and contact sheet: regular peaks, no long flat stretch. |
| TIM-03 | Cuts and accents land on the music | minor | auditor | Compare scenes (umd analyze) with beats (beat_this or librosa if installed, otherwise listening): 2 frames apart at most. |
| TIM-04 | Duration matches the brief and the platform | major | automatic | umd analyze: probe.duration within ±thresholds.duration_tolerance of project.json duration_s. |
| TIM-05 | Shots long enough to be read | minor | auditor | umd analyze scenes: no shot under 0.5 s outside a deliberate montage; text shots long enough (see TXT-01). |
| TIM-06 | Cuts land on motion, never between two parked shots | major | automatic | umd analyze: seams.parked = 0 (mean motion below motion_floor in the 0.25 s before AND after a cut). |

### LIF · Life and density

Nothing is fully frozen, scenes vary, motions overlap.

**Build rules**

- Nothing is ever fully still, even on the last shot: breathing, blinking, living light or particles.
- Vary framing, composition and rhythm from scene to scene; never the same layout twice.
- Characters: eyes react 6 to 10 frames before the body.
- Offset elements (stagger, overlapping action): they never all move at once.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| LIF-01 | No frozen picture over 1 s, last shot included | major | automatic | umd analyze: freezes has no segment longer than thresholds.freeze_s. |
| LIF-02 | Visual variety between scenes | major | auditor | Contact sheet: no two scenes with the same composition, framing and entrance. |
| LIF-03 | Eyes lead the body, breathing and blinks | minor | auditor | Frames around a reaction (umd frames --at): gaze 6 to 10 frames before the body; blinks present. |
| LIF-04 | Offset motions, no mechanical unison | minor | auditor | Code (stagger, delays) and successive frames: elements of a group start and end at different times. |
| LIF-05 | Under 1 s of near-still picture per 30 s, end card excluded | major | automatic | umd analyze: stillness.per_30s ≤ thresholds.still_per_30s_max (0.5 s buckets below motion_floor, the last end_card_s seconds excluded). |

### ART · Art direction

A look validated on stills before animating, faithful to the brief, without an AI signature.

**Build rules**

- Render key stills (umd still) and compare them with the reference before animating; correct for up to three rounds.
- Colours and type come from the brief and motion-tokens.json; at most two font families.
- No default purple gradient, glass everywhere, emoji as icons, generic 3D blobs or centred template layouts.
- Respect the format's safe areas (title-safe 90%, platform UI zones in 9:16).
- Logos and icons as vectors; no blurry upscaled asset.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| ART-01 | Key stills validated before animation | blocker | automatic | umd lint: stills.count ≥ 1 per scene in .motion/stills/ and storyboard.md has a dated "Stills validated" line. |
| ART-02 | Palette and type from the brief respected | major | auditor | umd lint (fonts.families ≤ thresholds.fonts_max, colours outside tokens) and frames: consistent with BRIEF.md. |
| ART-03 | No AI-signature visuals | major | auditor | Contact sheet against the list in references/craft/anti-slop.md. |
| ART-04 | Format safe areas respected | minor | auditor | Key frames: text and logo inside title-safe (90%) and outside the platform's UI zones (9:16). |
| ART-05 | Assets sharp at output resolution | major | auditor | Frames at 100%: logos, icons and photos sharp, no pixelation or upscale blur. |
| ART-06 | One idea, a hook and a hero moment at the target level | major | auditor | Jury (agents/critic.md): concept_wow ≥ quality_target from project.json (default 8). A hook readable before 2 s, one identifiable hero moment (time), a satisfying end frame. Cite the times. |
| ART-07 | Typography finished to the target level | major | auditor | Jury: design_typography ≥ quality_target. Tight tracking on large display, line breaks by meaning, no widow, one emphasis device per line, the right font loaded (no fallback). Cite the frame. |
| ART-08 | Colour and finish at the target level | major | auditor | Jury: finish_texture ≥ quality_target. A palette per sequence that follows the story (colour script), motivated light, grain or dither against banding, no aliasing. Cite the frame. |

### MOT · Easing and choreography

Consistent durations and curves, a purpose for every motion, no AI motion tells.

**Build rules**

- Durations and curves only from .motion/motion-tokens.json; no hard-coded values in components.
- Every motion has a role: guide the eye, explain a change, give feedback, link two ideas.
- Entrances ease-out, exits ease-in, on-screen moves ease-in-out; never linear on a spatial move.
- One focal motion at a time; the others follow, offset.
- Ban AI tells: pulsing dots, blur on every entrance, bouncy springs everywhere, everything fading up 20 px, infinite floating.
- On the web, animate only transform and opacity; never transition: all.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| MOT-01 | Durations and curves come from motion tokens | major | automatic | umd lint: hardcoded_motion.count ≤ thresholds.hardcoded_motion_max outside the token file. |
| MOT-02 | No AI motion tells | major | auditor | umd lint (ai_tells) then successive frames: no infinite pulsing, systematic blur-in, springs everywhere or uniform fade-up. |
| MOT-03 | Every motion has a purpose | major | auditor | storyboard.md: every noted animation has a role; no purely decorative looping animation. |
| MOT-04 | Easing matches the physics of the motion | minor | auditor | umd lint (linear_moves) and code: entrances ease-out, exits ease-in, no linear on moves. |
| MOT-05 | One focal motion at a time | minor | auditor | Successive frames of a transition: one element leads, the others follow offset. |
| MOT-06 | Web: only transform and opacity, never transition: all | major | automatic | umd lint: layout_props.count and transition_all.count are 0. |

### TXT · On-screen text

Long enough to read, contrasted, never clipped or overlapping.

**Build rules**

- Text display time: at least max(1.2 s, words ÷ 3 + 0.5 s).
- Contrast ≥ 4.5:1 (≥ 3:1 for large text); over moving backgrounds add a scrim or stroke.
- Minimum body text size: about 4% of frame height in video.
- No overlap or overflow; everything stays inside title-safe.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| TXT-01 | Every text stays on screen long enough to be read | blocker | automatic | umd lint: storyboard.text_too_short is 0 (rule max(text_min_s, words ÷ text_words_per_s + 0.5)), confirmed with umd frames. |
| TXT-02 | Text contrasted, even over moving backgrounds | major | auditor | Frames where text crosses a busy background: scrim, stroke or calm area; estimated contrast ≥ 4.5:1. |
| TXT-03 | No clipped, overlapping or out-of-zone text | major | auditor | Key frames of each card: full text, no overlap, inside title-safe. |
| TXT-04 | Text size large enough for the format | minor | auditor | Frame at 100%: body text height ≥ 4% of frame height (more in 9:16). |

### SAF · Motion safety

No dangerous flashes, no nauseating motion without an alternative.

**Build rules**

- Never more than 3 flashes per second (WCAG 2.3.1), including white cuts and strobes.
- Limit fast zooms, spins and large parallax; on the web, turn them off with prefers-reduced-motion.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| SAF-01 | At most 3 flashes per second | blocker | automatic | umd analyze: flashes.max_per_s ≤ thresholds.flashes_per_s (full-frame measure, approximation of WCAG 2.3.1). |
| SAF-02 | No aggressive vestibular motion | minor | auditor | Successive frames: no fast, repeated full-screen zoom or spin, no long large parallax. |

### WEB · Animated web pages

Smooth, stable, respectful of prefers-reduced-motion and native scrolling.

**Build rules**

- Every non-essential animation stops or shrinks with prefers-reduced-motion: reduce.
- Budget: 95% of frames on time on a 4× throttled CPU; animate transform and opacity.
- No animation shifts the layout (CLS < 0.1).
- No scroll-jacking: scrolling stays native, with keyboard and trackpad.
- Interactions: visible feedback within 100 ms, UI durations of 100 to 300 ms.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| WEB-01 | prefers-reduced-motion honoured | blocker | automatic | umd webperf: reduced_motion.respected is true (animations stopped or strongly reduced in reduce mode). |
| WEB-02 | Smooth animations, no dropped frames | major | automatic | umd webperf: smooth_ratio ≥ thresholds.web_smooth_frames_min with a 4× throttled CPU. |
| WEB-03 | No layout shift caused by animation | major | automatic | umd webperf: cls < thresholds.web_cls_max. |
| WEB-04 | Responsive, consistent interactions | major | auditor | Hover, focus, click: feedback within 100 ms, same durations and curves everywhere. |
| WEB-05 | No scroll-jacking, keyboard navigation intact | major | auditor | Scroll with wheel, keyboard (Space, arrows) and trackpad: native speed, sections reachable by focus. |
| WEB-06 | will-change used sparingly | minor | automatic | umd lint: will_change.count ≤ 5 permanent declarations. |

### AUD · Audio

Compliant loudness, a clear voice, music ducking under the voice, sounds in sync.

**Build rules**

- Mix with umd mix (automatic ducking), then normalise with umd normalize (−14 LUFS, true peak ≤ −1 dBTP by default).
- Sound lands 0 to 1 frame after the image it underlines, never before.
- Fade in and out; no silence longer than 0.5 s at the start.
- Voice: humanised script, brand names pronounced correctly, 140 to 170 words per minute.
- Export 48 kHz stereo, AAC ≥ 192 kb/s (or Opus in WebM).

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| AUD-01 | Compliant loudness and true peak under the ceiling | blocker | automatic | umd analyze: loudness.integrated within ±thresholds.loudness_tolerance_lu of thresholds.loudness_lufs and loudness.true_peak ≤ thresholds.true_peak_dbtp. |
| AUD-02 | Music ducks under the voice | major | auditor | Mix command (umd mix or sidechaincompress) in render.json or the logs, and listening to a spoken passage: the voice clearly dominates. |
| AUD-03 | Sound effects in sync, 0 to 1 frame after the image | minor | auditor | With a "## Sound cues" section in the storyboard: umd sync measures each sound's attack against its event (±sync_tolerance_ms) and decides on its own. Without cues: watch the cuts and impacts; the sound lands 0 to 1 frame after the picture. |
| AUD-04 | No leading silence or abrupt cut | major | automatic | umd analyze: silence.leading_s and silence.trailing_s ≤ thresholds.silence_edge_max_s, and audio_end.abrupt is false. |
| AUD-05 | Clear, natural voice, names pronounced right | major | auditor | Listening and transcript: no robotic artefacts, 140–170 words/min, brand names correct. |
| AUD-06 | Delivery audio format | minor | automatic | umd analyze: probe.audio at 48 kHz, 2 channels, AAC ≥ 192 kb/s or Opus. |
| AUD-07 | Layered sound design at the target level | major | auditor | Jury: sound_sync ≥ quality_target. At hero moments several layers (riser, impact, sub, detail), the music carved under the voice, silence used as an accent at least once; each effect on its picture (umd sync). |

### CAP · Captions

Every word present, on time, readable and spelled right.

**Build rules**

- Known script: forced alignment (ctc-forced-aligner). Otherwise: word timestamps (faster-whisper, WhisperX).
- Generate with umd captions, check with umd captions-check.
- Two lines at most, 17 characters per second at most, inside the safe area, never hiding the key visual.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| CAP-01 | Every word, in sync | blocker | automatic | umd captions-check: coverage ≥ thresholds.caption_coverage_min and max_offset_ms ≤ thresholds.caption_offset_ms. |
| CAP-02 | Readable, well-placed captions | major | auditor | Frames with captions: two lines at most, strong contrast, inside the safe area, not hiding the subject. |
| CAP-03 | Reasonable reading speed | minor | automatic | umd captions-check: max_cps ≤ thresholds.caption_cps_max and max_lines ≤ thresholds.caption_lines_max. |
| CAP-04 | Names and brands spelled exactly | minor | auditor | Compare the caption file with the script and BRIEF.md (proper names, brands, figures). |

### REN · Render and encoding

A reproducible render, in the right format, with no visible loss or artefact.

**Build rules**

- Time is driven by the frame number (umd capture, useCurrentFrame, timeline.seek); never by the clock.
- Local fonts and assets (Fontsource): no network loading during render.
- High-quality master, then delivery encode H.264 High yuv420p, constant frame rate, faststart.
- Gradients: add grain or dithering against banding.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| REN-01 | Deterministic render: two identical renders | blocker | automatic | umd compare on two renders (umd render --twice): identical is true, or ssim ≥ 0.999 if the encoder adds noise. |
| REN-02 | Output format matches the brief | major | automatic | umd analyze: probe.width, height and fps equal the brief, constant frame rate, yuv420p for MP4. |
| REN-03 | Delivered encode faithful to the master | major | automatic | umd vmaf: vmaf ≥ thresholds.vmaf_min. |
| REN-04 | Local fonts and assets | major | automatic | umd lint: remote_assets.count is 0 (no Google Fonts, image or video CDN loaded at render). |
| REN-05 | No unintended black frames | minor | automatic | umd analyze: black has no segment longer than thresholds.black_frames_max_s outside planned fades; the first frame is not blank. |
| REN-06 | No artefacts: banding, aliasing, flicker | major | auditor | Frames at 100% on gradients, thin lines and moving text. |

### LIC · Licences and rights

Every asset, model and dependency is allowed in the deliverable.

**Build rules**

- Record every asset in .motion/assets.lock.json with its source and licence as soon as it enters the project.
- Commercial deliverable: no non-commercial weights, no Tencent model in the EU, no embedded AGPL, no unlicensed asset.
- Remotion: free up to 3 employees, company licence above; declare it in project.json.
- Describe references in your own words; never have someone else's video copied.

| ID | Check | Severity | Method | How |
| --- | --- | --- | --- | --- |
| LIC-01 | No asset, model or dependency forbidden for commercial use | blocker | automatic | umd licenses: violations is 0 for the project.json policy. |
| LIC-02 | Remotion licence fits the team | blocker | automatic | umd licenses: remotion.ok is true (project.json license_policy.remotion is individual, small-company, non-profit or company-license). |
| LIC-03 | Every asset is inventoried with its licence | major | automatic | umd licenses: unlisted_assets is 0 and every assets.lock.json entry has source and license. |
| LIC-04 | Required attributions present | minor | auditor | Assets marked attribution_required: credits in the video, the description or deliverables/credits.txt. |
| LIC-05 | No third-party trademark, likeness or work without rights | major | auditor | Contact sheet and assets: third-party logos, real faces, music and clips under rights are justified; references described, not copied. |

# Licences

Licences are the most concrete risk in a motion project: many state-of-the-art models have non-commercial weights. The plugin handles them at three levels:

- **At kickoff**, the project's policy is written into `license_policy`: commercial use or not, region, Remotion status (free up to 3 employees, paid company licence above), accepted exceptions.
- **While you work**, a hook refuses to install (npm, pnpm, yarn, bun, pip, uv, pipx, poetry) a package or model that the policy forbids, and suggests an alternative. The registry has 39 entries:
  - non-commercial weights such as F5-TTS, MusicGen, YuE, FLUX.1 [dev]…, and tools under a non-commercial licence (anything2explainer, CC BY-NC datasets);
  - Tencent Hunyuan models, whose licence does not apply in Europe;
  - AGPL and GPL;
  - Animate UI's Commons Clause;
  - repositories without a licence;
  - paid collections, or collections you may not redistribute.
- **At audit**, `umd licenses` cross-checks dependencies, declared models and `.motion/assets.lock.json`. Every asset is recorded there with its source and licence; required credits are copied into `deliverables/credits.txt`.

An exception is still possible: it is your decision, written down explicitly in `license_policy.allow`.

For images, `umd commons` only offers public domain, CC0 and CC BY (CC BY-SA only if you ask), downloads the file and records it in `assets.lock.json` with its author and credit line.

# Token economy

The plugin cuts tokens in three places:

- **what is loaded at all times**: as little as possible;
- **what Claude reads**: JSON summaries, a contact sheet and targeted frames rather than raw output and dozens of images;
- **what gets redone**: only what changed is re-checked, and the project is not re-explored every session.

### What the plugin does on its own

| Mechanism | Effect |
| --- | --- |
| **Almost nothing loaded at all times** | About 270 tokens loaded at all times: the description of the `motion` skill and those of the two agents. The eleven `/umd:*` commands cost nothing until you run them. In a umd project, the startup hook adds about 150 tokens of context. |
| **References on demand** | 56 guides of 800 to 2,300 tokens each, read one at a time, only when needed: for example the project's route, then its engine's guide. |
| **Checks done in code** | 29 of the 64 checks are decided by the CLI from FFmpeg measures, lint, licences and browser tests. The auditors only look at what needs eyes. |
| **Contact sheet** | Each render produces a 16-frame sheet: a single image to read. Claude then extracts only 2 to 6 targeted frames if a doubt remains. |
| **Compact output** | Renders, encodes and analyses write their full output to disk and return only a summary. In our test, 3 commands went from about 3,700 tokens of output to about 700. |
| **Incremental audit by default** | Only the checks that a changed file or a new render can affect are re-checked. If nothing changed, no auditor is started. |
| **Quick mode** (`/umd:audit quick`) | Automatic measures only, no agent. |
| **Local searches** | `umd styles` and `umd moves` search indexes shipped with the plugin: zero tokens, no network. Only the chosen style is downloaded. |
| **Drafts** (`/umd:render draft`) | Half resolution at 15 fps while iterating. |
| **Cheaper model for the auditors** | `"audit_model": "sonnet"` in `.motion/project.json`; your session stays on your usual model. |
| **Handoff** (`/umd:handoff`) | A short note lets the next session resume without re-exploring. The startup hook points to it for 14 days. |
| **A style card instead of the prompt** | The chosen style prompt (1,200 to 7,700 tokens) is read once, summed up in 200 words in `BRIEF.md`, and only that summary is read again, by the critic and by the build. |
| **Grouped auditors** | A group with 3 checks or fewer is given to another group's agent: an agent for two criteria would cost as much as one for fifteen. |

### Transparency

- **Warned before spending.** Before each step, `/umd:go` states its token cost: measured on this project's earlier runs when there are some, estimated otherwise (agents launched, images read). An expensive step waits for your go-ahead, with the cheaper options: in practice the build (about 120 to 290 k tokens for 30 s, critique included) and the first full audit (about 110 to 250 k). In `.motion/project.json`, `"cost_confirm": "medium"` asks more often, `"never"` never; with a `token_budget`, any step that would exceed it waits for your go-ahead.
- `/umd:tokens` reads Claude Code's local transcripts for this folder, subagents included. For each `/umd:*` command it shows input, output, cache-write and cache-read tokens. It adds the one change that would save the most on your project.
- With a `token_budget` in `.motion/project.json`, it shows the share of the budget used.
- The audit report also shows the tokens saved by compact output.

### By kind of piece

| Piece | Typical cost | To spend less |
| --- | --- | --- |
| **Short** (logo, micro-interaction, 2 to 10 s) | Low: few beats, one sheet is enough | `/umd:audit quick` while iterating, a full audit before delivery |
| **Medium** (promo, presentation, short, 15 to 90 s) | Medium: the storyboard and drafts dominate | Validate the look on stills before animating, 2 draft rounds, auditors on Sonnet |
| **Long** (narrative film, explainer of several minutes, `director` route) | High: many scenes, assets and reviews | Work sequence by sequence (`/umd:build 1-6`), audits by group, `/umd:handoff` at the end of each session |

# Companion tools

These tools are not included in the plugin: they are separate projects, installed separately. `/umd:kickoff` suggests the ones that fit your route and installs them only with your approval. Skills cost almost nothing until they are used. An MCP server, on the other hand, adds its tools to every session: install it at project level, only for the route that needs it.

| Tool | When | What it adds |
| --- | --- | --- |
| [remotion-dev/skills](https://github.com/remotion-dev/skills) | Route with Remotion | Remotion best practices. Mind the Remotion licence |
| [greensock/gsap-skills](https://github.com/greensock/gsap-skills) | Pages or scenes animated with GSAP | Timelines, ScrollTrigger, plugins |
| [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) | Route with HyperFrames | HTML → video skills and CLI |
| [LottieFiles/motion-design-skill](https://github.com/LottieFiles/motion-design-skill) | Every route | Timing, easing and choreography principles |
| [kylezantos/design-motion-principles](https://github.com/kylezantos/design-motion-principles) | Animated UIs and pages | Audit mode and anti-AI-tell checklist |
| [blader/humanizer](https://github.com/blader/humanizer) | Pieces with voice-over or lots of text | Removes AI phrasing from scripts and captions |
| [rive-app/skills](https://github.com/rive-app/skills) | Interactive vector animation | Official Rive skills |
| [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Debugging animated pages | Performance traces, dropped frames |
| [ahujasid/mcp-for-blender](https://github.com/ahujasid/mcp-for-blender) | `blender` route only | Drives a running Blender |
| [echris6/motion-video-kit](https://github.com/echris6/motion-video-kit) | Premium business commercials | The source of the motion grammar: notes on 28 films, critic prompts, 3D product realism, case studies |
| [Leonxlnx/cinetic](https://github.com/Leonxlnx/cinetic) | A ready template (update video, UI walkthrough, social ad) | 34 scenes and 7 film templates in Remotion or HyperFrames |
| [kajisho5/ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill) | Editing existing footage | 42 FFmpeg recipes and a review of the cut |
| [Moh4696/cinematic-skill](https://github.com/Moh4696/cinematic-skill) | Narrated documentaries and archive films | One camera over a board of photos and maps, each picture timed to the voice |
| [NiazMorshed2007/reanimate](https://github.com/NiazMorshed2007/reanimate) | A reference animation to study (site, video, gif, Lottie, WebGL), or your own animation to port | Records it, extracts its durations and curves, rebuilds it and measures the gap frame by frame. Needs Bun; tested on macOS and Linux only. See [the recipe](plugins/umd/references/recipes/match-reference.md) |

All are free and open source. The exact install commands, checked against each project, are in [references/companions.md](plugins/umd/references/companions.md).

# Troubleshooting

| Problem | Solution |
| --- | --- |
| The `/umd:...` commands do not show up | Restart Claude Code or type `/reload-plugins`. Check `/plugin` → **Installed** and the **Errors** tab. |
| `node: command not found` | Install Node.js 18+ and make sure `node` is on your PATH. |
| Adding the marketplace fails | Make sure `git` is installed. Without a GitHub SSH key, set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` and try again. |
| `ffmpeg not found` | Run `/umd:doctor`. After an install through winget or Homebrew, open a new terminal so the PATH is reloaded. You can also point to the binaries with `UMD_FFMPEG` and `UMD_FFPROBE`. |
| `Playwright not found` or `Chromium is not installed` | `/umd:doctor fix` installs both in `~/.umd/runtime`. |
| `Unknown duration` when rendering | Set `window.umdDuration` (in seconds) in the page, or `duration_s` in `.motion/project.json`. |
| The render is not reproducible (REN-01) | A source of randomness escapes virtual time: network data, a server timestamp, WebGPU, a font loaded online. The engine's guide (`references/engines/`) lists the rules. Drive the scene with `window.umdRender(t)`. |
| 3D is slow or blank in the render | Headless Chromium uses software rendering. Iterate with `/umd:render draft` and check one frame first with `umd still`. |
| An install is blocked by the guard | Use the suggested alternative (`references/licenses.md`). If you accept the risk, add the name to `license_policy.allow`: that is your decision, Claude does not make it for you. |
| `/umd:deliver` refuses to deliver | A blocker is open, or the render changed since the audit: `/umd:fix`, then `/umd:render` and `/umd:audit`. |
| `umd sync` says "no hit within 250 ms" | The planned sound is missing or too quiet under the music: place the effect on the cue time (`umd mix --sfx file.wav@6.5`) and check it rises above the music. |
| `/umd:tokens` is empty | Transcripts appear after the first Claude Code session in this folder. If you moved your configuration, set `CLAUDE_CONFIG_DIR`. |

## Privacy and security

The plugin sends no telemetry.

- **What it contacts:**
  - During a render, it serves your files on `127.0.0.1` and only contacts the URLs your page loads itself.
  - `/umd:doctor fix` downloads Playwright from npm, Chromium from Playwright's servers, and FFmpeg through winget or Homebrew.
  - `umd styles get` downloads the chosen prompt from GitHub; `umd commons` queries Wikimedia Commons. No data from your project is sent.
- **What it reads:** `/umd:tokens` reads Claude Code's transcripts on your machine and sends nothing.
- **Hooks:** they run locally and are short enough to read: [licence guard](plugins/umd/scripts/hooks/license-guard.mjs), [session reminder](plugins/umd/scripts/hooks/session-start.mjs).
- **Reporting a vulnerability:** see [SECURITY.md](SECURITY.md).

The plugin helps you spot licence traps; it does not replace a lawyer's advice.

# For AI agents

You can hand installation and onboarding to your AI agent: just give it the repository link. Everything it needs is written for it.

## The sentence to copy

```
Install and set up this plugin for me, then guide me through my first project: https://github.com/1AngelMicka/ultimate-motion-design
```

## What the agent finds

| File | For |
| --- | --- |
| [AGENTS.md](AGENTS.md) | The guide written for an agent: install (two ways), checks, onboarding, rules to respect |
| [llms.txt](https://1angelmicka.github.io/ultimate-motion-design/llms.txt) | The summary and map of the docs, in the format agents read |
| [llms-full.txt](https://1angelmicka.github.io/ultimate-motion-design/llms-full.txt) | The whole documentation in one text file, to read in one go |

## What it will do

1. It will ask you to type the two `/plugin` commands in Claude Code. An agent cannot type a slash command for you. Alternatively, it writes the install into your project's `.claude/settings.json`, and you only need to restart Claude Code.
2. It will have you run `/umd:doctor`, which checks FFmpeg, Playwright and Chromium and offers to install them.
3. It will explain `/umd:go`, the one command to remember, and help you word your first brief.

It must never install anything system-wide without asking you, nor add a licence exception or lower a threshold on your behalf: those decisions stay yours.

## With an agent other than Claude Code

The plugin is built for Claude Code, but its engine is a zero-dependency Node CLI: any agent can use it to render an HTML page to video, analyse a video or check licences. The method's steps are plain Markdown files that anyone can read. Details in [AGENTS.md](AGENTS.md).

**The skill alone.** The [`skills/motion-design`](https://github.com/1AngelMicka/ultimate-motion-design/tree/main/skills/motion-design) folder is a standalone skill (one `SKILL.md` and its 55 guides): copy it into your agent's skills folder (`~/.claude/skills/`, `~/.codex/skills/`…), or install it with `npx skills add 1AngelMicka/ultimate-motion-design` and pick `motion-design`. It brings the method and the craft; the plugin adds reproducible rendering, the scored audit and the licence guard.

# Contributing

Ideas, bugs, new recipes and new engines are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Planned:

- calibrating the VMAF, caption and web thresholds, which remain conventions;
- a full real-world run, from `/umd:go` to delivery;
- an After Effects and Premiere module through MCP;
- automated platform exports;
- a visual judge specialised in timing.

## Credits and licence

The scoring, audit and token-saving mechanics come from [quality-pack](https://github.com/1AngelMicka/quality-pack), by the same author. The motion grammar, critique rounds and music timing are adapted from [motion-video-kit](https://github.com/echris6/motion-video-kit); the styles come from [lemo-opuscar](https://github.com/lemomo-ai/lemo-opuscar), [mg-styles-15](https://github.com/Vincentwei1021/mg-styles-15) and [awesome-opus5-5-videos](https://github.com/yihui-dev/awesome-opus5-5-videos); the 120 techniques from [motionvideo.xyz](https://github.com/motionvideohq/motionvideo.xyz). The catalogue and guides build on a study of more than 1,100 repositories, and every link used is in [SOURCES.md](SOURCES.md). Third-party tools are credited in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). MIT licence.