@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/motion-video/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: motion-video
+description: "Produce beat-synced 1080p motion-graphic videos in AICUT (HTML + GSAP) with an AI voice-over, Vietnamese karaoke captions, SFX and generated music, in one of two proven styles (glass keynote or Spider-Verse-style comic). Use when the user asks for a launch/release/feature video, motion graphic, animated explainer or promo clip, or a restyle of an existing one. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "bestagentkits/motion-video-skill"
+---
+
+# Motion video
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Make a 1920×1080 30 fps motion-graphic video where the scene cuts land on the
+music's beats, reveals land on spoken words, and the audio is broadcast-clean.
+The workflow is fully scripted: facts → script → multix audio → forced
+alignment → beat grid → bar-spliced music → timeline + mix → HTML composition →
+lint/check/snapshot → render → remux → social encode.
+
+Two finished editions show what each style should feel like. Their working
+projects are deliberately not bundled here: the generated voice-over, music and
+SFX are large and provider-licensed. Study the published demo, then build every
+new video from `assets/templates/index-skeleton.html` plus the style reference.
+
+| Style | Style reference | Public demo | Feel |
+|---|---|---|---|
+| Comic multiverse | `references/style-comic-spiderverse.md` | [Dewee v3.34 comic edition](https://x.com/goon_nguyen/status/2103332658151555231), the 151 s social encode | loud, playful, hand-made |
+| Glass keynote | `references/style-glass-keynote.md` | the 144 s edition of the same release | premium, calm, clear |
+
+## Scope
+
+This skill handles:
+- New videos in either style, restyles of an existing video as a separate project,
+  and partial reworks (new music, re-timed drops, re-mix, re-render, social encode).
+- Audio through the `multix` CLI: Gemini TTS voice, ElevenLabs SFX, ElevenLabs
+  Music composition plans, ElevenLabs forced alignment.
+
+This skill does NOT handle:
+- Generative text-to-video footage (use `multix` Seedance/Veo directly).
+- React/Remotion compositions or generic HyperFrames questions (use the
+  hyperframes or remotion skills).
+- Publishing to social accounts: produce the file and let the user post it.
+
+## How to work
+
+1. Pin the outcome before touching files: topic and sources, style (one of the
+   two, or a new one derived from them), duration, voice language (English VO +
+   Vietnamese captions by default), ending, signature. Ask only if the style or
+   the facts source is unknown.
+2. Create `assets/videos/<slug>/` (never overwrite a finished edition) and a plan
+   under `plans/` following the repo convention. Copy the templates from
+   `assets/templates/` of this skill: `scripts/*.mjs`, `data/*.example.json`
+   (rename to `.json`), `hyperframes.json`, `index-skeleton.html` as
+   `index.html`, plus `scripts/fit-beat-grid.py`.
+3. Follow `references/production-pipeline.md` step by step. Each step writes a
+   file the next one reads, so do not reorder them.
+4. Get the music right with `references/audio-and-beat-sync.md`: fit the grid,
+   splice bars so the drops land where the script needs them, verify the splice,
+   and measure the voice/music balance.
+5. Build `index.html` with `references/composition-contract.md` and the chosen
+   style reference, starting from `assets/templates/index-skeleton.html`. When a
+   scene type repeats (stats, diagrams, charts, terminal, graph, outro), follow
+   the demo's choreography for that scene instead of inventing a new one.
+6. Finish only when every check in "Done when" passes; report measured numbers,
+   not impressions.
+
+Keep credentials inside multix's own config. Never print API keys or copy them
+into project files, plans or reports.
+
+## Done when
+
+- `hyperframes lint` and `check` pass; snapshots of every scene were reviewed.
+- `verify-arrangement.py` reports every segment within ±2 ms and
+  `measure-mix-balance.py` shows the music ~4–6 dB under speech.
+- ffprobe: 1920×1080, 30 fps, expected duration, AAC 48 kHz stereo;
+  ebur128 ≈ −14 LUFS with peak ≤ −1 dBFS; blackdetect finds nothing outside fades.
+- `build-timeline` printed no clip/overlap/missing-word warnings.
+- On-screen facts trace to the sources collected in step 1.
+
+## Resources
+
+- `references/production-pipeline.md`: every command from scaffold to social
+  encode and studio preview, plus the rebuild table.
+- `references/audio-and-beat-sync.md`: voice, SFX cues, music plans,
+  bar-splice arrangement, anchors, mix numbers and the ducking pitfall.
+- `references/composition-contract.md`: TIMING shape, helpers, determinism,
+  scene windows, captions, mascot, renderer limits, signature.
+- `references/style-glass-keynote.md` / `references/style-comic-spiderverse.md`:
+  tokens, fonts, layers, components, transitions and caption look per style.
+- `scripts/fit-beat-grid.py <music> [--min-bpm N --max-bpm N]`: BPM, BEAT0 and a
+  per-bar kick/energy table.
+- `scripts/verify-arrangement.py <project> [--tolerance-ms 2]`: splice lag per
+  segment; exits 1 on drift.
+- `scripts/measure-mix-balance.py <project>`: music under speech vs in gaps,
+  from `build-timeline.mjs --stems`.
+- `scripts/tests/`: `python -m unittest discover -s scripts/tests` (needs
+  ffmpeg, numpy, scipy).
+- `assets/templates/`: project scripts (`generate-audio-assets`,
+  `align-voiceover`, `arrange-music`, `build-timeline`), example data files and
+  the composition skeleton.
+
+## Source
+
+Rewritten for AICUT from [`bestagentkits/motion-video-skill`](https://github.com/bestagentkits/motion-video-skill)
+(MIT), skills/motion-video/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/motion-video/references/audio-and-beat-sync.md

@@ -0,0 +1,109 @@
+# Audio and beat sync
+
+## Voice-over
+
+- Model `gemini-3.8-flash-tts` through `multix gemini generate-speech`, one call
+  per scene with all its lines joined. Style prompts that worked:
+  - hype: "Hyped animated superhero movie trailer narrator with hip-hop swagger.
+    Fast, punchy, playful, big grin in the voice, crisp diction, dramatic little
+    pauses before reveals." (voice Fenrir, comic)
+  - keynote: "Energetic, upbeat tech product launch announcer. Confident, warm
+    and playful, fast pace, crisp diction, smiling voice." (voice Puck, glass keynote)
+  - outro: "Calm, warm and intimate, slow and soft, a quiet hopeful promise at
+    the end of a movie."
+- Energetic lines are sped up 8% in the mix (`TEMPO = 1.08`, ffmpeg `atempo`);
+  outro lines keep natural pace.
+- Each line is cut from the scene WAV between its aligned first/last word with
+  0.08 s pre-roll and 0.15 s tail, never past the midpoint to the neighbour line,
+  then placed on the timeline independently. That is what lets a single line
+  ("Let's go!") sit in a silent stop or a word ("Nits") hit a drop.
+
+## Sound effects
+
+`data/sfx.json`: `{ id, prompt, duration }` → `multix elevenlabs sfx --prompt-influence 0.6`.
+`data/cues.json` places them; each cue has `sfx`, optional `vol` (default 0.5),
+`offset`, and exactly one anchor:
+
+| Anchor | Meaning |
+|---|---|
+| `scene` + `word` (+ `nth`) | onset of that spoken word |
+| `beat` | quarter note n of the music grid |
+| `abs` | absolute seconds |
+| `scene` + `at` | seconds after the scene cut |
+
+Prefer word and beat anchors; they survive re-timing. The comic edition used
+19 SFX files and 62 cues.
+
+## Music generation
+
+MiniMax Music answered HTTP 410 for new accounts and fal.ai was not configured,
+so both videos use ElevenLabs Music composition plans:
+
+```bash
+multix elevenlabs music --plan data/music-plan.json --format mp3_44100_192 --output ./assets/audio/music/bgm-raw.mp3
+```
+
+- Put BPM, key and instrumentation in `positive_global_styles`, and write the
+  intent of each section into its local styles (intro, build, drop, groove,
+  breakdown, final drop, tail). Ask for a "hard stop / one beat of silence" before
+  the first drop if the script has a shout line there.
+- ElevenLabs does not honour `duration_ms` per section. Expect the drops in the
+  wrong places and fix that with the arrangement step, not by re-rolling.
+- Generate the calm ending as a separate short composition (`outro-plan.json`)
+  and fade it in under the main track's tail (`OUTRO_BED`).
+- Keep the previous `bgm-raw.mp3` before regenerating so you can compare.
+
+## Beat grid
+
+`scripts/fit-beat-grid.py` fits a constant-tempo grid (BPM, BEAT0) to low-band +
+full-band onsets and prints one row per bar: kick marks (`K`/`.`) and RMS dB.
+Read the energy column to find the source's own intro, builds, drops and
+breakdowns. librosa is deliberately not used; its import hung on Windows.
+
+## Bar-splice arrangement
+
+`data/music-arrangement.json` maps target beat ranges to source beats:
+
+```json
+{ "source": "./assets/audio/music/bgm-raw.mp3", "output": "./assets/audio/music/bgm.flac",
+  "bpm": 110, "beat0": 0.04, "crossfade": 0.025, "fadeOut": { "beat": 244, "seconds": 6.5 },
+  "segments": [ { "to": [0, 16], "from": 0, "role": "intro" }, { "to": [40, 76], "from": 76, "role": "drop A" } ] }
+```
+
+- Copy whole bars (multiples of 4 beats) so phrasing stays musical; take each
+  target drop from a source bar where a build resolves into a drop.
+- A gap between segments (e.g. target beats 38–40 left empty) becomes a silent
+  stop: the classic place for a shout line right before the drop.
+- Joins are 25 ms crossfades that end exactly on the target downbeat.
+- The first segment must start at 0 s. If it starts later, ffmpeg `amix`
+  re-bases the stream and every segment shifts (a uniform 40 ms lag happened).
+- Verify with `scripts/verify-arrangement.py <project>`; the reference result was
+  within ±0.5 ms for all nine segments.
+
+## Timeline anchors
+
+In `build-timeline.mjs`: `KICK` lists beat ranges where the full beat plays
+(drives visual pulses), `DROPS` the drop beats (big flash/shake/speed lines),
+`ANCHORS` pins scene cuts and line onsets to `beat(n)` or seconds. Scenes without
+anchors cut on the first beat at least 0.12 s after the previous voice ends.
+Comic anchors: "Let's go!" at beat 38 (silent stop), feature 01 at drop A
+(beat 40), feature 07 at drop C (152), the word "Nits" on the final drop (200),
+outro on the calm bed from 136.4 s.
+
+## Mix
+
+```text
+music  -5 dB  -> sidechaincompress(threshold=0.03, ratio=3, attack=15, release=350, makeup=1) keyed by the voice bus
+voice  per-scene gain to -16 LUFS, peaks <= -1 dBFS
+sfx    per-file gain to -16 LUFS, cue vol on top
+sum -> 3.5 s fade out -> two-pass loudnorm I=-14 TP=-1.5 LRA=11 -> AAC 192k 48 kHz (./assets/audio/mix.m4a)
+```
+
+Balance target: music ~5 dB under the voice while speaking and near voice level
+in the gaps. The first edition used −7 dB with ratio 5 / threshold 0.02: the
+music sat ~10 dB under the voice and viewers reported "there is no music".
+Measure with `build-timeline.mjs --stems` + `scripts/measure-mix-balance.py`
+instead of trusting the numbers by ear on laptop speakers.
+
+The voice bus is also rendered to a mono envelope at the video frame rate
+(`data/vo-envelope.json`, `TIMING.env`) that drives mouths and waveforms.

package/skills/motion-video/references/composition-contract.md

@@ -0,0 +1,107 @@
+# Composition contract
+
+Rules every `index.html` follows, independent of the visual style. The skeleton
+at `assets/templates/index-skeleton.html` implements all of them.
+
+## HyperFrames runtime
+
+- Root: `<div id="root" data-composition-id="main" data-start="0" data-duration="N"
+  data-width="1920" data-height="1080">`. `build-timeline.mjs` rewrites
+  `data-duration` on `#root` and `#mix` from `DURATION`.
+- One paused GSAP timeline registered as `window.__timelines["main"]`; the
+  renderer seeks it frame by frame. End with `tl.set({}, {}, T.duration)` so the
+  timeline length equals the video length.
+- Audio is one element: `<audio id="mix" src="./assets/audio/mix.m4a" data-start="0"
+  data-duration="N" data-track-index="10" data-volume="1">`. Never let the page
+  play separate VO/SFX files; the ffmpeg mix is the single source of sound.
+- GSAP from `cdn.jsdelivr.net/npm/gsap@3.14.2`; fonts as local TTF files with
+  `font-display: block`.
+
+## Determinism
+
+- All times come from `window.TIMING` (injected between `/*TIMING:BEGIN*/` and
+  `/*TIMING:END*/`). No `Date`, no `requestAnimationFrame`, no CSS animations or
+  transitions: only timeline tweens.
+- Randomness only through the seeded `rng(seed)` helper.
+- Build all DOM synchronously before the first tween (mascots, word spans,
+  generated rows, SVG nodes). Nothing is created during playback.
+- Use `immediateRender: false` on `fromTo` tweens that reuse a shared layer
+  (flash, wipe, dots, speed lines, RGB offsets); otherwise the first tween's
+  start state leaks to time 0.
+
+## TIMING shape
+
+```text
+duration, fps, beat0, beatLen, kick[[from,to)], drops[beat], outroBeat,
+scenes{ id: { start, end, lines[{ on, off, words[[word, start, end]] }] } },
+captions[{ start, end, words[[text, start]] }], sfx[{ sfx, vol, t }], env[frame] (0..1)
+```
+
+Words are lower-cased with punctuation stripped (`"let's"`, `"v334"`), so look
+them up that way.
+
+## Helpers
+
+| Helper | Use |
+|---|---|
+| `B(n)` | time of quarter note n |
+| `isKick(n)` | beat n is inside a full-beat range; scale reactions by it |
+| `W(sid, word, nth)` / `WE(...)` | onset / end of a spoken word; warns and falls back to scene start when missing |
+| `envKeys(el, t0, t1, step, map)` | keyframes from the voice envelope (mouths, waveforms, meters) |
+| `pop`, `rise`, `slideX`, `flipIn`, `draw`, `typeIn`, `bump`, `odo`, `fadeOut` | entrance vocabulary shared by both styles |
+| `flash`, `shake` | cut/drop punctuation on shared layers |
+
+Choreograph with word anchors: "the chip appears on the word *OAuth*", not
+"0.8 s after the scene starts". Re-timing the voice then moves visuals with it.
+
+## Scene windows
+
+A `WINDOWS` table lists `[selector, scene id, transition, ...style fields]`. One
+loop turns it into: transition in at the scene start, transition out just before
+the next scene start (the out-transition matches the next window's kind), a
+flash/speed accent on cuts scaled by `isKick`, and `intro(sc, t0)` for the
+scene's headline. Scene starts come from `TIMING.scenes`, which already sit on
+beats. Big moments (`TIMING.drops`) get their own flash + shake.
+
+## Beat reactions
+
+Loop `n` over beats until `outroBeat`; on kick beats pulse a background layer
+(orbs or halftone), on kick downbeats scale a `#pulse` wrapper by ~1%. Keep it
+subtle: reactions are texture, cuts and drops carry the rhythm.
+
+## Captions
+
+- Vietnamese karaoke: one `.cap` per caption chunk (≤ 9 words, split at
+  punctuation), each word a span that highlights at its borrowed English onset.
+- Bottom band only, width stops left of the signature (1660 px of 1920 in the
+  comic edition). Nothing else may live in that band: `check` will flag overlap.
+
+## Mascot and HUD
+
+- Mascot is inline SVG built by a `mascot(uid, accessory)` function with
+  `.m-move` (position), `.m-squash` (squash/stretch from the feet), `.m-face`
+  (fake head turn by sliding the face), `.m-eyes`, `.m-pupils`, `.m-mouth`.
+  Accessories per scene (headphones, cape, glasses) make it reusable.
+- Talking = `envKeys` on `.m-mouth` scaleY between line on/off.
+- A HUD counter (feature n / 12 + progress segments) runs from the first
+  feature scene to the last and hides for cover and outro.
+
+## Renderer limits
+
+- More than ~40 elements with `radial-gradient`, `filter: blur()` or
+  `clip-path` on screen produced black frames. Bake textures (halftone dots,
+  grain, graffiti, distress) into PNG tiles under the project's `assets/images/` and use them as
+  `background-image` or `mask-image`.
+- Attach SVG filters (RGB split) only while an effect runs: `tl.set(el, { filter:
+  "url(#rgb)" })` and back to `none` a few frames later.
+- `visibility` toggles are cheaper than `opacity: 0` for heavy full-frame layers
+  (halftone wipes).
+- Keep `index.html` in one file unless it gets unwieldy; lint warns above ~1000
+  lines (`composition_file_too_large`) but renders fine. The references are
+  1332 and 1636 lines.
+
+## Signature
+
+"Zuey" handwritten signature bottom-right from 1.0 s to the end: text revealed
+with a stepped `clipPath`, underline drawn with `strokeDashoffset`. Style it to
+match the video (marker font with misregistration for comic).

package/skills/motion-video/references/production-pipeline.md

@@ -0,0 +1,147 @@
+# Production pipeline
+
+The end-to-end flow that produced both reference videos. Each step feeds a file
+to the next, so run them in this order. Paths are relative to the project dir
+(e.g. `assets/videos/<slug>/`) and written `./scripts/...` for the project's
+copies; `<skill>` is this skill's directory.
+
+## 0. Scaffold
+
+```text
+<project>/
+  index.html                 composition (start from <skill>/assets/templates/index-skeleton.html)
+  hyperframes.json           copy <skill>/assets/templates/hyperframes.json
+  data/                      script.json, sfx.json, cues.json, music-plan.json, outro-plan.json, music-arrangement.json
+  scripts/                   copy <skill>/assets/templates/scripts/*.mjs and <skill>/scripts/fit-beat-grid.py
+  assets/fonts/              local TTF files (OFL/Apache fonts from Google Fonts)
+  assets/images/             baked texture tiles (PNG)
+  assets/audio/{vo,sfx,music}/
+  renders/
+```
+
+Start the data files from `<skill>/assets/templates/data/*.example.json`.
+Keep one project per video; a restyle of an existing video is a new project dir
+so the first edition stays untouched.
+
+## 1. Facts and script
+
+- Collect facts only from primary sources (release notes, repo docs, code). Every
+  on-screen label must trace to one; write the evidence into a short report
+  under `plans/reports/` before scripting.
+- `data/script.json`: `voice` (model, voice, style), `outroStyle`, `scenes[]`.
+  Each scene has `id` (`sNN-slug`, used as the VO file name and the timing key),
+  optional `outro: true`, and `lines[]` with `en` (displayed/aligned text),
+  optional `say` (pronunciation for TTS, e.g. "three point thirty-four"), and `vi`
+  (caption). Keep one idea per line: lines are the unit of placement.
+- Budget: ~150 words of VO per minute at TEMPO 1.08. The references are 144 s and
+  151 s with 16 scenes (cover, stats, 12 features, stability, outro).
+
+## 2. Generate audio (multix)
+
+```bash
+node ./scripts/generate-audio-assets.mjs vo      # Gemini TTS, one WAV per scene
+node ./scripts/generate-audio-assets.mjs sfx     # ElevenLabs SFX from data/sfx.json
+node ./scripts/generate-audio-assets.mjs music   # ElevenLabs Music from music-plan.json + outro-plan.json
+```
+
+`--force` regenerates, `--only=id1,id2` limits to some scenes/SFX. The script runs
+multix in a temp dir because multix drops copies into `./multix-output`.
+Credentials come from multix's own config; never print or copy key values.
+Music details, the arrangement and the mix are in `audio-and-beat-sync.md`.
+
+## 3. Align the voice
+
+```bash
+node ./scripts/align-voiceover.mjs        # ElevenLabs forced alignment -> data/vo-lines.json
+```
+
+Warnings like `12 aligned words vs 13 script tokens` mean `say`/`en` tokenize
+differently from what was spoken; fix the text or re-generate that scene.
+
+## 4. Beat grid and music arrangement
+
+```bash
+python ./scripts/fit-beat-grid.py ./assets/audio/music/bgm-raw.mp3 --min-bpm 100 --max-bpm 130
+# edit data/music-arrangement.json (bpm, beat0, segments) from the bar table
+node ./scripts/arrange-music.mjs          # -> ./assets/audio/music/bgm.flac
+python <skill>/scripts/verify-arrangement.py .   # every segment lag within +-2 ms
+```
+
+## 5. Timeline and mix
+
+Edit the `EDIT` block of `./scripts/build-timeline.mjs` (KICK ranges, DROPS,
+OUTRO_BED, DURATION, ANCHORS), then:
+
+```bash
+node ./scripts/build-timeline.mjs --dry       # schedule only: scene starts (with beat numbers) and line spans
+node ./scripts/build-timeline.mjs             # + captions, SFX cues, audio mix, voice envelope, TIMING injection
+node ./scripts/build-timeline.mjs --no-audio  # timing only (keeps the existing mix and envelope)
+node ./scripts/build-timeline.mjs --stems     # also writes stems for the balance check
+python <skill>/scripts/measure-mix-balance.py .
+```
+
+Read every warning: `clips the previous voice`, `overlaps previous line`,
+`voice runs past its scene end`, `cue: "word" #n not found`. Each one is a
+visible or audible defect; fix the anchor or the cue rather than ignoring it.
+
+## 6. Composition
+
+Author `index.html` against `composition-contract.md` and one style reference.
+Choreograph each scene with `W(sid, "word")` so reveals land on the spoken word.
+
+## 7. Validate
+
+```bash
+npx --yes hyperframes@0.7.99 lint
+npx --yes hyperframes@0.7.99 check
+npx --yes hyperframes@0.7.99 snapshot --at 2,18.5,40,80,120,148 --describe false
+```
+
+`check` flags overlaps and contrast; use `data-layout-allow-overlap` only on
+intentional overlaps (stacked cards, mascots over panels). Snapshots are large
+PNGs: downscale to JPEG before viewing them if the tool context is limited.
+Look at every scene's busiest moment, the caption band and the signature.
+
+## 8. Render, restore the mix, verify
+
+```bash
+npx --yes hyperframes@0.7.99 render -q high -f 30 --strict -o renders/<slug>.mp4
+ffmpeg -y -i renders/<slug>.mp4 -i ./assets/audio/mix.m4a -map 0:v:0 -map 1:a:0 -c copy -movflags +faststart renders/out.mp4
+# replace renders/<slug>.mp4 with renders/out.mp4
+ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,sample_rate,channels -show_entries format=duration renders/<slug>.mp4
+ffmpeg -i renders/<slug>.mp4 -af ebur128=peak=true -f null -          # ~ -14 LUFS, peak <= -1 dBFS
+ffmpeg -i renders/<slug>.mp4 -vf blackdetect=d=0.1:pix_th=0.05 -an -f null -   # no black segments except the fades
+```
+
+The remux matters: the renderer re-encodes AAC and pushed the true peak to
+0.0 dBFS in the first edition; copying the untouched `mix.m4a` keeps −14 LUFS /
+−1.5 dBTP.
+
+## 9. Social encode
+
+```bash
+ffmpeg -y -i renders/<slug>.mp4 -c:v libx264 -preset slow -crf 21 -maxrate 6M -bufsize 12M \
+  -pix_fmt yuv420p -profile:v high -level 4.1 -g 60 -c:a aac -b:a 192k -ar 48000 \
+  -movflags +faststart renders/<slug>-social.mp4
+```
+
+Result on the comic edition: 406 MB → 101.6 MB, SSIM 0.977. Check with
+`ffmpeg -i social.mp4 -i master.mp4 -lavfi ssim -f null -` when quality matters.
+
+## 10. Studio preview
+
+```bash
+npx --yes hyperframes@0.7.99 preview --port 3002 --no-open .
+```
+
+Run it as a tracked background process, reuse it if the port is already held
+by this project, and stop it when the session ends.
+
+## Rebuild cheatsheet
+
+| Changed | Re-run |
+|---|---|
+| Script text of a scene | `generate-audio-assets vo --only=<id> --force` → `align-voiceover --force` → `build-timeline` |
+| Music track | `fit-beat-grid` → edit arrangement → `arrange-music` → `verify-arrangement` → `build-timeline` |
+| Anchors / cues | `build-timeline` (audio changes) or `--no-audio` (captions/timing only) |
+| Visuals only | `lint` → `check` → `render` → remux |

package/skills/motion-video/references/style-comic-spiderverse.md

@@ -0,0 +1,87 @@
+# Style: comic multiverse (Spider-Verse inspired)
+
+Loud, hand-made comic energy: halftone Ben-Day dots, thick ink outlines,
+cyan/magenta misregistration, RGB glitch cuts, halftone dot wipes, speed-line
+bursts, graffiti, a skyline in exaggerated perspective, and motion "on twos".
+Reference edition: the [published Dewee v3.34 comic
+video](https://x.com/goon_nguyen/status/2103332658151555231), 151 s, 110 BPM,
+voice Fenrir, drops at beats 40/152/200, signature "Zuey".
+
+Choose it for hype launches, social cuts and anything that should feel young
+and playful. Inspired by the look only: no Marvel names, logos or characters.
+
+## Tokens
+
+```css
+--ink: #0d0a1a; --paper: #fff6e5; --cyan: #19d3ff; --magenta: #ff2e9a;
+--red: #ff2b3a; --yellow: #ffd21f; --purple: #5b1fd1; --violet: #1a0b3d;
+--orange: #ff7a1a; --green: #2ee59d;
+--rx: 0;   /* misregistration offset, animated on beats */
+```
+
+Fonts (all OFL except Permanent Marker, Apache 2.0): Anton (headlines), Bangers
+(labels, kickers, SFX words), Permanent Marker (signature, graffiti notes),
+Be Vietnam Pro 700/800 (captions), JetBrains Mono (code, logs).
+
+## Layers (back to front)
+
+`#stage` wraps the whole world and receives the RGB glitch filter. Inside it:
+five "universes" (`.uni#u-night|cyan|sun|punk|red`, full-frame gradient
+backgrounds cross-faded per scene) → `#rays` (repeating-conic sunburst, slow
+140° rotation) → `#skyline` (per-scene toggle) → `#tags` (graffiti PNG, slow
+drift) → `#tone` (dots PNG with radial mask, pulses on beats) → `#shake` →
+`#pulse` → scenes `#sc01…#sc16`. Above the stage: `#speed` → `#glitch-bars` →
+`#dots` (halftone wipe) → `#flash` → `#hud` → `#captions` → `#sig` → `#grain`
+(overlay PNG) → `#edge` vignette → `#fade`.
+
+Baked textures in the project's `assets/images/`: `dots-ink.png`, `dots-cyan.png`,
+`dots-pink*.png`, `grain.png`, `graffiti-tags.png`, `distress.png`,
+`grid-dot.png`. They exist because the live radial-gradient versions blacked out
+frames in the renderer.
+
+## Components
+
+- `.panel`: paper card, 6 px ink border, triple offset shadow
+  `-6px -4px 0 cyan, 6px 4px 0 magenta, 16px 16px 0 ink`, halftone `::before`
+  in a corner mask, optional `.hatch` cross-hatching, `.dark` variant with pink dots.
+- `.hl`: Anton uppercase, yellow fill, 3 px ink stroke, text-shadow cyan/magenta
+  offset by `var(--rx)` plus a stacked ink extrusion, `distress.png` mask.
+- `.kick`: yellow Bangers caption box rotated −3°, hard ink shadow.
+- Mascot: purple blob with cyan/magenta ghost copies behind it (print
+  misregistration), halftone shading clipped to the body, accessories.
+- HUD: a tilted comic corner box, "DEWEE COMICS / No. 01 / 12", flip counter
+  and progress segments.
+- Diagrams are drawn as comic panels: terminal logs, force-graph snapshots from
+  the seeded rng, stamped `✓ allow` / `✗ deny` rows, bug sprites squashed on
+  words.
+
+## Motion language
+
+- On twos: `on2(duration, baseEase)` quantises any ease to 12 steps per second,
+  so poses hold like hand-drawn animation. Use it for character and UI motion;
+  keep camera-ish moves (background drift, universe fades) smooth.
+- Transitions: `none`, `glitch` (RGB split via SVG `feOffset` on `#rgb-r`/`#rgb-b`
+  + slice bars, 0.28 s), `dots` (halftone dots swell to cover the frame then
+  shrink, `--r` 0 → 46 → 0), `flip` (page turn from the left edge), `slam`
+  (scale 1.3 → 1 with power4.in + shake), `fade` (outro only).
+- Every cut also gets `flash` + `speed` lines (stronger on kick beats); the three
+  drops get flash 0.8, shake 1.1–1.4 and full speed lines.
+- Beat reactions: `--rx` misregistration kick on every other beat, `#tone`
+  scale/opacity pulse, `#pulse` 1.2% scale on kick downbeats.
+- Headline intro: kick label slides in, then each `.hl .w` flips up in 3D
+  (rotationX −70 → 0) with a stagger.
+- Outro drops the comic energy: universe to "night", rays dim, mascot floats
+  with blinks, lines fade in slowly: "Coming soon → Real soon → September 2026
+  → To be continued".
+
+## Captions
+
+Yellow narration box (5 px ink border, hard ink + cyan shadow), 40 px Be Vietnam
+Pro 800, ink text; the current word turns `#a3005a`. Width stops at 1660 px so
+it never touches the signature.
+
+## Signature
+
+`#sig` bottom-right (right 40, bottom 22): "Zuey" in Permanent Marker 76 px,
+white fill with ink stroke and cyan/magenta/ink shadows, revealed with
+`steps(8)` clip; a magenta underline stroke draws in after it.

package/skills/motion-video/references/style-glass-keynote.md

@@ -0,0 +1,69 @@
+# Style: glass keynote
+
+A calm, premium tech-launch look: dark indigo space, drifting colour orbs,
+frosted glass cards, gradient display type with an italic serif accent. Reads
+like a product keynote. Reference edition: the 144 s Dewee v3.34 launch video
+(124 BPM, voice Puck, drop at beat 36).
+
+Choose it for product launches, changelogs and explainers where clarity and
+polish matter more than energy.
+
+## Tokens
+
+```css
+--bg: #070817; --ink: #f5f3ff; --mute: #aeacd6; --dim: #8f8dbb;
+--lilac: #c4b5fd; --violet: #8b5cf6; --pink: #f0abfc; --sky: #60a5fa;
+--green: #34d399; --amber: #fbbf24; --red: #f87171;
+--stroke: rgba(196, 181, 253, 0.26);
+--grad: linear-gradient(100deg, #f0abfc 0%, #a78bfa 45%, #60a5fa 100%);
+```
+
+Fonts: Plus Jakarta Sans (variable, 800 for headlines), Instrument Serif Italic
+(accent words inside headlines, gradient-filled), JetBrains Mono (kickers, labels,
+code), Be Vietnam Pro 600–800 (captions: full Vietnamese diacritics).
+
+## Layers (back to front)
+
+`#bg` → `#orbs` (three large radial glows, 48 s sine drift loops) → `#grid`
+(dot grid, radial mask, brightens on beats) → `#vignette` → `#pulse` wrapper →
+scenes → `#wipe` (rotated light band swept across on kick cuts) → HUD →
+captions → `#flash` → `#fade`.
+
+## Components
+
+- `.kicker`: mono uppercase label with a gradient number badge, top-left at 120/88.
+- `.h1`: 70 px Plus Jakarta 800, `-0.035em` tracking, `<em>` words in Instrument
+  Serif italic with `--grad` text fill.
+- `.card`: glass panel, vertical indigo gradient at 94% alpha, 1.5 px `--stroke`
+  border, radius 24, deep soft shadow plus an inner top highlight.
+- `.chip` pills with state colours (green ok, amber warn, red fail, sky info, "new").
+- Chat bubbles, terminal lines (`.term-line`), level badge (`.lvl`, amber
+  gradient) with an XP bar, odometer `.tile` digits (`odo` helper), 3D flip cards
+  (`.face.front` / `.face.back`, `backface-visibility: hidden`), data packets and
+  sparks moving along drawn SVG paths.
+- `.slam`: 200 px gradient word for the big number/statement moments.
+- Mascot: soft violet blob with accessories (headphones, cape, glasses), plus a
+  small HUD mascot that squashes on every kick.
+
+## Motion language
+
+- Transitions: `none`, `up` (y 110 → 0, power3.out 0.5 s), `zoom` (scale 1.3 →
+  1, expo.out), `flip` (rotationY −70, perspective 2200), `iris` (clip-path
+  circle 0 → 80%), `fade` for the outro. Rotate through them so no two neighbour
+  scenes share a transition.
+- Out: fade + scale 0.95 in 0.22 s; the scene before the drop zooms through
+  (scale 2.2) into it.
+- Eases are smooth (power3/expo/back); nothing is stepped.
+- Cuts get a light flash (0.14, or 0.3 on kick beats) and the `#wipe` band on kicks.
+
+## Captions
+
+Dark translucent pill (`rgba(10, 8, 30, 0.72)`, radius 20, 46 px Be Vietnam Pro 700),
+unread words 50% white, the current word `#e9d5ff`, then white.
+
+## Known issue in the reference
+
+Its mix used music −7 dB with sidechain ratio 5 / threshold 0.02, which sat the
+music ~10 dB under the voice. Use the balance from `audio-and-beat-sync.md` for
+new work. It has no signature; add the one from `composition-contract.md` if the
+video needs it.