creator-editing-studio 1.3.1 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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

@@ -134,6 +134,51 @@ The plan is there to save them a rebuild, not to put a form in front of them.
 The failure this is guarding against is a whole edit rendered the wrong way. Anything that does
 not risk that should move fast.
 
+## What makes motion read as expensive
+
+The twelve motion laws stop an edit looking broken. These seven are what separate motion that
+looks competent from motion that looks paid for. They were taken from studying reference edits
+frame by frame, and they apply to UI, graphics and footage alike.
+
+**1. Blur anything that moves fast.** In the edits that feel most expensive, nothing travels
+sharp. An element crossing the frame in six frames should be a smear that only resolves as it
+slows — and that includes digits rolling from one number to another, and a line redrawing on a
+chart. Sharp fast motion is the single clearest tell of cheap animation, because real cameras and
+real eyes do not work that way. Use the velocity blur helpers rather than deciding per element.
+
+**2. Morph, don't replace.** When something becomes something else, animate the thing itself
+rather than fading one out and another in. A row that is clicked and confirmed should stretch and
+turn into the confirmation; it should not be covered by a new element that happens to sit in the
+same place. An element that exists in two moments travels between them. This is the law that most
+reliably makes a sequence feel connected rather than assembled.
+
+**3. Overshoot, then settle.** Things that arrive exactly at their final size and stop look
+pasted on. Let an arrival come in slightly too large, or slightly past its mark, and ease back.
+The overshoot is small — a few per cent — and it is the difference between landing and being
+placed.
+
+**4. Animate the data, not the container.** When a value, a chart or a list changes, hold the
+frame still and change only what actually changed. Re-entering the whole panel to show a new
+number throws away the viewer's orientation and makes the change read as a new scene instead of
+an update.
+
+**5. Reveal one thing at a time.** Rows, cards, icons and bullets arrive in reading order with a
+few frames between them, never as a group. If a container also needs to grow, grow it slowly
+underneath while the contents arrive — two speeds, not one.
+
+**6. Earn the hard cut.** In a piece built from continuous motion, a single hard cut to a flat
+colour lands hard precisely because it is the only one. Bursts of hard cuts are their own beat
+and work too, but mixing the two at random wastes both. Decide which the piece is.
+
+**7. Show what is coming.** Small anticipations make an interface feel alive: text typing into a
+pill that grows with it, with the next word already faintly present; a cursor that starts moving
+before the thing it will click appears. The viewer reads intent, not just motion.
+
+A note on where these come from. Every one of them was found by studying an edit frame by frame
+and writing down what it actually did — not by reading about animation. When something looks good
+to you, save the clip and the timecode and do the same. That habit is worth more than any list,
+including this one.
+
 ## Verify the render before you call it done
 
 You have not seen the video. The timeline in your head is not evidence. Before you say an
@@ -180,6 +225,14 @@ is the thing most likely to be wrong, not them. Three rules, learned the hard wa
 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.
 
+**A transcript is not evidence.** Whisper suppresses repeated phrases: when someone says a line
+twice it transcribes it once and stretches the last recognised word across the speech it dropped,
+so the transcript reads clean while the audio plainly repeats. Run `node scripts/coverage.mjs
+<media> <words.json>` after every transcription and before planning anything — it flags any word
+far longer than the median, and any stretch above the noise floor with no word on it. Both mean
+the transcript is hiding speech. Check the energy across the flagged word: one decaying word is
+fine, a dip to silence followed by a second loud onset is a repeat.
+
 **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

package/template/scripts/coverage.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Find speech the transcriber did not transcribe.
+ *
+ *   node scripts/coverage.mjs <media> <words.json> [--gap 0.35] [--floor -38]
+ *
+ * WHY THIS EXISTS. Whisper suppresses repeated phrases. When a speaker says the same line twice,
+ * it transcribes it once and silently leaves a hole where the duplicate was — so a transcript can
+ * read perfectly clean while the audio plainly repeats. On demo-test that cost four rounds: the
+ * owner said three times that "adds a few zooms" repeated, the transcript said it did not, and the
+ * hole got mistaken for a pause and trimmed.
+ *
+ * A transcript is not evidence on its own. This checks it against the audio: any stretch that is
+ * loud enough to be speech but carries no word is either a dropped duplicate or a dropped line,
+ * and both are faults. Run it after every transcription, before planning anything.
+ */
+import {spawnSync} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {FFMPEG} from './lib/media.mjs';
+
+const [, , media, wordsFile, ...rest] = process.argv;
+if (!media || !wordsFile) {
+  console.error('Usage: node scripts/coverage.mjs <media> <words.json> [--gap 0.35] [--floor -38]');
+  process.exit(2);
+}
+const opt = (n, d) => {
+  const i = rest.indexOf(`--${n}`);
+  return i >= 0 ? Number(rest[i + 1]) : d;
+};
+/** Shortest unlabelled speech run worth reporting, in seconds. */
+const MIN_GAP = opt('gap', 0.35);
+/** Above this RMS it is speech, below it is room tone. */
+const FLOOR_DB = opt('floor', -38);
+
+const SR = 16000;
+const WIN = Math.round(SR * 0.05);
+
+const pcm = spawnSync(FFMPEG, ['-v', 'error', '-i', media, '-vn', '-ac', '1', '-ar', String(SR), '-f', 's16le', '-'], {
+  encoding: 'buffer',
+  maxBuffer: 1 << 28,
+});
+if (pcm.status !== 0) {
+  console.error(pcm.stderr?.toString().slice(0, 600));
+  process.exit(1);
+}
+const buf = pcm.stdout;
+const samples = buf.length / 2;
+
+const loud = (t) => {
+  const a = Math.round(t * SR);
+  let s = 0;
+  let c = 0;
+  for (let i = a; i < a + WIN && i < samples; i++) {
+    const v = buf.readInt16LE(i * 2);
+    s += v * v;
+    c++;
+  }
+  const r = Math.sqrt(s / Math.max(1, c));
+  return r > 0 ? 20 * Math.log10(r / 32768) : -99;
+};
+
+const data = JSON.parse(readFileSync(wordsFile, 'utf8'));
+const words = data.words ?? data;
+const fps = data.fps ?? 30;
+/** Words may carry frames (f/t) or seconds (start/end). */
+const spans = words.map((w) => ({
+  from: w.start ?? w.f / fps,
+  to: w.end ?? (w.t ?? w.f) / fps,
+}));
+
+const covered = (t) => spans.some((s) => t >= s.from - 0.06 && t <= s.to + 0.06);
+
+const duration = samples / SR;
+const holes = [];
+let run = null;
+for (let t = 0; t < duration; t += 0.05) {
+  const speech = loud(t) > FLOOR_DB;
+  if (speech && !covered(t)) {
+    if (!run) run = {from: t, to: t};
+    else run.to = t;
+  } else if (run) {
+    if (run.to - run.from >= MIN_GAP) holes.push(run);
+    run = null;
+  }
+}
+if (run && run.to - run.from >= MIN_GAP) holes.push(run);
+
+/**
+ * The detector that actually works.
+ *
+ * A collapsed duplicate does not leave an untranscribed hole — Whisper stretches the LAST word it
+ * did recognise across the speech it dropped. On demo-test the word "adds" came back 0.68s long
+ * with the lowest confidence in the sentence, covering a whole repeated phrase, so a coverage test
+ * based on spans called the file clean. Word duration is what gives it away.
+ */
+const lengths = words.map((w, i) => ({w, i, dur: spans[i].to - spans[i].from})).filter((x) => x.dur > 0);
+const sortedDur = lengths.map((x) => x.dur).sort((a, b) => a - b);
+const median = sortedDur[Math.floor(sortedDur.length / 2)] || 0.2;
+const stretched = lengths.filter((x) => x.dur > median * 3);
+if (stretched.length) {
+  console.log(
+    `${stretched.length} word(s) far longer than the ${median.toFixed(2)}s median — ` +
+      `each may be covering speech the transcriber dropped:\n`,
+  );
+  for (const x of stretched) {
+    const label = x.w.w ?? x.w.word;
+    console.log(
+      `  "${label}" ${spans[x.i].from.toFixed(2)}s - ${spans[x.i].to.toFixed(2)}s = ` +
+        `${x.dur.toFixed(2)}s (${(x.dur / median).toFixed(1)}x median)`,
+    );
+  }
+  console.log('\nCheck the energy across each one. A single decaying word is fine; a dip to');
+  console.log('silence followed by a second loud onset is a repeat the transcript is hiding.');
+}
+
+if (!holes.length && !stretched.length) {
+  console.log(`clean — every stretch above ${FLOOR_DB}dB has a word on it (${words.length} words, ${duration.toFixed(2)}s)`);
+  process.exit(0);
+}
+
+if (!holes.length) process.exit(1);
+
+console.log(`${holes.length} stretch(es) of SPEECH WITH NO WORDS — the transcript is missing something:\n`);
+for (const h of holes) {
+  const before = spans.filter((s) => s.to <= h.from).pop();
+  const after = spans.find((s) => s.from >= h.to);
+  const bw = before ? words[spans.indexOf(before)] : null;
+  const aw = after ? words[spans.indexOf(after)] : null;
+  console.log(
+    `  ${h.from.toFixed(2)}s - ${h.to.toFixed(2)}s  (${(h.to - h.from).toFixed(2)}s)` +
+      `  between "${bw ? bw.w ?? bw.word : 'start'}" and "${aw ? aw.w ?? aw.word : 'end'}"`,
+  );
+}
+console.log('\nMost likely a repeated phrase the transcriber collapsed. Listen to it before cutting it.');
+process.exit(1);

package/template/scripts/refs.mjs

@@ -7,7 +7,7 @@
  *   npm run refs -- --all   redo every sheet
  *
  * Reads entries shaped like:
- *   ## 4. `farza.mp4` — Farza
+ *   ## 4. `clip-name.mp4` — Creator name
  *   - **00:11–00:14** — what happens...
  * Writes work/refs/<clip>-<mm.ss>-<mm.ss>.jpg and work/refs/INDEX.md (moment -> sheet), and lists
  * clips that are in the folder but have no entry yet, or entries whose clip is missing.

package/template/src/components/CommandCard.tsx

@@ -205,7 +205,7 @@ export const CONNECT_SEGMENTS: Segment[] = [
   {kind: 'plain', text: 'claude mcp add '},
   {kind: 'flag', text: '--scope user --transport http '},
   {kind: 'accent', text: 'creator-editing-os'},
-  {kind: 'plain', text: ' https://creator-editing-os.mahipal-231.workers.dev/mcp/'},
+  {kind: 'plain', text: ' <your connector URL>'},
   {kind: 'redacted', text: 'XXXX-XXXX-XXXX-XXXX'},
 ];