creator-editing-studio 1.2.8 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.2.8",
+  "version": "1.3.1",
   "description": "Scaffolds a Creator Editing OS studio — components, scripts and rules for editing video from a plain-English brief.",
   "license": "UNLICENSED",
   "type": "module",

package/template/CLAUDE.md

@@ -48,53 +48,91 @@ Everything else in `src/design/` is the system and should be left alone. If a vi
 a colour or a size that is not in tokens.ts, the answer is to add it to tokens.ts, never to
 type it into a component.
 
-## The order of work — the plan is approved before anything is cut
+## The order of work
 
-**Never render an edit the owner has not agreed to in writing first.** A render is the last
-step, not the first. Rebuilding a rejected edit costs more than every minute the plan takes.
+Two things are fixed: **you read their references before you design anything**, and **they see
+the edit as a plan before you render it.** Everything else bends to the job in front of you.
 
-Every edit runs in this order. Do not skip a step, and do not collapse two into one.
+### 0. References first. Always. Before the brief, before the footage.
 
-**1. Watch and probe.** `npm run prep -- <name>`. Get the real duration, fps and resolution
-of every clip. Never assume them.
+This is the first thing you do in any editing session, and it is not optional, because it is the
+only reason their edits look like theirs instead of like everyone's.
 
-**2. Transcribe with word-level timings.** The transcript is the truth — not the script, not
-what the owner remembers saying. Every beat you place later is anchored to a word index, and
-every word index comes from this file.
+Read both, in this order:
 
-**3. Read the owner's style first, in this order:** `STYLE.md` §9 Rejected, then §8 Approved,
-then `references/references.md` and the contact sheets in `work/refs/`. Rejected comes first
-because removing options is faster than adding them. A reference beats a default wherever
-they disagree.
+1. **The references for this project** — anything they put in the video's own folder or named in
+   its `BRIEF.md`: a clip they want it to feel like, a screenshot, a link, a sentence like
+   "similar to that last one but calmer".
+2. **The references saved for them generally** — `references/references.md` and the contact
+   sheets in `work/refs/`, plus `STYLE.md` §9 Rejected and §8 Approved. §9 first: ruling options
+   out is faster than adding them.
 
-**4. Write the plan, and hand it over.** Two things. Neither is a markdown file for them to
-open — a plan only gets corrected if it is in front of them.
+Then say back, in one or two lines, which of their references you are using and for what. Not a
+summary of all of them — the ones that will show up in this edit.
+
+A reference beats a house default wherever the two disagree. A default is a guess that suits
+everyone; a reference is a fact about them.
+
+**If they have no references yet, do not stall and do not nag.** Say so in one line, use the
+house defaults, and ask for one reference at the end when they are reacting to something real —
+that is when people can actually name what they like.
+
+### 1. Prep and transcribe
+
+`npm run prep -- <name>`. Real duration, fps and resolution for every clip — never assumed.
+Then transcribe with word-level timings. **The transcript is the truth, not the script and not
+what they remember saying.**
+
+### 2. The first cut, before the plan
+
+Cut the silence, the filler and the retakes first. This is mechanical — no design decisions in
+it — so it does not need their approval, and doing it first is what makes the plan possible:
+every beat is anchored to a word, and words only have frame numbers once the cut exists.
+
+Re-map the word timings onto the cut timeline before going further.
+
+### 3. The plan — and this is where you stop
+
+Two things, neither of them a file for them to open. A plan only gets corrected if it is in
+front of them.
 
 **The plan goes in the reply, as a table**, one row per beat:
 
 | # | In | Out | Trigger word (frame) | What is on screen | Audio under it |
 |---|---|---|---|---|---|
 
-Followed by the total runtime, the caption script, and a short list of what you chose not to do
-and why. In the reply, not attached.
+Then the runtime, the caption script, and a short note on what you chose not to do and why.
+
+**The motion sheet is a PNG of real rendered frames.** Build the graphics, render one still per
+beat with `npm run stills`, and lay them out as a numbered contact sheet — each tile labelled
+with its timecode, the words that trigger it, and the approved beat it comes from. Prose about
+motion cannot be corrected, because they cannot see it. A picture can: they point at a tile
+number and say what to change.
+
+Every graphic names the beat it comes from, out of `STYLE.md` §8 or their references. **A
+graphic that cannot name its beat is not approved and does not go on the sheet.** That rule is
+what stops motion graphics drifting into generic.
+
+Then stop and ask: *here is the plan, change anything that is off, say go ahead and I will cut
+it.* Wait for a yes. "Go ahead", "yes", "approved", "ship it" is a yes. Silence is not.
 
-**The motion sheet is a PNG of real rendered frames** — one tile per beat, numbered, each
-labelled with its timecode, the words that trigger it, and the approved beat it comes from. Build
-the graphics, render one still per beat with `npm run stills`, and lay them out as a contact
-sheet composition. A graphic that cannot name its beat is not approved and does not go on the
-sheet. Describing motion in prose does not work: they cannot see it, so they cannot correct it.
-They point at a tile number and say what to change.
+### Keep it proportionate
 
-Then stop and ask. Say plainly: *here is the plan, change anything that is off, say go ahead
-and I will cut it.* **Wait for a yes.** "Go ahead", "approved", "ship it" is a yes. Silence is
-not, and neither is a reply about something else.
+The plan is there to save them a rebuild, not to put a form in front of them.
 
-**5. Only then cut, render, and verify.** Verification is not optional and is not a claim —
-see below.
+- **A short or simple job gets a short plan.** Three beats, three rows, three tiles. Do not pad
+  a thirty-second clip into a fifteen-row table.
+- **A fix to an edit they have already approved is not a new plan.** They said "captions lower,
+  hold that shot longer" — do it, show it, done. Re-plan only when the structure changes.
+- **If they say "just do it", do it.** Put the table in one short message and cut straight
+  after, so there is still a record of what was intended — but do not block on an answer.
+- **Never ask a question you can answer yourself.** Probe the file, read the brief, pick the
+  sensible default and say which one you picked. Questions are for the things that would
+  genuinely change the edit.
+- **One round of questions, not a drip.** If you need to ask, ask everything at once.
 
-If the owner says "just edit it" and skips the plan, write the plan anyway, in one short
-message, and cut immediately after. It costs thirty seconds and it is the only record of
-what was intended.
+The failure this is guarding against is a whole edit rendered the wrong way. Anything that does
+not risk that should move fast.
 
 ## Verify the render before you call it done
 
@@ -129,10 +167,25 @@ and not in the stills, it did not render — find out why before shipping.
 `OffthreadVideo` placed in one starts from its own frame 0 and plays its own audio over the
 live line. Pass an explicit `startFrom`, and mute it unless its sound is wanted.
 
-**Repetition the owner can hear but you cannot.** If the owner says a line repeats, transcribe
-the rendered output over that exact window before arguing. If the audio is clean, the repeat
-is visual — a held caption, a reused graphic, or a duplicated framing — and that is still a
-real fault worth fixing, not a misunderstanding to explain away.
+**Something they can hear and you cannot.** When they report a fault you cannot find, your check
+is the thing most likely to be wrong, not them. Three rules, learned the hard way:
+
+- **Transcribe the WHOLE file, not the window they named.** A seven-second sample came back clean
+  and was used to tell the owner he was imagining a repeat that was really there.
+- **Check every render in `out/`, not the one you just made.** They are probably playing an older
+  file, because nothing on their machine says which is current. Ask which file, or test them all.
+- **If they say it more than once, stop checking and start believing.** A repeated complaint is
+  evidence your method is wrong. Change the method.
+
+If the audio really is clean, the repeat is visual — a held caption, a reused graphic, a duplicated
+framing — and that is still a real fault, not a misunderstanding to explain away.
+
+**Four generations of lossy audio.** The voice must be cut as PCM and encoded exactly once, at
+delivery. Cutting an AAC file, trimming the result, and then letting the renderer re-encode it
+puts the voice through four generations of loss, and raising the bitrate on the later passes
+preserves the damage rather than repairing it. It is clearly audible and it gets worse with
+every extra render. Use `node scripts/voice.mjs` to pull the voice losslessly from the camera
+file, render the picture muted, and mux the two together at the end.
 
 ## Non-negotiables
 

package/template/scripts/exact-frames.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Pull EXACT frame numbers out of a rendered file.
+ *
+ *   node scripts/exact-frames.mjs <file.mp4> <frame,frame,...> <outDir>
+ *
+ * Why this exists: `-ss` seeking is not frame accurate. Checking v4's cut boundaries with it
+ * returned frames 1-3 later than asked for, which made clean cuts look like defects and nearly
+ * sent a good edit back for rework. Decoding from the start and selecting by frame index is
+ * slower and is the only thing that can be trusted for a boundary check.
+ *
+ * The select expression is passed as one argv entry through spawnSync, never a shell — its
+ * commas are exactly what breaks a shell-quoted filter graph.
+ */
+import {spawnSync} from 'node:child_process';
+import {mkdirSync, rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {FFMPEG} from './lib/media.mjs';
+
+const [, , file, framesArg, outDir = 'work/exact'] = process.argv;
+if (!file || !framesArg) {
+  console.error('Usage: node scripts/exact-frames.mjs <file> <frame,frame,...> [outDir]');
+  process.exit(2);
+}
+
+const frames = framesArg.split(',').map(Number).sort((a, b) => a - b);
+rmSync(outDir, {recursive: true, force: true});
+mkdirSync(outDir, {recursive: true});
+
+// eq(n\,N) — the backslash has to survive into the filter string, so it is doubled here.
+const expr = frames.map((f) => `eq(n\\,${f})`).join('+');
+
+const r = spawnSync(
+  FFMPEG,
+  [
+    '-y', '-v', 'error',
+    '-i', file,
+    '-vf', `select='${expr}',scale=440:-1`,
+    '-fps_mode', 'passthrough',
+    '-frames:v', String(frames.length),
+    join(outDir, 'x%03d.png'),
+  ],
+  {encoding: 'utf8'},
+);
+if (r.status !== 0) {
+  console.error(r.stderr?.slice(0, 900));
+  process.exit(1);
+}
+
+console.log(frames.map((f, i) => `x${String(i + 1).padStart(3, '0')}.png = frame ${f}`).join('\n'));

package/template/scripts/voice.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Build the voice track ONCE, losslessly, straight from the camera file.
+ *
+ *   node scripts/voice.mjs --source <clip.mp4> --takes <takes.json> [--drop 17.2333:17.6667] --out <voice.wav>
+ *
+ * WHY THIS EXISTS. The voice on demo-test went through FOUR lossy generations before it reached
+ * the viewer: the camera's own AAC 128k, then the cut, then a second trim, then the render — each
+ * one re-encoding what the last one had already damaged. Raising the bitrate on the later passes
+ * does not recover anything; it just preserves the damage at a bigger file size. It is audible,
+ * and it gets worse with every extra render.
+ *
+ * The rulebook already says it: render the picture muted and add the original voice back
+ * untouched. This is the tool that makes that easy. The voice is cut as PCM and stays PCM until
+ * the single encode at delivery, so the viewer hears one generation of loss instead of four.
+ *
+ * `atrim` takes colon-separated options, so the filter graph carries no commas inside a function
+ * call — and it is passed through spawnSync as one argv entry, never a shell.
+ */
+import {spawnSync} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {FFMPEG} from './lib/media.mjs';
+
+const args = process.argv.slice(2);
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const source = opt('source');
+const takesFile = opt('takes');
+const out = opt('out');
+if (!source || !out) {
+  console.error('Usage: node scripts/voice.mjs --source <clip> [--takes <takes.json>] [--drop a:b] --out <voice.wav>');
+  process.exit(2);
+}
+
+/** The spans to keep, in source seconds. With no takes file, keep the whole clip. */
+let keep = [{from: 0, to: null}];
+if (takesFile) keep = JSON.parse(readFileSync(takesFile, 'utf8')).keep;
+
+const parts = [];
+keep.forEach((k, i) => {
+  const range = k.to == null ? `start=${k.from.toFixed(4)}` : `start=${k.from.toFixed(4)}:end=${k.to.toFixed(4)}`;
+  parts.push(`[0:a]atrim=${range},asetpts=PTS-STARTPTS[a${i}]`);
+});
+parts.push(`${keep.map((_, i) => `[a${i}]`).join('')}concat=n=${keep.length}:v=0:a=1[joined]`);
+
+/**
+ * A second pass of removals, expressed in the CUT timeline rather than the source — that is where
+ * a tightened pause lives, because its position only exists after the first cut.
+ */
+const drop = opt('drop');
+let label = 'joined';
+if (drop) {
+  const [a, b] = drop.split(':').map(Number);
+  parts.push(`[joined]asplit=2[d0][d1]`);
+  parts.push(`[d0]atrim=start=0:end=${a.toFixed(4)},asetpts=PTS-STARTPTS[p0]`);
+  parts.push(`[d1]atrim=start=${b.toFixed(4)},asetpts=PTS-STARTPTS[p1]`);
+  parts.push(`[p0][p1]concat=n=2:v=0:a=1[cut]`);
+  label = 'cut';
+}
+
+const r = spawnSync(
+  FFMPEG,
+  [
+    '-y', '-v', 'error',
+    '-i', source,
+    '-filter_complex', parts.join(';'),
+    '-map', `[${label}]`,
+    // PCM, and the source's own sample rate — no resampling, no encoding.
+    '-c:a', 'pcm_s16le',
+    out,
+  ],
+  {encoding: 'utf8'},
+);
+if (r.status !== 0) {
+  console.error(r.stderr?.slice(0, 900));
+  process.exit(1);
+}
+
+const probe = spawnSync(
+  FFMPEG.replace(/ffmpeg(\.exe)?$/i, (m) => (m.endsWith('.exe') ? 'ffprobe.exe' : 'ffprobe')),
+  ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', out],
+  {encoding: 'utf8'},
+);
+console.log(`voice written lossless -> ${out}  (${Number(probe.stdout).toFixed(3)}s, pcm_s16le)`);
+console.log('Render the picture muted, then mux this in with ONE encode at delivery.');

package/template/templates/BRIEF.md

@@ -28,6 +28,8 @@ Length target:          <!-- e.g. 25s, 90s -->
 
 
 ## Moments from references
+<!-- READ FIRST, BEFORE ANY DESIGN DECISION. These, and the ones saved in references/references.md,
+     beat the house defaults wherever the two disagree. -->
 <!-- You DON'T need the name of the effect. Clip + time + what you like about it.
      Format: - clip-file.mp4 mm:ss-mm:ss — what you like (feel words are fine: snappy, floaty, punchy)
 - a-reel-you-like.mp4 00:02-00:04 — the colour screens flipping with each phrase, feels punchy -->