ossclip 0.1.19 → 0.1.21

package/README.md

@@ -27,6 +27,9 @@ ossclip produce input.mp4 -o out.mp4
 # Long-form in, one short out: the strongest ~60s window, chosen by the producer
 ossclip produce podcast.mp4 --produce --clip 60 -o clip.mp4
 
+# Keep your own editor: export the planned cuts as labelled markers, no render, no LLM
+ossclip analyze input.mp4 --format premiere-xml   # Premiere Pro; resolve-edl for Resolve, fcpxml for FCP
+
 # Edit what it produced — direct manipulation, in the browser
 ossclip edit "<work directory>"
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Local-first CLI video producer: cuts silence and fillers, word-timed captions, face-aware framing, and LLM-planned code-rendered graphics — transcription and rendering never leave your machine",
   "type": "module",
   "license": "MIT",
@@ -36,9 +36,9 @@
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/core": "0.1.19",
-    "@ossclip/renderer": "0.1.19",
-    "@ossclip/scenes": "0.1.19"
+    "@ossclip/renderer": "0.1.21",
+    "@ossclip/core": "0.1.21",
+    "@ossclip/scenes": "0.1.21"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/analyze.ts

@@ -0,0 +1,138 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod/v4";
+import {
+  ProductionSchema,
+  buildFcpxmlMarkers,
+  buildPremiereXmlMarkers,
+  buildResolveMarkerEdl,
+  keptPauses,
+  type CleanupLevel,
+} from "@ossclip/core";
+import { produce } from "./produce";
+import type { PhaseTimings } from "./phase-timing";
+
+/**
+ * `ossclip analyze` (next-directions §2–3; design doc
+ * 2026-08-12-analyse-fcpxml-export-design.md): the analyzer without the
+ * renderer. §140 measured the render at 85% of wall time on two machines —
+ * this command is the product of skipping it: the same pipeline up to the
+ * cut report (no LLM, no Remotion), plus an export file an editor's own NLE
+ * can review. Markers, not applied cuts, by design — see the exporter.
+ */
+
+/**
+ * zod enum, not a string: a typo'd `--format fcpxmll` must error naming the
+ * choice, never fall back to a default that silently writes the wrong file
+ * (CLAUDE.md's `--source-fit containn` rule, verbatim).
+ *
+ * `resolve-edl`, not `edl` (§142): it is Resolve's marker-EDL dialect —
+ * markers with colours, for `Timeline → Import → Timeline Markers from EDL`
+ * — not a cut EDL. A future cut EDL gets its own name; "edl" meaning either
+ * would be a permanent ambiguity. It exists because Resolve's FCPXML import
+ * silently drops clip markers (field-verified the day fcpxml shipped);
+ * Premiere reads the fcpxml markers fine.
+ */
+export const ExportFormatSchema = z.enum(["fcpxml", "resolve-edl", "premiere-xml"]);
+export type ExportFormat = z.infer<typeof ExportFormatSchema>;
+
+/** The FILE extension per format — "demo.resolve-edl" would import nowhere. */
+const FORMAT_EXTENSIONS: Record<ExportFormat, string> = {
+  fcpxml: "fcpxml",
+  "resolve-edl": "edl",
+  "premiere-xml": "xml",
+};
+
+/** Same shape as produce's `defaultOutPath`: beside the input, new extension. */
+export function defaultExportPath(input: string, format: ExportFormat): string {
+  return input.replace(/(\.[^.]+)?$/, `.${FORMAT_EXTENSIONS[format]}`);
+}
+
+export interface AnalyzeOptions {
+  cleanup: CleanupLevel;
+  format: ExportFormat;
+  out?: string;
+  transcript?: string;
+  workdir?: string;
+  noiseDb?: number;
+  whisperModel?: string;
+  whisperLanguage?: string;
+  blooperMarker?: string;
+  collapseRetakes?: boolean;
+  sort?: "name" | "mtime";
+  sortExplicit?: boolean;
+}
+
+export interface AnalyzeResult {
+  workdir: string;
+  outPath: string;
+  /** Suggested-cut markers — one per remove segment. */
+  markerCount: number;
+  /** Informational kept-pause markers (§142 round 2) — counted separately
+   * so the CLI and telemetry can say which is which. */
+  pauseCount: number;
+  sourceDurationSec: number;
+  phaseTimings: PhaseTimings;
+}
+
+/**
+ * The I/O glue: run the existing no-render pipeline, read back the
+ * `production.json` it wrote, hand it to the pure exporter, write the file.
+ * The read-back goes through `ProductionSchema.parse` even though this very
+ * run just wrote it — the file is user-visible and hand-editable, and a
+ * truncated or tweaked one must error here, not export garbage markers.
+ */
+export async function runAnalyze(
+  inputArg: string,
+  opts: AnalyzeOptions,
+): Promise<AnalyzeResult> {
+  const result = await produce(inputArg, {
+    cleanup: opts.cleanup,
+    transcript: opts.transcript,
+    render: false,
+    mezzanine: false,
+    workdir: opts.workdir,
+    noiseDb: opts.noiseDb,
+    whisperModel: opts.whisperModel,
+    whisperLanguage: opts.whisperLanguage,
+    blooperMarker: opts.blooperMarker,
+    collapseRetakes: opts.collapseRetakes,
+    sort: opts.sort,
+    sortExplicit: opts.sortExplicit,
+    cover: false,
+  });
+  const production = ProductionSchema.parse(
+    JSON.parse(await readFile(join(result.workdir, "production.json"), "utf8")),
+  );
+  // §142, learned the hard way in one field-test hour: each NLE gets its OWN
+  // dialect. Premiere rejects modern fcpxml outright, Resolve's fcpxml import
+  // silently drops markers — so fcpxml is for actual Final Cut Pro.
+  const content =
+    opts.format === "resolve-edl"
+      ? buildResolveMarkerEdl(production)
+      : opts.format === "premiere-xml"
+        ? buildPremiereXmlMarkers(production)
+        : buildFcpxmlMarkers(production);
+  const markerCount = (production.cutlist ?? []).filter((s) => s.kind === "remove").length;
+  const pauseCount = keptPauses(production).length;
+  const outPath = resolve(opts.out ?? defaultExportPath(resolve(inputArg), opts.format));
+  await writeFile(outPath, content);
+  const detail =
+    opts.format === "resolve-edl"
+      ? "in Resolve: Media Pool → right-click your timeline → Timelines → Import → Timeline Markers from EDL"
+      : opts.format === "premiere-xml"
+        ? "in Premiere: File → Import, pick the .xml, relink media if offline"
+        : "for Final Cut Pro; Premiere needs --format premiere-xml, Resolve --format resolve-edl";
+  console.log(
+    `✓ ${opts.format} → ${outPath} (${markerCount} cut marker${markerCount === 1 ? "" : "s"}` +
+      `${pauseCount > 0 ? ` + ${pauseCount} kept-pause marker${pauseCount === 1 ? "" : "s"}` : ""} — ${detail})`,
+  );
+  return {
+    workdir: result.workdir,
+    outPath,
+    markerCount,
+    pauseCount,
+    sourceDurationSec: result.sourceDurationSec,
+    phaseTimings: result.phaseTimings,
+  };
+}

package/src/phase-timing.ts

@@ -0,0 +1,140 @@
+/**
+ * Per-phase timing for `produce` (FINDINGS §140). "3 hours" was
+ * unattributed: `produce_completed` carried one `duration_ms` for the whole
+ * run, so nothing could say WHICH of the four candidate phases — whisper,
+ * LLM planning, the Remotion render, ffmpeg concat/normalize — the time went
+ * to, and each has a completely different fix if it dominates. Everything in
+ * this file is pure (clock injected, no I/O), per the house split; produce()
+ * owns the wrapping and program.ts owns the telemetry event.
+ */
+
+/**
+ * The four attributed phases, exactly the candidates from the §140 table.
+ * Everything ELSE produce does (audio extraction, silence/level analysis,
+ * content-rect and face sampling, the mezzanine) lands in the log line's
+ * `other` remainder rather than a fifth phase — the remainder is PRINTED, so
+ * if it ever dominates a real run it accuses itself and earns a phase then.
+ */
+export type ProducePhase = "transcribe" | "llm" | "render" | "ffmpeg";
+
+/** Milliseconds per phase; a phase that never ran is ABSENT, never 0. */
+export type PhaseTimings = Partial<Record<ProducePhase, number>>;
+
+/** Pipeline order — the log line reads like the run did. */
+const PHASE_ORDER: ProducePhase[] = ["transcribe", "llm", "render", "ffmpeg"];
+
+/**
+ * The log labels name the TOOL, not the internal phase id, because the §140
+ * table (and any hardware decision made from it) is about the tools:
+ * "whisper 12m" tells the user what to swap; "transcribe 12m" makes them ask.
+ */
+const PHASE_LABELS: Record<ProducePhase, string> = {
+  transcribe: "whisper",
+  llm: "llm",
+  render: "render",
+  ffmpeg: "ffmpeg",
+};
+
+export class PhaseTimer {
+  private readonly ms: PhaseTimings = {};
+  private readonly startedAt: number;
+
+  constructor(private readonly now: () => number = () => performance.now()) {
+    this.startedAt = this.now();
+  }
+
+  /**
+   * Accumulates — the llm phase is repair + window selection + scenes, and
+   * the ffmpeg phase is concat + loudnorm, so a phase is a SUM of calls, not
+   * one interval. Recorded in a `finally` so time spent is time recorded even
+   * when the phase throws: the throw aborts the run either way, but a future
+   * `produce_failed` that wants to say where the time went must not find the
+   * books cooked.
+   */
+  async time<T>(phase: ProducePhase, fn: () => Promise<T>): Promise<T> {
+    const t0 = this.now();
+    try {
+      return await fn();
+    } finally {
+      this.ms[phase] = (this.ms[phase] ?? 0) + (this.now() - t0);
+    }
+  }
+
+  timings(): PhaseTimings {
+    return { ...this.ms };
+  }
+
+  /** Wall clock since construction — the phases never sum to it; `other` is the gap. */
+  totalMs(): number {
+    return this.now() - this.startedAt;
+  }
+}
+
+/**
+ * Three scales, matched to what a human checks at each: one decimal under a
+ * minute (an 8.2s llm phase must not flatten to "8s" when comparing runs),
+ * zero-padded seconds under an hour ("1m03s", so it can't be misread as
+ * 1m30s), minutes only above it.
+ */
+export function formatPhaseDuration(ms: number): string {
+  const sec = ms / 1000;
+  if (sec < 60) return `${sec.toFixed(1)}s`;
+  if (sec < 3600) {
+    return `${Math.floor(sec / 60)}m${String(Math.floor(sec % 60)).padStart(2, "0")}s`;
+  }
+  return `${Math.floor(sec / 3600)}h${String(Math.floor((sec % 3600) / 60)).padStart(2, "0")}m`;
+}
+
+/**
+ * The run log's one-line breakdown, in the ▸ voice, real seconds — this is
+ * the user's own machine, so unlike telemetry there is nothing to bucket.
+ * Absent phases are omitted (a cached transcript is not a 0.0s whisper run),
+ * the remainder is printed as `other` so unattributed time stays visible,
+ * and a run with no measured phases prints only the total — an `other` at
+ * 100% would just restate it. The remainder clamps at zero: the phases and
+ * the total read the clock at different instants, and a -0.0s from that skew
+ * would read as a bug in the very line meant to build trust in the numbers.
+ */
+export function formatPhaseLine(timings: PhaseTimings, totalMs: number): string {
+  const measured = PHASE_ORDER.filter((p) => timings[p] !== undefined);
+  const total = `▸ time: total ${formatPhaseDuration(totalMs)}`;
+  if (measured.length === 0) return total;
+  const parts = measured.map((p) => `${PHASE_LABELS[p]} ${formatPhaseDuration(timings[p]!)}`);
+  const other = totalMs - measured.reduce((sum, p) => sum + timings[p]!, 0);
+  if (other > 0) parts.push(`other ${formatPhaseDuration(other)}`);
+  return `${total} — ${parts.join(" · ")}`;
+}
+
+/**
+ * Same idea as telemetry.ts's `durationBucket` — the exact seconds never
+ * leave the machine — but with sub-minute resolution, because the question
+ * this answers ("which phase dominates?") has phases that legitimately live
+ * in seconds: an llm plan at 8s and a render at 40 minutes both being ">1m"
+ * would erase the very comparison §140 exists to make.
+ */
+export function phaseDurationBucket(
+  seconds: number,
+): "<10s" | "10-60s" | "1-5m" | "5-15m" | ">15m" {
+  if (seconds < 10) return "<10s";
+  if (seconds <= 60) return "10-60s";
+  if (seconds <= 300) return "1-5m";
+  if (seconds <= 900) return "5-15m";
+  return ">15m";
+}
+
+/**
+ * The `produce_completed` props for the phases that ran: `<phase>_bucket`,
+ * bucketed, never raw milliseconds (§134 floor — a raw per-phase duration is
+ * even closer to fingerprinting a specific take than the total the floor
+ * already buckets). Keys are pinned against `assertSafeProps` in
+ * phase-timing.test.ts, since a spread into `telemetry.record` is invisible
+ * to telemetry.test.ts's source-text drift check.
+ */
+export function phaseBucketProps(timings: PhaseTimings): Record<string, string> {
+  const props: Record<string, string> = {};
+  for (const p of PHASE_ORDER) {
+    const ms = timings[p];
+    if (ms !== undefined) props[`${p}_bucket`] = phaseDurationBucket(ms / 1000);
+  }
+  return props;
+}

package/src/produce.ts

@@ -98,6 +98,7 @@ 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,
@@ -134,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;
 }
 
 /**
@@ -532,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
@@ -641,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)" : ""}`,
@@ -758,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));
@@ -901,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) {
@@ -1055,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));
@@ -1180,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}`);
@@ -2230,6 +2252,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   }
 
   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 {
@@ -2238,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(),
     };
   }
 
@@ -2245,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) -----------------------------------------
@@ -2419,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 {
@@ -2428,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, runAnalyze } from "./analyze";
+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,87 @@ export function buildProgram(): Command {
       await telemetry.flush();
     });
 
+  program
+    // American spelling is primary (house style, 2026-08-12); the British
+    // alias stays because a command someone has already learned must not
+    // become an "unknown command" over an s/z.
+    .command("analyze")
+    .alias("analyse")
+    .description(
+      "analyze 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 (Premiere) | resolve-edl (Resolve coloured timeline markers — " +
+        "its fcpxml import drops markers)",
+      "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 runAnalyze(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("analyze_completed", {
+          format,
+          cleanup_level: cleanup,
+          source_duration_bucket: durationBucket(result.sourceDurationSec),
+          markers: result.markerCount,
+          kept_pauses: result.pauseCount,
+          ...phaseBucketProps(result.phaseTimings),
+        });
+      } catch (err) {
+        // Constructor name only, like produce_failed: messages quote paths.
+        telemetry.record("analyze_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)")