@docyrus/animaguru 0.13.0 → 0.15.0

package/skills/animaguru-shadow-theatre/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: animaguru-shadow-theatre
 description: Build Shadow Theatre visuals and motion in an AnimaGuru PixiJS video workspace. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
 ---
 
 # Shadow Theatre

package/skills/animaguru-silkscreen-poster/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: animaguru-silkscreen-poster
 description: Build Silkscreen Poster visuals and motion in an AnimaGuru PixiJS video workspace. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
 ---
 
 # Silkscreen Poster

package/skills/animaguru-stop-motion-objects/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: animaguru-stop-motion-objects
 description: Build Stop Motion Objects visuals and motion in an AnimaGuru PixiJS video workspace. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
 ---
 
 # Stop Motion Objects

package/skills/animaguru-studio-product-reveal/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: animaguru-studio-product-reveal
 description: Build Studio Product Reveal visuals and motion in an AnimaGuru PixiJS video workspace. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
 ---
 
 # Studio Product Reveal

package/skills/animaguru-video/SKILL.md

@@ -17,7 +17,7 @@ Read the sibling `animaguru` skill for authentication, model discovery, credit a
 
 1. If `category` is unset, first ask which category the user wants, offering **Explainer** (explain an idea, product, service or process), **Advertisement** (product, launch, offer, creator or editorial advertising), and **General Video** (films, music visuals, titles, loops or visual essays). Wait for the answer, then save `category` as `explainer`, `advertisement` or `general-video` and `setupStage` as `style`.
 2. With the category established, present its available visual styles from `animaguru.templates.json`. Share the [AnimaGuru animation-style gallery](https://animaguru.com/animation-styles), or open it in the internal browser when available, so the user can watch previews. Ask them to choose a style and wait. Present the installed styles as concise names and visual descriptions. With many options, offer the gallery and a brief shortlist suited to the user's stated preferences while keeping the full catalog available. Even if a category has only one style, ask for an explicit choice. Do not invent unavailable styles. The gallery is a visual aid; if it is unavailable, use the installed catalog and skill descriptions to continue the choice with the user.
-3. Save the chosen `template` ID and its `skill` name in `animaguru.project.json`, set `setupStage` to `brief`, and update the player's `shared/locales/en/player.json` template label to the selected category/style. Read that style's local `SKILL.md`, then run the quick interview below with its relevant visual questions. After the brief is complete, set `interview` to `complete` and `setupStage` to `ready`.
+3. Save the chosen `template` ID and its `skill` name in `animaguru.project.json`, set `setupStage` to `brief`, and update the player's `shared/locales/en/player.json` template label to the selected category/style. Read that style's local `SKILL.md` by path (`.claude/skills/SKILL/SKILL.md` or `.agents/skills/SKILL/SKILL.md`; style skills are not auto-loaded), then run the quick interview below with its relevant visual questions. After the brief is complete, set `interview` to `complete` and `setupStage` to `ready`.
 
 Keep the gallery URL in `galleryUrl`. All available style skills are already installed for both agents; selection does not require another CLI command, download, account or paid generation.
 
@@ -42,7 +42,7 @@ Cover the missing essentials, grouping related questions:
 4. **Visual and motion direction:** Apply the selected style skill's questions to the user's brand, references, preferred energy, subjects and asset constraints.
 5. **Production scope:** Existing assets/project, preferred models and authorized credit budget. Discover current estimates before spending. If generation is not authorized, prepare a concrete plan and request only the missing authorization.
 
-Save the answers in `production/brief.md`. Develop the story, sequence and pacing from that brief and the selected category. The visual template must not impose a family audience, emotional arc, fixed scene sequence, film length, narration tone or CTA. Once the brief is established, proceed with routine creative decisions without repeated approvals.
+Save the answers in `production/brief.md`. For a short vertical social ad (Reels, Shorts, TikTok, about 15–60 s), read `references/short-form-ad.md` next: it is the end-to-end command sequence, so the CLI, catalog and older films need no exploration. Develop the story, sequence and pacing from that brief and the selected category. The visual template must not impose a family audience, emotional arc, fixed scene sequence, film length, narration tone or CTA. Once the brief is established, proceed with routine creative decisions without repeated approvals.
 
 ## Production contract
 
@@ -56,7 +56,37 @@ Save the answers in `production/brief.md`. Develop the story, sequence and pacin
 - Motion must depend on absolute timeline time. Seed procedural variation once. Keep `window.animaguru.seek(seconds)` and `renderFrame(frame, fps)` working and asynchronous. When adding video, await its decoded frame and upload the texture before resolving a render. Do not use independent uncontrolled media clocks for exported scenes.
 - Update `src/film-resources.ts` with the real resources and start/end times whenever the film changes. This metadata drives the authoring timeline and `window.animaguru.resources`. Register image/video/audio files with public-relative `source` paths, and group repeated uses of the same resource into clips on its row. Keep the timeline in sync with scene/caption/audio timing and outside exported embed/capture layouts.
 - Write user-facing copy in `shared/locales/`. If adding languages, switch scene copy, captions, transcript and narration together; export an explicitly selected matching soundtrack. Load fonts covering the required glyphs.
-- Fit the real narration to cue timings. Mix the music underneath speech and save a full-length master locally; `config.audio` connects it to both preview and export. Do not report narration as complete if only transcript text exists.
+- Fit the real narration to cue timings. Mix the music underneath speech and save a full-length master locally; `config.audio` connects it to both preview and export. Do not report narration as complete if only transcript text exists. Use the audio tools below rather than writing your own cutting, beat-analysis or mixing scripts.
+
+## Film code: kit and scene modules
+
+Build on the shared kit instead of re-implementing helpers: `src/kit/` in a standalone project, root `runtime/kit/` in a workspace (import `../../../runtime/kit` from `animations/NAME/src/`). Read `kit/index.ts` and the starter `src/film.ts` for the API. It provides:
+
+- `FilmBase`: the player contract (stage, resources, captions toggle, review `texts` and `cues`, async `render`). A film passes `{ config, chapters, design?, captions?, captionStyle? }`, adds scenes in `build()` and registers per-frame updates with `film.on(t => …)`. Captions given to it become a burned-in `CaptionBar` placed inside the safe area and hidden in clean exports.
+- `cueSheet(timing)` and `joinCaptions()` over `production/audio/timing.json`: `cue.at("vo-03-turn", 1, 0.1)` is the second caption of that segment plus 0.1 s, so scenes follow the voiceover when it is re-cut. Never copy cue numbers into the code by hand.
+- Motion: `win`, `inOut`, `easeOut`/`easeIn`/`easeInOut`/`easeBack`, `bump`, `lerp`, `mixColor`, `hex`, seeded `rng`, `show`, `setText`.
+- Text and fonts: `txt(value, size, { family: "heading" | "body" | "mono", weight, fill, … })`, `useBrandFonts(branding, monoFamily?)`, `loadFonts([{ family, url }])` (variable fonts get their weight range), `gradientFill(colors)`.
+- Drawing: `panel`, `partialLine`, `bezier`, `pointAt`, `check`, `cross`, `person`, `glowTexture`, `vignetteTexture`, `rasterSvg` (exact-width logo textures), `Badge`, `Pill`.
+- Layout: `safeArea(config)` and `stack(nodes, { x, y, gap })`. Set `"safeArea": "reels"` (or `{ top, right, bottom, left }` pixels) in `film.config.json` for vertical social films; review checks text against it.
+
+Keep `src/film.ts` to setup and the scene list, and put each scene in `src/scenes/NAME.ts` as `export function hook(film: FilmBase, cue: CueSheet) { … }` that adds to `film.world` and calls `film.on`. Write and fix one scene file at a time with targeted edits rather than rewriting the whole film. Claude Code's Write tool refuses to replace a file that has not been opened with Read in this session (`cat` does not count), so Read the starter `src/film.ts` before replacing it.
+
+## Motion library
+
+Before choreographing a scene from scratch, search the AnimaGuru motion library for a finished example to start from: `animaguru motion search DESCRIPTION [--category ID] [--labels mobile,dark]` (natural language and keywords both work; `animaguru motion categories` lists the categories, such as `kinetic-typography` and `application-ui`). Each result describes what it looks like, its labels, techniques and duration. `animaguru motion get ID` prints its timed beats, options and code; `animaguru motion get ID --write src/scenes` (or `animations/NAME/src/scenes` in a workspace, where the kit import is rewritten for `runtime/kit`) writes the scene and its shared modules. Call its entry function from `build()` with `{ at }`, an area (`x, y, width, height`) and your copy, colors and fonts, then adapt the choreography to the brief rather than shipping the sample copy. The MCP tools `search_motion_examples` and `get_motion_example` return the same data. Search needs `animaguru auth login`; it spends no credits.
+
+## Asset library
+
+Pro and Team accounts can take ready-made music, sound effects, voice-overs, clips, images and sprites from the AnimaGuru asset library instead of generating them: `animaguru library search DESCRIPTION --type music|sfx|speech|video|image|sprite` (natural language and keywords). `animaguru library download ID --output public/assets/` saves a file into the film (sprites save their sheets with `animation.json` frame rectangles and timing); `animaguru library import ID --project PROJECT_ID` adds it to a cloud project instead. Prefer a library whoosh or background track over generating one; it spends no credits.
+
+## Voiceover, music and captions
+
+1. Generate the lines in one call: a batch file with shared speech defaults and one `{ name, prompt }` per segment, `animaguru assets batch PROJECT_ID --file production/generation/vo-lines.json --dry-run`, then `--yes --download production/audio/vo/`. Generate music with `assets generate … --type music --yes --download production/audio/music/`. See the `animaguru` skill for authorization.
+2. Write `production/audio/vo.json`: `{ "tempo": 1.12, "start": 0.25, "gap": 0.35, "maxPause": 0.26, "segments": [{ "id": "vo-01-hook", "captions": ["Four channel reports.", "Three versions of margin."] }] }`. Each segment's file defaults to `production/audio/vo/ID.wav`; `captions` are the on-screen lines (or give `text` to split at sentence ends), and `gapBefore` overrides the gap. Run `npm run audio:vo -- --animation NAME`. It trims silences, caps long pauses, speeds up the read, places the segments and writes `production/audio/work/vo-track.wav` and `production/audio/timing.json`; it warns when the voice runs into the end-card hold (`endHold`, default 3 s).
+3. Run `npm run audio:music -- --animation NAME --file production/audio/music/BED.mp3 --length DURATION [--drop SECONDS] [--end-hit SECONDS]`. It finds tempo, bars, sections and the final hit, and writes a bar-aligned edit to `production/audio/music-edit.json`, so the drop lands on `--drop` and the bed's own ending near `--end-hit`.
+4. Run `npm run audio:mix -- --animation NAME` (optional `production/audio/mix.json` for `musicDb`, `duck`, `loudness`, `output`). It ducks the music under the voice, masters two-pass to −14 LUFS and −2 dBTP, writes AAC to `public/assets/SLUG-mix.m4a` and sets `audio` in `film.config.json`.
+
+Drive scenes from `cueSheet(timing)` and captions from `joinCaptions(timing.captions)`; the `captions` resource track should list the same lines for `.srt`/`.vtt` export. These tools measure but do not listen: say so in delivery unless someone listened.
 
 ## Review and delivery
 
@@ -64,7 +94,7 @@ Run `npm run build`. Review the actual browser at desktop and mobile sizes, play
 
 Deliver the playable HTML film first unless the user asked for MP4 too. For an embeddable HTML5 deliverable, use the download menu or `npm run export:html`. Unzip and test the static package over HTTP(S), including its iframe example; it should play without the authoring workspace or an AnimaGuru account. `npm run build` includes the same download in the static player. Preserve embed mode and hide authoring controls there.
 
-For MP4, run `npm run export:mp4`, open the printed local capture URL in an available browser, and keep it open until completion. The script verifies H.264/AAC, dimensions, duration and exact frame count and writes a JSON report next to the MP4. Captions stay out of the picture; the `captions` resource track becomes `.srt` (YouTube, desktop players) and `.vtt` (HTML5) subtitle files with the MP4's name, so keep that track's clips equal to the spoken lines. For social feeds that need open captions, add `-- --burn-captions`; it saves `SLUG-LANGUAGE-captioned.mp4` with captions in the picture and no subtitle files. Set `"poster"` in `film.config.json` to the seconds of the film's most representative frame (title, product or end card, never a fade or a blank moment); the export saves it beside the MP4 as a 1280-pixel JPEG thumbnail, which `animaguru youtube upload` and video pages can use. Exporting existing local assets spends no generation credits. If browser control is unavailable, give the user the printed URL and explain the one manual step.
+For MP4, run `npm run export:mp4 -- --headless`; it captures in a local headless Chrome (installed Chrome or Edge, `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`, or `npx playwright install chromium`). Without `--headless`, open the printed local capture URL in a browser and keep it open until completion. The script verifies H.264/AAC, dimensions, duration and exact frame count and writes a JSON report next to the MP4. Captions stay out of the picture; the `captions` resource track becomes `.srt` (YouTube, desktop players) and `.vtt` (HTML5) subtitle files with the MP4's name, so keep that track's clips equal to the spoken lines. For social feeds that need open captions, add `-- --burn-captions`; it saves `SLUG-LANGUAGE-captioned.mp4` with captions in the picture and no subtitle files. Set `"poster"` in `film.config.json` to the seconds of the film's most representative frame (title, product or end card, never a fade or a blank moment); the export saves it beside the MP4 as a 1280-pixel JPEG thumbnail, which `animaguru youtube upload` and video pages can use. Exporting existing local assets spends no generation credits. If browser control is unavailable, give the user the printed URL and explain the one manual step.
 
 `npm run dev` starts the preview. The capture API and file map are documented in the generated project README. Publishing a website, package or campaign is separate from creating the local video.
 
@@ -74,7 +104,9 @@ The expanded styles include original 8-second procedural studies in `src/studies
 
 Use `src/studies/timing.ts` for analytic easing, measured stroke reveals and cue comparisons; `src/studies/media.ts` for optional source-time/trim mapping. Derive graphics, captions and audio events from shared cue data when synchronizing them. Keep procedural sound optional; generated narration/music and supplied tracks remain supported.
 
-`npm run review` prints a local browser URL. Open it to collect actual text bounds, representative frames and repeated cold-seek comparisons into `production/review/`. Optional cues with `audioTime` are checked to an output-frame tolerance. Reading-time notes are configurable design guidance, not a substitute for watching/listening; partial type reveals and occlusion still need visual review. Do not report a check as passed when metadata or media was unavailable.
+`npm run review -- --headless` collects actual text bounds every 0.2 s, representative frames and repeated cold-seek comparisons into `production/review/` and prints one line per finding (without `--headless`, open the printed URL). Besides seek, frame-bound, reading-time and cue checks, it flags overlapping text, text outside `safeArea`, text below `minTextSize` (default 2.2% of the shorter side) and film text under a burned-in caption, with time ranges. Fix those before looking at frames. Optional cues with `audioTime` are checked to an output-frame tolerance. Reading-time notes are design guidance, not a substitute for watching/listening; partial type reveals and occlusion still need visual review. Do not report a check as passed when metadata or media was unavailable.
+
+For visual review, run `npm run frames -- --animation NAME --at 1.3,4.9,…` (or `--every 3`, `--count 12`; `--no-captions`, `--full` for full-size JPEGs). It saves labelled contact sheets of up to 12 frames to `production/review/frames/` and prints the layout notes for those times. Look at one sheet instead of many single frames, and re-run only the times you changed.
 
 ## Sharing a finished film
 

package/skills/animaguru-video/references/short-form-ad.md

@@ -0,0 +1,57 @@
+# Short-form vertical ad (Reels, Shorts, TikTok)
+
+A tested sequence for a 15–60 s 9:16 ad with voiceover, music and burned-in captions, first used for a 45 s B2B product reel. It replaces exploring the CLI, the catalog and older films. Adapt the story to the brief: the beats below are a starting point, not a template.
+
+## 1. Brand and claims
+
+- If the shared kit is a placeholder, run `npm run inspect:site -- https://SITE --pages /product,/about` and follow `animaguru-brand-kit`. Look at `hero.png` and the saved logo files before using them.
+- Take product claims from the saved `text.md` pages and record them in `production/sources.json`. Do not invent customers, figures, testimonials or prices; label example values in interface mock-ups as illustrative.
+
+## 2. Film setup
+
+- `animaguru create animation NAME`, then save category, template and skill in its `animaguru.project.json`.
+- `film.config.json`: `"width": 1080, "height": 1920, "fps": 30, "duration": 45, "safeArea": "reels", "poster": END_CARD_SECONDS`.
+- One remote asset project for the film's media: `animaguru projects create --name "BRAND — reel"`.
+
+## 3. Script and beats
+
+A read at about 2 words per second, sped up 1.12×, fits 85–95 words into 45 s with a 3–4 s end-card hold. One voiceover segment per beat (`vo-01-hook`, `vo-02-problem`, …). This beat pattern worked for a 45 s ad:
+
+| Beat | Time | Job |
+| --- | --- | --- |
+| Hook | 0–5 s | One concrete, visual problem |
+| Problem | 5–11 s | Why it happens |
+| Turn | 11–15 s | The reframing line |
+| Product | 15–19 s | The product enters on the music drop |
+| Proof | 19–33 s | Two or three capabilities as interface moments |
+| Outcome | 33–37 s | What the viewer gets |
+| End card | 37–45 s | Logo, tagline, call to action, URL; voice ends by about 41 s |
+
+## 4. Generate the audio
+
+- `production/generation/vo-lines.json`: `{"defaults": {"type": "speech", "model": "gemini-3.8-flash-tts", "voice": "Kore", "delivery": "Confident, crisp diction, medium-brisk pace, short pauses at full stops."}, "assets": [{"name": "vo-01-hook", "prompt": "…"}]}`. Check current models and voices with `animaguru catalog --type speech`.
+- `animaguru assets batch PROJECT_ID --file production/generation/vo-lines.json --dry-run`, then `--yes --download production/audio/vo/`.
+- `animaguru assets generate PROJECT_ID --type music --name music-bed --prompt "STYLE, instrumental, tense intro, a clear drop, strong final hit" --yes --download production/audio/music/`. The bed comes back longer than the film; step 5 fits it.
+- Eight speech lines and one music bed cost about 10 credits for the first reel; always dry-run first and stay within the authorized budget. Keep the JSON receipts in `production/generation/`.
+
+## 5. Cut, fit and mix
+
+1. `production/audio/vo.json` with each segment's on-screen `captions`, then `npm run audio:vo -- --animation NAME`.
+2. `npm run audio:music -- --animation NAME --file production/audio/music/music-bed.mp3 --length 45 --drop PRODUCT_BEAT_START --end-hit END_CARD_START+5.5`.
+3. `npm run audio:mix -- --animation NAME`.
+
+## 6. Build the film
+
+- `src/film.ts`: `FilmBase` with `captions: joinCaptions(timing.captions)`; `cueSheet(timing)` times every scene; `film.mark(DROP, "Music drop")` records music hits for review. Scenes go in `src/scenes/*.ts`, one per beat.
+- Layout inside the Reels safe area: headlines at 72–96 px in the top third (y 260–600), interface cards in the middle (y 650–1350), labels at 26 px or more, and nothing but the caption below y 1440. The caption bar sits at about y 1500 by default.
+- `npm run build -- --animation NAME` typechecks.
+
+## 7. Review in two or three rounds
+
+- `npm run review -- --animation NAME --headless`, then fix every overlap, safe-area, small-text and caption line it prints.
+- `npm run frames -- --animation NAME --at TIMES`, with each beat's midpoint and each transition, gives one contact sheet per 12 frames. Fix what it shows, then re-run only the changed times.
+
+## 8. Export
+
+- `npm run export:mp4 -- --animation NAME --headless --burn-captions` for the feed upload (muted autoplay needs captions in the picture), and the same without `--burn-captions` for a clean MP4 with `.srt`/`.vtt`.
+- Report what was measured (frames, duration, codecs, loudness) separately from what was watched or listened to.

package/skills/animaguru-whiteboard-line-drawing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: animaguru-whiteboard-line-drawing
 description: Build stroke-by-stroke animated illustrations and annotations in marker, ink or chalk treatments. Use for the Whiteboard and Line Drawing visual style in an AnimaGuru video workspace.
+disable-model-invocation: true
 ---
 
 # Whiteboard & Line Drawing

package/templates/video/AGENTS.md

@@ -17,7 +17,8 @@ Selections and setup progress are recorded in `animaguru.project.json`. Availabl
 - Keep `src/film-resources.ts` aligned with the real film: add every image/video/audio/graphic resource and text layer, its actual cue times and public-relative source path. `Film.resources` powers the full-width timeline below the player. Do not leave demo resources in a finished film or invent audio tracks when none exist. The timeline belongs to the authoring player, outside embed/capture mode.
 - `shared/locales/`: all user-facing copy. `public/assets/`: local media. `production/`: brief, sources, storyboard, narration, requests and receipts.
 - Use `publicAsset("assets/file.ext")` from `src/assets.ts` for public media. Root-absolute paths break an HTML5 export hosted in a subfolder. `npm run export:html` produces a portable static ZIP with an iframe example; the download menu also supports this format. `npm run build` includes a ready-made HTML5 download for static hosting.
-- `npm run dev`: preview. `npm run build`: TypeScript check and production build. `npm run export:mp4`: local MP4 capture; open its printed URL and wait for completion.
+- `src/kit/`: shared film kit (`FilmBase`, cue lookup, text, shapes, captions, safe areas); the starter film shows its use. Put each scene of a real film in `src/scenes/*.ts`.
+- `npm run dev`: preview. `npm run build`: TypeScript check and production build. `npm run export:mp4 -- --headless`: local MP4 capture in headless Chrome (without `--headless`, open its printed URL and wait). `npm run review -- --headless` and `npm run frames -- --at 1.2,4.8`: layout checks and contact sheets. `npm run audio:vo|audio:music|audio:mix`: voiceover timing, music fit and mastering.
 
 Use strict TypeScript, two-space indentation and double quotes. Preserve the `window.animaguru` async seeking/frame API. Keep scene content and captions in the canvas. Load local assets and await video decoding for capture. Set the final duration and soundtrack in the shared config. Do not embed credentials or reuse another client's media.
 

package/templates/video/WORKSPACE-AGENTS.md

@@ -6,6 +6,7 @@ This root owns shared branding, installed skills, dependencies, the PixiJS playe
 - Read `branding/brand.json`, branding files/guides in `branding/`, and any relevant branding files the user placed at the root. If the kit is still the scaffold placeholder or incomplete, read `.agents/skills/animaguru-brand-kit/SKILL.md` (or `.claude/skills/animaguru-brand-kit/SKILL.md` in Claude Code). Use an official website or brand guide in the first prompt; if none was supplied, ask for one before researching the brand. Populate `branding/` and record sources in `branding/brand-guide.md`. Every animation inherits these shared settings. Keep guides local; exports include registered web assets, rather than the whole branding folder.
 - Read the installed `animaguru-video` skill and the selected film's `animaguru.project.json`. After establishing the shared brand source, first ask for **Explainer**, **Advertisement**, or **General Video**; then ask for a visual style using `animaguru.templates.json` and https://animaguru.com/animation-styles; then run the compact creative interview. Reuse explicit choices and supplied/completed answers. Save the brief inside that film's `production/` folder. Purpose and visual style are separate decisions.
 - Production paths such as `film.config.json`, `src/film.ts`, `src/film-resources.ts`, `public/assets/`, `shared/locales/en/film.json` and `production/` in style recipes are relative to the selected animation. Shared runtime examples are in root `runtime/studies/`. Do not copy the player, scripts, skills or node_modules into each animation.
+- Build films on the shared kit in `runtime/kit/` (`FilmBase`, cue lookup from `production/audio/timing.json`, text, shapes, captions, safe areas); keep each scene in its own `src/scenes/*.ts` file. The `animaguru-video` skill lists the kit and the audio tools.
 - Use the shared `runtime/assets.ts` helper for portable public media paths. A film constructor may receive a `FilmContext` with the shared branding, logo texture and registered asset paths. Imported artwork and audio belong in the selected film's public/assets/. Set its soundtrack in film.config.json; use null for an intentionally silent film. Narration in production/ is not automatically a web asset.
 
 Run commands from the workspace root:
@@ -13,8 +14,11 @@ Run commands from the workspace root:
 - `npm run dev`: the workspace hub and separate `/animations/NAME/` players.
 - `npm run build -- --animation NAME`: typecheck and build that film.
 - `npm run export:html -- --animation NAME`: portable HTML5 ZIP with local media and common branding.
-- `npm run export:mp4 -- --animation NAME`: verified MP4 without burned-in captions, plus `.srt`/`.vtt` subtitle files from the captions track (`--burn-captions` draws them into the picture instead, as `NAME-LANG-captioned.mp4`), and a `.jpg` thumbnail of the `poster` frame set in film.config.json; open the printed capture page.
-- `npm run review -- --animation NAME`: frame, text, seeking and soundtrack checks.
+- `npm run export:mp4 -- --animation NAME`: verified MP4 without burned-in captions, plus `.srt`/`.vtt` subtitle files from the captions track (`--burn-captions` draws them into the picture instead, as `NAME-LANG-captioned.mp4`), and a `.jpg` thumbnail of the `poster` frame set in film.config.json. Add `--headless` to capture in local headless Chrome; otherwise open the printed capture page.
+- `npm run review -- --animation NAME --headless`: frame, text, layout (overlap, safe area, text size), seeking and soundtrack checks, one line per finding.
+- `npm run frames -- --animation NAME --at 1.2,4.8`: labelled contact sheets in `production/review/frames/` plus layout notes for those times.
+- `npm run audio:vo|audio:music|audio:mix -- --animation NAME`: cut and place the voiceover (`timing.json`), fit the music bed, and master the soundtrack.
+- `npm run inspect:site -- URL`: brand evidence (screenshot, colors, fonts, logos, text) in `branding/source/HOST/`.
 - `npm run example -- STYLE_ID --animation NAME`: install a study only in an untouched selected film.
 - `animaguru submit animations/NAME --yes`: private hosting; choose recipients/public sharing from the user's request.
 - `animaguru cloud push -m "MESSAGE"`: in a linked workspace, save every film and the shared kit as a cloud version; `animaguru cloud pull` brings in teammates' versions.

package/templates/video/package.json

@@ -13,7 +13,12 @@
     "export:mp4": "node scripts/export-mp4.mjs",
     "export:html": "node scripts/export-html.mjs",
     "example": "node scripts/install-example.mjs",
-    "review": "node scripts/review.mjs"
+    "review": "node scripts/review.mjs",
+    "frames": "node scripts/frames.mjs",
+    "audio:vo": "node scripts/audio-vo.mjs",
+    "audio:music": "node scripts/audio-music.mjs",
+    "audio:mix": "node scripts/audio-mix.mjs",
+    "inspect:site": "node scripts/site-inspect.mjs"
   },
   "dependencies": {
     "pixi.js": "8.22.0"
@@ -22,6 +27,7 @@
     "@ffmpeg-installer/ffmpeg": "1.1.0",
     "@ffprobe-installer/ffprobe": "2.1.2",
     "fflate": "0.8.3",
+    "playwright-core": "1.64.0",
     "typescript": "5.9.3",
     "vite": "8.3.3"
   }

package/templates/video/scripts/audio-mix.mjs

@@ -0,0 +1,101 @@
+/**
+ * npm run audio:mix -- [--animation NAME] [--config production/audio/mix.json]
+ * Edits the music bed (production/audio/music-edit.json), ducks it under the voiceover, normalises the mix in two
+ * loudnorm passes (−14 LUFS, −2 dBTP by default) and encodes AAC for the film; then points film.config.json at it.
+ */
+import { mkdir, readFile, writeFile, access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { projectArguments, projectContext } from "./project-context.mjs";
+import { ffmpeg, measureLoudness, parseFlags, projectPath, readJson, round } from "./audio-tools.mjs";
+
+const RATE = 48000;
+export const MIX_DEFAULTS = { musicDb: -9, duck: { threshold: 0.03, ratio: 6, attack: 20, release: 350 }, loudness: { i: -14, tp: -2, lra: 9 } };
+
+/** The music part of the graph for input `input`, as edited by audio:music (a trim or a bar-aligned cut). */
+export function musicGraph(edit, { input = 0, duration, musicDb = MIX_DEFAULTS.musicDb, label = "music" }) {
+  const headIn = Math.max(0, Number(edit?.headIn ?? 0)), fadeIn = Number(edit?.fadeIn ?? (headIn > 0.05 ? 0.25 : 0.02)), fadeOut = Number(edit?.fadeOut ?? 0.6);
+  const ending = `atrim=0:${duration},apad=whole_dur=${duration},afade=t=out:st=${round(Math.max(0, duration - fadeOut))}:d=${fadeOut},volume=${musicDb}dB,aformat=sample_fmts=fltp:sample_rates=${RATE}:channel_layouts=stereo[${label}]`;
+  if (edit?.type === "cut") {
+    const crossfade = Number(edit.crossfade ?? 0.02), cutA = Number(edit.cutA), cutB = Number(edit.cutB);
+    if (!(cutA > headIn) || !(cutB >= 0)) throw new Error("A music cut needs cutA after headIn and a non-negative cutB.");
+    return [
+      `[${input}:a]asplit=2[${label}A][${label}B]`,
+      `[${label}A]atrim=${headIn}:${round(cutA + crossfade, 4)},asetpts=PTS-STARTPTS,aresample=${RATE},afade=t=in:d=${fadeIn}[${label}Head]`,
+      `[${label}B]atrim=${cutB},asetpts=PTS-STARTPTS,aresample=${RATE}[${label}Tail]`,
+      `[${label}Head][${label}Tail]acrossfade=d=${crossfade}:c1=tri:c2=tri,${ending}`,
+    ];
+  }
+  return [`[${input}:a]atrim=${headIn},asetpts=PTS-STARTPTS,aresample=${RATE},afade=t=in:d=${fadeIn},${ending}`];
+}
+
+/** The whole pre-loudness graph: optional music (input 0) and optional voiceover (next input), ending at [mix]. */
+export function mixGraph({ music, vo, edit, duration, musicDb = MIX_DEFAULTS.musicDb, duck = MIX_DEFAULTS.duck }) {
+  if (!music && !vo) throw new Error("Nothing to mix: set a voiceover track, a music bed, or both.");
+  const filters = [];
+  const voInput = music ? 1 : 0;
+  if (music) filters.push(...musicGraph(edit, { input: 0, duration, musicDb }));
+  if (vo) {
+    // Mono VO, a little presence and gentle compression, centred in stereo.
+    filters.push(`[${voInput}:a]aresample=${RATE},aformat=channel_layouts=mono,highpass=f=80,equalizer=f=3200:t=q:w=1.2:g=2,acompressor=threshold=-20dB:ratio=3:attack=5:release=120:makeup=3dB,pan=stereo|c0=c0|c1=c0,aformat=sample_fmts=fltp:channel_layouts=stereo,apad=whole_dur=${duration},atrim=0:${duration}${music ? ",asplit=2[vo][key]" : "[mix]"}`);
+  }
+  if (music && vo) {
+    filters.push(`[music][key]sidechaincompress=threshold=${duck.threshold}:ratio=${duck.ratio}:attack=${duck.attack}:release=${duck.release}:makeup=1[ducked]`);
+    filters.push(`[ducked][vo]amix=inputs=2:normalize=0,atrim=0:${duration}[mix]`);
+  } else if (music) filters.push(`[music]aformat=channel_layouts=stereo[mix]`);
+  return filters.join(";");
+}
+
+async function exists(file) { try { await access(file); return true; } catch { return false; } }
+
+async function main() {
+  const root = fileURLToPath(new URL("../", import.meta.url));
+  const selection = projectArguments(process.argv.slice(2));
+  const flags = parseFlags(selection.rest, { config: "string" });
+  const context = await projectContext(root, selection.animation);
+  const base = context.projectRoot, config = context.config, duration = Number(config.duration);
+  const mixFile = projectPath(base, flags.config ?? "production/audio/mix.json", "--config");
+  const mix = await readJson(mixFile, {});
+  const editFile = path.join(base, "production/audio/music-edit.json");
+  const plan = await readJson(editFile, null);
+  const voPath = mix.vo === null ? null : projectPath(base, mix.vo ?? "production/audio/work/vo-track.wav", "vo");
+  const vo = voPath && await exists(voPath) ? voPath : null;
+  if (mix.vo && !vo) throw new Error(`Voiceover not found: ${mix.vo}. Run npm run audio:vo first.`);
+  const musicRelative = mix.music === null ? null : mix.music ?? plan?.file ?? null;
+  const music = musicRelative ? projectPath(base, musicRelative, "music") : null;
+  if (music && !await exists(music)) throw new Error(`Music bed not found: ${musicRelative}.`);
+  const edit = mix.edit ?? plan?.edit ?? null;
+  if (music && !edit) console.log("No music edit found; the bed plays from its start and fades out. Run npm run audio:music for a fitted edit.");
+  const loudness = { ...MIX_DEFAULTS.loudness, ...mix.loudness };
+  const output = projectPath(base, mix.output ?? `public/assets/${config.slug}-mix.m4a`, "output");
+  const publicRoot = path.resolve(base, "public");
+  if (!output.startsWith(publicRoot + path.sep)) throw new Error("The mix output must be inside the animation's public/ folder so the player and exporter can load it.");
+  if (!output.endsWith(".m4a")) throw new Error("Write the mix as an .m4a file (AAC).");
+
+  const work = path.join(base, "production/audio/work");
+  await mkdir(work, { recursive: true });
+  await mkdir(path.dirname(output), { recursive: true });
+  const premaster = path.join(work, "premaster.wav"), master = path.join(work, "master.wav");
+  const graph = mixGraph({ music, vo, edit, duration, musicDb: mix.musicDb ?? MIX_DEFAULTS.musicDb, duck: { ...MIX_DEFAULTS.duck, ...mix.duck } });
+  await ffmpeg(["-y", "-loglevel", "error", ...(music ? ["-i", music] : []), ...(vo ? ["-i", vo] : []), "-filter_complex", graph, "-map", "[mix]", "-ar", String(RATE), "-ac", "2", "-c:a", "pcm_s24le", "-t", String(duration), premaster]);
+  // Two-pass loudnorm: measure, then normalise linearly with the measured values.
+  const first = await measureLoudness(premaster, loudness);
+  const second = `loudnorm=I=${loudness.i}:TP=${loudness.tp}:LRA=${loudness.lra}:measured_I=${first.integrated}:measured_TP=${first.truePeak}:measured_LRA=${first.range}:measured_thresh=${first.threshold}:offset=${first.offset}:linear=true`;
+  await ffmpeg(["-y", "-loglevel", "error", "-i", premaster, "-af", second, "-ar", String(RATE), "-ac", "2", "-c:a", "pcm_s24le", "-t", String(duration), master]);
+  await ffmpeg(["-y", "-loglevel", "error", "-i", master, "-c:a", "aac", "-b:a", "192k", "-ar", String(RATE), "-ac", "2", "-movflags", "+faststart", output]);
+  const result = await measureLoudness(output, loudness);
+
+  const configPath = path.join(base, "film.config.json");
+  const filmConfig = JSON.parse(await readFile(configPath, "utf8"));
+  const audio = path.relative(publicRoot, output).split(path.sep).join("/");
+  if (filmConfig.audio !== audio) { filmConfig.audio = audio; await writeFile(configPath, JSON.stringify(filmConfig, null, 2) + "\n"); }
+
+  const parts = [vo ? `voiceover ${path.relative(base, vo)}` : null, music ? `music ${path.relative(base, music)}${edit?.type === "cut" ? ` (${edit.headIn}–${edit.cutA} s → ${edit.cutB} s)` : edit ? ` (from ${edit.headIn} s)` : ""}` : null].filter(Boolean);
+  console.log(`Mixed ${parts.join(" + ")}${music && vo ? `, music at ${mix.musicDb ?? MIX_DEFAULTS.musicDb} dB, ducked under the voice` : ""}.`);
+  console.log(`Before normalising: ${round(first.integrated, 1)} LUFS, ${round(first.truePeak, 1)} dBTP. Encoded AAC: ${round(result.integrated, 1)} LUFS, ${round(result.truePeak, 1)} dBTP (target ${loudness.i} LUFS, ${loudness.tp} dBTP).`);
+  if (result.truePeak > -1) console.log("Warning: the encoded true peak is above -1 dBTP; lower loudness.tp in production/audio/mix.json and rerun.");
+  if (Math.abs(result.integrated - loudness.i) > 1) console.log("Warning: the encoded loudness is more than 1 LU off target; check for long silences or a very dynamic bed.");
+  console.log(`Wrote ${path.relative(base, output)}; film.config.json audio is "${audio}". Listen once with npm run dev before exporting.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/templates/video/scripts/audio-music.mjs

@@ -0,0 +1,175 @@
+/**
+ * npm run audio:music -- [--animation NAME] --file production/audio/music/BED.mp3 [--length 45] [--drop 17.1] [--end-hit 43]
+ * Finds the bed's tempo, bars, sections and final hit, then suggests a bar-aligned edit that fits the film:
+ * a downbeat at --drop, and the bed's own ending near --end-hit. Writes production/audio/music-edit.json for audio:mix.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { projectArguments, projectContext } from "./project-context.mjs";
+import { chromaFrames, cosine, decodePcm, detectBeats, onsetEnvelope, parseFlags, projectPath, round, writeJson } from "./audio-tools.mjs";
+
+const SAMPLE_RATE = 22050;
+
+function spanDb(pcm, sampleRate, from, to) {
+  let energy = 0, count = 0;
+  for (let index = Math.max(0, Math.floor(from * sampleRate)), end = Math.min(pcm.length, Math.floor(to * sampleRate)); index < end; index++) { energy += pcm[index] * pcm[index]; count++; }
+  return count ? 10 * Math.log10(energy / count + 1e-12) : -120;
+}
+
+/**
+ * Downbeat phase: a section entry is a rise in energy, sharpest at its true bar line. Each local maximum of the
+ * 8-beat after/before energy difference votes for its beat position within the bar. Falls (breakdowns, the final
+ * decay and its reverb tail) blur across bar lines, so they only vote when the bed has no rises.
+ */
+export function downbeatOffset(beatDb, { beatsPerBar = 4, window = 8, minStep = 3, audibleBeats = beatDb.length } = {}) {
+  const mean = (from, to) => { let sum = 0, count = 0; for (let index = Math.max(0, from); index < Math.min(beatDb.length, to); index++) { sum += 10 ** (beatDb[index] / 10); count++; } return count ? 10 * Math.log10(sum / count + 1e-12) : -120; };
+  const step = beatDb.map((_, index) => mean(index, index + window) - mean(index - window, index));
+  const tally = (sign) => {
+    const votes = new Array(beatsPerBar).fill(0);
+    for (let index = window; index < Math.min(step.length - 2, audibleBeats - window); index++) {
+      const value = sign * step[index];
+      if (value < minStep) continue;
+      let peak = true;
+      for (let other = Math.max(0, index - 2); other <= index + 2; other++) if (other !== index && sign * step[other] > value) peak = false;
+      if (peak) votes[index % beatsPerBar] += Math.min(value, 8);
+    }
+    return votes;
+  };
+  let votes = tally(1);
+  if (!votes.some(Boolean)) votes = tally(-1);
+  const best = votes.indexOf(Math.max(...votes));
+  return { offset: votes[best] > 0 ? best : 0, votes: votes.map((value) => round(value, 1)) };
+}
+
+/** Tempo, bars with energy and chroma, sections, lead-in, the final hit and where the sound ends. */
+export function analyzeMusic(pcm, sampleRate = SAMPLE_RATE) {
+  const duration = pcm.length / sampleRate;
+  const envelope = onsetEnvelope(pcm, sampleRate);
+  const beat = detectBeats(envelope.flux, envelope.fps, envelope.offset);
+  const beats = [];
+  for (let time = beat.phase; time + beat.period * 0.5 < duration; time += beat.period) beats.push(time);
+  const levels = Array.from(envelope.rms, (value) => 20 * Math.log10(value + 1e-9)), peak = Math.max(...levels);
+  const frameTime = (index) => index / envelope.fps + envelope.offset;
+  const audible = levels.map((value, index) => value > peak - 35 ? index : -1).filter((index) => index >= 0);
+  const leadIn = audible.length ? Math.max(0, frameTime(audible[0]) - 0.05) : 0;
+  const soundEnd = audible.length ? Math.min(duration, frameTime(audible.at(-1))) : duration;
+  const beatDb = beats.map((time) => spanDb(pcm, sampleRate, time, time + beat.period));
+  const { offset } = downbeatOffset(beatDb, { audibleBeats: beats.filter((time) => time < soundEnd).length });
+  const downbeats = beats.filter((_, index) => index % 4 === offset);
+  if (offset > 0 && beats[offset] - beat.period * 4 >= -beat.period * 0.5) downbeats.unshift(beats[offset] - beat.period * 4);
+  const chroma = chromaFrames(pcm, sampleRate);
+  const bars = downbeats.map((start, index) => {
+    const end = downbeats[index + 1] ?? Math.min(duration, start + beat.period * 4), profile = new Float64Array(12);
+    for (const frame of chroma) if (frame.time >= start && frame.time < end) for (let bin = 0; bin < 12; bin++) profile[bin] += frame.chroma[bin];
+    return { start, end, db: spanDb(pcm, sampleRate, start, end), chroma: profile };
+  });
+  // Sections start where the bar energy steps by 3 dB or more (or the harmony changes clearly).
+  const sections = [];
+  for (const [index, bar] of bars.entries()) {
+    const previous = bars[index - 1];
+    if (!previous || Math.abs(bar.db - previous.db) >= 3 || cosine(bar.chroma, previous.chroma) < 0.8) sections.push({ start: bar.start, end: bar.end, bars: 1, db: bar.db });
+    else { const section = sections.at(-1); section.end = bar.end; section.db = 10 * Math.log10((10 ** (section.db / 10) * section.bars + 10 ** (bar.db / 10)) / (section.bars + 1)); section.bars++; }
+  }
+  // The final hit: the first bar line after which the energy falls 6 dB or more and stays down to the end.
+  let finalHit = null;
+  for (let index = 1; index < bars.length; index++) {
+    if (bars[index].start > soundEnd) break;
+    if (bars[index - 1].db - bars[index].db >= 6 && bars.slice(index).every((bar) => bar.db < bars[index - 1].db - 4)) { finalHit = bars[index].start; break; }
+  }
+  if (finalHit === null) finalHit = (bars.filter((bar) => bar.start <= soundEnd - 1).at(-1) ?? bars.at(-1) ?? { start: soundEnd }).start;
+  return { duration, bpm: beat.bpm, beat: beat.period, phase: beat.phase, downbeatOffset: offset, bars, sections, leadIn, finalHit, soundEnd };
+}
+
+const similarity = (a, b) => (a && b ? cosine(a.chroma, b.chroma) - Math.abs(a.db - b.db) / 12 : 0);
+
+/**
+ * Bar-aligned edits that fit the film. With `drop`, a downbeat (cutA) lands at that film time and the tail resumes at
+ * a matching downbeat (cutB) chosen so the bed's final hit lands near `endHit`. Without `drop`, the cut may fall
+ * anywhere between 20% and 75% of the film. Short beds are trimmed and faded instead.
+ */
+export function planMusicEdit(analysis, { length, drop = null, endHit = null, preRoll = 0.04, crossfade = 0.02, fadeOut = 0.6 } = {}) {
+  if (!(length > 0)) throw new Error("Pass the film length in seconds.");
+  const decay = Math.max(0, analysis.soundEnd - analysis.finalHit);
+  const target = endHit ?? Math.max(length - 4, length - decay - 0.3);
+  const { bars } = analysis, candidates = [];
+  const tail = (filmAtCut, cutBar) => {
+    const finalFilm = filmAtCut + analysis.finalHit - cutBar.start, endFilm = filmAtCut + analysis.soundEnd - cutBar.start;
+    return { finalFilm, endFilm, landing: finalFilm - target, shortfall: Math.max(0, length - 0.3 - endFilm) };
+  };
+  // 1. Trim: one continuous stretch of the bed (no cut), so its continuity is perfect.
+  const trim = (headIn, note, rise = 0, whole = false) => {
+    const landing = analysis.finalHit - headIn - target, musicEnd = analysis.soundEnd - headIn;
+    const late = headIn > analysis.leadIn + 0.5 ? 0.1 : 0;
+    candidates.push({ type: "trim", headIn, score: (whole ? 2 : 1.5) + 0.08 * Math.min(rise, 8) - Math.abs(landing) - Math.max(0, length - 0.3 - musicEnd) - 0.01 * headIn - late,
+      film: { drop, finalHit: analysis.finalHit - headIn, musicEnd }, landing, note });
+  };
+  if (analysis.soundEnd - analysis.leadIn <= length + 0.25) trim(analysis.leadIn, "The bed fits the film; it plays from its start and fades at the end.", 0, true);
+  for (const [index, bar] of bars.entries()) {
+    const headIn = drop === null ? bar.start : bar.start - drop;
+    if (headIn < 0 || Math.abs(analysis.finalHit - headIn - target) > analysis.beat * 4) continue;
+    trim(headIn, drop === null ? `Starts at bar ${index + 1}.` : `Starts ${round(headIn, 2)} s in so bar ${index + 1} lands on the drop.`, drop === null ? 0 : Math.max(0, bar.db - (bars[index - 1]?.db ?? bar.db)));
+  }
+  // 2. Cut: head from headIn to bar A, then jump to bar B whose music matches what bar A would have played.
+  // A forward jump shortens the bed; a backward jump repeats bars to lengthen it.
+  const barLength = analysis.beat * 4;
+  for (const [a, barA] of bars.entries()) {
+    if (barA.start > analysis.finalHit) break;
+    let headIn, filmAtCut;
+    if (drop !== null) { headIn = barA.start - drop; filmAtCut = drop; if (headIn < 0 || headIn > 30) continue; }
+    else { headIn = analysis.leadIn; filmAtCut = barA.start - headIn; if (filmAtCut < 0.2 * length || filmAtCut > 0.75 * length) continue; }
+    const wanted = analysis.finalHit - (target - filmAtCut);
+    for (const [b, barB] of bars.entries()) {
+      if (Math.abs(b - a) <= 2 || barB.start > analysis.finalHit || Math.abs(barB.start - wanted) > barLength * 1.5) continue;
+      let start = headIn, at = filmAtCut, fit = tail(at, barB);
+      // Without a fixed drop, starting up to a bar later into the intro removes a late landing exactly.
+      if (drop === null && fit.landing > 0 && fit.landing < barLength) { start = headIn + fit.landing; at = barA.start - start; fit = tail(at, barB); }
+      const entry = Math.max(0, barA.db - (bars[a - 1]?.db ?? barA.db)), rise = drop === null ? 0 : Math.max(0, barB.db - (bars[a - 1]?.db ?? barB.db));
+      const score = similarity(barA, barB) + 0.5 * similarity(bars[a - 1], bars[b - 1]) + 0.06 * Math.min(entry, 8) + 0.08 * Math.min(rise, 8)
+        - Math.abs(fit.landing) - fit.shortfall - 0.01 * start - (start > analysis.leadIn + 0.05 && drop === null ? 0.05 : 0);
+      candidates.push({ type: "cut", headIn: start, cutA: barA.start - preRoll, cutB: barB.start - preRoll, score, film: { drop: at, finalHit: fit.finalFilm, musicEnd: fit.endFilm }, landing: fit.landing,
+        note: `Bar ${a + 1} → bar ${b + 1}${b < a ? ", repeating bars" : ""}.` });
+    }
+  }
+  if (!candidates.length) candidates.push({ type: "trim", headIn: analysis.leadIn, score: 0, film: { drop: null, finalHit: analysis.finalHit - analysis.leadIn, musicEnd: analysis.soundEnd - analysis.leadIn }, landing: analysis.finalHit - analysis.leadIn - target, note: "No bar-aligned edit fits; trimmed with a fade-out." });
+  candidates.sort((x, y) => y.score - x.score);
+  const tidy = (candidate) => ({ type: candidate.type, headIn: round(Math.max(0, candidate.headIn)), ...(candidate.type === "cut" ? { cutA: round(candidate.cutA), cutB: round(candidate.cutB), crossfade } : {}),
+    fadeIn: candidate.headIn > 0.05 ? 0.25 : 0.02, fadeOut, score: round(candidate.score), landingError: round(candidate.landing),
+    film: { drop: candidate.film.drop === null ? null : round(candidate.film.drop), finalHit: round(candidate.film.finalHit), musicEnd: round(candidate.film.musicEnd) }, note: candidate.note });
+  const unique = [];
+  for (const candidate of candidates) if (!unique.some((item) => item.type === candidate.type && Math.abs(item.headIn - candidate.headIn) < 1e-3 && item.cutB === candidate.cutB)) unique.push(candidate);
+  return { target: round(target), edit: tidy(unique[0]), candidates: unique.slice(1, 4).map(tidy) };
+}
+
+async function main() {
+  const root = fileURLToPath(new URL("../", import.meta.url));
+  const selection = projectArguments(process.argv.slice(2));
+  const flags = parseFlags(selection.rest, { file: "string", length: "number", drop: "number", "end-hit": "number", "pre-roll": "number" });
+  const context = await projectContext(root, selection.animation);
+  const base = context.projectRoot;
+  if (!flags.file) throw new Error("Usage: npm run audio:music -- [--animation NAME] --file production/audio/music/BED.mp3 [--length 45] [--drop 17.1] [--end-hit 43]");
+  const file = projectPath(base, flags.file, "--file");
+  const length = flags.length ?? Number(context.config.duration);
+  const pcm = await decodePcm(file, SAMPLE_RATE);
+  const analysis = analyzeMusic(pcm);
+  const plan = planMusicEdit(analysis, { length, drop: flags.drop ?? null, endHit: flags["end-hit"] ?? null, preRoll: flags["pre-roll"] ?? 0.04 });
+  const output = path.join(base, "production/audio/music-edit.json");
+  await writeJson(output, {
+    file: path.relative(base, file).split(path.sep).join("/"),
+    request: { length, drop: flags.drop ?? null, endHit: flags["end-hit"] ?? null, targetEndHit: plan.target },
+    analysis: { duration: round(analysis.duration), bpm: round(analysis.bpm, 2), beat: round(analysis.beat, 4), phase: round(analysis.phase), bars: analysis.bars.length,
+      downbeats: analysis.bars.map((bar) => round(bar.start)), leadIn: round(analysis.leadIn), finalHit: round(analysis.finalHit), soundEnd: round(analysis.soundEnd),
+      sections: analysis.sections.map((section) => ({ start: round(section.start, 2), end: round(section.end, 2), bars: section.bars, db: round(section.db, 1) })) },
+    edit: plan.edit, candidates: plan.candidates,
+  });
+  const describe = (edit) => edit.type === "cut"
+    ? `play ${edit.headIn}–${edit.cutA} s, cut to ${edit.cutB} s (${edit.note}); drop at film ${edit.film.drop} s, final hit at ${edit.film.finalHit} s (${edit.landingError >= 0 ? "+" : ""}${edit.landingError} s), sound to ${edit.film.musicEnd} s; score ${edit.score}`
+    : `play from ${edit.headIn} s without a cut (${edit.note}); final hit at film ${edit.film.finalHit} s (${edit.landingError >= 0 ? "+" : ""}${edit.landingError} s), sound to ${edit.film.musicEnd} s; score ${edit.score}`;
+  console.log(`Music: ${round(analysis.duration, 2)} s, ${round(analysis.bpm, 1)} BPM (beat ${round(analysis.beat, 4)} s), ${analysis.bars.length} bars, lead-in ${round(analysis.leadIn, 2)} s, final hit ${round(analysis.finalHit, 2)} s, sound ends ${round(analysis.soundEnd, 2)} s.`);
+  console.log(`Sections: ${analysis.sections.map((section) => `${round(section.start, 1)}–${round(section.end, 1)} (${section.bars} bars, ${round(section.db, 0)} dB)`).join(", ")}`);
+  console.log(`Target: final hit at film ${plan.target} s of ${length} s${flags.drop !== undefined ? `, drop at ${flags.drop} s` : ""}.`);
+  console.log(`Chosen: ${describe(plan.edit)}`);
+  for (const candidate of plan.candidates) console.log(`  alt: ${describe(candidate)}`);
+  console.log(`Wrote ${path.relative(base, output)}. Run npm run audio:mix to build the soundtrack (edit the "edit" block to pick an alternative).`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();