ConardLi/garden-skills

Motion Showreel

Turn an idea into a video focused on graphics, text, or UI animations, delivering an MP4 and reconstructable source code. Preserve the motion density and creative freedom of short clips, while also supporting chapter-based content up to 20 minutes.

Principle: The page exposes a deterministic render(t), the script captures frames frame-by-frame, and ffmpeg assembles the MP4. Visuals, voiceover, music, and sound effects share a single timeline.js. Without voiceover, visuals are organized by content and musical beat; with voiceover, the real speech timing takes precedence, with music and sound effects arranged around it.

Where a good film comes from: Change density, motion quality, a single memorable moment, and the relationship between image and sound—these four factors usually determine the viewing experience. But exactly how and how much things move is determined by style and content; not every film needs multi-angle shots, springs, and full-screen sound effects. Global rules only guard a few baselines (see "Baselines"), everything else is a starting point for the model, not a ceiling.

Video sense: For explainers, product demos, and narrative films, the behavior and relationships of objects should evolve with the content, maintaining spatial continuity between shots. Do not turn each sentence of a voiceover into a static title card wrapped with fades, zooms, and background particles. First, write storyboards clarifying "what change the audience needs to see, the before/after state of the subject, and how it connects to the previous shot," then choose motion effects. Logo, kinetic typography, loops, and deliberately static styles should still follow their own grammar; don't judge quality by constant motion or forced 60fps. See references/craft.md "Continuous Narration" for specifics.

---

Scope

User wants	Use this Skill?
Product promo, motion reel, UI animation, kinetic typography/beat-sync, logo reveal, intro, looping animation	✅
Green-screen character (from video model) + code-built scene, text, effects	✅ Characters provided by user (references/formats.md type H)
User provides a script or recording, wants an MP4 with explanation	✅ Voiceover-driven mode; TTS must use user's original script
Click-through, live presentation, interactive web demo, or article-to-script conversion	Use web-video-presentation
Webpage, landing page, interactive prototype, static visual draft	❌ Use web-design-engineer
Photorealistic human performance, live-action feel, editing existing footage, generating video directly from models	❌

Duration: Maximum 20 minutes (1200 seconds), based on the user's confirmed duration. Short films are still best at 5–60 seconds; don't make a long film a continuous high-density beat-sync. Over 2 minutes, read references/long-form.md, and plan, produce, and review by chapters. If the user's specified duration conflicts with the actual length of the voiceover or content, stop to confirm the adjustment plan; do not silently cut, speed up the voiceover, or change the duration.

Opus's Strengths and Default Traps

• Strengths: Can mix Canvas, SVG/DOM, WebGL, Three.js, even change media per section in one file; motion can be calculated with precise formulas (closed-form springs, beat grids, sub-frame motion blur); sound and visuals read the same timeline; can autonomously "render stills → review → modify" for extended periods; strong aesthetic judgment, a simple "give it your all" can produce stunning results.
• Default Traps: Without constraints, visuals tend towards dark backgrounds, centered large text, all elements fading in together, purple-blue gradients with glow, static camera; music tends to be A minor four-on-the-floor, an impact + crash on every downbeat, a gong on the logo, making several films sound like the same song. Therefore, first find benchmarks (for both visuals and sound), clearly define the style and a forbidden list. But constraints shouldn't be rigid: the style library and technique library are starting points, free to modify, mix, or customize as the theme requires.
• Handles poorly: Photorealistic characters, complex hands/fabric/hair, anything requiring real physical accuracy, photorealistic products (unless user provides models or images). When encountering these, stylize or use the green-screen character + code scene division.

---

Workflow

0 Environment Check (once)
1 Requirements Confirmation ──────── Fill missing items, summarize requirements → 🛑 Wait for user confirmation
2 brief.md ──────── Benchmark → Purpose + Style → Reel Read → Storyboard + Sound plan
3 Style Frames ────────── Style already defined: 3 frames; Style undefined: 1 frame for each of 3 directions → 🛑 Wait for user confirmation
4 Production ──────────── With voiceover: prepare real audio & timestamps first → timeline → shot by shot → proxy → final
5 Music & Mix ────── BGM, sound effects independent source selection; with voiceover: voice priority
6 Review ──────────── Technical check (programmatic, must all pass) + Review (look at images, list issues, user final review)
7 Delivery

Working directory: create <slug>/ inside the user's current directory. All files go inside: brief.md, index.html, motion.js, timeline.js, score.mjs or score.tone.js (based on scaffold's --audio selection), build.sh, fonts/, assets/, audio/, qa/, out/.

Step 0: Environment

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

Step 1: Requirements Confirmation (stop and wait for user)

Concentrate on asking for missing items. Do not repeat what has already been provided. The following information must be explicitly stated; fixed defaults must not replace user decisions:

Required Info	What to Clarify
Core topic, what to produce	What to present, what content must appear
Duration	Exact seconds or minutes, whether small fluctuations are allowed; must not exceed 1200 seconds
Landscape or portrait	Determine actual dimensions based on choice; also retain the ability for the user to specify other aspect ratios like 1:1. Can suggest resolution and frame rate, and include them in the confirmation summary
BGM source	AI-generated / User-provided; user may also explicitly turn it off
Sound effects source	AI-generated / User-provided; selected separately from BGM, can also be turned off
Voiceover method	None / AI TTS / User-provided recording

Conditionally required: When choosing TTS, the user must provide the voiceover script; do not write, supplement, modify, or synthesize without it. Also clarify the TTS service and required API configuration (reuse existing configuration; credentials via environment variables, not written into brief). Supports Gemini, MiniMax, and custom adapters, read references/narration.md as needed. When choosing user recording, require the recording file or accessible URL; when choosing user BGM/sound effects, require the corresponding files. The voiceover language, timbre, etc., can be inferred from the script or configuration and written into the summary; otherwise, ask provided.

Optional info: Reference materials, audience and publishing platform, theme style. If audience and platform are not given, infer based on content and explain in the summary. If style is not given, defer to the style frame stage to provide three directions.

How to handle assets: If the user has already given specific content and authorized AI generation, produce based on that. If the user has not provided sufficient specific content, ask for necessary materials, or conduct online research based on the topic, retaining sources. When a voiceover script is provided, first extract information from it, don't make the user repeat themselves. AI may generate illustrations, scenes, abstract graphics, and clearly marked illustrative content. Real product features, numbers, and brand materials still adhere to the "Baselines"; do not use fabricated information to impersonate real content. Requirements for brand logos or real product screenshots are in references/stack.md.

• If the user provides a reference video: First run inspect.mjs sheet <ref> --cells 30 for an overview, inspect.mjs grid <ref> --strips to measure cut points and their beat grid (BPM candidates, steps per segment, consecutive frames for each transition), inspect.mjs heat <ref> to see where and how much things move in each segment. Write the measurements into the brief's benchmark section. Only learn structure and techniques, do not copy assets.
• If the user provides a track: Without voiceover, first run audio.mjs beats <track> --out <slug>/audio/beats.json; with voiceover, music beats are subordinate to the narrative rhythm.
• For products, brands, or technical terms that should appear in the video, verify if unsure.

After filling in the gaps, summarize the topic, duration, aspect ratio, BGM/sound effects sources, voiceover method, and raw material status, then stop and wait for user confirmation before writing the brief. Even if the initial request has all the information, send a summary for confirmation first. If the user says "go all out," "surprise me," or "you decide," this only authorizes creative choices, not the omission of required information or skipping confirmations. You may only proceed without a specific confirmation if the user explicitly requests to skip it; record their authorization.

Free Rein Mode: Retain full creative autonomy, only adhering to baselines and the technical pipeline. Style, structure, and techniques can be determined independently, and the style library may be completely ignored. Still write a brief and provide three directions, performing the two confirmations per the rules above, unless the user explicitly waives a confirmation.

Step 2: brief.md

Find benchmarks first: Before writing, pick 1–2 benchmark works for this film (this topic + this purpose). These can be movie title sequences, commercials, games, motion design pieces, or design movements. In the brief, write down "what to learn" (composition, rhythm, camera grammar, color logic, music 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/after comparison, a countdown, one thing transforming into another, a single unbroken long take. Write each down in 2–3 lines, choose one, and state the reason. The first idea that comes to mind is often a cliché of that style.

Select Purpose and Style separately:

• For Purpose (what to film, what structure to use), read the relevant section in references/formats.md.
• For Style (what it looks like, how it moves, what it sounds like), first read references/styles/INDEX.md, then only read the 1–2 selected style files. Styles can be used directly, modified (replacing one or two rules), mixed (one primary, one secondary, or switching media per paragraph), or customized using styles/_template.md. Style rules stay fixed; the story, shots, and structure come from the user's topic, don't reuse them from other films. Each style file has a "Identity Signals" and "Cheapest Version" section: pick 2–3 signals for the topic (at least one not from the cliché list), and write in the brief which clichés were subverted, or why they were kept. When a user picks a style, they want to recognize it instantly; two or three signals are enough.
• Then read references/craft.md (technique library) as needed.

Write the brief using references/brief-template.md. The core is:

Reel Read:
  format: [purpose, type from formats.md]
  benchmark: [benchmark work · what to learn · what not to learn]
  structure: [three candidate structures → which chosen, why]
  style: [style from styles/ (including modifications), or mix plan, or custom rules]
  signals: [which 2–3 identity signals were chosen, why; which clichés were subverted]
  takeaway: [one sentence or image the audience remembers]
  hook: [what happens in the first second]
  signature: [memorable moment: at what second, using what technique]
  palette / type / motion / camera / texture: [specific values based on chosen style]
  sound: [silent / synthesized (sound benchmark, groove, harmony, orchestration, curve, see sound.md section 2) / user track (BPM, drop)]
  audio-sources: [BGM and sound effects each as AI / user / off]
  narration: [none / user script TTS / user recording; with voiceover: sentence timeline path, voice priority]
  forbidden: [forbidden list for this film]

Then write the storyboard: Without voiceover, retain the beat grid + storyboard table. With voiceover, associate sentences with shots and events, write Shot / Sentence ID | Change to explain | Subject start/end state | Inherited objects and space | Key events and time basis | Shot & Sound. One shot can cover multiple sentences; one sentence can have multiple actions. Do not treat voiceover sentence breaks as cut commands, and don't require each sentence to fill the screen. Actual intervals are backfilled after audio preparation; do not use word count estimates as the final alignment reference. For long-form, additionally write a chapter table, chapter durations, and cross-chapter consistency rules.

If the user only says "go all out," translate that into the specific constraints above; otherwise, the result is luck-based.

Step 3: Style Frames (second stop for user confirmation)

Set up the project: sh <skill>/scripts/scaffold.sh <slug> [--audio synth|tone|layer|file|none] (synth = level 1 synthesis; only copy the selected score; file uses the prepared final audio track). The scaffold's engine defaults are for technical initialization only, they cannot replace requirements confirmation. The starter is only to verify the pipeline works; replace all visuals and copy.

A. User has already defined the style (or provided clear references): The seconds in the commands below are just examples. Use the actual effective times for the film's opening, signature moment, and ending. Do not copy 14.5 seconds for short or long films.

1. Build the hook frame, signature frame, and ending frame with real code, using the final colors, fonts, and copy.
2. render.mjs <slug> --still 0.6,7.2,14.5 --sheet. Review it yourself first; fix obvious issues before showing to the user. If the style relies on motion, also produce a continuous proxy (using --start --duration) per the requirements below in this section.
3. Send the Reel Read summary, storyboard outline, and style frames to the user, asking "Is the direction correct?"

B. User has not defined the style (including Free Rein Mode): Give 3 clearly distinct directions, rules in styles/INDEX.md:

• A: Fits the theme/brand. B: A different visual language (from another group). C: Bold (custom, mixed, or structurally daring. At least one direction should not be a ready-made library style).
• Write a mini Reel Read (style, benchmark, memorable moment, music direction, 3–5 lines) for each direction, and render one representative keyframe for each using real code. Place the three directions in the same project, switchable via ?dir=a|b|c. Directions B and C only need to serve this single keyframe; they don't need to be playable full films.
• Run render.mjs <slug> --directions a,b,c --at 14.5,2,0 to render all three and compose them into qa/directions.png with labels. Send to the user, asking "Which one, or how to mix?"

In both cases, actually wait for the user's response before entering production. For TTS projects, also provide the user's original script segmentation plan and a short vocal sample (using only the user's text), confirming the sound direction together. Do not add extra mandatory stops. If the user explicitly stated no confirmation is needed, choose one yourself, state the reason, self-review, and continue; at delivery, include the unchosen directions (for case B, include qa/directions.png; for case A, write one line each about the two other possible directions), so the user can revisit later.

For directions that rely on continuous motion, provide a 6–10 second representative motion sample (or the full film if under 6 seconds) in addition to stills, covering one state change and its lead-in/out. First review the consecutive frames yourself to eliminate jumps. Include the sample with the style frames for confirmation; do not add a third mandatory stop. If the voiceover is not yet generated, clearly label it as a motion preview and do not claim exact synchronization with speech.

Step 4: Production

Before production, read references/stack.md (page contract, determinism, pitfalls of each technology). For ready-made solutions, check references/recipes.md.

With voiceover, first lock in the narration timeline: Synthesize the user's script or import their recording per references/narration.md, obtaining the real duration and sentence-level timestamps. Then arrange the visuals. For user recordings, obtain text and timestamps via available transcription tools or user-provided SRT/JSON; without reliable timestamps, do not claim exact sentence-level alignment. If a duration conflict arises, confirm it first; do not silently fill, crop, or speed up. Import the real intervals into the shot table, preserving pauses and emphasis in the narration; do not forcibly align to musical bars. For content over 2 minutes, produce by chapter per references/long-form.md, retaining chapter caches.

Sentence segments only provide sync ranges; shots and subject motion can flow continuously across sentences. For key changes requiring word-level sync, use real word timestamps or manually annotated anchors via narration.js, allowing visuals and sound effects to reference the same event; with only sentence-level timestamps, maintain sentence-level sync and do not fabricate per-word timestamps. During production, use preview.mjs with audio for scrub preview and frame-by-frame inspection; previews only drive the same render(t), they do not enter the official render.

1. Write all time points into timeline.js; the page and score.mjs both import from it. Write the shot list into SHOTS (the review tool reports motion per shot), write deliberate holds into HOLDS (e.g., a logo card [[b(36), DUR]]), write impactful downbeats needing breath into DROPS. The review tools read these. When transitions should hit the beat, use revealOn(beat, transitionDuration, revealPoint) to calculate the start time, so the new content's reveal frame lands on the beat.
2. Produce shots one by one. Render 3 stills for each shot: beginning, middle, and end. For key state changes and shot edges, check continuous proxies to ensure subjects aren't reset, motion speed doesn't jump, and shots don't break. Good stills do not replace motion checks; for fast motion, use inspect.mjs strip to check consecutive frames.
3. Run the determinism check: render.mjs <slug> --determinism. If it fails, fix it first.
4. For films 30 seconds or longer, or slow to render, first produce a low-resolution proxy: --size 960x540 --out out/proxy.mp4.
5. Produce the final film: First set FPS, SIZE, AUDIO, LOOP at the top of build.sh based on the brief. Then run sh <slug>/build.sh. It builds the music, runs the determinism check first (no film if it fails), then renders, then runs the text framing check (produces review materials only, doesn't block the build), and finally runs a technical check with the same specs (duration from timeline.js's DUR). Append --subframes, --dpr, --grain as extra parameters as needed by the style. These parameters significantly increase processing time; report the estimated time before rendering.

For mixed audio tracks, use AUDIO=file AUDIO_FILE=audio/final.wav sh build.sh. The old synth/tone/layer/none build methods remain available. Long-form films use build-long.mjs for persistent chapter-by-chapter builds, see references/long-form.md.

Hard Rules:

• Visuals must be determined only by t. Do not use Math.random, Date.now, requestAnimationFrame, timers, or CSS animations. Do not maintain state between frames.
• Load all fonts and assets completely before setting READY = true. Self-host fonts in the project.
• Derive layout from the width and height returned by stageSize(). Do not hardcode pixel values.

Step 5: BGM, Sound Effects & Mix

See references/sound.md. BGM and sound effects are produced according to their confirmed sources, allowing combinations like user-provided music + AI sound effects. The table below shows engine options for AI synthesis. Do not override confirmed source selections with engine defaults. The sound direction (benchmark, groove, harmony, orchestration, curve) is defined in the brief:

Level	What to Use	Best For
Level 1 · Built-in Synth	score.mjs, synthesizer in Node (drums, tablas, bass, pad, pluck, marimba/glockenspiel/kalimba, organ, vocal pad, FM, ambient noise, sound effects, sidechain, reverb, lo-fi processing), zero dependencies	Electronic, UI, chiptune, ambient, lo-fi, handcrafted/toy-like, most motion design films
Level 2 · Tone.js	score.tone.js, offline render in headless browser using Tone.js: sampled instruments (audio.mjs samples salamander downloads CC BY piano), convolution reverb, richer synthesizers and effects	Styles needing realistic instruments, spatial feel, cinematic quality
External Track	User-provided music (their own, licensed, or from AI music services)	User already has a track

• Building: audio.mjs build <slug>/score.mjs or score.tone.js, both output audio/music.wav at -14 LUFS.
• User Track: Without voiceover, first run audio.mjs beats (auto-uses librosa if available) to align the timeline, then in the score use S.load() to layer sound effects. With voiceover, use musical beats only as reference, adjusting music and effects around the speech; do not move the confirmed narration timeline.
• Silent: Skip when BGM, sound effects, and voiceover are all off. Turning off only BGM does not mean the whole film is silent.
• With voiceover: Reduce melody, dense percussion, and large dynamics in the music; use sound effects only for informative actions, avoiding key words and sentence beginnings. Retain separate tracks, use narration.mjs mix for ducking during speech, unified loudness, and peak processing. Use real sentence timestamps to check visuals, but the listening experience still requires user final review.

After every build, run audio.mjs check on the final mix to review numbers and plots. When the host supports auditioning, also listen; do not equate passing numerical checks with confirmed listening quality. If DROPS is defined in timeline.js, the check will also measure the dip and rise before the downbeat; if there's no breath, it issues a WARN.

Step 6: Review

Technical Check: Programmatic judgment. Failure means no delivery.

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   # use --audio none for silent films; add --loop for loops

It checks: file decodability, dimensions, frame rate, duration, frame count, audio track, black frames, loudness, true peak, and loop seam (if applicable). Exit code is 1 on any FAIL. Must fix failures. Any spec not passed will be listed as NOT CHECKED and the review is incomplete. build.sh automatically passes the specs. The render tool itself also refuses to publish files with wrong frame counts.

Review: For human judgment, not programmatic. Examine: sampled stills, phone-sized sampled stills, frozen segments (those declared in HOLDS are marked as deliberate holds; the rest need judgment for empty beats), cut points, per-shot motion and flash frames, text framing marked images (qa/text-*.png), audio plots. Use the review checklist in references/review.md, write down observations and the most critical 3 issues in writing. For films with numbers or charts, verify the numbers and data consistency. After fixing, re-render only the problematic segment, then the full film. Log the process in qa/review_log.md. If the host supports sub-agents, assign one unrelated to production to review only these materials for issues (review.md "Independent Review").

With voiceover, additionally run narration.mjs check to verify sentence timeline coverage, audio length vs. confirmed specs; review sentence by sentence whether script, visuals, and speech are consistent. Automated checks cannot replace auditory review. For long-form, review chapter by chapter and check the seams for visuals, sound, and timeline.

The review conclusion is a reference for the user, it does not replace the user watching the film. Mark inapplicable items as "N/A", such as audio-visual sync for silent works. Do not force scores.

Step 7: Delivery

Tell the user:

• Paths to out/final.mp4 and out/poster.png (poster: render.mjs <slug> --poster <t>).
• brief.md: The complete structured prompt, with records of the two confirmations. Reusable. Does not contain API credentials.
• With voiceover: Include the user's original script, sentence-level timeline, and sources for each track. For long-form: include chapter manifest and chapter rebuild commands.
• Technical check results (all PASS), unresolved issues from the review log, render duration.
• How to rebuild (sh build.sh), how to modify only one segment.
• Sources and licenses for third-party assets (fonts, user assets, tracks). Remind the user to double-check factual content.

Save the review conclusions and verified evidence in the project's qa/review_log.md, and deliver it with the production files.

---

Baselines (apply to all styles)

1. Requirements & Script: Required info confirmed; video does not exceed 20 minutes; TTS script must come from user. Duration conflicts require confirmation; do not revise script, truncate, or speed up without authorization.
2. Factual Accuracy: Product features, numbers, names only from user or reliable sources; mark anything uncertain.
3. Text Readability: Font size legible at mobile dimensions; display duration sufficient for reading (see craft.md section 7); text does not overflow, overlap, or get occluded.
4. Assets Licensed: Logos, screenshots, fonts, music must all be usable; list them at delivery.
5. Technical Correctness: Deterministic rendering, all technical checks pass, no black frames, ending not abrupt (either a deliberate hold or seamless loop).
6. Style Consistency: Selected style rules followed throughout; do not fall into the brief's forbidden list.

Beyond this, how much the camera moves, whether to use springs, the density of sound effects, the pace—all are determined by style and content (see references/styles/ and craft.md).

---

Quick Command Reference (S=<skill>/scripts)

Purpose	Command
Install deps / Check env / 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|file|none]
Stills + grid	node $S/render.mjs <slug> --still 0.5,3,7.2 --sheet · --range 0:15:1 --sheet
Three directions / Poster	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 material)	node $S/render.mjs <slug> --text-check [--safe auto|none|T,R,B,L] → qa/text.json + marked images (build.sh runs automatically)
Analyze reference film	node $S/inspect.mjs grid <ref> --strips (cut points + beat grid + transition frames) · heat <ref> (motion heatmap per segment)
Proxy / Final / Segment	--size 960x540 --out out/proxy.mp4 · Final sh <slug>/build.sh --subframes 2 --grain 4 (specs at 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 (reads DROPS)
Narration / Final Mix	node $S/narration.mjs tts … · import … · mix … · check … (parameters in narration.md)
Long-form rebuild	node $S/build-long.mjs <slug>/chapters.json (parameters in long-form.md)
Preview with sound	node $S/preview.mjs <slug> --size 1920x1080 --fps 30 (add --audio audio/final.wav; usage in stack.md)
Review & QC materials	node $S/inspect.mjs qa out/final.mp4 --expect-… (build.sh passes these automatically) · sheet · phone · strip --at 4.2 · loop · motion (reads SHOTS / HOLDS: per-shot motion, jumps, flash frames)

Reference Files (read as needed)

File	When to Read
references/formats.md	Step 2: For Purpose, e.g., promo, reel, UI animation, kinetic typography, logo, data burst, green-screen compositing
references/styles/INDEX.md	Step 2: Catalog of 43 styles, three-direction rules, mixing rules. Then read only the selected styles/<slug>.md. Use styles/_template.md for custom styles
references/craft.md	Steps 2 and 4: Rhythm, motion, transitions, camera, typography, color, texture, memorable moment, default flavor checklist
references/brief-template.md	When writing the brief
references/stack.md	Step 4: Page contract, determinism, pitfalls of each technology, fonts, assets, multi-aspect, performance
references/recipes.md	When you need a ready-made technique
references/sound.md	Step 2 (Section 2: Sound Direction) and Step 5
references/review.md	Step 6: Technical check explanation, review checklist, independent review, common issues, delivery checklist
references/narration.md	When selecting TTS, user voiceover, or independent BGM/sound effect mixing
references/long-form.md	Over 2 minutes: Chapter planning, persistent caching, segmented audio, and checkpoint resume