creator-editing-studio 1.2.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "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/scripts/takes.mjs

@@ -1,35 +1,38 @@
 #!/usr/bin/env node
 /**
- * Best-take selection: turn a script plus a messy take into a clean cut plan.
+ * Best-take selection: one messy take in, one clean cut plan out.
  *
- *   npm run takes -- <script.md|txt> <words.json> [--project <name>] [--out <file>]
- *                    [--fps 30] [--gap-keep 0.18] [--min-coverage 0.6] [--loose]
+ *   npm run takes -- <words.json> [--media <video>] [--script <script.md>]
+ *                    [--project <name>] [--out <file>] [--fps 30]
+ *                    [--similar 0.72] [--window 90] [--gap-max 0.6] [--gap-keep 0.25]
  *
- * THE PROBLEM THIS SOLVES. A talking head is read from a script, so the speaker fumbles and
- * says a sentence again. `trim.mjs` removes silence and filler, but it keeps every attempt —
- * so the cut contains the stumble AND the fix, and someone watches the whole thing to find
- * them. On the setup video that meant 16 drop ranges chosen by hand, several missed, and a
- * trip to CapCut to take out repeats nobody caught.
+ * WHAT IT IS FOR. A talking head is full of second attempts. Somebody fumbles, stops, says the
+ * sentence again, and both versions end up in the cut — so a human watches the whole thing to
+ * find them. This finds them instead, keeps the better one, and proves afterwards that none are
+ * left.
  *
- * WHY NOT JUST HUNT FOR REPEATS. Repeat-hunting is a filter: it finds duplicates it recognises
- * and misses the rest. Anchoring to the script is a constructor: each sentence of the script is
- * an atom, every atom gets exactly one span of audio, and anything that is not the winning span
- * for some atom never enters the cut. Repeats are not removed — they are impossible. Filler,
- * half-sentences, asides and dead air are gone for the same reason, without a rule for each.
+ * THE SPEECH IS THE TRUTH, NOT THE SCRIPT. An earlier version of this file anchored to the
+ * written script: every script sentence got one span and anything unmatched was dropped. It
+ * threw away six passages of real material on the first take it was pointed at — lines the
+ * speaker improvised on the day and meant to keep, including "you don't have to put the brief
+ * into the brief file". A repeat that survives is visible and fixable; a good line silently
+ * deleted is neither. So the default here is inverted:
  *
- * It also fails loudly. If a script sentence has no usable take, the build stops and names the
- * line, instead of handing over a cut with a hole for someone to find on playback.
+ *     KEEP EVERYTHING, UNLESS IT IS A SECOND ATTEMPT AT SOMETHING ELSE THAT IS KEPT.
  *
- * WHAT IT WRITES  work/<project>/<stem>.takes.json
- *   keep[]      {from, to, atom}   source seconds to use, in order
- *   dropped[]   {from, to, reason, text}
- *   atoms[]     every script sentence, its chosen take and the attempts that lost
- *   checks{}    the verification results, all of which must pass
+ * Nothing has to justify its existence. A script, if there is one, is only a checker: it reports
+ * lines that never got said and breaks ties between close takes. It can never remove anything,
+ * and most people filming to camera do not have one.
  *
- * The shape of `keep[]` matches `trim.mjs`, so the rest of the pipeline is unchanged.
+ * WHAT IT WRITES  work/<project>/<stem>.takes.json
+ *   keep[]      {from, to, units}  source seconds to use, in order
+ *   groups[]    every retake cluster, which attempt won and why the others lost
+ *   dropped[]   what went, with the reason
+ *   checks{}    verification, all of which must pass
  */
 import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
 import {basename, dirname, join} from 'node:path';
+import {decodePcm} from './lib/media.mjs';
 
 /* ------------------------------------------------------------------------ args */
 
@@ -38,292 +41,304 @@ const flag = (name, fallback) => {
   const i = args.indexOf(`--${name}`);
   return i === -1 ? fallback : args[i + 1];
 };
-const has = (name) => args.includes(`--${name}`);
 const positional = args.filter((a, i) => !a.startsWith('--') && !String(args[i - 1] ?? '').startsWith('--'));
 
-const [scriptPath, wordsPath] = positional;
-if (!scriptPath || !wordsPath) {
-  console.error('usage: npm run takes -- <script.md|txt> <words.json> [--project <name>]');
+const wordsPath = positional[0];
+if (!wordsPath) {
+  console.error('usage: npm run takes -- <words.json> [--media <video>] [--script <script.md>]');
   process.exit(1);
 }
 
 const FPS = Number(flag('fps', 30));
-/** A gap longer than this between kept spans is collapsed down to it. */
-const GAP_KEEP = Number(flag('gap-keep', 0.18));
-/** Below this share of an atom's words matched, a span is not a take of that atom at all. */
-const MIN_COVERAGE = Number(flag('min-coverage', 0.6));
-/** Padding kept around a span so cuts do not clip the first and last phoneme. */
-const PAD = 0.06;
+/** How alike two passages must be before they count as attempts at the same thing. */
+const SIMILAR = Number(flag('similar', 0.72));
+/** Retakes happen close together. Two matching sentences minutes apart are both wanted. */
+const WINDOW = Number(flag('window', 90));
+/** A silence longer than this is dead air and gets collapsed. */
+const GAP_MAX = Number(flag('gap-max', 0.6));
+/** ...down to this. Not zero: speech with every gap removed sounds like a machine. */
+const GAP_KEEP = Number(flag('gap-keep', 0.25));
+/**
+ * Breathing room kept either side of a kept passage.
+ *
+ * 150ms, not the 60 an earlier version used. Below about 120 the cut lands close enough to the
+ * first phoneme to clip it, and the join reads as abrupt even when every word is intact.
+ */
+const PAD = 0.15;
 
-/* ------------------------------------------------------------- script and words */
+/* ------------------------------------------------------------------- the words */
+
+const key = (t) => t.toLowerCase().replace(/['‘’]/g, '').replace(/[^a-z0-9]/g, '');
+
+const words = JSON.parse(readFileSync(wordsPath, 'utf8')).words.filter((w) => w.start != null && w.end != null);
+if (words.length < 10) {
+  console.error('Not enough timed words to work with.');
+  process.exit(1);
+}
 
 /**
- * The script as atoms.
+ * Cues that announce a retake out loud.
  *
- * A sentence is the right unit: small enough that one fumble does not cost a paragraph, big
- * enough to identify uniquely in the transcript. Markdown furniture and the BRIEF.md comment
- * blocks are stripped — they are instructions to the writer, never spoken.
+ * When someone says one of these, the passage BEFORE it was abandoned — they are telling you so.
+ * Cheaper and more certain than any similarity measure.
  */
-const atomise = (raw) =>
-  raw
-    // Everything above the first `---` is front matter or a note to whoever wrote the script.
-    // It is never spoken, and counting it as missing dialogue buries the lines that really are.
-    .split(/^---\s*$/m)
-    .slice(1)
-    .join('\n')
-    .replace(/<!--[\s\S]*?-->/g, '')
-    .replace(/^#.*$/gm, '')
-    .replace(/^[-*|>].*$/gm, '')
-    .replace(/`[^`]*`/g, ' ')
-    .split(/(?<=[.?!])\s+/)
-    .map((s) => s.replace(/\s+/g, ' ').trim())
-    .filter((s) => s.split(/\s+/).filter(Boolean).length >= 3);
+const RESTART_CUES = [
+  'let me redo that', 'let me try that again', 'one more time', 'sorry let me',
+  'can i do that again', 'take two', 'scratch that', 'let me say that again',
+  'start again', 'i will say that again',
+];
+
+/* --------------------------------------------------------------- units of speech
+ * A unit is one spoken thought: it ends where the speaker put a full stop, or where they left a
+ * gap long enough to be a boundary rather than a breath. Working in units rather than fixed word
+ * counts means a retake is compared against the whole thought it replaced. */
+
+const units = [];
+{
+  let start = 0;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    const next = words[i + 1];
+    const gapAfter = next ? next.start - w.end : Infinity;
+    const endsSentence = /[.?!]$/.test(w.word);
+    if (endsSentence || gapAfter > 0.7 || i === words.length - 1) {
+      const span = words.slice(start, i + 1);
+      if (span.length) {
+        units.push({
+          index: units.length,
+          startIndex: start,
+          endIndex: i,
+          from: span[0].start,
+          to: span[span.length - 1].end,
+          text: span.map((x) => x.word).join(' '),
+          keys: span.map((x) => key(x.word)).filter(Boolean),
+          confidence: span.reduce((a, x) => a + (x.score ?? 0.8), 0) / span.length,
+          complete: endsSentence,
+          worstGap: span.slice(1).reduce((m, x, k) => Math.max(m, x.start - span[k].end), 0),
+        });
+      }
+      start = i + 1;
+    }
+  }
+}
+
+/* -------------------------------------------------------------- energy and pace */
 
-/** Comparable key for a word. Mirrors align_script.py so both agree on what "same" means. */
 /**
- * Spellings that mean the same word.
+ * Loudness per unit, so a flat read can lose to a committed one.
  *
- * The script is written in British English and the recogniser answers in American. Without this,
- * "licence" never matches "license" and a correctly spoken sentence is reported as missing while
- * the audio for it is thrown away as off-script. That is a worse failure than a repeat.
+ * Optional: without --media there is no audio to measure and the score simply does without it,
+ * rather than the tool refusing to run.
  */
-const SPELLING = new Map(Object.entries({
-  license: 'licence', color: 'colour', colors: 'colours', favorite: 'favourite',
-  realize: 'realise', organize: 'organise', gray: 'grey', analyze: 'analyse',
-}));
+let rmsOf = () => null;
+const mediaPath = flag('media', null);
+if (mediaPath && existsSync(mediaPath)) {
+  const RATE = 22050;
+  const pcm = decodePcm(mediaPath, RATE);
+  if (pcm) {
+    rmsOf = (from, to) => {
+      const a = Math.max(0, Math.floor(from * RATE));
+      const b = Math.min(pcm.length, Math.ceil(to * RATE));
+      if (b <= a) return null;
+      let sum = 0;
+      for (let i = a; i < b; i++) sum += pcm[i] * pcm[i];
+      return Math.sqrt(sum / (b - a));
+    };
+  }
+}
+
+for (const u of units) {
+  u.seconds = u.to - u.from;
+  u.wordsPerSecond = u.keys.length / Math.max(0.3, u.seconds);
+  u.rms = rmsOf(u.from, u.to);
+}
 
-const key = (token) => {
-  const bare = token.toLowerCase().replace(/['‘’]/g, '').replace(/[^a-z0-9]/g, '');
-  return SPELLING.get(bare) ?? bare;
+const median = (xs) => {
+  const s = xs.filter((x) => x != null).sort((a, b) => a - b);
+  return s.length ? s[Math.floor(s.length / 2)] : null;
+};
+const medianRms = median(units.map((u) => u.rms));
+const medianPace = median(units.map((u) => u.wordsPerSecond)) ?? 3;
+
+/* ------------------------------------------------------------------ similarity */
+
+/** Longest common subsequence length — tolerant of an inserted stumble or a swapped word. */
+const lcs = (a, b) => {
+  const prev = new Array(b.length + 1).fill(0);
+  const cur = new Array(b.length + 1).fill(0);
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = a[i - 1] === b[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], cur[j - 1]);
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = cur[j];
+  }
+  return prev[b.length];
 };
 
 /**
- * Contractions, expanded.
+ * How alike two units are, measured against the SHORTER one.
  *
- * The script says "it'll" and the speaker says "it will" — or the other way round, depending on
- * the day and the recogniser. Both sides expand to the same pair of words so they compare equal.
- * Only forms carrying an apostrophe are touched, so "well" is never mistaken for "we will".
+ * Against the shorter, because an abandoned start — "so the main reason, so the main reason is
+ * that…" — is a short fragment entirely contained in the full attempt. Measured against the
+ * longer it would score low and be kept; against the shorter it scores 1.0 and is correctly
+ * recognised as the same thought, begun twice.
  */
-const CONTRACTION = new Map(Object.entries({
-  itll: ['it', 'will'], theyll: ['they', 'will'], youll: ['you', 'will'], well: ['we', 'will'],
-  itsa: ['it', 'is', 'a'], its: ['it', 'is'], thats: ['that', 'is'], whats: ['what', 'is'],
-  theres: ['there', 'is'], heres: ['here', 'is'], lets: ['let', 'us'], youre: ['you', 'are'],
-  theyre: ['they', 'are'], weve: ['we', 'have'], youve: ['you', 'have'], ive: ['i', 'have'],
-  dont: ['do', 'not'], doesnt: ['does', 'not'], didnt: ['did', 'not'], isnt: ['is', 'not'],
-  wasnt: ['was', 'not'], arent: ['are', 'not'], wont: ['will', 'not'], cant: ['can', 'not'],
-  couldnt: ['could', 'not'], wouldnt: ['would', 'not'], shouldnt: ['should', 'not'],
-  youd: ['you', 'would'], id: ['i', 'would'], wed: ['we', 'would'], ill: ['i', 'will'],
-}));
-
-/** One spoken or written word becomes the one or more keys it is equivalent to. */
-const keysOfWord = (token) => {
-  const k = key(token);
-  if (!k) return [];
-  // Only expand when the original actually had an apostrophe, so ordinary words are left alone.
-  if (/['‘’]/.test(token) && CONTRACTION.has(k)) return CONTRACTION.get(k);
-  return [k];
+const similarity = (a, b) => {
+  if (!a.keys.length || !b.keys.length) return 0;
+  const shorter = Math.min(a.keys.length, b.keys.length);
+  // Short units match each other on function words alone — "give it three things" against
+  // "this is the time you give it that" shares "give it" and scores 0.5 on a four-word unit.
+  // Below five words there is not enough signal to call anything a retake.
+  if (shorter < 5) return 0;
+  const overlap = lcs(a.keys, b.keys);
+  // And the overlap has to be real words, not two articles and a pronoun.
+  if (overlap < 4) return 0;
+  return overlap / shorter;
 };
 
-const keysOf = (text) => text.split(/[\s\-/]+/).flatMap(keysOfWord);
+/* ---------------------------------------------------------------------- groups */
+
+const groupOf = new Array(units.length).fill(-1);
+const groups = [];
 
 /**
- * Filler. Deliberately short.
+ * Grouping is against a representative, never transitive.
  *
- * Stripping every "so" and "you know" makes speech sound sanded down, which reads as
- * over-edited and is its own kind of amateur. These are only ever used to PENALISE a take,
- * never to cut inside a winning one — if the best attempt at a line contains an "um", the line
- * keeps its "um" and sounds like a person.
+ * Chaining members together — A matches B, B matches C, so group them all — merges passages that
+ * have nothing to do with each other as soon as one ambiguous unit sits between them. It put
+ * "give it three things" in the same group as "they just won't really feel like you". A unit
+ * joins a group only if it is similar to that group's FIRST member, which keeps a group to one
+ * thought said more than once.
  */
-const FILLER = new Set(['um', 'uh', 'uhh', 'umm', 'erm', 'hmm', 'mmm', 'ah', 'eh']);
+for (let i = 0; i < units.length; i++) {
+  if (groupOf[i] !== -1) continue;
+  const members = [i];
+  for (let j = i + 1; j < units.length; j++) {
+    if (groupOf[j] !== -1) continue;
+    if (units[j].from - units[i].to > WINDOW) break;
+    if (similarity(units[i], units[j]) < SIMILAR) continue;
+    members.push(j);
+  }
+  if (members.length < 2) continue;
+  groups.push({members});
+  for (const m of members) groupOf[m] = groups.length - 1;
+}
 
-const words = JSON.parse(readFileSync(wordsPath, 'utf8')).words.filter((w) => w.start != null && w.end != null);
-const rawScript = readFileSync(scriptPath, 'utf8');
-// A plain .txt script has no `---` rule, so give it one — atomise() always drops what is above
-// the first rule, and without this a bare script would come back empty.
-const atoms = atomise(/^---\s*$/m.test(rawScript) ? rawScript : `---\n${rawScript}`);
-/** Each spoken word as the list of keys it is equivalent to. Index stays 1:1 with `words`. */
-const tokenKeys = words.map((w) => {
-  const ks = keysOfWord(w.word);
-  return ks.length ? ks : ['\u0000'];
-});
-const tokens = tokenKeys.map((ks) => ks[0]);
-
-if (!atoms.length) {
-  console.error(`No script sentences found in ${scriptPath}.`);
-  process.exit(1);
+/** A spoken cue abandons whatever came immediately before it. */
+const abandoned = new Set();
+for (const u of units) {
+  const flat = u.keys.join(' ');
+  if (!RESTART_CUES.some((c) => flat.includes(c.replace(/[^a-z0-9 ]/g, '')))) continue;
+  const prev = units[u.index - 1];
+  if (prev) abandoned.add(prev.index);
 }
 
-/* --------------------------------------------------------------- finding takes */
+/* --------------------------------------------------------------------- scoring */
 
 /**
- * Every span of transcript that is a plausible attempt at `atom`.
+ * One number per attempt.
  *
- * Greedy forward alignment from each position whose word matches the atom's first word, allowing
- * the speaker to skip, swap or insert a few words. A take is scored on how much of the sentence
- * actually made it out, how sure the aligner was, and whether it ran smoothly — a long pause or
- * an "um" inside a sentence is exactly what a fumbled attempt sounds like.
+ * Completeness dominates — a finished sentence beats a smoother fragment every time. Everything
+ * else nudges. The tie-break at the end is deliberate and matches how people actually record:
+ * they repeat a line until they are happy, so the last attempt is usually the keeper.
  */
-const findTakes = (atom, atomIndex) => {
-  const want = keysOf(atom);
-  if (!want.length) return [];
-  const out = [];
-  /** How far past the sentence the speaker may wander before the attempt is abandoned. */
-  const window = Math.ceil(want.length * 2.2) + 6;
-
-  /**
-   * A take may begin on any of the sentence's first three words.
-   *
-   * Anchoring only on the first word loses a whole sentence to a single swapped article — the
-   * script says "This system gets better", the speaker says "The system gets better", and the
-   * line is reported missing while its audio is discarded. Coverage still has to clear the
-   * threshold, so a take that drops its opening words scores lower rather than passing free.
-   */
-  const anchors = want.slice(0, 3);
-
-  for (let start = 0; start < tokens.length; start++) {
-    const anchorAt = anchors.indexOf(tokens[start]);
-    if (anchorAt === -1) continue;
-
-    let wi = anchorAt;
-    let matched = anchorAt;
-    let last = start;
-    let extras = 0;
-    for (let ti = start; ti < Math.min(tokens.length, start + window) && wi < want.length; ti++) {
-      // A contraction covers more than one script word, so consume as many as it supplies.
-      let consumed = 0;
-      while (consumed < tokenKeys[ti].length && wi + consumed < want.length && tokenKeys[ti][consumed] === want[wi + consumed]) consumed++;
-      if (consumed > 0) {
-        matched += consumed;
-        wi += consumed;
-        last = ti;
-      } else if (want.indexOf(tokens[ti], wi) !== -1 && want.indexOf(tokens[ti], wi) - wi <= 3) {
-        // The speaker skipped a word or two and carried on; follow them.
-        wi = want.indexOf(tokens[ti], wi) + 1;
-        matched++;
-        last = ti;
-      } else {
-        extras++;
-      }
-    }
-
-    const coverage = matched / want.length;
-    if (coverage < MIN_COVERAGE) continue;
-
-    const from = words[start].start;
-    const to = words[last].end;
-    const span = words.slice(start, last + 1);
-
-    let worstGap = 0;
-    for (let i = 1; i < span.length; i++) worstGap = Math.max(worstGap, span[i].start - span[i - 1].end);
-    const fillerInside = span.filter((w) => FILLER.has(key(w.word))).length;
-    const confidence = span.reduce((a, w) => a + (w.score ?? 0.8), 0) / span.length;
-
-    out.push({
-      atomIndex,
-      startIndex: start,
-      endIndex: last,
-      from,
-      to,
-      coverage,
-      confidence,
-      worstGap,
-      fillerInside,
-      extras,
-      text: span.map((w) => w.word).join(' '),
-      /**
-       * One number, so the chooser has something to maximise.
-       *
-       * Coverage dominates: a complete sentence beats a smooth fragment every time. The small
-       * bonus for starting later is there because when someone fumbles they fix it on the next
-       * try, so with two otherwise equal attempts the second is the keeper.
-       */
-      score:
-        coverage * 10 +
-        confidence * 2 -
-        Math.max(0, worstGap - 0.4) * 3 -
-        fillerInside * 0.8 -
-        (extras / want.length) * 1.5 +
-        (start / tokens.length) * 0.3,
-    });
-
-    start = last; // attempts cannot overlap each other
-  }
-  return out;
+const score = (u) => {
+  let s = 0;
+  s += u.complete ? 6 : 0;
+  s += Math.min(u.keys.length / 12, 1) * 3;
+  s += u.confidence * 2;
+  s -= Math.max(0, u.worstGap - 0.45) * 3;
+  if (abandoned.has(u.index)) s -= 20;
+  // Pace: too fast reads as rushed, too slow as laboured. Either direction costs the same.
+  s -= Math.min(2, Math.abs(u.wordsPerSecond - medianPace) / Math.max(0.8, medianPace) * 2);
+  // Energy, only when there was audio to measure.
+  if (u.rms != null && medianRms) s += Math.max(-1.5, Math.min(1.5, (u.rms / medianRms - 1) * 2));
+  return s;
 };
 
-const takesPerAtom = atoms.map((atom, i) => findTakes(atom, i));
+for (const u of units) u.score = score(u);
 
-/* -------------------------------------------------------------- choosing takes */
+/* ------------------------------------------------------- optional script checker
+ * A script never removes anything. It reports lines that were never said, and nudges a tie
+ * toward whichever attempt is closest to what was written. */
 
-/**
- * One take per atom, in script order, never overlapping.
- *
- * Greedy picking of each atom's best take breaks as soon as the best take of sentence 4 sits
- * earlier in the tape than the chosen take of sentence 5. This is weighted interval scheduling
- * over the atoms in order: for each candidate, the best total reachable while ending before the
- * next atom starts. Small enough to be exact rather than heuristic.
- */
-const NEG = -1e9;
-const best = takesPerAtom.map((takes) => takes.map(() => ({total: NEG, prev: -1})));
-
-for (let a = 0; a < atoms.length; a++) {
-  const takes = takesPerAtom[a];
-  for (let c = 0; c < takes.length; c++) {
-    if (a === 0) {
-      best[a][c] = {total: takes[c].score, prev: -1};
-      continue;
-    }
-    let bestPrev = NEG;
-    let bestPrevIndex = -1;
-    for (let p = 0; p < takesPerAtom[a - 1].length; p++) {
-      if (best[a - 1][p].total === NEG) continue;
-      if (takesPerAtom[a - 1][p].endIndex >= takes[c].startIndex) continue;
-      if (best[a - 1][p].total > bestPrev) {
-        bestPrev = best[a - 1][p].total;
-        bestPrevIndex = p;
-      }
-    }
-    // An atom with no reachable predecessor can still start a run; the coverage check below
-    // is what decides whether the result is acceptable, not this.
-    best[a][c] =
-      bestPrevIndex === -1
-        ? {total: takes[c].score, prev: -1}
-        : {total: bestPrev + takes[c].score, prev: bestPrevIndex};
-  }
-}
+const scriptPath = flag('script', null);
+let scriptMissing = [];
+if (scriptPath && existsSync(scriptPath)) {
+  const raw = readFileSync(scriptPath, 'utf8');
+  const body = /^---\s*$/m.test(raw) ? raw.split(/^---\s*$/m).slice(1).join('\n') : raw;
+  const lines = body
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/^#.*$/gm, '')
+    .replace(/`[^`]*`/g, ' ')
+    .split(/(?<=[.?!])\s+/)
+    .map((s) => s.replace(/\s+/g, ' ').trim())
+    .filter((s) => s.split(/\s+/).length >= 4);
 
-const chosen = new Array(atoms.length).fill(null);
-let cursor = -1;
-for (let a = atoms.length - 1; a >= 0; a--) {
-  const takes = takesPerAtom[a];
-  if (!takes.length) continue;
-  let pick = cursor;
-  if (pick === -1) {
-    let top = NEG;
-    for (let c = 0; c < takes.length; c++)
-      if (best[a][c].total > top) {
-        top = best[a][c].total;
-        pick = c;
-      }
+  for (const line of lines) {
+    const lk = line.split(/\s+/).map(key).filter(Boolean);
+    const best = Math.max(0, ...units.map((u) => lcs(lk, u.keys) / Math.max(1, lk.length)));
+    if (best < 0.6) scriptMissing.push({text: line, bestMatch: Number(best.toFixed(2))});
+  }
+  // Closest-to-script wins a close call, but only by a little.
+  for (const g of groups) {
+    for (const m of g.members) {
+      const u = units[m];
+      const best = Math.max(0, ...lines.map((l) => lcs(l.split(/\s+/).map(key).filter(Boolean), u.keys) / Math.max(1, u.keys.length)));
+      u.score += best * 1.2;
+    }
   }
-  if (pick === -1 || !takes[pick]) continue;
-  chosen[a] = takes[pick];
-  cursor = best[a][pick].prev;
 }
 
-/* ------------------------------------------------------------------ the result */
+/* ----------------------------------------------------------------- the decision */
 
-const missing = [];
-atoms.forEach((atom, i) => {
-  if (!chosen[i]) missing.push({index: i, text: atom, attempts: takesPerAtom[i].length});
-});
+const drop = new Set();
+const groupReport = [];
 
-const keep = chosen
-  .filter(Boolean)
-  .map((t) => ({from: Math.max(0, t.from - PAD), to: t.to + PAD, atom: t.atomIndex, text: t.text}))
-  .sort((a, b) => a.from - b.from);
+for (const g of groups) {
+  const members = [...new Set(g.members)].sort((a, b) => a - b);
+  let winner = members[0];
+  for (const m of members) {
+    const a = units[m];
+    const b = units[winner];
+    // Within a hair of each other, the later one wins.
+    if (a.score > b.score + 0.3 || (Math.abs(a.score - b.score) <= 0.3 && a.from > b.from)) winner = m;
+  }
+  for (const m of members) if (m !== winner) drop.add(m);
+  groupReport.push({
+    kept: {at: Number(units[winner].from.toFixed(2)), text: units[winner].text.slice(0, 90), score: Number(units[winner].score.toFixed(2))},
+    dropped: members.filter((m) => m !== winner).map((m) => ({
+      at: Number(units[m].from.toFixed(2)),
+      text: units[m].text.slice(0, 90),
+      score: Number(units[m].score.toFixed(2)),
+    })),
+  });
+}
+for (const i of abandoned) drop.add(i);
+
+const kept = units.filter((u) => !drop.has(u.index));
+
+/* ------------------------------------------------------------- building the plan
+ * Consecutive survivors become one span, so the cut is not chopped at every sentence. A gap
+ * between spans is collapsed only when it is longer than a breath — and a pause in front of a
+ * short line is usually deliberate, so those are left alone. */
+
+const keep = [];
+for (const u of kept) {
+  const last = keep[keep.length - 1];
+  if (last && u.startIndex === last.endIndex + 1 && u.from - last.to < GAP_MAX) {
+    last.to = u.to;
+    last.endIndex = u.endIndex;
+    last.units.push(u.index);
+  } else {
+    keep.push({from: u.from, to: u.to, startIndex: u.startIndex, endIndex: u.endIndex, units: [u.index]});
+  }
+}
 
-// Overlapping padding between neighbours would double a word; meet in the middle instead.
+for (const k of keep) {
+  k.from = Math.max(0, k.from - PAD);
+  k.to += PAD;
+}
 for (let i = 1; i < keep.length; i++) {
   if (keep[i].from < keep[i - 1].to) {
     const mid = (keep[i].from + keep[i - 1].to) / 2;
@@ -332,134 +347,78 @@ for (let i = 1; i < keep.length; i++) {
   }
 }
 
-const keptIndexes = new Set();
-chosen.filter(Boolean).forEach((t) => {
-  for (let i = t.startIndex; i <= t.endIndex; i++) keptIndexes.add(i);
-});
-
-const dropped = [];
-let runStart = null;
-for (let i = 0; i < words.length; i++) {
-  const inCut = keptIndexes.has(i);
-  if (!inCut && runStart === null) runStart = i;
-  if ((inCut || i === words.length - 1) && runStart !== null) {
-    const end = inCut ? i - 1 : i;
-    const text = words.slice(runStart, end + 1).map((w) => w.word).join(' ');
-    const alsoKept = chosen.filter(Boolean).some((t) => keysOf(t.text).join(' ').includes(keysOf(text).join(' ')));
-    dropped.push({
-      from: words[runStart].start,
-      to: words[end].end,
-      reason: alsoKept ? 'retake' : text.split(/\s+/).length <= 2 ? 'filler' : 'off-script',
-      text,
-    });
-    runStart = null;
-  }
+/** Gaps between spans, after the cut: long dead air collapsed, deliberate beats kept. */
+const gaps = [];
+for (let i = 1; i < keep.length; i++) {
+  const gap = keep[i].from - keep[i - 1].to;
+  const nextIsShort = units[keep[i].units[0]].keys.length <= 6;
+  const target = gap > GAP_MAX && !nextIsShort ? GAP_KEEP : gap;
+  gaps.push({after: i - 1, was: Number(gap.toFixed(2)), becomes: Number(target.toFixed(2)), keptAsBeat: target === gap && gap > GAP_MAX});
 }
 
-/* ----------------------------------------------------------------- verification
- * Run on the transcript the cut WILL have, worked out from the spans kept, so there is no
- * second transcription and no waiting. Every one of these must pass; a build that fails here
- * is a build that would have sent someone to CapCut. */
-
-const outWords = [...keptIndexes].sort((a, b) => a - b).map((i) => words[i]);
-const outKeys = outWords.map((w) => key(w.word)).filter(Boolean);
-
-const N = 4;
-
-/**
- * How often the SCRIPT says each phrase.
- *
- * "go to the code tab" appears twice in this script on purpose, and so does "I like how the".
- * Flagging every repeated phrase would report both as stutters. A repeat is only a fault when
- * the cut says something more often than the script does.
- */
-const scriptGrams = new Map();
-{
-  const sk = atoms.flatMap((a) => keysOf(a));
-  for (let i = 0; i + N <= sk.length; i++) {
-    const gram = sk.slice(i, i + N).join(' ');
-    scriptGrams.set(gram, (scriptGrams.get(gram) ?? 0) + 1);
-  }
-}
+const dropped = [...drop].sort((a, b) => a - b).map((i) => ({
+  from: Number(units[i].from.toFixed(2)),
+  to: Number(units[i].to.toFixed(2)),
+  reason: abandoned.has(i) ? 'announced-retake' : 'retake',
+  text: units[i].text.slice(0, 110),
+}));
 
-const repeats = [];
-const seen = new Map();
-for (let i = 0; i + N <= outKeys.length; i++) {
-  const gram = outKeys.slice(i, i + N).join(' ');
-  const at = outWords[i].start;
-  const previous = seen.get(gram) ?? [];
-  if (previous.length >= (scriptGrams.get(gram) ?? 0) && previous.some((t) => at - t < 20)) {
-    repeats.push({gram, first: Number(previous[previous.length - 1].toFixed(2)), again: Number(at.toFixed(2))});
+/* ----------------------------------------------------------------- verification */
+
+const survivors = kept;
+const stillAlike = [];
+for (let i = 0; i < survivors.length; i++) {
+  for (let j = i + 1; j < survivors.length; j++) {
+    if (survivors[j].from - survivors[i].to > WINDOW) break;
+    if (similarity(survivors[i], survivors[j]) >= SIMILAR) {
+      stillAlike.push({
+        a: Number(survivors[i].from.toFixed(2)),
+        b: Number(survivors[j].from.toFixed(2)),
+        text: survivors[j].text.slice(0, 70),
+      });
+    }
   }
-  seen.set(gram, [...previous, at]);
 }
 
-const survivingFiller = outWords.filter((w) => FILLER.has(key(w.word))).map((w) => ({
-  word: w.word,
-  at: Number(w.start.toFixed(2)),
-}));
-
+const keptSeconds = keep.reduce((a, k) => a + (k.to - k.from), 0);
+const sourceSeconds = words[words.length - 1].end - words[0].start;
 const checks = {
-  everyAtomPlaced: missing.length === 0,
-  noRepeatedPhrase: repeats.length === 0,
-  fillerLeftInside: survivingFiller.length,
-  atoms: atoms.length,
-  placed: atoms.length - missing.length,
-  keptSeconds: Number(keep.reduce((a, k) => a + (k.to - k.from), 0).toFixed(2)),
-  sourceSeconds: Number((words[words.length - 1].end - words[0].start).toFixed(2)),
+  noRepeatsLeft: stillAlike.length === 0,
+  units: units.length,
+  retakeGroups: groups.length,
+  unitsDropped: drop.size,
+  spans: keep.length,
+  keptSeconds: Number(keptSeconds.toFixed(2)),
+  sourceSeconds: Number(sourceSeconds.toFixed(2)),
+  energyScored: medianRms != null,
 };
 
 /* ---------------------------------------------------------------------- output */
 
-const stem = basename(wordsPath).replace(/\.words\.json$|\.json$/, '');
+const stem = basename(wordsPath).replace(/\.?words\.json$|\.json$/, '') || 'take';
 const project = flag('project', null);
-const outPath =
-  flag('out', null) ??
-  (project ? join('work', project, `${stem}.takes.json`) : join(dirname(wordsPath), `${stem}.takes.json`));
+const outPath = flag('out', null) ?? (project ? join('work', project, `${stem}.takes.json`) : join(dirname(wordsPath), `${stem}.takes.json`));
 mkdirSync(dirname(outPath), {recursive: true});
-
-writeFileSync(
-  outPath,
-  JSON.stringify(
-    {
-      fps: FPS,
-      gapKeep: GAP_KEEP,
-      checks,
-      keep,
-      dropped,
-      repeats,
-      missing,
-      atoms: atoms.map((text, i) => ({
-        text,
-        chosen: chosen[i] ? {from: chosen[i].from, to: chosen[i].to, coverage: Number(chosen[i].coverage.toFixed(2))} : null,
-        attempts: takesPerAtom[i].length,
-      })),
-    },
-    null,
-    2,
-  ),
-);
-
-const pct = ((checks.keptSeconds / checks.sourceSeconds) * 100).toFixed(0);
-console.log(`${outPath}`);
-console.log(`  ${checks.placed}/${checks.atoms} script sentences placed`);
-console.log(`  ${checks.keptSeconds}s kept of ${checks.sourceSeconds}s (${pct}%)`);
-console.log(`  ${dropped.filter((d) => d.reason === 'retake').length} retakes, ${dropped.filter((d) => d.reason === 'off-script').length} off-script, ${dropped.filter((d) => d.reason === 'filler').length} filler dropped`);
-
-let failed = false;
-if (!checks.everyAtomPlaced) {
-  failed = true;
-  console.error(`\n${missing.length} script sentence(s) have no usable take:`);
-  for (const m of missing.slice(0, 10)) console.error(`  - "${m.text.slice(0, 70)}" (${m.attempts} attempts found)`);
-  console.error('  Re-record these lines, or re-run with --loose to lower the match threshold.');
+writeFileSync(outPath, JSON.stringify({fps: FPS, gapMax: GAP_MAX, gapKeep: GAP_KEEP, pad: PAD, checks, keep, gaps, groups: groupReport, dropped, scriptMissing}, null, 2));
+
+console.log(outPath);
+console.log(`  ${checks.units} units, ${checks.retakeGroups} retake group(s), ${checks.unitsDropped} dropped`);
+console.log(`  ${checks.keptSeconds}s kept of ${checks.sourceSeconds}s (${((keptSeconds / sourceSeconds) * 100).toFixed(0)}%) in ${checks.spans} span(s)`);
+console.log(`  energy scoring: ${checks.energyScored ? 'on' : 'off (pass --media to enable)'}`);
+if (groupReport.length) {
+  console.log('\n  retakes dropped:');
+  for (const g of groupReport.slice(0, 8)) {
+    for (const d of g.dropped) console.log(`    ${String(d.at).padStart(7)}s  "${d.text}"`);
+  }
 }
-if (repeats.length) {
-  failed = true;
-  console.error(`\n${repeats.length} phrase(s) still repeat in the cut:`);
-  for (const r of repeats.slice(0, 10)) console.error(`  - "${r.gram}" at ${r.first}s and again at ${r.again}s`);
+const beats = gaps.filter((g) => g.keptAsBeat).length;
+if (beats) console.log(`\n  ${beats} long pause(s) kept as deliberate beats before a short line.`);
+if (scriptPath) {
+  console.log(`\n  script check: ${scriptMissing.length} line(s) never said`);
+  for (const m of scriptMissing.slice(0, 6)) console.log(`    - "${m.text.slice(0, 68)}"`);
 }
-if (survivingFiller.length) {
-  console.log(`\n  ${survivingFiller.length} filler word(s) kept inside winning takes — left in on purpose.`);
+if (stillAlike.length) {
+  console.error(`\n${stillAlike.length} near-duplicate(s) still in the cut:`);
+  for (const s of stillAlike.slice(0, 8)) console.error(`  ${s.a}s and ${s.b}s — "${s.text}"`);
+  process.exit(1);
 }
-
-if (failed && !has('loose')) process.exit(1);