director-cinematic 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +49 -2
  3. package/bin.mjs +53 -0
  4. package/package.json +29 -4
  5. package/template/.agents/skills/episode-edit/SKILL.md +116 -0
  6. package/template/.agents/skills/episode-edit/references/ai-footage-triage.md +26 -0
  7. package/template/.agents/skills/episode-edit/references/cutting-craft.md +60 -0
  8. package/template/.agents/skills/episode-edit/references/panel-repair.md +41 -0
  9. package/template/.agents/skills/episode-edit/references/qc-checklist.md +36 -0
  10. package/template/.agents/skills/episode-edit/references/scene-review-brief.md +44 -0
  11. package/template/.agents/skills/episode-edit/references/sound-design.md +88 -0
  12. package/template/.agents/skills/episode-edit/references/transitions-effects.md +51 -0
  13. package/template/.agents/skills/scene-direction/SKILL.md +147 -0
  14. package/template/.agents/skills/scene-direction/references/filmmaking-craft.md +156 -0
  15. package/template/.agents/skills/scene-direction/references/filmmaking-sources.md +71 -0
  16. package/template/.agents/skills/studio-lifecycle/SKILL.md +119 -0
  17. package/template/.agents/skills/studio-lifecycle/references/studio-editing.md +117 -0
  18. package/template/.agents/skills/studio-lifecycle/references/studio-prompt-craft.md +118 -0
  19. package/template/.agents/skills/video-group-direction/SKILL.md +415 -0
  20. package/template/.agents/skills/video-group-direction/references/h3-prompt-contract.md +75 -0
  21. package/template/.claude/settings.json +22 -0
  22. package/template/.codex/config.toml +12 -0
  23. package/template/AGENTS.md +251 -0
  24. package/template/CLAUDE.md +32 -0
  25. package/template/contracts/README.md +7 -0
  26. package/template/contracts/director-scene-plan.md +91 -0
  27. package/template/director-manifest.json +77 -0
  28. package/template/docs/ASSET_LIBRARY.md +234 -0
  29. package/template/docs/CONNECT.md +125 -0
  30. package/template/docs/DIAGNOSTICS.md +24 -0
  31. package/template/docs/DIRECTION_REVIEW.md +192 -0
  32. package/template/docs/DIRECTOR_LOOP.md +257 -0
  33. package/template/docs/EMOTION_REVIEW.md +73 -0
  34. package/template/docs/EXPERIMENT_PROTOCOL.md +78 -0
  35. package/template/docs/IMPORT.md +120 -0
  36. package/template/docs/STORYBOARD_AUTONOMY.md +171 -0
  37. package/template/docs/evidence/director-knowledge/source-receipts.json +62 -0
  38. package/template/docs/evidence/episode-edit/capcut-render-test.md +29 -0
  39. package/template/docs/evidence/video-direction/2026-11-09-research.md +58 -0
  40. package/template/gitignore +14 -0
  41. package/template/package-lock.json +44 -0
  42. package/template/package.json +23 -0
  43. package/template/src/cli/main.mjs +109 -0
  44. package/template/src/director/direction-review.mjs +108 -0
  45. package/template/src/director/original-image-checkpoint.mjs +62 -0
  46. package/template/src/director/original-image.mjs +211 -0
  47. package/template/src/director/scene-plan.mjs +138 -0
  48. package/template/src/director/studio-revision.mjs +175 -0
  49. package/template/src/director/workflow.mjs +65 -0
  50. package/template/src/integrations/epidemic/connect.mjs +113 -0
  51. package/template/src/integrations/waoowaoo/claude.mjs +102 -0
  52. package/template/src/integrations/waoowaoo/config.mjs +84 -0
  53. package/template/src/integrations/waoowaoo/discovery.mjs +58 -0
  54. package/template/src/integrations/waoowaoo/native.mjs +65 -0
  55. package/template/tools/edit/app.mjs +19 -0
  56. package/template/tools/edit/build.mjs +265 -0
  57. package/template/tools/edit/edl.mjs +103 -0
  58. package/template/tools/edit/fetch.mjs +31 -0
  59. package/template/tools/edit/frames.mjs +35 -0
  60. package/template/tools/edit/house-style.default.json +94 -0
  61. package/template/tools/edit/lib.mjs +61 -0
  62. package/template/tools/edit/listen.mjs +38 -0
  63. package/template/tools/edit/probe.mjs +110 -0
  64. package/template/tools/edit/project.mjs +78 -0
  65. package/template/tools/edit/render-check.mjs +164 -0
  66. package/template/tools/edit/review.mjs +78 -0
  67. package/template/tools/edit/schemas/clip-review.schema.json +169 -0
  68. package/template/tools/edit/schemas/edl.schema.json +202 -0
  69. package/template/tools/edit/schemas/qc.schema.json +15 -0
  70. package/template/tools/edit/sound.mjs +239 -0
  71. package/template/tools/resolve-timeline.mjs +74 -0
  72. package/template/workspace/.gitkeep +0 -0
  73. package/workspace.mjs +124 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Director contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,50 @@
1
- # Temporary Holding Version
1
+ # director-cinematic
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Director is an AI film-director workspace for [Claude Code](https://claude.com/claude-code). It reads your
4
+ script, then drives a Waoowaoo Studio over MCP: project and episodes, analysis, reference images, the
5
+ automated storyboard pipeline, and an edit of the finished footage into a CapCut draft.
6
+
7
+ This package installs the **base workflow**. The skills are plain files in your workspace: change them to
8
+ your own style.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npx director-cinematic init my-director
14
+ cd my-director
15
+ claude
16
+ ```
17
+
18
+ Needs Node.js 24 and Claude Code. capcut-cli (pinned 0.34.0, for CapCut drafts) installs with the workspace.
19
+ Episode editing also needs ffmpeg (`brew install ffmpeg` on macOS); `init` checks your machine and tells you
20
+ what is missing (`npx director-cinematic doctor` checks again).
21
+
22
+ Send a script in Claude Code. Director asks which Studio site you use, connects it, and asks you to open a
23
+ new conversation and sign in with your own Studio account.
24
+
25
+ ## Music and sound effects (optional)
26
+
27
+ The sound stage uses Epidemic Sound with your own account. Create an MCP Server key in Epidemic Sound
28
+ (Account -> API keys; downloads need a paid plan), then in your workspace run:
29
+
30
+ ```bash
31
+ npm run sound:connect
32
+ ```
33
+
34
+ Paste the key when asked (it stays hidden). It is checked with Epidemic, stored only in
35
+ `~/.config/epidemic-sound/` on your machine, and never goes into a chat. Open a new conversation afterwards.
36
+
37
+ ## Make it yours
38
+
39
+ - `.agents/skills/*/SKILL.md` and their `references/`: how Director directs, reviews and edits.
40
+ - `AGENTS.md`: the workspace rules every agent reads first.
41
+ - `tools/edit/house-style.default.json`: transitions, effects and sound defaults for the edit.
42
+
43
+ ## Update
44
+
45
+ ```bash
46
+ npx director-cinematic@latest update
47
+ ```
48
+
49
+ Run it inside your workspace. Files you never touched get the new version. Files you edited stay yours; if
50
+ the new version also changed one of them, it is saved next to it as `<file>.upstream` for you to merge.
package/bin.mjs ADDED
@@ -0,0 +1,53 @@
1
+ #!/usr/bin/env node
2
+ // director-cinematic: install the Director workspace, update its base workflow, check the machine.
3
+ import { spawn } from 'node:child_process';
4
+ import { resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { doctor, install, update, UPSTREAM_SUFFIX } from './workspace.mjs';
7
+
8
+ const templateDir = fileURLToPath(new URL('./template/', import.meta.url));
9
+ const [command = 'help', ...args] = process.argv.slice(2);
10
+ const say = text => process.stdout.write(`${text}\n`);
11
+
12
+ function npmCi(cwd) {
13
+ return new Promise(done => {
14
+ const child = spawn('npm', ['ci', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd, stdio: 'inherit' });
15
+ child.once('error', () => done(1));
16
+ child.once('exit', code => done(code ?? 1));
17
+ });
18
+ }
19
+
20
+ async function printDoctor(workspace) {
21
+ const checks = await doctor({ workspace });
22
+ for (const c of checks) say(`${c.ok ? 'ok ' : 'missing'} ${c.name}${c.found ? ` (${c.found})` : ''}${c.ok ? '' : `\n ${c.fix}`}`);
23
+ return checks.every(c => c.ok);
24
+ }
25
+
26
+ async function main() {
27
+ if (command === 'init') {
28
+ const target = resolve(args[0] ?? 'director-cinematic');
29
+ const result = await install({ templateDir, target });
30
+ say(`Installed Director ${result.version} (${result.files} files) in ${target}`);
31
+ if (await npmCi(target) !== 0) say('npm ci failed; run it again inside the folder.');
32
+ say('');
33
+ await printDoctor(target);
34
+ say(`\nNext: cd ${JSON.stringify(target)} && claude\nSend a script; Director asks which Studio site you use and connects it.`);
35
+ say('Skills live in .agents/skills: edit them to your own style. "npx director-cinematic@latest update" keeps your edits.');
36
+ return 0;
37
+ }
38
+ if (command === 'update') {
39
+ const target = resolve(args[0] ?? '.');
40
+ const r = await update({ templateDir, target });
41
+ say(`Director ${r.from} -> ${r.to}: ${r.replaced.length} updated, ${r.added.length} added, ${r.removed.length} removed.`);
42
+ if (r.keptEdits.length) say(`Kept your edits (${r.keptEdits.length}):\n ${r.keptEdits.join('\n ')}`);
43
+ if (r.conflicts.length) say(`You and the new version both changed these; the new version is saved next to each as *${UPSTREAM_SUFFIX}. Merge what you want, then delete the ${UPSTREAM_SUFFIX} file:\n ${r.conflicts.join('\n ')}`);
44
+ if (r.dependenciesChanged && await npmCi(target) !== 0) say('npm ci failed; run it again inside the folder.');
45
+ return 0;
46
+ }
47
+ if (command === 'doctor') return (await printDoctor(resolve(args[0] ?? '.'))) ? 0 : 1;
48
+ say('Usage: npx director-cinematic <command>\n init [folder] install a new Director workspace (default ./director-cinematic)\n update [folder] bring in the new base workflow without overwriting your edits\n doctor [folder] check Node.js, Claude Code, ffmpeg and the workspace capcut-cli');
49
+ return command === 'help' ? 0 : 2;
50
+ }
51
+
52
+ try { process.exitCode = await main(); }
53
+ catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
package/package.json CHANGED
@@ -1,6 +1,31 @@
1
1
  {
2
2
  "name": "director-cinematic",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Director: an AI film-director workspace for Claude Code that drives a Waoowaoo Studio over MCP. One command installs the base workflow and skills, which you then edit to your own style.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "bin": {
8
+ "director-cinematic": "bin.mjs"
9
+ },
10
+ "files": [
11
+ "bin.mjs",
12
+ "workspace.mjs",
13
+ "template/",
14
+ "README.md",
15
+ "LICENSE"
16
+ ],
17
+ "engines": {
18
+ "node": ">=24 <26"
19
+ },
20
+ "keywords": [
21
+ "claude-code",
22
+ "mcp",
23
+ "agent",
24
+ "skills",
25
+ "video",
26
+ "film"
27
+ ],
28
+ "scripts": {
29
+ "prepublishOnly": "node ../scripts/build-installer.mjs"
30
+ }
31
+ }
@@ -0,0 +1,116 @@
1
+ ---
2
+ name: episode-edit
3
+ description: Edit one finished Studio episode into a CapCut draft the user finishes and exports. Pull the clips with footage.list, have each scene reviewed in a fresh context, cut assembly to locked EDL with a reason for every cut, build the draft (no captions: the user makes them in CapCut), check the render, and hand over. Use when the user says an episode is done and wants it edited, cut, assembled or put into CapCut.
4
+ ---
5
+
6
+ # Episode edit
7
+
8
+ You are the episode's editor. You decide every cut; the user does the last pass in CapCut and exports. Edit **one episode at a
9
+ time**: when the user says the footage is done, take every finished episode in episode order, one after another, unless they
10
+ name episodes. Requests come as people talk ("tập 1 xong rồi, dựng giúp anh", "put episode 2 in CapCut"); never expect a step list.
11
+
12
+ ## Three rules that keep the edit good
13
+ 1. **You never look at the footage yourself.** Images fill your context and then the edit suffers. Scene reviewers look, in fresh
14
+ contexts, and give you evidence with times. You work from text: `footage.json`, the reviews, the house style.
15
+ 2. **Speech the video model invented is muted.** The user makes the captions in CapCut (Auto captions) and styles them there;
16
+ muting keeps invented speech out of them. The edit adds no captions.
17
+ 3. **Every cut has a reason and an idiom** (see `references/cutting-craft.md`). "It looked fine" is not a reason.
18
+
19
+ The episode folder `workspace/<project>/<Episode N>/` is the only state. If a session stops, read the folder and continue from the
20
+ first missing file; never rely on the conversation.
21
+
22
+ ## Stages
23
+ Run the scripts from this repository's root. Each prints one JSON line; read it before going on.
24
+
25
+ **1. Footage.** Call `footage.list` for the episode and save the whole result as `footage.json` in the episode folder. Then
26
+ `node tools/edit/fetch.mjs "<episode>"` and `node tools/edit/probe.mjs "<episode>"`. Panels without video: tell the user which
27
+ ones before cutting; edit around them. Expired links: call `footage.list` again and re-run fetch.
28
+
29
+ **2. Scene review (delegated).** For each scene in `scenes.json`:
30
+ `node tools/edit/review.mjs "<episode>" pack <scene>`, then give one fresh sub-agent this short brief:
31
+ > You are the assistant editor for one scene. Repository: <repo root>. Episode folder: "<episode>". Scene: <scene>. Read and follow
32
+ > `.agents/skills/episode-edit/references/scene-review-brief.md`. Input `reviews/<scene>.pack.json`, output `reviews/<scene>.json`.
33
+
34
+ Claude Code: the Agent tool. Codex: a sub-agent, or `codex exec -C <repo> "<brief>"` as a child process. Scenes are independent:
35
+ run them in parallel. Then `node tools/edit/review.mjs "<episode>" check` must report every scene `ok`; send a reviewer back with
36
+ the errors otherwise.
37
+
38
+ **3. Decide what each clip can do: edit it, or repair the panel.** Read the reviews (text only).
39
+ - An edit fix is allowed only when it is honest: a trim to the clean window, a mute, a cut-away or reordering, a reaction or insert
40
+ that keeps the beat, or a punch-in of at most 1.3x done as a `crop` (source rectangle, 16:9). No position keyframes (CapCut reads
41
+ their units differently; TA_122 E3 panel 23 landed off-frame and no check could see it).
42
+ - When no such fix keeps the beat (the reviewer says `regenerate`, a wrong person stays next to the speaker, identity is wrong for
43
+ the beat, the line is never spoken), **repair the panel** instead of hiding it. Read `references/panel-repair.md`.
44
+ - Repairs are paid; run them without asking first (user decision 2026-11-17). Gather every panel that needs one in this episode,
45
+ repair them as one batch, and report it: panel number, what was wrong (with the second), what you changed (prompt, image or
46
+ video) and how many candidates. If a repair does not work, keep the best honest stopgap, keep editing, and list the panel under
47
+ "not fixed" in the handoff; never call a stopgap fixed.
48
+
49
+ **4. Assembly → rough → fine.** Read `references/cutting-craft.md` and `references/ai-footage-triage.md`. Write `edl.json`
50
+ (schema `tools/edit/schemas/edl.schema.json`):
51
+ - assembly: every usable beat in film order inside its clean window;
52
+ - rough: cut for story and emotion, drop what repeats, place reactions;
53
+ - fine: trim heads and tails to the action, check rhythm against the house style (`tools/edit/house-style.default.json`, overridden
54
+ by `workspace/<project>/house-style.json`).
55
+
56
+ Per shot: `file`, `in`, `out` (inside the reviewer's clean window unless the reason says why not), `reason`, `idiom`, `audio`
57
+ (`mute` when the reviewer found off-script speech in the kept part), `lines` (lineIndex with the reviewer's spoken `from`–`to`),
58
+ optional `keyframes`, `transitionOut`, `emphasis`. The sound stage ducks music under the `lines` spans. Transitions, push-ins,
59
+ emphasis effects and colour notes follow `references/transitions-effects.md`: each one marks a beat the text names; most cuts get none.
60
+
61
+ **5. Lock and build.** One CapCut project per Studio project: each episode is appended after the previous one.
62
+ `node tools/edit/build.mjs "<episode>" --into "<project>"`. Do not ask the user to close CapCut: the build quits it the normal way
63
+ (CapCut saves its open project, like Cmd+Q), writes, and opens it again so the change shows. It only adds this episode after the
64
+ project's end. `workspace/<project>/capcut.json` records what is in the project and a fingerprint of what the tools last wrote.
65
+ It refuses an invalid EDL (fix it). The loudness pass is the one project-wide change (one gain keeps every episode at one level). A
66
+ failed build leaves the project as it was (a draft it created goes to the Trash). If CapCut does not quit (an unsaved dialog), the
67
+ build refuses with `capcut-did-not-quit`: only then ask the user. Read `build.json`: loudness,
68
+ lint.
69
+
70
+ **5b. Sound (music, SFX, ambience).** After the picture is built, read `references/sound-design.md`.
71
+ - **Epidemic Sound access first.** The sounds come from the Epidemic Sound MCP (tools such as `SearchRecordings`,
72
+ `SearchSoundEffects`, `EditRecording`, `DownloadRecording`). If those tools are not available in this session, run
73
+ `npm run sound:status`. Stop the sound stage (the picture is done; nothing is lost) and ask the user, in their language:
74
+ - `EPIDEMIC_NOT_CONFIGURED`: to create an MCP Server key in Epidemic Sound (Account -> API keys; downloads need a paid plan),
75
+ then run `npm run sound:connect` in a terminal in this folder and paste the key there (it stays hidden). It checks the
76
+ key with Epidemic, saves it in a private file and registers the `epidemic-sound` server for Claude Code.
77
+ - `EPIDEMIC_CONFIGURED`: only to open a new conversation (tools load when a conversation starts).
78
+ Never ask for the key in the chat, never run `sound:connect` yourself, and never print or store the key.
79
+ - **Spot from text** (EDL reasons, review notes, line emotions): write `sound/cue_sheet.json` in the episode folder, one cue per
80
+ music, SFX or ambience event with `id`, `kind`, `at`, `dur` (episode clock), `reason`, and later `file`, `hasVocals` (music,
81
+ from metadata), `source { provider: "epidemic", kind, id, title }`, optional `sourceIn`, `fadeIn`, `fadeOut`, `gainDb`.
82
+ - **Find and fetch**: search with a brief per cue, pick by metadata (instrumental under lines, BPM band, length), fit music with
83
+ `EditRecording`, download into `sound/files/`. Reuse the series' sting/theme from `workspace/<project>/sound-license-log.jsonl`.
84
+ - **Place and measure**: `node tools/edit/sound.mjs "<episode>" --into "<project>"` (CapCut is quit and reopened like the build).
85
+ It refuses an invalid cue sheet (vocals under a line, a cue outside the episode, a missing file or source), leaves headroom,
86
+ ducks, solves levels, logs licenses, and writes `sound/measurements.json`; fix every flag it prints. `--measure-only` checks a
87
+ cue sheet without touching the draft.
88
+
89
+ Follow `references/qc-checklist.md`: render check (`--into "<project>"`, it samples this episode inside the project), then a fresh QC sub-agent. `revise` findings go back
90
+ into `edl.json` (and the cue sheet); at most two automatic rounds, then list what remains.
91
+
92
+ **Revisions end in the one project; work drafts are temporary.** Never leave the user an extra CapCut project.
93
+ - To iterate on a revision, build it into the episode's work draft: `build.mjs "<episode>" --work "<project>"` (named
94
+ "<project> E<NN> work", replaced on each run), add sound and run QC on it with `--name "<project> E<NN> work"`.
95
+ - When it passes, merge: `build.mjs "<episode>" --into "<project>"` rebuilds the project from that episode on (its EDL, then every
96
+ later episode's EDL, then each one's cue sheet) and moves the episode's work draft to the Trash. Run the render check on the
97
+ project again.
98
+ - The merge only runs while the project is what the tools last wrote (fingerprint). If it refuses with
99
+ `project-edited-since-last-build` or `project-fingerprint-unknown`, the user may have edited the project in CapCut: ask them, and
100
+ only with their yes rerun with `--accept-overwrite`; otherwise leave the revision in its work draft and tell them where it is.
101
+ - A sound-only change in the project: `sound.mjs "<episode>" --into "<project>"` replaces that episode's cues (same rule).
102
+
103
+ **7. Hand over.** Tell the user in their language, plainly: the project to open in CapCut (CapCut was reopened by the build),
104
+ the length, what you cut and why in a few lines, and in their own section:
105
+ - **Not fixed (needs a new take or your decision):** each panel, the second in the project, what is wrong, what the edit does
106
+ meanwhile, and the repair you propose (or that you made, with its result).
107
+ - **Check in CapCut:** every shot the proxy cannot show as CapCut will (crops, push-ins, transitions, emphasis effects), with its
108
+ second.
109
+ - **Colour:** the clips that do not match their scene and the direction to push them; the user grades in CapCut.
110
+ - **Captions:** the edit adds none. The user makes them in CapCut (Text, Auto captions) and picks the font, colour and style
111
+ there; say so in one line.
112
+ - What QC still flags, and what is theirs to do (final colour, export).
113
+
114
+ ## Honest reporting
115
+ Say what the evidence shows and what was not checked. A built draft is not a watched film: "QC pass" means the checklist on the
116
+ render passed, nothing more.
@@ -0,0 +1,26 @@
1
+ # AI footage triage
2
+
3
+ Every generated clip is coverage: keep its clean window, not the whole clip. The reviewer reports the flaw and its time; you pick
4
+ the remedy. Prefer an honest edit remedy; when none keeps the beat, repair the panel (`panel-repair.md`) after the user's yes.
5
+ Never hide a flaw with a punch-in over 1.3x or with position keyframes.
6
+
7
+ | Flaw (review `kind`) | Edit remedy, in order | Regenerate when |
8
+ |---|---|---|
9
+ | `off-script-speech` | `audio: mute` on the shot; keep the picture if it serves the beat | the beat needs the clip's own voice and it says the wrong thing |
10
+ | `unvoiced-line` | put the line on a shot where it is spoken; or keep the picture without the line and say so in the handoff | the line carries the story and no clip speaks it |
11
+ | `extra-character` | out-point before the person appears; a crop (≤ 1.3x, 16:9) if they are at the edge | they are there for the whole clean part of the beat |
12
+ | `identity-drift` | keep the part before the drift; cover with a reaction or insert | the face is wrong for most of the clip |
13
+ | `morph` | cut before or after; punch-in to frame it out | it sits in the middle of the only usable action |
14
+ | `burned-in-text` | crop or punch-in if it is in the lower band | it covers the subject |
15
+ | `bad-head` / `frozen-tail` | trim (skip at least the first 2 frames; end before the freeze) | never: trimming is enough |
16
+ | `portrait-or-odd-size` | drop it from a 16:9 cut unless a crop keeps the subject (state the loss) | the shot is needed in 16:9 |
17
+ | `internal-cut` | use the part before (or after) the cut as its own shot | never: it is two shots, edit them as two |
18
+ | `continuity` | reorder, cut away, or accept with the reason (emotion beats a match) | the story becomes unclear |
19
+
20
+ Notes:
21
+ - Drift builds frame by frame, so the start and the end of a clip are the riskiest parts.
22
+ - Cut on movement to hide a seam; a still frame between two moving parts is the worst place for a cut.
23
+ - A crop of 1.05–1.3x (a 16:9 source rectangle) hides an edge flaw; do not crop a portrait clip to fill 16:9. A gentle centred
24
+ push-in (scale keyframes up to 1.3) is motion, not a cover.
25
+ - AI clips ship with their own audio: never trust it blindly. The reviewer's hearing evidence decides keep or mute.
26
+ - Report every `regenerate` you could not cover to the user with the panel, the reason and what the edit does meanwhile.
@@ -0,0 +1,60 @@
1
+ # Cutting craft
2
+
3
+ Original guidance distilled from the episode-edit research (report "Kỹ năng dựng phim cho Director", 2026-11-16). Sources are
4
+ named; numbers marked *heuristic* are starting points to calibrate on this project's footage.
5
+
6
+ ## Priorities when choices conflict (Murch's order)
7
+ Emotion first, then story, then rhythm, then eye trace, then the 2D plane, then 3D space continuity (Murch, *In the Blink of an
8
+ Eye*). Give up criteria from the bottom: a take with the right feeling beats a take with a matching background. A cut sits where
9
+ the audience would blink: at the boundary between two thoughts, not in the middle of one.
10
+
11
+ ## Dmytryk's rules (On Film Editing, 1984)
12
+ 1. Never cut without a positive reason. 2. When unsure, cut long rather than short. 3. Cut in movement. 4. The fresh is better than
13
+ the stale: leave once the action has left. 5. Begin and end a scene with continuing action. 6. Right values over right matches.
14
+ 7. Substance first, form second.
15
+
16
+ ## Reasons and idioms
17
+ Every EDL shot names its `idiom` and a `reason` sentence (what the audience learns or feels from it):
18
+
19
+ | Idiom | Use it when |
20
+ |---|---|
21
+ | `establish` | the audience needs to know where and who before the scene plays (open wide, at least 2 s) |
22
+ | `speaker-visible` | the line matters and the face carries it |
23
+ | `listener-reaction` | the reaction tells more than the line (cut to the listener before the line ends) |
24
+ | `action-continuity` | an action continues across shots; cut in the movement |
25
+ | `insert-detail` | an object or detail carries the plot (ticket, map, bag) |
26
+ | `intensify-emotion` | the scene builds: move closer in shot size |
27
+ | `emphasize-character` | one character's state is the point of the moment |
28
+ | `time-jump` | time or place jumps (dissolve or a clear cut on a new setting) |
29
+ | `scene-transition` | scene boundary |
30
+ | `hold-beat` | a silent beat lands (hold, do not cut away early) |
31
+ | `cover-flaw` | the shot exists to hide a flaw elsewhere (say which) |
32
+
33
+ Leake et al. (SIGGRAPH 2017) encode dialogue editing as these kinds of idioms: start wide, keep the speaker visible, intensify
34
+ emotion with closer shots, emphasise a character. `footage.json` already carries shot type, speaker and emotion per line.
35
+
36
+ ## Dialogue
37
+ - Sound and picture rarely change at the same moment. L-cut: the line continues over the listener's face. J-cut: the next shot's
38
+ sound starts before its picture. *Heuristic*: move to the listener 6–12 frames (0.25–0.5 s) before the line ends.
39
+ - Cutting dialogue too tight makes characters look impatient. Keep a breath of 0.3–0.8 s between lines; a heavier answer gets a
40
+ longer pause. A reaction shot can be reused within its scene.
41
+ - Shot length for a line: the spoken span plus a breath, about 1.0–1.2× the line (*heuristic*). Do not stretch a line to fill a clip.
42
+
43
+ ## Rhythm
44
+ - Measure the cut as a distribution, not an average (Salt): median, spread and how lengths alternate. Equal-length shots read as a
45
+ slideshow; AI clips all come out at the same length, so vary them on purpose.
46
+ - Scenes tend to move from wider to closer shots, and shots shorten toward a climax and lengthen after it (Cutting, 2016).
47
+ - House style holds the numbers per series (dialogue 2.5–5 s, action 1.5–3 s, holds 4–8 s, establishing ≥ 2 s; *heuristic*).
48
+ Kids' and language-learning series: no shot with a line shorter than the time to read it at the style's CPS.
49
+
50
+ ## Transitions
51
+ Straight cut inside a scene. A crossfade only for a jump in time or place (house style `transitions.timeJump`: `mix`; CapCut's
52
+ `dissolve` and `dissolve-ii` do not survive the export, so the EDL refuses them). A crossfade takes half its length from each shot:
53
+ keep spoken lines clear of it. Fade from and to black at the episode's ends (`fadeInSeconds`/`fadeOutSeconds`; the build writes
54
+ them as clip fade animations, because alpha keyframes are not exported). Never crossfade between two continuous dialogue shots.
55
+ One transition vocabulary per series. Push-ins are `scale` keyframes; the build writes them as scale_x + scale_y. Full rules for
56
+ transitions, push-ins, emphasis effects and colour: `transitions-effects.md`.
57
+
58
+ ## Shape of an episode
59
+ Micro-drama: hook in the first seconds (no logo opening), escalation, turn, cliffhanger last. Kids' learning series: a short
60
+ greeting or title, clear scenes, end on story and a next-episode tease (made-for-kids videos cannot use end screens).
@@ -0,0 +1,41 @@
1
+ # Panel repair: fix a broken shot instead of hiding it
2
+
3
+ Uses the Studio MCP panel tools (L6): `panels.get`, `panels.update`, `panels.image_modify`, `panels.image_regenerate`,
4
+ `panels.video_generate`, `panels.video_select`, with `tasks.get` and `media.view`. If these tools are not in the session, the
5
+ Studio has not been updated: say so and list the panel under "not fixed". Write every prompt and edit instruction by
6
+ `.agents/skills/studio-lifecycle/references/studio-prompt-craft.md` (which field reaches the model, the edit recipe, the H3
7
+ video prompt on the panel path).
8
+
9
+ ## 1. Diagnose: is the image wrong, or did the video model invent it?
10
+ - `panels.get` for the panel: prompts, acting notes, the image key, the current and candidate videos.
11
+ - Look at the panel image with `media.view` (or have a fresh reviewer look at it with the clip's sheet).
12
+ - The flaw is already in the image (extra person, wrong outfit, wrong prop, wrong framing): fix the image first, then the video.
13
+ - The image is right and the video adds the flaw (people walking in, a face morphing, invented speech): fix the video prompt.
14
+
15
+ ## 2. Change the smallest thing that removes the cause
16
+ - Image: `panels.image_modify` with a precise instruction ("remove the two girls at the left and right edges; keep Eliza, the
17
+ counter and the light unchanged"); `panels.image_regenerate` only when the composition itself is wrong.
18
+ - Video: `panels.update` the `videoPrompt`: what happens in the shot and who does it. Studio builds the video prompt from it, the
19
+ shot type and camera move, the script lines, and (Studio L6b) the panel's `actingNotes` as a Performance block, one line per
20
+ on-screen character. So fix a wrong expression, gesture or body language in `actingNotes` (it also changes the panel image), and
21
+ a wrong action in `videoPrompt`; `photographyRules` do not reach the video. Describe only who and what is in frame ("only Eliza
22
+ is in frame for the whole shot; the camera holds still"): never name people who must not appear, a name invites them in. Do not
23
+ write dialogue, art style or camera wording that contradicts the shot fields into `videoPrompt` (Studio adds the lines and the
24
+ `Camera:` line). Keep the line and the action, the prompt's language and structure, and what the other panels depend on
25
+ (continuity of outfit, props, place).
26
+ - Speech: the clip must say the script line; keep the dialogue fields as they are.
27
+
28
+ ## 3. Generate, then report
29
+ Run the episode's repairs as one batch without asking first (stage 3 of the skill), then report them: `panels.video_generate` (one video per call, and it
30
+ replaces the current video: keep the old clip's download from `panels.get` to compare; the model comes from the project's
31
+ configuration), then `tasks.get` until it is done. Never retry a paid call
32
+ with a new commandId after an unclear result: call again with the same commandId. A take that fails or stalls follows "A generation
33
+ that fails or stalls" in `../../studio-lifecycle/references/studio-editing.md`: cancel it, generate again, at most 3 attempts, then
34
+ report. Keep building the episode with the current take meanwhile.
35
+
36
+ ## 4. Review the candidates in fresh contexts, pick, re-edit
37
+ - Download each candidate from `panels.get`, run `probe.mjs`-style checks on it (frames sheet, listen) through a fresh scene
38
+ reviewer with the scene review brief, and compare against the flaw you fixed.
39
+ - `panels.video_select` the best one. If none fixes it, say so: one more repair round at most, then "not fixed".
40
+ - Then `footage.list`, `fetch.mjs`, `probe.mjs` again for the episode, update `edl.json` for that shot (clean window, lines), build in
41
+ the episode's work draft, QC, and merge into the project (stage 6 of the skill).
@@ -0,0 +1,36 @@
1
+ # QC checklist (render, not draft)
2
+
3
+ Benchmarks show editing agents often cut the wrong window; only the rendered picture and sound prove the edit. The editor runs
4
+ `node tools/edit/render-check.mjs "<episode>" --into "<project>"`, then gives a fresh QC sub-agent this brief:
5
+
6
+ > You are the QC reviewer for one edited episode. Repository: <repo root>. Episode folder: "<episode>". Read
7
+ > `.agents/skills/episode-edit/references/qc-checklist.md`, look at `qc/` and write `qc/qc.json`
8
+ > (schema `tools/edit/schemas/qc.schema.json`).
9
+
10
+ ## The QC reviewer checks
11
+ Read `qc/check.json` (cut table, sample times, loudness, `notRendered`) and look at the sheets in `qc/`. The proxy
12
+ render shows the cut picture only: it does not draw captions, transitions or keyframes and has no clip audio. Check those from
13
+ `check.json` (the EDL, the sound mix measured on `qc/mix.wav`) and list them as "seen only in CapCut". The edit adds no captions
14
+ (the user makes them in CapCut), so there are none to check.
15
+
16
+ 1. **Every cut** (`qc/cuts/*.jpg`, frames just before and after each cut): no flash frame, no frozen frame, no character who
17
+ should not be there, no jump that reads as a mistake (same framing, small change). Screen direction holds inside a scene.
18
+ 2. **Openings and endings**: fade in and out land, the first shot establishes, the last shot is a real ending.
19
+ 3. **Picture**: no portrait clip stretched or pillar-boxed unless the EDL reason says so; no burned-in text; faces consistent.
20
+ A shot with a `crop` or push-in: judge it by applying the EDL crop to the source clip, and list it under "check in CapCut"
21
+ with its second; never report it as verified from the emulation. A shot whose reviewer said `regenerate` and that is still in
22
+ the cut is at least `major` unless the EDL reason names the user's decision to keep it.
23
+ 4. **Sound** (`loudness.mix`, and `sound/measurements.json` when the sound stage ran): integrated loudness near the house target,
24
+ true peak at or below the ceiling, music at least the house gap under every line (`perLine`), no flag left; muted shots listed.
25
+ The proxy render plays the music, SFX and ambience tracks but not the clips' own audio.
26
+ 5. **Rhythm** (`check.json` shotStats): median and spread of shot lengths; flag a run of equal-length shots.
27
+ 6. **Transitions and effects** (the EDL, `check.json` effects and effectFindings): each non-cut transition and emphasis has a story
28
+ reason; no spoken line within 0.5 s of a crossfade or black fade; effectFindings (budget, spacing) resolved or justified; every one
29
+ listed under "check in CapCut" with its second.
30
+
31
+ Write each finding with its timeline second, severity (blocker / major / minor), what is wrong and the concrete fix (an EDL change).
32
+ `status`: `pass` (no blocker or major), `revise` (fixable in the EDL), `fail` (needs new footage). List what you checked in `checked`.
33
+
34
+ ## The editor then
35
+ Applies `revise` fixes to `edl.json`, builds a revision draft (`--name "<project> E<NN> v2"`) and runs QC again; at most two automatic rounds. Remaining findings
36
+ and every `fail` go to the user in the handoff, plainly.
@@ -0,0 +1,44 @@
1
+ # Scene review brief
2
+
3
+ You are the assistant editor for one scene. You look closely at its clips so the editor never has to. You judge and report; you
4
+ do not edit, build drafts, call Studio or regenerate anything. Your whole answer is one JSON file.
5
+
6
+ ## Inputs
7
+ - The pack `reviews/<scene>.pack.json` in the episode folder: per clip the planned shot (description, shot type, camera move,
8
+ planned length), the script lines matched to it (speaker, text, emotion), measurements (duration, size, orientation, audio,
9
+ sound spans) and its sheet.
10
+ - Sheets: `sheets/<clip>.jpg`, 8 frames, 4x2, read left to right then top to bottom, at the times in `sheetTimes`.
11
+ - On demand, from the repository root:
12
+ - `node tools/edit/frames.mjs "<episode>" <clip> --from <s> --to <s> [--fps 4]`: up to 16 frames of a window, times printed.
13
+ - `node tools/edit/listen.mjs "<episode>" <clip> [--from s --to s]`: rough hearing with times and the detected `language` (compare it with the script's language). It mishears Vietnamese words; use it
14
+ to know whether someone speaks, roughly what, and whether it is the script line or something else. Never copy its text. On ambience
15
+ or music it often invents a generic sentence ("subscribe…"): trust it only where sound spans and moving mouths agree.
16
+
17
+ ## How to look (keep your context small)
18
+ 1. Read the pack. Then for each clip, look at its sheet once.
19
+ 2. Look closer only where it decides something: where a script line is spoken, where a flaw starts, the first and last second.
20
+ One or two `frames.mjs` windows per clip is normal; more than four means you are browsing, stop.
21
+ 3. Run `listen.mjs` on every clip with audio and sound spans. Compare with the script lines.
22
+
23
+ ## What to decide per clip
24
+ - **Clean window** `clean.from`–`clean.to`: the longest stretch with no flaw that matters, on the clip's own clock. Skip at least the
25
+ first 2 frames (0.083 s at 24 fps). End before a flaw starts, before a frozen or drifting tail, before a character leaves the frame
26
+ when that leaves an empty set. Say why in `clean.why`.
27
+ - **Flaws** with times: `extra-character` (someone not in the planned shot appears), `identity-drift` (a face, hair, outfit or prop
28
+ changes), `morph` (warping, melting hands, extra limbs), `off-script-speech` (audible speech that is not the clip's script line),
29
+ `unvoiced-line` (a script line that is never spoken), `burned-in-text`, `bad-head`, `frozen-tail`, `portrait-or-odd-size`
30
+ (portrait or a size the 16:9 canvas would crop hard), `internal-cut` (the clip cuts to another shot inside the file), `continuity` (wrong screen direction, set or time of day versus the plan),
31
+ `other`. Report what you saw, not what is likely.
32
+ - **Lines**: for every script line of the clip, `spoken` yes / no / unsure, and when yes the `from`–`to` on the clip clock. Use the
33
+ sound spans for the edges and the mouth movement in frames to confirm who speaks. Unsure is an honest answer; say why in `note`.
34
+ - **Content** one sentence of what the clean window shows; **uses**: establish, speaker, reaction, action, insert, cutaway, transition.
35
+ - **Verdict**:
36
+ - `usable`: the clean window serves the planned beat as it is;
37
+ - `fixable`: usable after a trim, a mute, a punch-in or a short cover; say which in `reason`;
38
+ - `regenerate`: no clean window serves the beat (identity wrong for most of the clip, the line never spoken and the beat needs it,
39
+ the shot shows something else). This is the only verdict that costs money, so give the evidence.
40
+
41
+ ## Output
42
+ Write `reviews/<scene>.json` valid against `tools/edit/schemas/clip-review.schema.json`, every clip of the pack exactly once, then
43
+ run `node tools/edit/review.mjs "<episode>" check` and fix any error it reports for your scene. Reply with one line: the file path
44
+ and the verdict counts.
@@ -0,0 +1,88 @@
1
+ # Sound design: music, SFX, ambience
2
+
3
+ Distilled from the research report "Nhạc nền và SFX cho Director" (2026-11-16). Numbers marked *heuristic* are starting points; the
4
+ house style (`sound` block) holds them. Text decides intent; Epidemic Sound metadata and `sound.mjs` measurements decide facts about
5
+ files; whether a track fits the picture is the user's ear.
6
+
7
+ ## Spotting (from text only)
8
+ - Spot on the locked cut. Each cue has an in, an out, a purpose and a reason tied to a story beat (EDL reasons, review notes, line emotions).
9
+ - 2–5 music cues per episode, covering roughly 40–70% of it (*heuristic*). Typical shape: short opening sting → situation or mischief
10
+ cue → sparse or silent under talk-heavy conflict → emotion or resolution cue → closing sting.
11
+ - Start a cue on a story beat (decision, discovery, entrance, reaction shot) or on the cut that opens a scene, never in the middle of a
12
+ line; if it must start under talk, sneak in between two lines with a 1–2 s fade. End on a button: a reaction, a landed joke, the
13
+ scene's last cut. Sad or tense colour never starts before the line or picture that causes it.
14
+ - Silence or ambience only under the key emotional line (music returns on the reaction), before a punchline, and under lines that
15
+ carry new words or information a child must understand.
16
+ - Music over: no-dialogue stretches, location changes, mischief and chases, an emotional turn after it has been said, the ending.
17
+ - Cues never cross an episode boundary (episodes are appended into one project). Keep one series kit: the same opening/closing sting
18
+ and theme across episodes (reuse the track ids in `workspace/<project>/sound-license-log.jsonl`).
19
+
20
+ ## Epidemic Sound MCP: what the live server does (probed 2026-11-16, server 1.20.0)
21
+ - `SearchRecordings`: `query.term` (a free-text brief) plus `filter` with `bpm {min,max}`, `duration {min,max}` (ms), `vocals`
22
+ (false = instrumental), `moodSlugs` / `taxonomySlugs` / `tagSlugs` / `featuredInstrumentSlugs` / `musicalKeys`, `first`. Results:
23
+ `data.recordings.nodes[].recording` with `id`, `title`, `bpm`, `audioFile.durationInMilliseconds`, `audioFile.lqmp3Url`
24
+ (free preview), `stems[]` (MELODY, DRUMS, BASS, INSTRUMENTS), `tags[]` as `{displayName, dimension.name}` — dimensions include
25
+ `mood`, `genre`, `production genre` and `vocal type` ("no vocals"). Set `hasVocals` from the `vocal type` tag.
26
+ - `SearchSoundEffects`: `query.term`, `filter.duration`, results with `id`, `title`, duration. Titles are descriptive
27
+ ("Ice, Handle, Stirring, Wet Ice Cubes, In Glass").
28
+ - `EditRecording`: `input.targetDurationMs` (≤ 300000) and **`input.downloadAudioFormat` (WAV or MP3) is required**; optional
29
+ `loopable`, `preferenceRegions`, `requiredRegionsAtOffsets`. Then `PollEditRecordingJob(id)` until `COMPLETED` (seconds), which
30
+ gives `edit.id` and `durationMs`: **the edit can be longer than asked** (30 s asked, 33.8 s returned: it snaps to the music). If
31
+ it is longer than the cue, ask again one bar shorter rather than trimming off the ending.
32
+ `DownloadRecordingEdit({input:{jobId, editId}})` returns `assetUrl`: a WAV 48 kHz 24-bit, link valid about a day.
33
+ - `DownloadRecording(id, {fileType: WAV|MP3, stemType: FULL|BASS|DRUMS|INSTRUMENTS})` and `DownloadSoundEffect(id, {fileType})`
34
+ return a signed URL **only with an active paid subscription**; without one they answer `FORBIDDEN` ("You don't have permission
35
+ to download this asset"). On FORBIDDEN tell the user the subscription is not active on the key's account; do not work around it.
36
+ - Tool results are JSON text in `content[0].text` with GraphQL-style `{data, errors}`; `RETRY_LATER` errors carry
37
+ `retryAfterSeconds`: wait that long, then repeat once.
38
+
39
+ ## Choosing music (Epidemic Sound)
40
+ - Write one natural-language brief per cue (up to 500 characters: mood, energy, tempo, genre, instruments, "instrumental") and search
41
+ with it; that is Epidemic's own documented LLM workflow. Filter instrumental when the cue plays under any line.
42
+ - Moods and genres must be real names from the MCP schema (`tools/list`) or search results, never invented. There is no "Playful".
43
+ Starting map (*heuristic*): mischief → Quirky / Funny / Sneaking, Comedy › Cartoons / Sneaky; curiosity → Dreamy / Mysterious;
44
+ sadness → Sad / Sentimental; worry → Suspense / Restless (avoid Scary, Dark, Fear for kids); resolution → Hopeful / Sentimental;
45
+ celebration → Happy / Euphoric.
46
+ - Children read tempo before major/minor (Dalla Bella 2001): contrast tempo and energy rather than subtle harmony.
47
+ Soft BPM bands (*heuristic*): mischief 100–130 (sneaky 80–100 staccato), curiosity 70–100, sad 60–80, worry 90–120,
48
+ resolution 70–100, celebration 120–140.
49
+ - Prefer sparse, higher-register, light-bass tracks under speech (low piano and fast tempo mask speech most; phones lose bass anyway).
50
+ - **Never vocals under dialogue** (any language). A track with vocals only in no-dialogue montage or end cards. `sound.mjs` refuses it.
51
+ - Take BPM, vocals and length from the track metadata. Do not run ML models on Epidemic files.
52
+ - Fit the length with `EditRecording` (target length, `requiredRegionsAtOffsets` to land the button on the cue's out); end on the
53
+ track's real ending, not a fade, when possible. Changes of length go in whole bars (`bar = beats × 60 / BPM`).
54
+
55
+ ## SFX (kid's realism)
56
+ Softened realism plus at most one cartoon layer (boing, pop, squeak, whoosh, sparkle) on a written gag or magic beat (Bluey's approach).
57
+
58
+ | Tier | What | Rule |
59
+ |---|---|---|
60
+ | 1 | story beats and gags: impacts, spills, breaks, doors, reveals, magic | always |
61
+ | 2 | featured props: pouring, setting a cup down, the ice machine | when clearly seen for more than 0.3 s |
62
+ | 3 | movement: footsteps, entering/leaving frame | one short texture, not every step |
63
+ | 4 | cloth, breath, tiny handling | usually skip |
64
+
65
+ - Text to type: character verb + prop → foley; discrete event noun → hard effect; magic/UI/transformation → designed; place → ambience.
66
+ - Density (*heuristic*): about one event per 2–4 s of picture, fewer under talk; at most 2 layers per event; at most one cartoon
67
+ accent per 10–15 s outside slapstick; never a cartoon accent on top of a spoken word.
68
+ - Timing: a hit lands on the contact frame or up to one frame late, never early (early sound is noticed about 3× sooner). A
69
+ whoosh is placed so its peak, not its start, meets the action. The review notes give the action's time; flag the cue for the user
70
+ when the exact frame is uncertain.
71
+ - Kids: no SFX more than about 3 dB above the dialogue just before it unless it is a planned surprise with a riser before it; pick
72
+ "soft", "cartoon", "toy" variants; avoid breaking glass, gunshot-like bangs, screams, sirens, long shrill tones.
73
+
74
+ ## Ambience
75
+ - One bed per location (not per clip), running under every cut inside it; change it with the location (0.5–1 s crossfade or a
76
+ 0.5–1.5 s pre-lap before the scene cut); a long file or a seamless loop over 30 s.
77
+ - No walla or intelligible children's voices under dialogue: speech-like beds mask speech worst for children.
78
+ - It is the glue for AI clips whose own audio is muted.
79
+
80
+ ## Levels (sound.mjs solves them; these are the targets)
81
+ Dialogue is the anchor. Music under a line ≥ 14 LU below it (kids; Torcoli 2019 gives ≥ 10 LU, non-experts want ~4 LU more);
82
+ music with no dialogue 6 LU below; ambience 19 LU below; SFX 6 LU below. Duck from the spoken spans: start 0.2 s before the line,
83
+ release over 0.8 s, hold through gaps under 1.5 s. True peak ≤ −1 dBTP with no limiter: the stage first leaves 1.5 dB of headroom by
84
+ lowering this episode's clip audio, then lowers cues together if the mix still peaks. Accept about −16 to −18 LUFS integrated.
85
+
86
+ ## Keep the AI clip's own audio?
87
+ Mute by default (already done for off-script speech and built-in music). Keep matching on-screen foley only if the neighbouring
88
+ clips of the same scene keep theirs too.