ossclip 0.1.35 → 0.1.37

package/src/produce.ts

@@ -66,6 +66,10 @@ import {
   splitThenDropHidden,
   emptyOverrideDoc,
   extractAudio,
+  encodeUploadAudio,
+  REMOTE_UPLOAD_MAX_BYTES,
+  createOpenAiCompatibleProvider,
+  openaiTranscriptionsUrl,
   fillPlainCues,
   splitCues,
   landscapeLayout,
@@ -124,6 +128,18 @@ import {
   makeMezzanine,
   mezzanineFileName,
   mezzanineScale,
+  // The color-grade pipeline (2026-08-30): validation, the preset/LUT split,
+  // the SVG filter spec preset grades ride render-props as, and the .cube
+  // bake+hash LUT grades ride the mezzanine as.
+  CONFIG_DIR,
+  resolveColorGrade,
+  resolveGradeToLook,
+  gradeToSvgFilterSpec,
+  parseCubeLut,
+  bakeCube,
+  lutHash,
+  type ColorGrade,
+  type SvgGradeFilterSpec,
   scaleContentTimeline,
   scaleFramingWindows,
   measureFace,
@@ -237,6 +253,7 @@ import { RenderTimelineHUD, StageAnimator, printProductionCompleteBanner } from
 import { reconcileCaptionEdits } from "./caption-report";
 import { overridesWriteLine, writeOverrideDoc } from "./overrides-write";
 import { recordedProduceArgs } from "./replay-argv";
+import { remoteWhisperHost, resolveWhisperBackend } from "./whisper-backend";
 import { makeCancelSignal, renderCover, renderProduction } from "@ossclip/renderer";
 import type { RenderPhase } from "@ossclip/renderer";
 import {
@@ -299,6 +316,17 @@ export const TranscriptKeySchema = z.object({
    * files) means "no translation", the `dictionary` contract.
    */
   translate: z.boolean().optional(),
+  /**
+   * Which BACKEND decoded it (2026-09-01): `remote:<normalized endpoint>`, or
+   * absent for local whisper.cpp — the `dictionary`/`translate` contract, so
+   * every key file written before remote existed still reads as local. Two
+   * engines on the same audio produce different words, so without this a warm
+   * workdir serves the local transcript to a remote run (and vice versa) —
+   * the exact staleness `language` and `translate` were added for. The
+   * remote MODEL name rides in `model` above, so switching Groq models
+   * re-keys through the existing field.
+   */
+  backend: z.string().optional(),
 });
 export type TranscriptKey = z.infer<typeof TranscriptKeySchema>;
 
@@ -326,6 +354,10 @@ export function transcriptCacheReusable(
       // Absent and false are the same "no translation", so pre-flag key
       // files reuse under a non-translate request.
       (effective.translate ?? false) === (requested.translate ?? false) &&
+      // Absent means LOCAL on both sides, so every pre-2026-09-01 key file
+      // still reuses under a local request — and a remote request against
+      // one of them re-transcribes, which is the point.
+      (effective.backend ?? "") === (requested.backend ?? "") &&
       // ORDER-SENSITIVE by choice: the dictionary becomes whisper's --prompt
       // text verbatim, so a reordered list genuinely is a different decoder
       // input — treating it as equal would serve a transcript biased by a
@@ -622,6 +654,13 @@ export interface ProduceOptions {
    * together (whisper decodes better knowing the source language).
    */
   whisperTranslate?: boolean;
+  /**
+   * `--whisper-backend`, already zod-parsed to the union by program.ts
+   * (2026-09-01 weak-CPU field report). Undefined means "not typed", which
+   * is what lets a configured `whisperUrl` select remote — the flag is
+   * mainly `local`, the per-run opt-out.
+   */
+  whisperBackend?: "local" | "remote";
   /**
    * Vocabulary terms for this run (`--dictionary`, F4 2026-08-16), already
    * split/trimmed by the action. Wholesale beats the config's `dictionary`
@@ -725,6 +764,16 @@ export interface ProduceOptions {
    * ignore an uploaded cover.
    */
   coverInVideo?: boolean;
+  /**
+   * `--color-grade <look>` / `--no-color-grade` — the watermark's tri-state
+   * carrying a VALUE: a string when typed (a preset id, or a `.cube`
+   * filename — `colorGradeFlagValue` classifies by extension), `false` for a
+   * typed --no-color-grade, undefined when neither so overrides.json and
+   * then the config's `colorGrade` decide (`resolveProductionColorGrade`).
+   * Deliberately unparsed in transit: validation warns-and-proceeds at the
+   * use site, because a grade typo must cost the look, never the run.
+   */
+  colorGrade?: string | false;
   /**
    * `--youtube` / `--no-youtube` tri-state, the watermark's exact contract:
    * true/false when TYPED, undefined when not — undefined lets the config's
@@ -861,6 +910,71 @@ export function resolveCoverInVideo(
   return flag ?? configValue === true;
 }
 
+/**
+ * `--color-grade`'s value classified into the ColorGradeSchema shape: a value
+ * ending in `.cube` names a LUT file in `~/.ossclip/luts`, anything else
+ * names a preset. Sniffed by extension rather than split into two flags
+ * because the user already knows which they typed — `kodak.cube` cannot be a
+ * preset id (presets never carry a dot) and a preset id cannot be a LUT
+ * (`.cube` is the one format the parser reads), so the classification is
+ * lossless. Case-insensitive on the extension: `KODAK.CUBE` is the same file
+ * on the case-preserving filesystems the LUT dir lives on. Validation is NOT
+ * here — the shape goes through `resolveColorGrade` like every other layer.
+ */
+export function colorGradeFlagValue(value: string): { preset?: string; lut?: string } {
+  return value.toLowerCase().endsWith(".cube") ? { lut: value } : { preset: value };
+}
+
+/**
+ * The effective color grade across all three surfaces — override > flag >
+ * config, `resolveWatermark`'s typed-beats-config precedence grown one layer:
+ * the overrides doc is the editor's per-project say, so it beats even a typed
+ * flag (the `resolveSrcTimingPins` rationale — a per-project decision made in
+ * the editor outranks a per-run flag, never merges with it). An explicit
+ * `false` at a switching layer (`colorGrade: false` in the doc, or a typed
+ * `--no-color-grade`) is OFF, not fall-through: "no grade" is a decision, and
+ * letting a lower layer overrule it would make the disable impossible to
+ * express.
+ *
+ * Every layer is validated through `resolveColorGrade`, and an INVALID layer
+ * is ignored — warned about by name, then the NEXT layer applies (decision
+ * 2026-08-30): the alternative, an invalid override going all the way to
+ * "off", would let one stale editor write silently strip the config grade a
+ * channel's whole look depends on. Warnings are RETURNED, not printed
+ * (`resolveSfxLevel`'s shape), so the whole matrix is testable without a TTY.
+ * `source` names the winning layer so the ▸ line can say where a grade came
+ * from — the watermark's "(from config; --no-… overrides)" visibility rule.
+ */
+export function resolveProductionColorGrade(p: {
+  override: ColorGrade | false | undefined;
+  flag: string | false | undefined;
+  config: unknown;
+}): { grade?: ColorGrade; source?: "override" | "flag" | "config"; warnings: string[] } {
+  const warnings: string[] = [];
+  if (p.override === false) return { warnings };
+  if (p.override !== undefined) {
+    // Schema-valid already (OverrideDocSchema parsed the doc), but the
+    // unknown-preset check lives in resolveColorGrade, not the schema — this
+    // is the layer where a preset the editor knew and this build doesn't
+    // falls through instead of failing the doc.
+    const r = resolveColorGrade(p.override, "overrides.json");
+    if (r.grade) return { grade: r.grade, source: "override", warnings };
+    if (r.warning) warnings.push(r.warning);
+  }
+  if (p.flag === false) return { warnings };
+  if (p.flag !== undefined) {
+    const r = resolveColorGrade(colorGradeFlagValue(p.flag), "--color-grade");
+    if (r.grade) return { grade: r.grade, source: "flag", warnings };
+    if (r.warning) warnings.push(r.warning);
+  }
+  // "config", not "config colorGrade": resolveColorGrade's warning already
+  // spells the key (`⚠ <source> colorGrade ignored — …`).
+  const r = resolveColorGrade(p.config, "config");
+  if (r.grade) return { grade: r.grade, source: "config", warnings };
+  if (r.warning) warnings.push(r.warning);
+  return { warnings };
+}
+
 /**
  * `--sfx-level` implies `--sfx`: typing a level is asking for sound effects,
  * and a run that quietly did nothing because the boolean was missing is the
@@ -2577,9 +2691,34 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         `--whisper-language overrides)`,
     );
   }
+  // Local whisper.cpp or an OpenAI-compatible server (2026-09-01 weak-CPU
+  // field report). Resolved BEFORE the key, like the language, so what
+  // actually decodes is what the cache is keyed on.
+  const backendPick = resolveWhisperBackend(opts.whisperBackend, cfg, process.env);
+  if (!backendPick.ok) throw new Error(backendPick.message);
+  const backend = backendPick.backend;
+  // BEFORE the key is built, so a translate request can never cross the
+  // cache with a remote one: the OpenAI-compatible API translates on a
+  // DIFFERENT endpoint with a DIFFERENT default model, and swapping both
+  // behind one flag would be a surprise rather than a convenience.
+  if (backend.kind === "remote" && opts.whisperTranslate === 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 requestedKey: TranscriptKey = {
-    model: requestedModel,
+    // The REMOTE model name when remote — one field, both engines, so an
+    // A/B between two Groq models re-keys the cache exactly like a local one.
+    model: backend.kind === "remote" ? backend.model : requestedModel,
     ...(whisperLang.language !== undefined ? { language: whisperLang.language } : {}),
+    // Spread-omitted on local so local key files stay byte-identical to
+    // every one written before remote existed (the translate posture). The
+    // URL goes through openaiTranscriptionsUrl so ".../v1" and ".../v1/"
+    // key identically — a trailing slash is not a different server.
+    ...(backend.kind === "remote"
+      ? { backend: `remote:${openaiTranscriptionsUrl(backend.baseUrl)}` }
+      : {}),
     // Omitted when off, so a non-translate run's key stays byte-identical to
     // every pre-flag key file (the dictionary posture).
     ...(opts.whisperTranslate === true ? { translate: true } : {}),
@@ -2617,51 +2756,100 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
           `re-transcribing with ${fmt(requestedKey)}`,
       );
     }
-    await preflight(
-      cfg.whisperPath,
-      "Run `ossclip setup`, install whisper.cpp yourself (https://github.com/ggml-org/whisper.cpp), or set OSSCLIP_WHISPER.",
-    );
-    const model = requestedKey.model;
-    // whisperModelPath/modelUrl are THE resolution and URL sources (shared
-    // with doctor and setup) — this error used to hold its own copy of the
-    // ggerganov URL, which 404'd for curated/custom names and the suggested
-    // `curl -L` then saved the 404 HTML as a fake model.
-    const modelPath = whisperModelPath(model, cfg.modelDir);
-    if (!existsSync(modelPath)) {
-      throw new Error(
-        `whisper model not found at ${modelPath}.\n` +
-          `Run \`ossclip setup${model === cfg.model ? "" : ` --model ${model}`}\` to download it — or manually:\n` +
-          `  curl -L -o ${modelPath} ${modelUrl(model, validModelSources(cfg.modelSources))}`,
+    if (backend.kind === "remote") {
+      // No whisper binary and no model file on this branch — the whole point
+      // of remote is that neither is installed (2026-09-01 field report).
+      // ffmpeg still is: the upload sidecar is an encode.
+      const host = remoteWhisperHost(backend.baseUrl);
+      const uploadPath = join(work, "audio-upload.ogg");
+      transcript = await phases.time("transcribe", async () => {
+        await encodeUploadAudio(tools, audioPath, uploadPath);
+        const bytes = statSync(uploadPath).size;
+        if (bytes > REMOTE_UPLOAD_MAX_BYTES) {
+          // Named here rather than paid for as somebody else's 413 after the
+          // whole upload: chunking is out of scope for v1, so the error has
+          // to carry both escape hatches itself.
+          throw new Error(
+            `the compressed audio is ${(bytes / 1_000_000).toFixed(1)} MB, over the ` +
+              `${(REMOTE_UPLOAD_MAX_BYTES / 1_000_000).toFixed(0)} MB single-file limit for remote ` +
+              `transcription (about 100 minutes of speech at this bitrate).\n` +
+              `Transcribe locally with --whisper-backend local, split the take, or point ` +
+              `OSSCLIP_WHISPER_URL at a server with a larger cap (Groq's dev tier allows 100 MB).`,
+          );
+        }
+        const anim = isInteractive()
+          ? new StageAnimator(
+              "REMOTE ASR",
+              `Transcribing via ${host} (${backend.model})...`,
+              "whisper",
+            ).start()
+          : null;
+        if (!anim) console.log(`▸ transcribing remotely (${host}, ${backend.model})…`);
+        try {
+          return await createOpenAiCompatibleProvider({
+            baseUrl: backend.baseUrl,
+            model: backend.model,
+            ...(backend.apiKey !== undefined ? { apiKey: backend.apiKey } : {}),
+          }).transcribe(uploadPath, {
+            // From the KEY, like the local branch: whatever re-keys the cache
+            // is what actually decoded, so the two can never disagree.
+            language: requestedKey.language,
+            prompt: whisperPromptFor(dictionary),
+          });
+        } finally {
+          // In a finally, unlike the local branch's trailing stop(): an HTTP
+          // failure here is EXPECTED (a wrong key, a rate limit), and a
+          // spinner still animating would overwrite the hint the user needs.
+          anim?.stop();
+        }
+      });
+    } else {
+      await preflight(
+        cfg.whisperPath,
+        "Run `ossclip setup`, install whisper.cpp yourself (https://github.com/ggml-org/whisper.cpp), or set OSSCLIP_WHISPER.",
       );
+      const model = requestedKey.model;
+      // whisperModelPath/modelUrl are THE resolution and URL sources (shared
+      // with doctor and setup) — this error used to hold its own copy of the
+      // ggerganov URL, which 404'd for curated/custom names and the suggested
+      // `curl -L` then saved the 404 HTML as a fake model.
+      const modelPath = whisperModelPath(model, cfg.modelDir);
+      if (!existsSync(modelPath)) {
+        throw new Error(
+          `whisper model not found at ${modelPath}.\n` +
+            `Run \`ossclip setup${model === cfg.model ? "" : ` --model ${model}`}\` to download it — or manually:\n` +
+            `  curl -L -o ${modelPath} ${modelUrl(model, validModelSources(cfg.modelSources))}`,
+        );
+      }
+      const whisperAnim = isInteractive()
+        ? new StageAnimator(
+            "WHISPER ASR",
+            `Transcribing audio stream with ${basename(modelPath)}...`,
+            "whisper",
+          ).start()
+        : null;
+      if (!whisperAnim) console.log(`▸ transcribing (${basename(modelPath)})…`);
+      transcript = await phases.time("transcribe", () =>
+        runWhisper(
+          {
+            whisperPath: cfg.whisperPath,
+            modelPath,
+            outBase: join(work, "whisper"),
+            // The RESOLVED language, not the raw flag — a config/model-implied
+            // code must reach the spawn exactly as it reached the cache key.
+            language: requestedKey.language,
+            // Vocabulary biasing (F4) — undefined for an empty dictionary, so
+            // the spawned args stay byte-identical to every pre-dictionary run.
+            // From the KEY, like the language: whatever re-keys the cache is
+            // what actually ran, so the two can never disagree.
+            ...(requestedKey.translate === true ? { translate: true } : {}),
+            prompt: whisperPromptFor(dictionary),
+          },
+          audioPath,
+        ),
+      );
+      if (whisperAnim) whisperAnim.stop();
     }
-    const whisperAnim = isInteractive()
-      ? new StageAnimator(
-          "WHISPER ASR",
-          `Transcribing audio stream with ${basename(modelPath)}...`,
-          "whisper",
-        ).start()
-      : null;
-    if (!whisperAnim) console.log(`▸ transcribing (${basename(modelPath)})…`);
-    transcript = await phases.time("transcribe", () =>
-      runWhisper(
-        {
-          whisperPath: cfg.whisperPath,
-          modelPath,
-          outBase: join(work, "whisper"),
-          // The RESOLVED language, not the raw flag — a config/model-implied
-          // code must reach the spawn exactly as it reached the cache key.
-          language: requestedKey.language,
-          // Vocabulary biasing (F4) — undefined for an empty dictionary, so
-          // the spawned args stay byte-identical to every pre-dictionary run.
-          // From the KEY, like the language: whatever re-keys the cache is
-          // what actually ran, so the two can never disagree.
-          ...(requestedKey.translate === true ? { translate: true } : {}),
-          prompt: whisperPromptFor(dictionary),
-        },
-        audioPath,
-      ),
-    );
-    if (whisperAnim) whisperAnim.stop();
     console.log(`▸ transcribed ${transcript.words.length} words`);
     await writeFile(transcriptKeyPath, JSON.stringify(requestedKey, null, 2));
   }
@@ -4714,6 +4902,88 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // on a bar-free source): there is no re-encode to scale, the render plays
   // the source itself, and the window emissions below must then stay in true
   // source pixels — which the identity `mezzFactor` below guarantees.
+  // ---- Color grade (`--color-grade` / config `colorGrade` / the editor's
+  // overrides.json) ---------------------------------------------------------
+  // Resolved HERE, before the mezzanine encode, because the feature's two
+  // halves split at exactly this seam: a PRESET grade rides render-props as
+  // an SVG filter spec (the props assembly below), while a LUT grade is baked
+  // INTO the mezzanine (ingest.ts's `lut` option) — ffmpeg's lut3d on the
+  // encode pass costs nothing per rendered frame, where a 33³ trilinear
+  // lookup in the browser would. Precedence and validation live in
+  // `resolveProductionColorGrade`; every warning it returns prints once here,
+  // and every failure path proceeds UNGRADED — a grade must cost the look at
+  // worst, never the run.
+  const gradeResolution = resolveProductionColorGrade({
+    override: overrideDoc.colorGrade,
+    flag: opts.colorGrade,
+    config: cfg.colorGrade,
+  });
+  for (const w of gradeResolution.warnings) console.log(w);
+  /** Preset grades: the spec render-props carries (absent = no grade). */
+  let colorGradeSpec: SvgGradeFilterSpec | undefined;
+  /** LUT grades: the baked .cube the mezzanine encode applies (absent = none). */
+  let gradeLut: { path: string; hash: string } | undefined;
+  if (gradeResolution.grade !== undefined) {
+    // The watermark's visibility rule: a grade sourced anywhere but the
+    // typed flag says so, so a config- or editor-sourced look never
+    // surprises the author on upload.
+    const gradeFromNote =
+      gradeResolution.source === "config"
+        ? " (from config; --no-color-grade overrides)"
+        : gradeResolution.source === "override"
+          ? " (editor override)"
+          : "";
+    const resolvedLook = resolveGradeToLook(gradeResolution.grade);
+    if (resolvedLook.kind === "preset") {
+      colorGradeSpec = gradeToSvgFilterSpec(resolvedLook);
+      console.log(`▸ color grade: ${gradeResolution.grade.preset}${gradeFromNote}`);
+    } else if (!mezzanineWillBuild) {
+      // --no-mezzanine on a bar-free source: the render plays the source
+      // file itself, so there is no encode to bake the LUT into. Warn and
+      // proceed ungraded rather than force a mezzanine the user refused.
+      console.log(
+        `⚠ color grade skipped — a .cube LUT is baked into the mezzanine, ` +
+          `and --no-mezzanine means this run doesn't build one`,
+      );
+    } else {
+      try {
+        // Basename only, enforced before any path math: `lut` is a NAME the
+        // schema documents as living in ~/.ossclip/luts, and resolving a
+        // separator-carrying value would turn a config key into a file probe
+        // (the SfxAddedPlacement id's "nothing may ever resolve a path
+        // against it" rule, applied at the one place this name meets the
+        // filesystem).
+        if (basename(resolvedLook.lutRef) !== resolvedLook.lutRef) {
+          throw new Error(
+            `"${resolvedLook.lutRef}" is not a bare filename — LUTs live in ${join(CONFIG_DIR, "luts")}`,
+          );
+        }
+        const lutPath = join(CONFIG_DIR, "luts", resolvedLook.lutRef);
+        const baseLut = parseCubeLut(readFileSync(lutPath, "utf8"));
+        // Tweaks + intensity are baked into the cube (bakeCube composes
+        // `params` on top of the base sample), so the hash keys the WHOLE
+        // grade: change the intensity and the mezzanine filename changes
+        // with it (`mezzanineFileName`'s existence-keyed cache).
+        const cubeText = bakeCube({
+          base: baseLut,
+          params: resolvedLook.tweaks,
+          intensity: resolvedLook.intensity,
+        });
+        const hash = lutHash(cubeText);
+        const bakedPath = join(work, `grade-${hash}.cube`);
+        await writeFile(bakedPath, cubeText);
+        gradeLut = { path: bakedPath, hash };
+        console.log(`▸ color grade: LUT ${resolvedLook.lutRef}${gradeFromNote}`);
+      } catch (err) {
+        // ENOENT and a malformed .cube land here alike: name the problem,
+        // proceed ungraded. parseCubeLut's errors already carry the line.
+        console.log(
+          `⚠ color grade skipped — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
   const mezzScale = mezzanineWillBuild
     ? mezzanineScale(
         { width: contentRect.w, height: contentRect.h, fps: sourceProbe.fps },
@@ -4726,7 +4996,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // why): mezzanine caching is existence-keyed, so a pre-pass full-res
     // mezzanine.mp4 must not satisfy a run that emits mezzanine-sized
     // windows — the scaled file rebuilds once under its own name.
-    const mezz = join(work, mezzanineFileName(!contentRect.full, mezzScale));
+    // `gradeLut?.hash` rides the name so a graded mezzanine can never satisfy
+    // an ungraded run (or vice versa) — the LUT is pixels in the file, and
+    // the cache is existence-keyed.
+    const mezz = join(work, mezzanineFileName(!contentRect.full, mezzScale, gradeLut?.hash));
     if (!existsSync(mezz)) {
       const mezzAnim = isInteractive()
         ? new StageAnimator(
@@ -4747,6 +5020,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       await makeMezzanine(tools, input, mezz, {
         cropVf: cropVf || undefined,
         scale: mezzScale ?? undefined,
+        // The LUT grade's whole delivery: baked into the encode, so the
+        // render (and the editor's preview, which plays the same file) see
+        // graded pixels with no per-frame cost.
+        lut: gradeLut,
       });
       if (mezzAnim) mezzAnim.stop();
     }
@@ -5069,6 +5346,14 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // one, and the composition reads an absent key as silence, not as an empty
     // track it still has to mount.
     ...(sfxCues.length > 0 ? { sfxCues } : {}),
+    // `--color-grade` PRESET looks, written only when one resolved (the
+    // watermark's absent-means-off contract): the two-stage SVG filter spec
+    // ({tableR, tableG, tableB, colorMatrix}, gradeToSvgFilterSpec) the
+    // composition mounts over the video. A LUT grade deliberately writes
+    // NOTHING here — it was baked into the mezzanine above, so the pixels
+    // the renderer plays already carry it, and a spec on top would grade
+    // twice.
+    ...(colorGradeSpec ? { colorGrade: colorGradeSpec } : {}),
   };
   await writeFile(join(work, "render-props.json"), JSON.stringify(props, null, 2));
 

package/src/program.ts

@@ -411,6 +411,12 @@ export function buildProgram(): Command {
         "(whisper's -tr; pair with --whisper-language for the SOURCE language)",
       false,
     )
+    .option(
+      "--whisper-backend <backend>",
+      "local | remote. local (default) runs whisper.cpp on this machine; remote posts the " +
+        "audio to the OpenAI-compatible server in OSSCLIP_WHISPER_URL (config: whisperUrl) — " +
+        "configuring that URL already implies remote, so this flag is mainly `local` to opt out",
+    )
     // COMMA-SEPARATED in one value, not variadic: a variadic option swallows
     // the optional positional [input] whenever the flag precedes the path,
     // and commander offers no way to give the positional priority.
@@ -472,6 +478,21 @@ export function buildProgram(): Command {
         "(set it once with coverInVideo: true in ~/.ossclip/config.json)",
     )
     .option("--no-cover-in-video", "no cover overlay, even when the config turns it on")
+    // The watermark's tri-state carrying a VALUE: commander folds the pair
+    // onto one key (string when typed, false for --no-color-grade, undefined
+    // when neither — which is what lets overrides.json and then the config's
+    // `colorGrade` decide). The value is NOT parsed here, unlike --sfx-level:
+    // it may be a preset id OR a .cube filename, so an enum parse can't hold
+    // it — classification and validation live at the consumer
+    // (colorGradeFlagValue / resolveProductionColorGrade in produce.ts),
+    // where a typo warns and the run proceeds ungraded rather than dying.
+    .option(
+      "--color-grade <look>",
+      "color grade the footage: a preset (talking-head | teal-orange | filmic-fade | " +
+        "cwa | punchy | mono) or a .cube LUT filename from ~/.ossclip/luts " +
+        '(set it once with colorGrade: {"preset": "..."} in ~/.ossclip/config.json)',
+    )
+    .option("--no-color-grade", "no color grade, even when the config sets one")
     // Same tri-state shape as --watermark above (positive declared first so
     // commander's default stays undefined = "not typed"): the config's
     // `youtube` key supplies the default (resolveYoutube), and a typed
@@ -646,6 +667,14 @@ export function buildProgram(): Command {
         opts.whisperLanguage !== undefined
           ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
           : undefined;
+      // An enum, unlike --whisper-language: there are exactly two backends,
+      // and a typo'd `--whisper-backend groq` silently running local whisper
+      // on the weak CPU the flag exists to spare is the --source-fit crop
+      // all over again.
+      const whisperBackend =
+        opts.whisperBackend !== undefined
+          ? z.enum(["local", "remote"]).parse(opts.whisperBackend)
+          : undefined;
       // --add-jump-cuts / --no-jump-cuts land on DIFFERENT commander keys
       // (see the option declarations for why the pair can't share one);
       // jumpCutsFlag reunites them into the tri-state ProduceOptions
@@ -705,6 +734,9 @@ export function buildProgram(): Command {
           whisperModel: opts.whisperModel,
           whisperLanguage,
           whisperTranslate: opts.whisperTranslate === true,
+          // undefined = "not typed", so a configured whisperUrl decides
+          // (resolveWhisperBackend at the use site).
+          whisperBackend,
           // Split/trim/drop-empties (dictionaryFlag) — undefined stays
           // undefined so the config's dictionary can supply the default.
           dictionary: dictionaryFlag(opts.dictionary),
@@ -722,6 +754,12 @@ export function buildProgram(): Command {
           // The watermark's tri-state again, resolved by resolveCoverInVideo
           // at the use site against the config's `coverInVideo`.
           coverInVideo: opts.coverInVideo,
+          // string | false | undefined straight through: undefined = "not
+          // typed" lets overrides.json and then the config's `colorGrade`
+          // decide, and the value itself is classified and validated at the
+          // use site (resolveProductionColorGrade) — see the option's own
+          // comment for why no parse happens here.
+          colorGrade: opts.colorGrade,
           // The same tri-state contract as watermark, resolved by
           // resolveYoutube at the use site; --portrait rides along untyped =
           // undefined so the config's path can supply it.
@@ -834,6 +872,15 @@ export function buildProgram(): Command {
         "(whisper's -tr; pair with --whisper-language for the SOURCE language)",
       false,
     )
+    .option(
+      "--whisper-backend <backend>",
+      // Same sentence as produce's, deliberately: `transcribe` is the command
+      // a user drives while SETTING remote transcription up, so the half that
+      // says the URL is the real switch cannot be the half that is dropped here.
+      "local | remote. local (default) runs whisper.cpp on this machine; remote posts the " +
+        "audio to the OpenAI-compatible server in OSSCLIP_WHISPER_URL (config: whisperUrl) — " +
+        "configuring that URL already implies remote, so this flag is mainly `local` to opt out",
+    )
     .action(async (input: string, opts) => {
       const cleanup = CleanupLevelSchema.parse(opts.cleanup);
       const result = await produce(input, {
@@ -850,6 +897,12 @@ export function buildProgram(): Command {
           opts.whisperLanguage !== undefined
             ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
             : undefined,
+        // Parsed, not coerced — produce's reasoning: a typo must error, not
+        // fall back to the local backend the flag exists to avoid.
+        whisperBackend:
+          opts.whisperBackend !== undefined
+            ? z.enum(["local", "remote"]).parse(opts.whisperBackend)
+            : undefined,
       });
       telemetry.record("transcribe_completed", {
         cleanup_level: cleanup,
@@ -886,6 +939,15 @@ export function buildProgram(): Command {
       "--whisper-language <code>",
       "transcription language code for a multilingual model, e.g. ur | de | auto (whisper defaults to en)",
     )
+    .option(
+      "--whisper-backend <backend>",
+      // Same sentence as produce's, deliberately: `transcribe` is the command
+      // a user drives while SETTING remote transcription up, so the half that
+      // says the URL is the real switch cannot be the half that is dropped here.
+      "local | remote. local (default) runs whisper.cpp on this machine; remote posts the " +
+        "audio to the OpenAI-compatible server in OSSCLIP_WHISPER_URL (config: whisperUrl) — " +
+        "configuring that URL already implies remote, so this flag is mainly `local` to opt out",
+    )
     .option(
       "--blooper-marker <word>",
       "mark the flubbed take wherever you say this word out loud (e.g. blooper). Off unless given",
@@ -914,6 +976,12 @@ export function buildProgram(): Command {
             opts.whisperLanguage !== undefined
               ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
               : undefined,
+          // Parsed, not coerced — produce's reasoning: a typo must error, not
+          // fall back to the local backend the flag exists to avoid.
+          whisperBackend:
+            opts.whisperBackend !== undefined
+              ? z.enum(["local", "remote"]).parse(opts.whisperBackend)
+              : undefined,
           blooperMarker: opts.blooperMarker,
           collapseRetakes: opts.collapseRetakes,
           sort: opts.sort === "mtime" ? "mtime" : "name",

package/src/setup/plan.ts

@@ -9,6 +9,7 @@ import {
   whisperAsset,
   whisperModelPath,
 } from "./manifest";
+import { resolveWhisperBackend } from "../whisper-backend";
 
 /**
  * The planning half of `ossclip setup` — pure over injected probes, like
@@ -111,10 +112,25 @@ export async function planSetup(
     }
   }
 
+  // Remote transcription (2026-09-01 weak-CPU field report) makes whisper.cpp
+  // and the model OPTIONAL: on the machine the report came from, downloading
+  // a 1.5 GB model to run an engine that is too slow to use is exactly the
+  // cliff remote exists to remove. Reported as `satisfied` with the reason,
+  // never as a silent skip — and a local install that ALREADY works still
+  // reports itself (ground rule one: setup never uninstalls, and a user who
+  // has both keeps the `--whisper-backend local` escape hatch working).
+  const remote = resolveWhisperBackend(undefined, cfg, p.env);
+  const remoteDetail =
+    remote.ok && remote.backend.kind === "remote"
+      ? `remote transcription configured (${remote.backend.baseUrl}) — local whisper not needed`
+      : null;
+
   const whisperOk = await p.binRuns(cfg.whisperPath, "--help");
   const whisperForceable = isManaged(cfg.whisperPath, opts.configDir);
   if (whisperOk && !(opts.force && whisperForceable)) {
     steps.push({ kind: "whisper", status: "satisfied", detail: cfg.whisperPath });
+  } else if (remoteDetail !== null) {
+    steps.push({ kind: "whisper", status: "satisfied", detail: remoteDetail });
   } else {
     const asset = whisperAsset(p.platform, p.arch);
     if (asset) {
@@ -153,6 +169,8 @@ export async function planSetup(
   const known = MODELS[model];
   if (p.exists(modelPath)) {
     steps.push({ kind: "model", status: "satisfied", detail: modelPath });
+  } else if (remoteDetail !== null) {
+    steps.push({ kind: "model", status: "satisfied", detail: remoteDetail });
   } else if (isAbsolute(model)) {
     steps.push({
       kind: "model",