motion-showreel

Motion Showreel

Turn an idea into a short video driven mainly by graphics, text or interface animation, delivering an MP4 and source code that can rebuild it.

How it works: the page exposes a deterministic render(t), the script captures frames one by one, then uses ffmpeg to composite the MP4. The soundtrack and sound effects are synthesized in code, sharing one timeline with the visuals timeline.js, so beat sync can be frame-accurate.

Where a good video comes from: density of change, motion feel, one memorable moment, and the audio-visual relationship—these four usually determine how it feels. But exactly how things move and how much they move is decided bystyle and content, not every video needs multiple camera angles, springs and wall-to-wall sound effects. Globally, only a few bottom lines are enforced (see “Bottom lines”); everything else is a starting point for the model, not a ceiling.

Scope

The user wants	Use this Skill?
Product promo shorts, motion design portfolios, UI motion, kinetic typography / beat sync, logo reveals, intros, looping motion graphics	✅
Green-screen people generated by video models + scenes, big type and motion graphics made in code	✅ People are provided by the user (`references/formats.md` category H)
Has a voiceover script or article, wants a several-minute video explaining line by line	❌ Use `web-video-presentation`
Websites, landing pages, interactive prototypes, static visual mockups	❌ Use `web-design-engineer`
Live-action human performance, documentary texture, editing existing footage, using video models to generate visuals directly	❌

Duration: best suited to 5–60 seconds. Pure music-driven pieces without narration can run to about 2 minutes (such as mixed-media-era era retrospectives of that kind); when over 60 seconds, produce and review each section separately, and before starting make the rendering and review costs clear to the user. Videos that need narrated explanation are outside the scope of this Skill.

Opus's strengths and default pitfalls

Strengths: within a single file it can mix Canvas, SVG/DOM, WebGL and Three.js, even switching medium for each section; motion can be computed precisely with formulas (closed-form springs, beat grids, sub-frame motion blur); sound and visuals read the same timeline; it can autonomously “render stills → look at images → revise” for long stretches; and it has strong aesthetic judgment—a single “go all out” can produce something stunning.
Default pitfalls: without constraints, visuals fall into dark backgrounds, centered big type, everything fading in together, purple-blue gradients with glow, and a static camera; the soundtrack falls into A minor four-on-the-floor, impact + crash on every downbeat, and bells on the end card, so several videos sound like the same song. So first find references (for both visuals and sound), and write down the style and a forbidden list. But constraints must not be rigid either: this Skill's style library and technique library are starting points—remix, blend or customize them whenever the theme calls for it.
What it does poorly: Photorealistic people, complex hands / cloth / hair, things that need real physical accuracy, photorealistic products (unless the user provides a model or images). When you run into these, stylize them, or switch to a division of labor with green-screen people + code scenes.

Workflow

0 环境检查（一次）
1 一次问清 ──────── 能从请求里推断的就不问
2 brief.md ──────── 对标 → 用途 + 风格 → Reel Read → 节拍网格 + 分镜 + 禁止清单
3 风格帧 ────────── 🛑 唯一的停顿点：已定风格 → 1 个方向 3 张帧；未定风格 → 3 个方向各 1 张帧
4 制作 ──────────── timeline → 逐镜头 → 静帧自检 → 确定性检查 → 小样 → 正片
5 声音（可选）────── 代码合成 / 用户曲子 / 无声
6 验收 ──────────── 技术检查（程序判定，必须全过）+ 审片（看图列问题，交给用户终审）
7 交付

Working directory: create <slug>/under the user's current directory, and put all files inside it:brief.md、index.html、motion.js、timeline.js、score.mjs or score.tone.js(choose according to the scaffold's --audio ),build.sh、fonts/、assets/、audio/、qa/、out/。

Step 0: Environment

On first use, run sh <skill>/scripts/setup.sh: it installs Playwright and Chromium, then runs check-env.mjs. Requires Node 18+ and ffmpeg; if they are missing, tell the user how to install them, do not install system software for the user. The tool comes with tests:cd <skill>/scripts && npm test。

Step 1: Ask everything at once

Use one messageto ask, at most 5 questions, skip anything already answered in the request. If the user says "you decide", use all default values and note that in the brief.

What to ask	Default value
Theme and assets: logo, product screenshots, copy, brand colors, fonts	Use only facts the user gives, do not invent features, data, or clients
The one sentence or one image the audience should remember after watching	Distill it from the theme
Duration, aspect ratio, platform	15 seconds · 1920×1080 · 30fps; use 1080×1920 for vertical platforms; 60fps can be used for UI motion
Style: do you have a specified style, reference video, or screenshot?	If not, give 3 directions in Step 3, choose by looking at images
Audio: silent / code-synthesized / you provide the track (must be commercially usable)	Code-synthesized

If the user provides a reference video: first run inspect.mjs sheet <ref> --cells 30 to see the whole picture,inspect.mjs grid <ref> --strips to measure the cut points and the beat grid they fall on (BPM candidates, how many beats each segment occupies, the consecutive frames of each transition),inspect.mjs heat <ref> to see where things move in each segment and how large an area they cover. Write the measured numbers into the benchmark column of the brief. Learn only the structure and techniques, do not copy assets.
If the user provides a track: first run audio.mjs beats <track> --out <slug>/audio/beats.json。
For product, brand, or technical terms that will appear in the visuals, verify anything you are unsure about first.

Hands-off mode: when the user says "go all out", "do whatever you want", "surprise me", or only gives a theme and no other requirements, enter hands-off mode: only keep the bottom line and the technical pipeline, and judge style, structure, and techniques yourself; you may completely avoid the styles in the style library. Still write a brief (this is how you make your own creativity controllable and reproducible), and still give 3 directions in Step 3.

Step 2: brief.md

First find benchmarks: before writing, choose 1–2 benchmark works for this film (this theme + this use), which can be film title sequences, commercials, games, motion works, or design movements. In the brief, write down "what to learn" (composition, rhythm, camera grammar, color logic, score structure) and "what not to learn" (characters, specific shots, melodies, logos, font files). Benchmarks raise the ceiling more than any rule.

Then think of three candidate structures: for example a journey, a before-and-after comparison, a countdown, one thing becoming another, a long take with no cuts. Write each in two or three lines, choose one, and state the reason. The first idea that comes up is often the cliché of this style.

PurposeandStyleChoose separately:

Purpose (what to shoot, what structure to tell it with) see references/formats.md, read only the corresponding section.
Style (what it looks like, how it moves, what it sounds like) first see references/styles/INDEX.md, thenread only the 1–2 selected style files. Styles can be used directly, adapted (replace one or two of the rules), mixed (one primary and one secondary, or switch media by section), or customized per styles/_template.md . Style rules stay fixed; the story, shots, and structure come from the user's theme, do not carry over from another film. Every style file has two sections, "Recognition signals" and "The most clichéd version": pick 2–3 signals based on the theme (at least one not among the clichés), and state in the brief which clichés were overturned, or why they were kept. When the user picks a style, what they want is to recognize that style at a glance; two or three signals are enough.
Then consult as needed references/craft.md(technique library).

Per references/brief-template.md write the brief, the core is:

Reel Read:
  format: [用途，formats.md 里的类型]
  benchmark: [对标作品 · 学什么 · 不学什么]
  structure: [三个候选结构 → 选中哪个、为什么]
  style: [styles/ 里的风格（含改造点），或者混搭方案，或者自定义规则]
  signals: [挑了哪 2–3 个辨识信号、为什么；翻掉了俗套的哪几条]
  takeaway: [观众记住的一句话或一个画面]
  hook: [前 1 秒发生什么]
  signature: [记忆点：第几秒、什么手法]
  palette / type / motion / camera / texture: [按所选风格写出具体值]
  sound: [无声 / 合成（声音对标、律动、和声、配器、曲线，见 sound.md 第 2 节）/ 用户曲子（BPM、drop）]
  forbidden: [这支片子的禁止清单]

Then in the brief write thebeat grid + shot list: first set the BPM and number of bars, one line per shot, stating clearly 拍号区间 | 画面（含原文文字）| 运动 | 镜头 | 声音 | 转场。

Even if the user only says "go all out," it must be translated into the specific constraints above, otherwise the result is a gamble.

Step 3: Style frames (🛑 the only pause point)

Create project:sh <skill>/scripts/scaffold.sh <slug> [--audio synth|tone|layer|none](default synth = tier 1 synthesis; copy only the selected score,build.sh 's AUDIO= is set accordingly too). The starter is only used to verify the pipeline runs; both the visuals and the copy must be replaced. First write timeline.js。

A. The user has already decided on a style(or gave a clear reference):

Build the hook frame, memory-point frame, and ending frame with real code, using the final colors, fonts, and copy.
render.mjs <slug> --still 0.6,7.2,14.5 --sheet, review it yourself first, fix obvious problems before showing the user. If the memory point relies on motion, additionally produce a 2–3 second sample (--start --duration）。
Send the user the Reel Read summary, shot outline, and style frames, and ask "Is the direction right?"

B. The user has not decided on a style (including hands-off mode): give 3 directions that are clearly differentiated, rules see styles/INDEX.md：

A fits the theme / brand, B switches to a different visual language (from another group), C is bold (custom, mixed, or structurally very bold, at least one direction is not off-the-shelf from the library).
For each direction write a mini Reel Read (style, benchmark, memory point, music direction, 3–5 lines), and render with real codeonekeyframe that best represents it. Put the three directions' pages in the same project, switch with ?dir=a|b|c . B and C only need to serve this one keyframe, they don't need to be a playable full film.
render.mjs <slug> --directions a,b,c --at 14.5,2,0 render all three at once and assemble them into a labeled qa/directions.png, send it to the user, and ask "Which one do you choose, or how should they be mixed?"

In both casesreally wait for the user's reply, then proceed to production. If the user said in advance that no confirmation is needed, choose one yourself, state the reason, and continue after self-review; at delivery, give the user the unchosen directions as well (for case B attach qa/directions.png, for case A write one sentence each about the other two possible directions), so the user can still switch back later.

Step 4: Production

Before production read references/stack.md(page contract, determinism, pitfalls of each technique). When you need ready-made patterns, consult references/recipes.md。

Write all time points into timeline.js, both the page and score.mjs import from here. Write the shot table into SHOTS(report motion per shot at acceptance), write deliberate holds into HOLDS(for example the end card [[b(36), DUR]]), and write heavy beats that need breathing room into DROPS; the acceptance tool reads them. When transitions need to land on the beat, use revealOn(拍点, 转场时长, 揭开点) to work back to the start point, so the frame where the new image appears lands on the beat.
Do it shot by shot. For each shot, render 3 stills: beginning, middle, and end; for fast motion use inspect.mjs strip to view consecutive frames.
Run the deterministic check render.mjs <slug> --determinism; if it fails, fix it first.
For pieces 30 seconds or longer or slow to render, produce a low-resolution preview first:--size 960x540 --out out/proxy.mp4。
Render the final: first at the top of build.sh set FPS、SIZE、AUDIO、LOOPaccording to the brief, then sh <slug>/build.sh. It builds the score, runs the deterministic check first (if it fails, no output), then renders, then runs the text framing check (only produces review materials, does not block the build), and finally runs the technical check with the same spec (taking the timeline.js of DUR）。--subframes、--dpr、--grain as a parameter appended afterward, add as the style requires. These parameters multiply the time cost; report the estimated time before starting the render.

Hard rules：

The image is determined only by t: do not use Math.random、Date.now, rAF, timers, or CSS animation, and do not save state between frames.
After fonts and assets are fully loaded, then set READY = true; host fonts in the project itself.
Derive layout from the width and height returned by stageSize() ; do not hardcode pixels.

Step 5: Sound (optional)

See references/sound.md. The sound direction (reference, groove, harmony, orchestration, curve) is decided in the brief in step 2; write this step according to it; choose one tier by style:

Tier	What to use	Suited for
Tier 1 · Built-in synthesis	`score.mjs`, the synthesizer in Node (drums, hand percussion, bass, pads, plucks, marimba / glockenspiel / kalimba, organ, vocal pads, FM, ambient noise floor, sound effects, sidechain, reverb, lo-fi processing), zero dependencies	Electronic, UI, chiptune, ambient, lo-fi, handmade and toy, most motion pieces
Tier 2 · Tone.js	`score.tone.js`, offline rendering with Tone.js in a headless browser: sampled instruments (`audio.mjs samples salamander` download CC BY piano), convolution reverb, richer synthesizers and effects	Styles that need real instruments, a sense of space, or a cinematic feel
External track	User-provided music (their own, licensed, or generated by an AI music service)	The user already has a score

Build:audio.mjs build <slug>/score.mjs or score.tone.js, both output −14 LUFS audio/music.wav。
User track: first run audio.mjs beats(automatically used when librosa is available), align to the timeline, then bring it in with S.load() in the score to layer sound effects.
Silent: skip this step.

You cannot hear the sound, so after every build you must run audio.mjs checkand look at the values and charts.timeline.js When DROPS is written into it, it also measures the dip in the half beat before each heavy beat and the lift on the heavy beat; if there is no breathing room, it gives a WARN.

Step 6: Acceptance

Technical check: determined by the program; if it fails, it cannot be delivered.

node <skill>/scripts/inspect.mjs qa <slug>/out/final.mp4 --out <slug>/qa/final \
  --expect-size 1920x1080 --expect-fps 30 --expect-duration 16 --audio required   # 无声片用 --audio none；循环片加 --loop

It checks whether the file can be decoded, dimensions, frame rate, duration, frame count, audio tracks, black frames, loudness, true peak, and loop seams (when needed). If any item is FAIL, the exit code is 1 and it must be fixed. Specification items that were not provided will be listed as NOT CHECKED, and in that case it does not count as passing acceptance.build.sh will automatically include the specifications. The rendering tool itself will also refuse to publish files with the wrong frame count.

Review: for human judgment, not programmatic determination. Look at extracted frame images, phone-size extracted frame images, frozen segments (those declared inHOLDS will be marked as intentional holds; for the rest, judge whether they are dead air), cut points, per-shot motion and flash frames, marked images for text framing (qa/text-*.png), audio graphs, and according to the references/review.md review sheet, write down observations item by item and the 3 most serious problems; for pieces with numbers and charts, verify the content and the numerical definitions. After fixing, re-render only the problematic segment, then output the full piece, and record the process in qa/review_log.md. When the host supports sub-agents, assign another agent that was not involved in production to look only at these materials and find problems (review.md "Independent Review").

The review conclusion is a reference for the user,it cannot replace the user watching the piece themselves. Mark inapplicable items as "not applicable", for example audio-video sync for silent works; do not force a score.

Step 7: Delivery

Tell the user:

out/final.mp4 and out/poster.png paths (poster:render.mjs <slug> --poster <t>）。
brief.md: the complete structured prompt, reusable.
Technical check results (all PASS), unresolved issues in the review record, rendering time.
How to rebuild (sh build.sh), how to change only one segment.
Sources and licenses of third-party materials (fonts, user materials, music); for factual content, remind the user to verify it again.

After delivery, spend a few minutes looking back: which move clearly made the piece better; if there is evidence (numbers, before-and-after comparison), record it in references/field-notes.md; add a note for the style used in the "practice record" of styles/INDEX.md , and write newly discovered weaknesses into the "pitfalls" of that style file. Record only reusable methods; keep the user's materials and private information in the project.

Bottom line (all styles must uphold)

Factual accuracy: product features, numbers, and names come only from the user or reliable sources; mark anything uncertain.
Text readability: font size is legible at phone size, and the dwell time is enough to finish reading (see craft.md section 7); text does not overflow, overlap, or get occluded.
Materials are licensed: logos, screenshots, fonts, and music must all be usable, and list them at delivery.
Technically correct: deterministic rendering, all technical checks pass, no black frames, and the ending must not cut off abruptly (ending freeze-frame or seamless loop).
Style consistency: the chosen style rules are upheld from beginning to end, and do not fall into the brief's prohibited list.

Beyond that, how much the camera moves, whether to use springs, sound effect density, and pacing are all determined by style and content (see references/styles/ and craft.md).

Tool quick reference (`S=<skill>/scripts`）

Purpose	Command
Install dependencies / check environment / self-test	`sh $S/setup.sh` · `node $S/check-env.mjs` · `cd $S && npm test`
Create project	`sh $S/scaffold.sh <slug> [--audio synth\|tone\|layer\|none]`
Still frames + contact sheet	`node $S/render.mjs <slug> --still 0.5,3,7.2 --sheet` · `--range 0:15:1 --sheet`
Three directions / cover	`node $S/render.mjs <slug> --directions a,b,c --at 14.5,2,0` → `qa/directions.png` · `--poster 14.5` → `out/poster.png`
Determinism	`node $S/render.mjs <slug> --determinism`
Text framing (review materials)	`node $S/render.mjs <slug> --text-check [--safe auto\|none\|T,R,B,L]` → `qa/text.json` + marker images (automatically run by build.sh)
Break down reference videos	`node $S/inspect.mjs grid <ref> --strips`(cut points + beat grid + transition consecutive frames) · `heat <ref>`(motion heatmap for each segment)
Draft / final cut / segments	`--size 960x540 --out out/proxy.mp4` · Final cut `sh <slug>/build.sh --subframes 2 --grain 4`(specs are at the top of build.sh) · `--start 6 --duration 3 --out out/seg.mp4`
Sound	`node $S/audio.mjs build <slug>/score.mjs`(or `score.tone.js`）· `samples salamander` · `beats <track> --out audio/beats.json` · `check audio/music.wav`(read `DROPS`）
Acceptance and review materials	`node $S/inspect.mjs qa out/final.mp4 --expect-…`(automatically included by build.sh) · `sheet` · `phone` · `strip --at 4.2` · `loop` · `motion`(read `SHOTS` / `HOLDS`: per-shot motion, jumps, flicker frames)

Reference files (read as needed)

File	When to read
`references/formats.md`	Step 2: purpose, such as promotional short film, portfolio, UI motion, typography beat sync, Logo, data highlight, green screen compositing
`references/styles/INDEX.md`	Step 2: catalog of 28 styles, three-direction rules, mix-and-match rules; then read only the selected `styles/<slug>.md`. For custom, use `styles/_template.md`
`references/craft.md`	Steps 2 and 4: rhythm, motion, transitions, shots, typography, color scheme, texture, memorable points, default flavor checklist
`references/brief-template.md`	When writing the brief
`references/stack.md`	Step 4: page contract, determinism, pitfalls of each technique, fonts, assets, multiple aspect ratios, performance
`references/recipes.md`	When ready-made approaches are needed
`references/sound.md`	Step 2 (Section 2: sound direction) and Step 5
`references/review.md`	Step 6: technical check instructions, review table, independent review, common issues, delivery checklist
`references/field-notes.md`	Step 2 when wanting to reference predecessors' practices; Step 7 write back after delivery