@ossclip/core 0.1.35 → 0.1.37

package/src/ingest.ts

@@ -85,6 +85,42 @@ export async function extractAudio(tools: IngestTools, src: string, outWav: stri
   ]);
 }
 
+/**
+ * Pure: ffmpeg args for the compressed remote-upload sidecar (2026-09-01,
+ * the remote-transcription backend). Split from the spawn the same way
+ * `openCommand()` is split from `openInBrowser()` — the codec choice is the
+ * whole decision here, so it must be assertable without an ffmpeg on the box.
+ *
+ * Opus 32 kbps 16 kHz mono: ASR-transparent for speech and ~240 KB/min, so
+ * ~100 minutes of audio fit under Groq's free-tier 25 MB per-file cap. The
+ * PCM wav `extractAudio` writes is 1.92 MB/min and hits that cap at ~13
+ * minutes — unusable for a normal recording session. FLAC was rejected:
+ * lossless buys ASR nothing and only reaches ~25 minutes.
+ */
+export function uploadAudioArgs(wavPath: string, outOgg: string): string[] {
+  return ["-y", "-i", wavPath, "-vn", "-c:a", "libopus", "-b:a", "32k", "-ar", "16000", "-ac", "1", outOgg];
+}
+
+/**
+ * Encode the remote-upload sidecar. libopus is in the bundled static ffmpeg;
+ * a user's own minimal build may lack it, in which case `run` surfaces
+ * ffmpeg's own "Unknown encoder" verbatim — better than a guess at the cause.
+ */
+export async function encodeUploadAudio(tools: IngestTools, wav: string, outOgg: string): Promise<void> {
+  await run(tools.ffmpegPath, uploadAudioArgs(wav, outOgg));
+}
+
+/**
+ * 24 million bytes: Groq's free tier caps a file at "25MB" without saying
+ * whether that is decimal or MiB — 24_000_000 sits under BOTH readings
+ * (25,000,000 and 26,214,336), so a boundary file fails HERE with our message
+ * (naming the ~100-minute ceiling and the local-backend escape hatch) instead
+ * of coming back as somebody else's 413 after the whole upload was paid for.
+ * (24 MiB = 25,165,824 would EXCEED a decimal cap — caught 2026-09-01.)
+ * Chunking is out of scope for v1.
+ */
+export const REMOTE_UPLOAD_MAX_BYTES = 24_000_000;
+
 /**
  * Extract ONE span of an existing wav, same 16 kHz mono PCM shape
  * (2026-08-26, the caption re-alignment pass).
@@ -190,11 +226,56 @@ export function mezzanineScale(
  * the legacy names so existing workdir caches stay valid; a scaled run
  * rebuilds once under its own name and old workdirs' render-props keep
  * referencing (and rendering from) the file they were emitted against.
+ *
+ * The LUT hash is in the name for the same reason: grading is baked into the
+ * mezzanine at build time, so a warm workdir keyed only on crop/scale would
+ * satisfy a graded run with UNGRADED frames (or a re-graded run with the old
+ * look). No LUT keeps today's names byte-for-byte, so existing warm workdirs
+ * stay valid.
  */
-export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null): string {
+export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null, lutHash?: string): string {
   const base = cropped ? "mezzanine-content" : "mezzanine";
-  if (!scale) return `${base}.mp4`;
-  return `${base}-${scale.width}x${scale.height}@${Math.round(scale.fps)}.mp4`;
+  const scaleSeg = scale ? `-${scale.width}x${scale.height}@${Math.round(scale.fps)}` : "";
+  const lutSeg = lutHash ? `-lut${lutHash}` : "";
+  return `${base}${scaleSeg}${lutSeg}.mp4`;
+}
+
+/** A 3D LUT to bake into the mezzanine; `hash` keys the cache (see `mezzanineFileName`). */
+export interface MezzanineLut {
+  path: string;
+  hash: string;
+}
+
+/**
+ * Escape a filesystem path for use as an ffmpeg filter option value.
+ *
+ * A `-vf` string is parsed twice: once as a filtergraph (where `\` `'` `[`
+ * `]` `,` `;` are special) and once as the filter's option value (where `:`
+ * `\` `'` are special — `:` is the option separator, so an unescaped drive
+ * letter like `C:` truncates the path there). Each level strips one layer of
+ * backslashes, so the option-level escapes must themselves be escaped for
+ * the graph level: `:` → `\\:`, `'` → `\\\'`, `\` → `\\\\`. Spaces need
+ * nothing — the argv goes straight to ffmpeg, no shell in between.
+ */
+export function escapeFilterPath(p: string): string {
+  // Level 1: filter option value — `:` `\` `'` are special.
+  const option = p.replace(/[\\':]/g, (c) => `\\${c}`);
+  // Level 2: filtergraph — escape again so level-1 backslashes survive.
+  return option.replace(/[\\'[\],;]/g, (c) => `\\${c}`);
+}
+
+/**
+ * The mezzanine's `-vf` chain, pure so the ordering contract is testable:
+ * LUT strictly AFTER crop/scale — grading the letterbox bars would be
+ * wasted math, and grading pre-scale pixels the render never sees changes
+ * nothing but costs full-res per-pixel lookups.
+ */
+export function mezzanineVf(opts: { cropVf?: string; scale?: MezzanineScale; lut?: MezzanineLut }): string {
+  return [
+    ...(opts.cropVf ? [opts.cropVf] : []),
+    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
+    ...(opts.lut ? [`lut3d=file=${escapeFilterPath(opts.lut.path)}:interp=tetrahedral`] : []),
+  ].join(",");
 }
 
 /**
@@ -206,17 +287,15 @@ export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null
  *
  * `scale` (from `mezzanineScale`) downsizes to display size in the SAME
  * pass, crop first — the scale dims are computed on the post-crop picture.
+ * `lut` bakes a 3D grade in last, on exactly the pixels the render will see.
  */
 export async function makeMezzanine(
   tools: IngestTools,
   src: string,
   out: string,
-  opts: { cropVf?: string; scale?: MezzanineScale } = {},
+  opts: { cropVf?: string; scale?: MezzanineScale; lut?: MezzanineLut } = {},
 ): Promise<void> {
-  const vf = [
-    ...(opts.cropVf ? [opts.cropVf] : []),
-    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
-  ].join(",");
+  const vf = mezzanineVf(opts);
   await run(tools.ffmpegPath, [
     "-y", "-i", src,
     ...(vf ? ["-vf", vf] : []),

package/src/lut-library.ts

@@ -0,0 +1,81 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { CONFIG_DIR } from "./config";
+import { parseCubeLut } from "./color-grade";
+
+/**
+ * The user's .cube LUT directory, discovered — the `sfx-pack.ts` shape for
+ * color grades. `parseCubeLut` stays pure; this module is the thin fs layer
+ * that walks `~/.ossclip/luts` and reports, per file, either a usable LUT or
+ * the reason it is not one. Nothing here throws: a hand-dropped .cube is user
+ * input, and a broken one must cost that one menu entry, not the editor.
+ */
+
+/** Where user LUTs live: `~/.ossclip/luts/<name>.cube`. */
+export function userLutDir(): string {
+  return join(CONFIG_DIR, "luts");
+}
+
+/** One LUT the menu can offer. `path` stays server-side, like SFX `absPath`. */
+export interface LutLibraryItem {
+  /** The filename stem — what `ColorGrade.lut` (basename) resolves against. */
+  id: string;
+  /** The .cube's own TITLE when it has one, else the stem. */
+  title: string;
+  /** Absolute path — the caller's I/O concern, never sent to a client. */
+  path: string;
+}
+
+/** Why one file is not in the library — `SfxPackIssue`'s shape, per file. */
+export interface LutLibraryIssue {
+  /** The .cube filename (basename) that failed. */
+  file: string;
+  message: string;
+}
+
+export interface LutLibrary {
+  items: LutLibraryItem[];
+  issues: LutLibraryIssue[];
+}
+
+/**
+ * Every parseable `.cube` under `dir`, plus an issue per file that is not one.
+ * Each file is fully parsed here — not just listed — because the menu is the
+ * ONLY surface where a broken LUT can be reported before a render silently
+ * drops it: `parseCubeLut` is strict about content on purpose, and offering a
+ * file the bake will refuse is the exact mismatch the SFX library gate exists
+ * to avoid.
+ *
+ * A missing directory is the normal case (most users never drop a LUT), not
+ * an issue. `dir` is a parameter with a default rather than a `homedir()`
+ * read inside, so tests point it at a tmp dir and never touch a real home
+ * (`loadSfxLibrary`'s rule).
+ */
+export function loadLutLibrary(dir: string = userLutDir()): LutLibrary {
+  let names: string[] = [];
+  try {
+    names = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".cube"))
+      .map((e) => e.name)
+      // Sorted so the menu reads the same on every machine — readdir order is
+      // not a promise (loadSfxLibrary's merge-order rule).
+      .sort();
+  } catch {
+    return { items: [], issues: [] };
+  }
+  const items: LutLibraryItem[] = [];
+  const issues: LutLibraryIssue[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    const stem = basename(name, extname(name));
+    try {
+      const lut = parseCubeLut(readFileSync(path, "utf8"));
+      // TITLE when the exporter wrote one — a human-readable label the stem
+      // (often `Vendor_Look_33pt_v2`) cannot match. Empty titles fall back.
+      items.push({ id: stem, title: lut.title?.trim() || stem, path });
+    } catch (e) {
+      issues.push({ file: name, message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  return { items, issues };
+}

package/src/overrides.ts

@@ -1,4 +1,5 @@
 import { z } from "zod/v4";
+import { ColorGradeSchema } from "./color-grade";
 import {
   LayoutSchema,
   SceneAnchorSchema,
@@ -142,6 +143,19 @@ export const SceneOverrideSchema = z.object({
       dx: z.number().optional(),
       /** `false` switches the automatic idle-zoom layer off for this scene. */
       autoZoom: z.boolean().optional(),
+      /**
+       * Audio gain for this window's footage, 1 = as recorded (field report
+       * 2026-08-31: one concatenated clip was recorded quieter than the
+       * rest). Lives inside `video` on purpose — it is a property of this
+       * window's playback, and the key already merges per scene, inherits
+       * across split halves, and has patch/clear plumbing. 0 mutes. Above 1
+       * amplifies — in the render via allowAmplificationDuringRender, and in
+       * the preview via the Player's own WebAudio gain (Remotion ≥4.0.5xx,
+       * use-amplification). Max 4: a field clip arrived quiet enough that 2x
+       * did not reach its neighbours (2026-08-31); past 4x you are boosting
+       * noise floor, not speech.
+       */
+      volume: z.number().min(0).max(4).optional(),
     })
     .optional(),
   /**
@@ -527,6 +541,24 @@ export type SfxAddedPlacement = z.infer<typeof SfxAddedPlacementSchema>;
 export const OverrideDocSchema = z.object({
   /** Global style tokens — the look is a system, so these are not per-element. */
   theme: ThemeSchema.partial().default({}),
+  /**
+   * Doc-global color grade — the `ColorGradeSchema` shape, or `false` for
+   * "explicitly no grade on this project". Doc-global like `theme`: a grade
+   * is one decision about the whole output, not a per-scene key. Optional
+   * with NO default (the `captionsHidden` rule) so every overrides.json
+   * written before the key existed parses byte-identically — but UNLIKE
+   * `captionsHidden`, an explicit `false` is meaningful and kept: it
+   * disables a config-level default grade for this one project, which
+   * deleting the key cannot express (absent means "let the flag, then the
+   * config, decide" — `resolveProductionColorGrade` in produce.ts owns that
+   * precedence). Schema-valid is not yet USABLE: an unknown preset id passes
+   * here (the schema cannot list what exists without going stale) and is
+   * caught by `resolveColorGrade` at the consumer, where it warns and falls
+   * through to the next layer instead of failing the whole doc. Timeless —
+   * no seconds anywhere — so `remapOverridesThroughRecut`'s `...doc` spreads
+   * carry it through a recut untouched.
+   */
+  colorGrade: z.union([ColorGradeSchema, z.literal(false)]).optional(),
   /**
    * Captions OFF for the whole video. Doc-global like `theme`, deliberately
    * NOT a per-scene key: visibility is one decision about the output —

package/src/recut.ts

@@ -269,6 +269,11 @@ export function resolveCutSourceRanges(
  * user cut exactly like an automatic one, with no separate report path
  * needed for "what got removed."
  */
+/** See the sliver comment inside `subtractRangesFromCutlist` — a keep this
+ * short only ever comes from rounded cut edges meeting full-precision span
+ * floats, and it crashes the Remotion player if it survives. */
+const SLIVER_EPS = 0.002;
+
 export function subtractRangesFromCutlist(
   cutlist: readonly Segment[],
   ranges: readonly { start: number; end: number }[],
@@ -292,11 +297,35 @@ export function subtractRangesFromCutlist(
       const overlapStart = Math.max(cursor, r.start);
       const overlapEnd = Math.min(seg.srcOut, r.end);
       if (overlapStart >= overlapEnd) continue;
-      if (overlapStart > cursor) out.push({ srcIn: cursor, srcOut: overlapStart, kind: "keep" });
-      out.push({ srcIn: overlapStart, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      // A keep sliver shorter than SLIVER_EPS joins the removal instead of
+      // surviving as its own segment (2026-08-31, the ADK crash): the cut
+      // writers round `src` to 3 decimals while the cutlist keeps full float
+      // precision, so the honest set difference can leave a keep of ~100µs.
+      // EdlVideo rounds both ends of such a span to the SAME frame and
+      // Remotion throws ("trimAfter must be greater than trimBefore"),
+      // blanking the whole player — in the preview AND the next render.
+      // 2ms covers the worst rounding drift (0.5ms per edge) and is far
+      // under one frame at any real fps, so nothing watchable is lost.
+      if (overlapStart - cursor >= SLIVER_EPS) {
+        out.push({ srcIn: cursor, srcOut: overlapStart, kind: "keep" });
+        out.push({ srcIn: overlapStart, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      } else {
+        out.push({ srcIn: cursor, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      }
       cursor = overlapEnd;
     }
-    if (cursor < seg.srcOut) out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "keep" });
+    if (seg.srcOut - cursor >= SLIVER_EPS) {
+      out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "keep" });
+    } else if (cursor < seg.srcOut) {
+      // Tail sliver: extend the removal that ends at `cursor` (there always
+      // is one — cursor only advances past a pushed removal).
+      const last = out[out.length - 1];
+      if (last && last.kind === "remove" && last.srcOut === cursor) {
+        out[out.length - 1] = { ...last, srcOut: seg.srcOut };
+      } else {
+        out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "remove", reason: "user", confidence: 1 });
+      }
+    }
   }
   return out;
 }

package/src/scene-schema.ts

@@ -146,6 +146,9 @@ export const SceneCueSchema = z
       dx: z.number().optional(),
       /** `false` switches the automatic idle-zoom layer off for this scene. */
       autoZoom: z.boolean().optional(),
+      /** Audio gain for this window, 1 = as recorded — mirror of
+       * `SceneOverrideSchema.video.volume`, which owns the argument. */
+      volume: z.number().min(0).max(4).optional(),
     })
     .optional(),
   /**

package/src/transcribe/index.ts

@@ -0,0 +1,3 @@
+export * from "./whisper-cli";
+export * from "./provider";
+export * from "./openai-compatible";

package/src/transcribe/openai-compatible.ts

@@ -0,0 +1,199 @@
+import { basename } from "node:path";
+import { z } from "zod/v4";
+import { TranscriptSchema, type Transcript, type Word } from "../schema";
+import { NOISE_TOKEN, normalizeWords, type TranscribeProvider, type TranscribeRequest } from "./provider";
+
+/**
+ * Transcription against any OpenAI-compatible `/v1/audio/transcriptions`
+ * server — Groq's free tier (8h audio/day, `whisper-large-v3-turbo`), a
+ * self-hosted speaches, or anything else speaking that shape.
+ *
+ * Why (2026-09-01 field report): on a weak CPU — an i3 2nd gen — whisper is
+ * the dominant cost of a produce run, minutes of decode per minute of video.
+ * A remote call makes it seconds. Local whisper-cli stays the DEFAULT; this
+ * is opt-in via `whisperUrl` / `OSSCLIP_WHISPER_URL`, and the API key is
+ * optional because self-hosted servers run keyless (unlike publish, where the
+ * key is required).
+ *
+ * Error posture is postiz.ts's, for the same reason: a transcription is the
+ * user's explicit action, so every non-2xx throws with the status and a body
+ * snippet, and there are NO retries — a retry against a metered free tier
+ * silently doubles the quota burn for a failure the user is about to see
+ * anyway.
+ */
+
+/**
+ * `whisperUrl` → the endpoint: trailing slashes dropped,
+ * `/audio/transcriptions` appended unless the user already wrote it
+ * (`postizApiBase`'s mould). The user configures the OpenAI-compatible BASE
+ * ("https://api.groq.com/openai/v1"), which is the URL every provider's
+ * quickstart prints — but someone who pastes the full endpoint must not end
+ * up posting to `/v1/audio/transcriptions/audio/transcriptions`.
+ */
+export function openaiTranscriptionsUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return trimmed.endsWith("/audio/transcriptions") ? trimmed : `${trimmed}/audio/transcriptions`;
+}
+
+export class RemoteTranscribeHttpError extends Error {
+  constructor(
+    readonly url: string,
+    readonly status: number,
+    bodySnippet: string,
+  ) {
+    // Per-status hints, PostizHttpError's mould: the raw status tells a user
+    // nothing about which of the two env vars (or which URL spelling) is
+    // wrong, and this path is reached by people who just pasted a quickstart.
+    const hint =
+      status === 401 || status === 403
+        ? " — the server rejected OSSCLIP_WHISPER_API_KEY (or none was sent — set it in the environment or ~/.ossclip/.env)"
+        : status === 404
+          ? " — no /audio/transcriptions here — whisperUrl should be the OpenAI-compatible base ending in /v1 (e.g. https://api.groq.com/openai/v1)"
+          : status === 413
+            ? " — audio too large for this server — free Groq caps uploads at 25MB; use --whisper-backend local or the dev tier"
+            : status === 429
+              ? " — rate limited (Groq free tier: 8h audio/day)"
+              : "";
+    super(`remote transcription POST ${url} failed: ${status}${hint}${bodySnippet ? `\n${bodySnippet}` : ""}`);
+    this.name = "RemoteTranscribeHttpError";
+  }
+}
+
+/**
+ * `verbose_json` as we consume it. LOOSE on purpose: servers add fields
+ * freely (Groq sends `task`, `duration`, `segments`, `x_groq`), and a strict
+ * object would turn a perfectly good transcription into a parse error the
+ * next time one of them ships a field.
+ */
+const RemoteWordSchema = z.looseObject({
+  word: z.string(),
+  start: z.number(),
+  end: z.number(),
+});
+const VerboseJsonSchema = z.looseObject({
+  language: z.string().optional(),
+  words: z.array(RemoteWordSchema).optional(),
+});
+
+export interface OpenAiCompatibleOptions {
+  /** OpenAI-compatible base, e.g. "https://api.groq.com/openai/v1". */
+  baseUrl: string;
+  model: string;
+  /** Optional: self-hosted servers (speaches, whisper.cpp server) run keyless. */
+  apiKey?: string;
+  /** The postiz test seam — the whole HTTP surface is testable without a network. */
+  fetchImpl?: typeof fetch;
+  /** Per-request cap; an hour of audio takes a while to upload and decode. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const BODY_SNIPPET_CHARS = 300;
+
+export function createOpenAiCompatibleProvider(opts: OpenAiCompatibleOptions): TranscribeProvider {
+  const url = openaiTranscriptionsUrl(opts.baseUrl);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    name: "openai-compatible",
+    async transcribe(audioPath: string, req: TranscribeRequest): Promise<Transcript> {
+      // Belt and braces — the CLI refuses this combination earlier, with the
+      // fix named. `/audio/translations` is a different endpoint AND a
+      // different default model upstream, so silently swapping both behind
+      // `--whisper-translate` would be a surprise, not a convenience.
+      if (req.translate === true) {
+        throw new Error(
+          "--whisper-translate needs the local backend (the OpenAI-compatible API translates on a different endpoint and model) — use --whisper-backend local, or drop the flag.",
+        );
+      }
+      const { openAsBlob } = await import("node:fs");
+      // Streams the file into multipart form-data instead of holding it in
+      // memory (postiz.ts's rationale): the upload sidecar is small, but a
+      // span wav or an uncompressed hour is not.
+      const blob = await openAsBlob(audioPath, {
+        type: audioPath.endsWith(".ogg") ? "audio/ogg" : "audio/wav",
+      });
+      const form = new FormData();
+      form.append("file", blob, basename(audioPath));
+      form.append("model", opts.model);
+      form.append("response_format", "verbose_json");
+      // The literal bracketed field name is the wire spelling OpenAI and Groq
+      // accept — it is an array parameter in a multipart body, not a typo.
+      form.append("timestamp_granularities[]", "word");
+      // "auto" is whisper.cpp's vocabulary, not an ISO code: sending it makes
+      // the server reject the request, while OMITTING the field is exactly
+      // what asks for auto-detection.
+      if (req.language !== undefined && req.language !== "auto") form.append("language", req.language);
+      if (req.prompt !== undefined) form.append("prompt", req.prompt);
+
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeoutMs);
+      let res: Response;
+      try {
+        res = await fetchImpl(url, {
+          method: "POST",
+          headers: opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
+          body: form,
+          signal: ac.signal,
+        });
+      } catch (err) {
+        throw new Error(
+          `remote transcription unreachable at ${url}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+      const text = await res.text();
+      if (!res.ok) throw new RemoteTranscribeHttpError(url, res.status, text.slice(0, BODY_SNIPPET_CHARS));
+      let json: unknown;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        throw new Error(
+          `remote transcription answered non-JSON from ${url}: ${text.slice(0, BODY_SNIPPET_CHARS)}`,
+        );
+      }
+      const parsed = VerboseJsonSchema.parse(json);
+      if (!parsed.words || parsed.words.length === 0) {
+        // Two causes, both worth naming: a server that transcribed fine but
+        // has no word-timestamp support (a plain whisper.cpp server), and
+        // near-silent audio, which Groq's turbo model answers wordlessly.
+        // Everything downstream (cuts, captions, zoom) is word-stamp driven,
+        // so a text-only answer is unusable, not a degraded success.
+        throw new Error(
+          `the server answered without word timestamps — it must support response_format=verbose_json with timestamp_granularities[]=word (Groq and speaches do; a plain whisper.cpp server may not), or the audio contained no speech (${url})`,
+        );
+      }
+      // No token merging and no §130 byte repair here: those heal whisper.cpp
+      // `-ml 1` artifacts (one BPE token per segment, split mid-character).
+      // The HTTP API returns whole words with punctuation attached — already
+      // the shape parseWhisperJson works to produce.
+      const words: Word[] = [];
+      for (const w of parsed.words) {
+        const wordText = w.word.trim();
+        if (!wordText || NOISE_TOKEN.test(wordText)) continue;
+        words.push({
+          text: wordText,
+          // Clamped: a server answering -0.01 for the first word would trip
+          // WordSchema's nonnegative and fail the whole run over a rounding
+          // artifact at the very start of the audio.
+          start: Math.max(0, w.start),
+          end: w.end,
+        });
+      }
+      return TranscriptSchema.parse({
+        // The requested code wins — it is what the cache key and the caption
+        // pipeline were told the audio is. Otherwise the server's own answer,
+        // lowercased. NOTE: some servers answer with a full NAME ("english")
+        // rather than a code; no code-sensitive consumer exists today
+        // (captions' RTL check is a Unicode heuristic), so no name→code table.
+        language:
+          req.language !== undefined && req.language !== "auto"
+            ? req.language
+            : parsed.language?.toLowerCase(),
+        words: normalizeWords(words),
+      });
+    },
+  };
+}

package/src/transcribe/provider.ts

@@ -0,0 +1,101 @@
+import type { Transcript, Word } from "../schema";
+
+/**
+ * The seam between ossclip and any transcription backend (2026-09-01, the
+ * weak-CPU field report: whisper is the dominant cost on an i3 2nd gen, and a
+ * free remote tier makes it disappear). Two implementations today —
+ * whisper.cpp on the box (`whisper-cli.ts`) and any OpenAI-compatible
+ * `/v1/audio/transcriptions` server (`openai-compatible.ts`).
+ *
+ * The local path deliberately keeps calling `runWhisper` directly rather than
+ * going through this interface: produce.ts and the edit server inject
+ * `runWhisper` itself as a test seam, and forcing that through a provider
+ * object would churn every stub for no behavior change.
+ */
+export interface TranscribeRequest {
+  /** Resolved language code; "auto" is handled per provider (whisper.cpp
+   *  takes it literally, the HTTP API wants the field OMITTED). */
+  language?: string;
+  /** `whisperPromptFor()` output — the user dictionary as decoder bias. */
+  prompt?: string;
+  /** whisper-cli's TRANSLATE task; the OpenAI-compatible provider rejects it
+   *  (a different endpoint AND a different default model upstream). */
+  translate?: boolean;
+}
+
+export interface TranscribeProvider {
+  name: string;
+  transcribe(audioPath: string, req: TranscribeRequest): Promise<Transcript>;
+}
+
+/** [BLANK_AUDIO], (buzzing), [MUSIC] … — noise markers, not speech. Shared:
+ *  remote servers emit the same bracketed markers whisper.cpp does. */
+export const NOISE_TOKEN = /^[[(].*[\])]$/;
+
+/**
+ * Run length at which a stack of zero-length words at ONE instant stops being
+ * a rounding artifact and becomes a repetition-loop hallucination. Real speech
+ * never emits 8 tokens at a single instant; the field case emitted 118.
+ */
+export const REPETITION_BURST_MIN = 8;
+
+/**
+ * Drop whisper repetition-loop bursts (field case 2026-08-18): an Urdu take
+ * re-decoded a whole phrase as 118 CONSECUTIVE tokens all stamped
+ * `from === to === 31040` — zero length, at one instant. The stamp repair
+ * below then fans such a burst out into 118 fabricated 50ms words marching
+ * forward from 31.04s, so the phrase ships TWICE in the captions (31.04s and
+ * 33.54s) and a fifth of the transcript carries the tell-tale exactly-0.05s
+ * duration. `-mc 0` in whisperArgs is the decoder-side mitigation for the same
+ * failure; it did not prevent this occurrence, and it can never repair an
+ * already-cached transcript.json — hence a parse-side guard too.
+ *
+ * A burst is a MAXIMAL run of consecutive zero-length/inverted words sharing
+ * one `start`. Equality is exact, not epsilon: these stamps are integer
+ * milliseconds divided by 1000, so members of one burst are the same double
+ * bit-for-bit, and a tolerance would only start swallowing real neighbors.
+ * Runs shorter than REPETITION_BURST_MIN fall through untouched — a lone
+ * zero-length stamp is a rounding artifact, not a hallucination. The drop is
+ * silent by design: this function is pure and total, and there is no logging
+ * channel in the parse path to warn on.
+ */
+export function dropRepetitionBursts(words: readonly Word[]): Word[] {
+  const out: Word[] = [];
+  let i = 0;
+  while (i < words.length) {
+    const w = words[i]!;
+    if (w.end > w.start) {
+      out.push(w);
+      i++;
+      continue;
+    }
+    let j = i + 1;
+    while (j < words.length && words[j]!.end <= words[j]!.start && words[j]!.start === w.start) j++;
+    if (j - i < REPETITION_BURST_MIN) for (let k = i; k < j; k++) out.push(words[k]!);
+    i = j;
+  }
+  return out;
+}
+
+/**
+ * The word-stamp hygiene EVERY backend's output goes through, extracted from
+ * the tail of `parseWhisperJson` so the remote provider cannot drift from it
+ * (2026-09-01). Burst drop runs BEFORE the repair, never after: the repair
+ * rewrites every burst member into a distinct monotone stamp, so once it has
+ * run the shared timestamp — the only evidence a burst existed — is gone.
+ *
+ * Copies before mutating, so a caller's array survives the call unchanged;
+ * `parseWhisperJson` builds its words fresh, so this is byte-identical to the
+ * in-place loop it replaces.
+ */
+export function normalizeWords(words: readonly Word[]): Word[] {
+  const kept = dropRepetitionBursts(words).map((w) => ({ ...w }));
+  // Whisper occasionally emits zero-length or inverted stamps; repair minimally.
+  for (let i = 0; i < kept.length; i++) {
+    const w = kept[i]!;
+    if (w.end <= w.start) w.end = w.start + 0.05;
+    const next = kept[i + 1];
+    if (next && next.start < w.end) next.start = w.end;
+  }
+  return kept;
+}