ossclip 0.1.18 → 0.1.20

package/src/produce.ts

@@ -15,7 +15,6 @@ import {
   applyOverrides,
   applyRepairs,
   assembleScenes,
-  applyCaptionEdits,
   buildCaptionLines,
   buildCutlist,
   buildZoomPlan,
@@ -99,12 +98,15 @@ import {
 } from "@ossclip/core";
 import { recordRecentProject } from "./edit";
 import { binOnPath, detectionLine } from "./llm-detect";
+import { PhaseTimer, formatPhaseLine, type PhaseTimings } from "./phase-timing";
 import {
   strandedOverrideSiblings,
   strandedPointerLine,
   workdirBaseName,
 } from "./stranded-overrides";
 import { editHint } from "./interactive/edit-hint";
+import { reconcileCaptionEdits } from "./caption-report";
+import { overridesWriteLine, writeOverrideDoc } from "./overrides-write";
 import { recordedProduceArgs } from "./replay-argv";
 import { renderCover, renderProduction } from "@ossclip/renderer";
 import {
@@ -133,6 +135,13 @@ export interface ProduceResult {
   sceneCount: number;
   /** Resolved provider name when the LLM ran; undefined without --produce. */
   llmProvider?: string;
+  /**
+   * Milliseconds per attributed phase (FINDINGS §140) — same contract as the
+   * fields above: produce() surfaces the raw numbers, the command layer
+   * buckets them before anything crosses the wire (`phaseBucketProps`). A
+   * phase that never ran (cached transcript, --no-render) is absent, not 0.
+   */
+  phaseTimings: PhaseTimings;
 }
 
 /**
@@ -531,6 +540,10 @@ async function preflight(bin: string, hint: string): Promise<void> {
 }
 
 export async function produce(inputArg: string, opts: ProduceOptions): Promise<ProduceResult> {
+  // First line on purpose: totalMs is the same wall clock program.ts wraps
+  // around this call for duration_ms, so `other` in the printed breakdown is
+  // genuinely "everything this run did that isn't an attributed phase" (§140).
+  const phases = new PhaseTimer();
   const cfg = loadConfig();
   // `let`, not `const`: a folder input is reassigned to the concat
   // intermediate below (folder-input-brief.md) so nothing past that point has
@@ -640,10 +653,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
 
   if (isFolder && folderListing) {
     const sort = opts.sort ?? "name";
-    const result = await concatFolder(tools, input, folderListing, work, sort, {
-      w: frame.width,
-      h: frame.height,
-    });
+    const result = await phases.time("ffmpeg", () =>
+      concatFolder(tools, input, folderListing!, work, sort, {
+        w: frame.width,
+        h: frame.height,
+      }),
+    );
     console.log(
       `▸ folder: ${result.clips.length} clip(s), sorted by ${sort}, ` +
         `concat ${result.durationSec.toFixed(1)}s${result.cached ? " (cached)" : ""}`,
@@ -757,14 +772,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       );
     }
     console.log(`▸ transcribing (${basename(modelPath)})…`);
-    transcript = await runWhisper(
-      {
-        whisperPath: cfg.whisperPath,
-        modelPath,
-        outBase: join(work, "whisper"),
-        language: opts.whisperLanguage,
-      },
-      audioPath,
+    transcript = await phases.time("transcribe", () =>
+      runWhisper(
+        {
+          whisperPath: cfg.whisperPath,
+          modelPath,
+          outBase: join(work, "whisper"),
+          language: opts.whisperLanguage,
+        },
+        audioPath,
+      ),
     );
     console.log(`▸ transcribed ${transcript.words.length} words`);
     await writeFile(transcriptKeyPath, JSON.stringify(requestedKey, null, 2));
@@ -900,14 +917,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       ).transcript;
       console.log(`▸ repairs cached (${repairs.filter((r) => r.applied).length})`);
     } else {
-      const result = await repairTranscript(provider, rawTranscript, {
-        speaker: opts.speaker ?? cfg.speaker,
-        // A repair may not merge words across a cut.
-        isCut: (startSec, endSec) =>
-          cutlist.some(
-            (s) => s.kind === "remove" && s.srcIn < endSec && s.srcOut > startSec,
-          ),
-      });
+      const result = await phases.time("llm", () =>
+        repairTranscript(provider!, rawTranscript, {
+          speaker: opts.speaker ?? cfg.speaker,
+          // A repair may not merge words across a cut.
+          isCut: (startSec, endSec) =>
+            cutlist.some(
+              (s) => s.kind === "remove" && s.srcIn < endSec && s.srcOut > startSec,
+            ),
+        }),
+      );
       transcript = result.transcript;
       repairs = result.applied;
       if (result.error) {
@@ -1054,16 +1073,18 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         console.log("▸ clip window cached");
       } else {
         console.log(`▸ selecting the strongest ~${clipTargetSec}s window (${providerName})…`);
-        clipFresh = await produceScenes(provider, {
-          transcript,
-          outputDuration: clipTargetSec,
-          intent: opts.intent,
-          speaker: opts.speaker ?? cfg.speaker,
-          forceComponent: opts.forceComponent,
-          framing: framingCtx,
-          clip: { targetSec: clipTargetSec },
-          aspect: landscape ? "16:9" : "9:16",
-        });
+        clipFresh = await phases.time("llm", () =>
+          produceScenes(provider!, {
+            transcript,
+            outputDuration: clipTargetSec!,
+            intent: opts.intent,
+            speaker: opts.speaker ?? cfg.speaker,
+            forceComponent: opts.forceComponent,
+            framing: framingCtx,
+            clip: { targetSec: clipTargetSec! },
+            aspect: landscape ? "16:9" : "9:16",
+          }),
+        );
         clipWindow = clipFresh.clip!.window;
         for (const note of clipFresh.clip!.notes) console.log(`  ▸ ${note}`);
         await writeFile(clipWindowCache, JSON.stringify(clipWindow, null, 2));
@@ -1179,15 +1200,17 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     } else {
       console.log(`▸ producing scenes (${providerName})…`);
       if (opts.forceComponent) console.log(`▸ forcing every graphic to ${opts.forceComponent}`);
-      const result = await produceScenes(provider, {
-        transcript,
-        outputDuration: map.outputDuration,
-        intent: opts.intent,
-        speaker: opts.speaker ?? cfg.speaker,
-        forceComponent: opts.forceComponent,
-        framing: framingCtx,
-        aspect: landscape ? "16:9" : "9:16",
-      });
+      const result = await phases.time("llm", () =>
+        produceScenes(provider!, {
+          transcript,
+          outputDuration: map.outputDuration,
+          intent: opts.intent,
+          speaker: opts.speaker ?? cfg.speaker,
+          forceComponent: opts.forceComponent,
+          framing: framingCtx,
+          aspect: landscape ? "16:9" : "9:16",
+        }),
+      );
       scenes = result.scenes;
       beatSheet = { hook: result.beatSheet.hook, coverText: result.beatSheet.coverText };
       console.log(`▸ hook: ${result.beatSheet.hook}`);
@@ -1595,7 +1618,8 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     clipStarts: map.spans.map((s) => s.outIn),
   });
   // User splits (R16 §61) — after the fill so takes split like scenes, and
-  // before the final override pass so edits on the `id@ms` halves land. A
+  // before the final override pass so edits on the `id@<split id>` halves land
+  // (the suffix is the split's own minted id, §137, not its time). A
   // split whose ROOT was a graphic scene already happened once inside
   // `splitThenDropHidden` above (PLAN 2026-08-04 Task 1) — re-running it here
   // is a no-op for that scene (the split point sits exactly on the joint
@@ -1607,7 +1631,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   }
   const { cues: mergedCues, orphans: rawOrphans } = applyOverrides(split, overrideDoc);
   // Halves of a TAKE the user deleted after splitting: a take id only exists
-  // once the fill above runs, so its `id@ms` half couldn't have been seen by
+  // once the fill above runs, so its `id@<split id>` half couldn't have been seen by
   // `splitThenDropHidden` earlier (that pass only ever saw graphic scenes).
   // Scene halves were already caught above; this is a no-op for them. Same
   // order as the editor's live memo.
@@ -1931,22 +1955,36 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // caption output for zero visual reason (PLAN Task A4.4).
     breakpoints: graphicCues.flatMap((c) => [c.startSec, c.endSec]),
   });
-  // The user's retyped caption words (editor, PLAN 2026-07-29 Task 7 scope
-  // (a)). Guarded per word: a stale edit — the pipeline re-derived a
-  // different word at that position — is dropped LOUDLY, never applied to
-  // the wrong word and never silently forgotten.
-  const { lines: captionLines, dropped: staleCaptionEdits } = applyCaptionEdits(
-    baseCaptionLines,
-    overrideDoc.captions,
-  );
-  const liveCaptionEdits = Object.keys(overrideDoc.captions).length - staleCaptionEdits.length;
-  if (liveCaptionEdits > 0) console.log(`▸ ${liveCaptionEdits} caption word(s) retyped by the editor`);
-  for (const d of staleCaptionEdits) {
-    console.log(
-      `  ⚠ caption edit at word ${d.index} dropped: expected "${d.expected}" there, ` +
-        `the transcript now has "${d.found}"`,
-    );
-  }
+  // §137 (Task 6 review, Critical 1): the caption half of a run — migrate the
+  // doc's keys, apply what applies, and account for the rest — is one pure
+  // pass in `caption-report.ts`, and this is its I/O.
+  //
+  // MIGRATION RUNS HERE, not only in the editor. The editor's is in memory and
+  // `edits.load` leaves the doc CLEAN, so `onRender` (which saves only when
+  // dirty) sends a user who opened an old project, saw every retype come back
+  // on screen, and clicked Render straight into this function with the
+  // untouched legacy doc — and `applyCaptionEdits` matched nothing, so the
+  // render shipped without a single retype after showing a state strictly more
+  // convincing than the truth. None of the reasoning that keeps this call out
+  // of `edit.ts` applies: `buildCaptionLines` just stamped a real `srcStart`
+  // on every word above (`captions.ts:128`), so there is nothing to backfill
+  // and no repair rule to duplicate.
+  //
+  // THE MIGRATED DOC IS WRITTEN BACK — the decision, stated: through the one
+  // sanctioned `overrides.json` write further down, with its `.bak` and atomic
+  // rename, never a second write here. A legacy key's resolvability DECAYS (it
+  // is found by the word it names, so the next re-plan that rewrites that word
+  // loses it for good), and this is the only durable repair in the product —
+  // the editor's evaporates, as Critical 1 showed. The edits it could NOT
+  // place stay in the doc regardless (`captionEditsToKeep`): they are printed
+  // by name below, and a run that cannot anchor one today is not permission to
+  // delete it — the next run, against a different cut, may place it (final
+  // review, Critical 1).
+  const captionWork = reconcileCaptionEdits(overrideDoc, baseCaptionLines);
+  overrideDoc = captionWork.doc;
+  const captionLines = captionWork.lines;
+  const captionKeysReanchored = captionWork.reanchored;
+  for (const line of captionWork.log) console.log(line);
 
   // Micro zoom punches (FINDINGS §15) reversing at real phrase breaks (§18).
   // Breaths are source-time; TimeMap has no span mapper, so both ends go
@@ -2185,26 +2223,38 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // next run's `priorMap` then sees drift and re-anchors again, the same
   // recovery path finding 3 already has to support — never a false "nothing
   // changed" that quietly corrupts positions.
-  if (cutResult.changed) {
-    // Keep a `.bak` of whatever was on disk first — the same safety net
-    // `saveConfigPatch` keeps for a config file it's about to replace —
-    // before overwriting the user's own data. Atomic write via tmp+rename,
-    // matching the edit server's own `PUT /overrides` handler: the producer
-    // or a live editor session may read this file at any moment, and a
-    // half-written document would be worse than a stale one.
-    try {
-      const raw = await readFile(overridesPath, "utf8");
-      await writeFile(`${overridesPath}.bak`, raw);
-    } catch {
-      // Nothing on disk to back up (first cut ever applied here) — fine.
-    }
-    const tmp = `${overridesPath}.tmp`;
-    await writeFile(tmp, JSON.stringify(overrideDoc, null, 2));
-    await rename(tmp, overridesPath);
-    console.log("▸ overrides.json re-anchored to the new cut and saved (previous copy kept as .bak)");
+  // `cutResult.changed` OR a §137 caption-key migration that actually MOVED an
+  // edit — the second is why this is no longer a bare cut check. Both are
+  // re-anchorings of the user's doc to something the pipeline just recomputed,
+  // and both go through the one sanctioned write; a separate write for the
+  // migration would be a SECOND sanctioned write, which the comment above
+  // exists to prevent.
+  //
+  // "ACTUALLY MOVED" is load-bearing and was not there at first (final review,
+  // Critical 2). Gated on "the migration reported something" instead, this
+  // fires on a run that repaired NOTHING — and since a caption migration is
+  // independent of the cut, it fires on runs where the pre-§137 gate wrote
+  // nothing at all.
+  //
+  // THEY DO NOT SHARE THE `.bak`, THOUGH, and that is the rest of the same
+  // finding (final review round 2). `refreshBackup: cutResult.changed`, never
+  // the gate: on the field workdir the caption migration re-anchors THREE
+  // edits, so the gate legitimately fires while `cutResult.changed` is false —
+  // and an unconditional refresh would then copy the already-damaged
+  // `overrides.json` over `overrides.json.bak`, which is that user's only
+  // pre-cut save and the only artefact their deleted split half can still be
+  // recovered from (`legacySplitId`). Repairing the captions would destroy the
+  // evidence for the split. `writeOverrideDoc` carries the full argument for
+  // why a caption-only write has nothing worth backing up.
+  if (cutResult.changed || captionKeysReanchored) {
+    await writeOverrideDoc(overridesPath, overrideDoc, { refreshBackup: cutResult.changed });
+    console.log(overridesWriteLine(cutResult.changed));
   }
 
   if (!opts.render) {
+    // §140: the breakdown goes above the closing lines on both exits, so the
+    // last thing on screen stays the success line and the edit hint.
+    console.log(formatPhaseLine(phases.timings(), phases.totalMs()));
     console.log(`▸ skipping render (--no-render). Props at ${join(work, "render-props.json")}`);
     console.log(editHint(work));
     return {
@@ -2213,6 +2263,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       sourceDurationSec: sourceProbe.duration,
       sceneCount: scenes.length,
       llmProvider: provider ? providerName : undefined,
+      phaseTimings: phases.timings(),
     };
   }
 
@@ -2220,21 +2271,23 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   const rawPath = join(work, "render-raw.mp4");
   console.log("▸ rendering…");
   let lastPct = -10;
-  await renderProduction(props, {
-    publicDir: dirname(renderVideo),
-    outPath: rawPath,
-    browserExecutable: cfg.browserExecutable,
-    onProgress: (p) => {
-      const pct = Math.floor(p * 100);
-      if (pct >= lastPct + 10) {
-        lastPct = pct;
-        process.stdout.write(`  ${pct}%\n`);
-      }
-    },
-  });
+  await phases.time("render", () =>
+    renderProduction(props, {
+      publicDir: dirname(renderVideo),
+      outPath: rawPath,
+      browserExecutable: cfg.browserExecutable,
+      onProgress: (p) => {
+        const pct = Math.floor(p * 100);
+        if (pct >= lastPct + 10) {
+          lastPct = pct;
+          process.stdout.write(`  ${pct}%\n`);
+        }
+      },
+    }),
+  );
   console.log("▸ normalizing loudness…");
   const normPath = join(work, "render-norm.mp4");
-  await loudnorm(tools, rawPath, normPath);
+  await phases.time("ffmpeg", () => loudnorm(tools, rawPath, normPath));
   await rename(normPath, outPath);
 
   // ---- Cover image (FINDINGS §31) -----------------------------------------
@@ -2394,6 +2447,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // Every produce run is a project the picker should offer (R17 §83) —
   // best-effort, so a read-only home dir never fails the render.
   await recordRecentProject(work);
+  // §140, same placement as the --no-render exit: breakdown, then the
+  // success line and the hint keep the bottom of the screen.
+  console.log(formatPhaseLine(phases.timings(), phases.totalMs()));
   console.log(`✓ done → ${outPath}`);
   console.log(editHint(work));
   return {
@@ -2403,5 +2459,6 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     sourceDurationSec: sourceProbe.duration,
     sceneCount: scenes.length,
     llmProvider: provider ? providerName : undefined,
+    phaseTimings: phases.timings(),
   };
 }

package/src/program.ts

@@ -6,6 +6,8 @@ import { z } from "zod/v4";
 import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
+import { ExportFormatSchema, runAnalyse } from "./analyse";
+import { phaseBucketProps } from "./phase-timing";
 import { produce } from "./produce";
 // The one interactive import that is STATIC rather than `await import()`: the
 // `resetInputSource()` run boundary in `buildProgram` has to run synchronously
@@ -461,6 +463,11 @@ export function buildProgram(): Command {
           render: opts.render !== false,
           source_duration_bucket: durationBucket(result.sourceDurationSec),
           scenes: result.sceneCount,
+          // Per-phase buckets (§140), one `<phase>_bucket` per phase that
+          // ran — bucketed in phaseBucketProps, never raw ms. Spread keys are
+          // invisible to telemetry.test.ts's source-text drift check, so the
+          // §134 pin for these lives in phase-timing.test.ts instead.
+          ...phaseBucketProps(result.phaseTimings),
           // Which branch of the input prompt was used — a branch name, never
           // the path itself (§136). The picker exists because typing a path
           // blocked non-technical users; this is how we find out if it helped.
@@ -528,6 +535,78 @@ export function buildProgram(): Command {
       await telemetry.flush();
     });
 
+  program
+    .command("analyse")
+    .alias("analyze")
+    .description(
+      "analyse a take and export the planned cuts as labelled NLE markers — no render, no LLM " +
+        "(FCPXML imports into Resolve and Premiere; review the markers, then cut in your own editor)",
+    )
+    .argument("<input>", "input video file (or a folder of clips)")
+    .option("--format <format>", "export format: fcpxml", "fcpxml")
+    .option("--out <path>", "export file path (default: <input>.<format>)")
+    .option("--cleanup <level>", "exact | light | standard | aggressive", "standard")
+    .option("--transcript <path>", "inject a transcript JSON instead of running whisper")
+    .option("--noise-db <db>", "override the measured silence threshold, e.g. -30", parseFloat)
+    .option("--workdir <dir>", "cache/work directory")
+    .option("--whisper-model <name>", "transcription model for this run, e.g. base.en | small.en")
+    .option(
+      "--whisper-language <code>",
+      "transcription language code for a multilingual model, e.g. ur | de | auto (whisper defaults to en)",
+    )
+    .option(
+      "--blooper-marker <word>",
+      "mark the flubbed take wherever you say this word out loud (e.g. blooper). Off unless given",
+    )
+    .option(
+      "--collapse-retakes",
+      "also mark consecutive near-identical sentences, keeping only the last complete attempt",
+      false,
+    )
+    .option("--sort <order>", "folder input: clip order, name | mtime", "name")
+    .action(async (input: string, opts, command) => {
+      const cleanup = CleanupLevelSchema.parse(opts.cleanup);
+      // Same parse-don't-coerce guard as --source-fit: a typo'd format must
+      // error naming the flag, never silently export a different file.
+      const format = ExportFormatSchema.parse(opts.format);
+      try {
+        const result = await runAnalyse(input, {
+          cleanup,
+          format,
+          out: opts.out,
+          transcript: opts.transcript,
+          workdir: opts.workdir,
+          noiseDb: opts.noiseDb,
+          whisperModel: opts.whisperModel,
+          whisperLanguage:
+            opts.whisperLanguage !== undefined
+              ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
+              : undefined,
+          blooperMarker: opts.blooperMarker,
+          collapseRetakes: opts.collapseRetakes,
+          sort: opts.sort === "mtime" ? "mtime" : "name",
+          sortExplicit: command.getOptionValueSource("sort") === "cli",
+        });
+        // Counts, buckets and names only (§134) — the format is an enum name,
+        // never a path; per-phase buckets ride along like produce's.
+        telemetry.record("analyse_completed", {
+          format,
+          cleanup_level: cleanup,
+          source_duration_bucket: durationBucket(result.sourceDurationSec),
+          markers: result.markerCount,
+          ...phaseBucketProps(result.phaseTimings),
+        });
+      } catch (err) {
+        // Constructor name only, like produce_failed: messages quote paths.
+        telemetry.record("analyse_failed", {
+          error_class: err instanceof Error ? err.constructor.name : "NonError",
+        });
+        throw err;
+      } finally {
+        await telemetry.flush();
+      }
+    });
+
   program
     .command("studio")
     .description("open Remotion Studio on a produced composition (visual debugging)")

package/editor-dist/assets/index-C8IPo60X.css

@@ -1 +0,0 @@
-.ossclip-scroll-list{scrollbar-width:thin;scrollbar-color:#3a3a44 transparent}.ossclip-scroll-list::-webkit-scrollbar{width:8px}.ossclip-scroll-list::-webkit-scrollbar-track{background:transparent}.ossclip-scroll-list::-webkit-scrollbar-thumb{background:#3a3a44;border-radius:4px}