ossclip 0.1.36 → 0.1.37

package/README.md

@@ -2,7 +2,7 @@
 
 **A local-first CLI that turns a talking-head take into a finished short.** It cuts silence and filler words, writes word-timed kinetic captions, frames on the measured face, and has an LLM plan **code-rendered on-screen graphics** — title cards, stat cards, diagrams, terminal and chat mockups — from what was actually said.
 
-Transcription is local (whisper.cpp), rendering is local (Remotion); the only network calls are the LLM planning ones, on your own key or your existing Claude Code / Google Antigravity subscription. Vertical 9:16 by default, landscape 16:9 with `--aspect`.
+Transcription is local (whisper.cpp — a remote server is opt-in, see below), rendering is local (Remotion); the only network calls are the LLM planning ones, on your own key or your existing Claude Code / Google Antigravity subscription. Vertical 9:16 by default, landscape 16:9 with `--aspect`.
 
 ![Left: the raw take. Right: the same take after ossclip produce — cut down, reframed on the measured face, word-timed captions](https://raw.githubusercontent.com/AhsanAyaz/ossclip/main/docs/site/assets/before-after.gif)
 
@@ -40,8 +40,18 @@ ossclip edit "<work directory>"
 
 **Scope, honestly:** ossclip is at its best polishing a take you have already cut down. `--clip` selects a single strongest window from long-form input — one clip, not N.
 
+**Color grading:** `--color-grade <preset|file.cube>` grades the footage — six presets (`talking-head`, `teal-orange`, `filmic-fade`, `cwa`, `punchy`, `mono`), or any `.cube` LUT you drop in `~/.ossclip/luts`. Presets preview live in the editor, where intensity, exposure, temperature, saturation and contrast are sliders; a LUT bakes into the mezzanine at render time. `"colorGrade"` in `~/.ossclip/config.json` sets a channel's look once, and `--no-color-grade` is a hard off for one run.
+
+**Sound effects:** `--sfx` places whooshes, dings and risers on the beats the producer planned (`--sfx-level subtle|normal|meme` — `meme` is what unlocks the record scratch). Needs `--produce`. A CC0 starter pack ships with the CLI; your own packs live in `~/.ossclip/sfx`. The editor gets an SFX lane: retime, swap, gain, mute-with-a-way-back, or add one at the playhead, audible in the preview.
+
+**Keep a 4K source's pixels:** `--resolution auto` renders at what the source still has after the crop (capped at 2160, never under 1080p) instead of forcing 1080p — invisible on the platforms that cap at 1080p, real on YouTube. `1080` (default), `1440` and `2160` are the fixed choices.
+
+**Frame 1 is the cover on some platforms:** `--cover-in-video` overlays the cover image on the opening frames — nothing is inserted, the overlay ends at the first spoken word, so no audio or caption timing moves. Off by default; `"coverInVideo": true` in the config turns it on for good.
+
 **Keep your own editor:** `ossclip analyze` exports every suggested cut as a labelled span marker — reason, duration, confidence — in the dialect your NLE actually reads (`premiere-xml`, `resolve-edl` with colours, or `fcpxml` for Final Cut). Review the markers, cut in your own timeline; nothing is applied for you. Import steps per NLE are in the repo README.
 
+**Weak CPU?** On an older machine whisper is the dominant cost of a run, so transcription can go to any OpenAI-compatible `/v1/audio/transcriptions` server instead — [Groq](https://console.groq.com)'s free tier, or your own [speaches](https://github.com/speaches-ai/speaches)/whisper.cpp server, which needs no key. Export `OSSCLIP_WHISPER_URL` (plus `OSSCLIP_WHISPER_API_KEY` where the server wants one) and every run transcribes remotely; `--whisper-backend local` opts a single run back out, and `ossclip doctor` and `ossclip setup` stop asking for whisper.cpp and the model file. Your audio leaves the machine on that path — which is why it is off until you configure it. Caps and self-hosting notes in the repo README.
+
 AI can make mistakes: the cut, the captions and every graphic are generated — review the output before publishing.
 
 **Telemetry:** ossclip sends anonymous usage events (counts, durations, provider name) — never footage, transcripts, file names or paths. Turn it off any time with `ossclip telemetry off`, `OSSCLIP_TELEMETRY=0`, or `DO_NOT_TRACK=1`. Full detail in the repo README's Telemetry section.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "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.36",
-    "@ossclip/renderer": "0.1.36",
-    "@ossclip/scenes": "0.1.36"
+    "@ossclip/renderer": "0.1.37",
+    "@ossclip/core": "0.1.37",
+    "@ossclip/scenes": "0.1.37"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/analyze.ts

@@ -117,6 +117,9 @@ export interface AnalyzeOptions {
   noiseDb?: number;
   whisperModel?: string;
   whisperLanguage?: string;
+  /** `--whisper-backend`, already zod-parsed by program.ts; undefined lets a
+   *  configured `whisperUrl` decide (resolveWhisperBackend in produce). */
+  whisperBackend?: "local" | "remote";
   blooperMarker?: string;
   collapseRetakes?: boolean;
   sort?: "name" | "mtime";
@@ -157,6 +160,7 @@ export async function runAnalyze(
     noiseDb: opts.noiseDb,
     whisperModel: opts.whisperModel,
     whisperLanguage: opts.whisperLanguage,
+    whisperBackend: opts.whisperBackend,
     blooperMarker: opts.blooperMarker,
     collapseRetakes: opts.collapseRetakes,
     sort: opts.sort,

package/src/doctor.ts

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import type { OssclipConfig } from "@ossclip/core";
 import { modelUrl, validModelSources, whisperModelPath } from "./setup/manifest";
+import { WHISPER_API_KEY_ENV, resolveWhisperBackend } from "./whisper-backend";
 
 /**
  * `ossclip doctor` (R18 §90a): check every prerequisite and print the exact
@@ -106,12 +107,23 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
         }),
   });
 
+  // Remote transcription (2026-09-01 weak-CPU field report) makes the next
+  // two checks OPTIONAL rather than blocking: a machine that transcribes on
+  // Groq has no reason to own whisper.cpp or a 1.5 GB model, and doctor
+  // reporting two red lines on a working install is how a user concludes the
+  // tool is broken. The LLM-provider posture, one level up: pass with a
+  // detail that says why nothing is needed.
+  const remote = resolveWhisperBackend(undefined, cfg, p.env);
+  const remoteBackend = remote.ok && remote.backend.kind === "remote" ? remote.backend : null;
+  const notNeeded = (found: string): string =>
+    `${found} not found — not needed: remote transcription configured`;
+
   const whisperOk = await p.binRuns(cfg.whisperPath, "--help");
   checks.push({
     name: "whisper-cli",
-    ok: whisperOk,
-    detail: cfg.whisperPath,
-    ...(whisperOk
+    ok: whisperOk || remoteBackend !== null,
+    detail: whisperOk ? cfg.whisperPath : remoteBackend !== null ? notNeeded(cfg.whisperPath) : cfg.whisperPath,
+    ...(whisperOk || remoteBackend !== null
       ? {}
       : {
           fix: viaSetup(
@@ -134,9 +146,9 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
   const modelOk = p.exists(modelPath);
   checks.push({
     name: `whisper model (${cfg.model})`,
-    ok: modelOk,
-    detail: modelPath,
-    ...(modelOk
+    ok: modelOk || remoteBackend !== null,
+    detail: modelOk ? modelPath : remoteBackend !== null ? notNeeded(modelPath) : modelPath,
+    ...(modelOk || remoteBackend !== null
       ? {}
       : {
           fix: viaSetup(
@@ -146,6 +158,26 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
         }),
   });
 
+  // NO network call, unlike every other backend doctor could probe: a
+  // transcription request costs the user's metered free tier, and `doctor` is
+  // run repeatedly while fixing something else. This line reports the
+  // CONFIGURATION — the three things a 401 or a 404 would be about — and the
+  // provider's own status hints name the rest when a real run happens.
+  // Omitted entirely when remote is not configured: the local install is the
+  // default, and an extra "not configured" line for an opt-in feature is
+  // noise on every other machine.
+  if (remoteBackend !== null) {
+    checks.push({
+      name: "remote transcription",
+      ok: true,
+      detail:
+        `${remoteBackend.baseUrl} · model ${remoteBackend.model} · ` +
+        (remoteBackend.apiKey !== undefined
+          ? `${WHISPER_API_KEY_ENV} set`
+          : `no API key (fine for self-hosted; Groq needs ${WHISPER_API_KEY_ENV})`),
+    });
+  }
+
   // Provider, in the same order auto-detection uses (agy → claude CLI →
   // gemini key → anthropic key): subscription CLIs beat ambient env keys
   // since 2026-08 — a logged-in CLI is an explicit, already-paid choice

package/src/edit.ts

@@ -70,6 +70,11 @@ import {
   portraitMimeType,
   readCoverProvenance,
   runWhisper,
+  // The remote transcription backend (2026-09-01) — the span re-decode goes
+  // through it whenever `whisperUrl` is configured.
+  createOpenAiCompatibleProvider,
+  type TranscribeRequest,
+  type Transcript,
   SegmentSchema,
   spliceTranscript,
   TranscriptSchema,
@@ -116,6 +121,7 @@ import { expandHome } from "./paths";
 // produce all resolve through — a second copy here would send a user to a
 // model file the rest of the tool never looks for.
 import { modelImpliedLanguage, whisperModelPath } from "./setup/manifest";
+import { resolveWhisperBackend } from "./whisper-backend";
 import {
   PORTRAIT_OVERRIDE_BASENAME,
   portraitExtensionForMime,
@@ -198,6 +204,37 @@ export interface RetranscribeConfig {
   modelDir?: string;
   language?: unknown;
   dictionary?: unknown;
+  /** The remote-backend pair (2026-09-01): a configured URL means this span
+   *  is decoded by an OpenAI-compatible server instead of whisper.cpp, so the
+   *  server must see the same two keys `resolveWhisperBackend` reads. */
+  whisperUrl?: string;
+  whisperRemoteModel?: string;
+}
+
+/**
+ * The half of a range re-decode that is the same on BOTH backends: the
+ * decoder bias. Extracted (2026-09-01) so the remote path shares these rules
+ * verbatim instead of growing a second copy that drifts — the validation is
+ * the load-bearing part, and it is unchanged from the local-only version.
+ */
+function retranscribeBias(cfg: RetranscribeConfig): { language?: string; prompt?: string } {
+  const dict = Array.isArray(cfg.dictionary)
+    && cfg.dictionary.length > 0
+    && cfg.dictionary.every((t) => typeof t === "string" && t.trim().length > 0)
+    ? (cfg.dictionary as string[]).map((t) => t.trim())
+    : [];
+  // `cfg.model` can be absent on the remote backend (a machine that never
+  // installed a local model), and no model name implies no language.
+  const language = typeof cfg.language === "string" && cfg.language.trim().length > 0
+    ? cfg.language.trim()
+    : cfg.model !== undefined
+      ? modelImpliedLanguage(cfg.model)
+      : undefined;
+  const prompt = whisperPromptFor(dict);
+  return {
+    ...(language !== undefined ? { language } : {}),
+    ...(prompt !== undefined ? { prompt } : {}),
+  };
 }
 
 /**
@@ -238,21 +275,38 @@ export function retranscribeSettings(
         "then `ossclip setup` to install it.",
     };
   }
-  const dict = Array.isArray(cfg.dictionary)
-    && cfg.dictionary.length > 0
-    && cfg.dictionary.every((t) => typeof t === "string" && t.trim().length > 0)
-    ? (cfg.dictionary as string[]).map((t) => t.trim())
-    : [];
-  const language = typeof cfg.language === "string" && cfg.language.trim().length > 0
-    ? cfg.language.trim()
-    : modelImpliedLanguage(cfg.model);
-  const prompt = whisperPromptFor(dict);
   return {
     tools: { ffmpegPath: cfg.ffmpegPath, ffprobePath: cfg.ffprobePath },
     whisperPath: cfg.whisperPath,
     modelPath: whisperModelPath(cfg.model, cfg.modelDir),
-    ...(language !== undefined ? { language } : {}),
-    ...(prompt !== undefined ? { prompt } : {}),
+    ...retranscribeBias(cfg),
+  };
+}
+
+/**
+ * The same thing for the REMOTE backend (2026-09-01): no whisper binary and
+ * no model file, because the point of remote is that neither is installed —
+ * but ffmpeg still is, since the span is sliced out of `audio.wav` locally
+ * before it is uploaded.
+ *
+ * Pure, like its local twin: the whole "remote configured but ffmpeg isn't"
+ * corner is testable without a network.
+ */
+export function retranscribeRemoteSettings(
+  cfg: RetranscribeConfig,
+):
+  | { tools: { ffmpegPath: string; ffprobePath: string }; language?: string; prompt?: string }
+  | { error: string } {
+  if (!cfg.ffmpegPath || !cfg.ffprobePath) {
+    return {
+      error:
+        "ffmpeg is not configured — run `ossclip doctor` to see what is missing, " +
+        "then `ossclip setup` to install it. (Remote transcription still slices the span locally.)",
+    };
+  }
+  return {
+    tools: { ffmpegPath: cfg.ffmpegPath, ffprobePath: cfg.ffprobePath },
+    ...retranscribeBias(cfg),
   };
 }
 
@@ -484,6 +538,13 @@ export async function startEditServer(
      */
     sliceAudio?: typeof extractAudioSpan;
     runWhisper?: typeof runWhisper;
+    /**
+     * The remote backend's half of the `runWhisper` seam (2026-09-01): with a
+     * `whisperUrl` configured the span goes to an OpenAI-compatible server
+     * instead of whisper.cpp, and a test must be able to observe that —
+     * including the failure sentence — without a network or an API key.
+     */
+    transcribeRemote?: (wavPath: string, req: TranscribeRequest) => Promise<Transcript>;
     /**
      * The sound library the SFX routes serve (`loadCfg`'s rule applied to the
      * pack loader): tests inject a hand-written library over a tmp dir, so the
@@ -955,17 +1016,67 @@ export async function startEditServer(
                 error: "this workdir has no transcript.json to re-stamp — re-run `ossclip produce`.",
               });
             }
-            const settings = retranscribeSettings((opts.loadCfg ?? loadConfig)());
-            if ("error" in settings) return send(200, { ok: false, error: settings.error });
-            if (!existsSync(settings.modelPath)) {
-              // The `--transcript`-only install: whisper was never needed to
-              // make this project, so say what to run rather than 500ing.
-              return send(200, {
-                ok: false,
-                error:
-                  `whisper model not found at ${settings.modelPath} — run \`ossclip setup\` ` +
-                  `to download it.`,
+            const cfg = (opts.loadCfg ?? loadConfig)();
+            // Which engine re-decodes the span, resolved HERE rather than in
+            // retranscribeSettings (2026-09-01): the flag is a CLI thing and
+            // there is no CLI in this loop, so a configured `whisperUrl` is
+            // the whole switch. `undefined` as the flag can only answer ok —
+            // only an explicit `--whisper-backend remote` with nothing
+            // configured fails — so this is a narrowing, not a live branch.
+            const backendPick = resolveWhisperBackend(undefined, cfg, process.env);
+            if (!backendPick.ok) return send(200, { ok: false, error: backendPick.message });
+            const backend = backendPick.backend;
+            // One plan, two shapes: the local one needs a binary and a model
+            // file on disk, the remote one needs neither. Both need ffmpeg —
+            // the span is always sliced here.
+            let plan: {
+              tools: { ffmpegPath: string; ffprobePath: string };
+              language?: string;
+              prompt?: string;
+              decode: (wavPath: string, req: TranscribeRequest) => Promise<Transcript>;
+            };
+            if (backend.kind === "remote") {
+              const settings = retranscribeRemoteSettings(cfg);
+              if ("error" in settings) return send(200, { ok: false, error: settings.error });
+              const provider = createOpenAiCompatibleProvider({
+                baseUrl: backend.baseUrl,
+                model: backend.model,
+                ...(backend.apiKey !== undefined ? { apiKey: backend.apiKey } : {}),
               });
+              plan = {
+                ...settings,
+                // Uploaded AS-IS, no opus sidecar (produce's rule does not
+                // apply): a span is seconds long, so its wav is far under any
+                // upload cap and the encode would cost more than it saves.
+                decode: opts.transcribeRemote ?? ((wavPath, r) => provider.transcribe(wavPath, r)),
+              };
+            } else {
+              const settings = retranscribeSettings(cfg);
+              if ("error" in settings) return send(200, { ok: false, error: settings.error });
+              if (!existsSync(settings.modelPath)) {
+                // The `--transcript`-only install: whisper was never needed to
+                // make this project, so say what to run rather than 500ing.
+                return send(200, {
+                  ok: false,
+                  error:
+                    `whisper model not found at ${settings.modelPath} — run \`ossclip setup\` ` +
+                    `to download it.`,
+                });
+              }
+              plan = {
+                ...settings,
+                decode: (wavPath, r) =>
+                  (opts.runWhisper ?? runWhisper)(
+                    {
+                      whisperPath: settings.whisperPath,
+                      modelPath: settings.modelPath,
+                      outBase,
+                      ...(r.language !== undefined ? { language: r.language } : {}),
+                      ...(r.prompt !== undefined ? { prompt: r.prompt } : {}),
+                    },
+                    wavPath,
+                  ),
+              };
             }
             // Parsed, not cast: this file is about to be rewritten, and a
             // truncated one must fail loudly here rather than become the new
@@ -985,22 +1096,16 @@ export async function startEditServer(
               });
             }
             await (opts.sliceAudio ?? extractAudioSpan)(
-              settings.tools,
+              plan.tools,
               audio,
               tmpWav,
               srcIn,
               srcOut - srcIn,
             );
-            const fresh = await (opts.runWhisper ?? runWhisper)(
-              {
-                whisperPath: settings.whisperPath,
-                modelPath: settings.modelPath,
-                outBase,
-                ...(settings.language !== undefined ? { language: settings.language } : {}),
-                ...(settings.prompt !== undefined ? { prompt: settings.prompt } : {}),
-              },
-              tmpWav,
-            );
+            const fresh = await plan.decode(tmpWav, {
+              ...(plan.language !== undefined ? { language: plan.language } : {}),
+              ...(plan.prompt !== undefined ? { prompt: plan.prompt } : {}),
+            });
             const restamped = alignRestamp(
               transcript.words.slice(range.from, range.to),
               fresh.words,

package/src/interactive/produce-wizard.ts

@@ -10,7 +10,7 @@ import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-
 import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
 
 /**
- * The produce wizard. Forty-three flags (plus the positional input path)
+ * The produce wizard. Forty-four flags (plus the positional input path)
  * sorted into three tiers: six prompts asked directly — the input path, plus
  * five flags (--out, --cleanup, --aspect, --produce, --intent) — twelve
  * behind one "anything else?" multiselect (--sfx being the twelfth, with
@@ -28,7 +28,12 @@ import { assertInteractive, confirm, intro, multiselect, select, text, unwrap }
  * multiselect entry is the OFF switch and the positive flag exists only for
  * replay pinning), --add-jump-cuts (same mirror: auto already punches, the
  * multiselect entry is the OFF switch, and the force flag exists to beat a
- * future config-off), or
+ * future config-off),
+ * --whisper-backend (2026-09-01, the --color-grade shape: it selects machine
+ * INFRASTRUCTURE — which transcription engine this box owns, alongside
+ * whisperPath and modelDir — not a per-run editorial choice, and the durable
+ * spelling is `whisperUrl` in ~/.ossclip/config.json; an honest prompt would
+ * also have to explain a base URL and an API key at a menu), or
  * (final-review fix wave, Finding 1) --sort. A folder's clip order only means anything once the
  * folder has been enumerated, and that enumeration happens inside
  * `produce()` — after the wizard has already returned argv — so there is

package/src/produce.ts

@@ -66,6 +66,10 @@ import {
   splitThenDropHidden,
   emptyOverrideDoc,
   extractAudio,
+  encodeUploadAudio,
+  REMOTE_UPLOAD_MAX_BYTES,
+  createOpenAiCompatibleProvider,
+  openaiTranscriptionsUrl,
   fillPlainCues,
   splitCues,
   landscapeLayout,
@@ -249,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 {
@@ -311,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>;
 
@@ -338,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
@@ -634,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`
@@ -2664,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 } : {}),
@@ -2704,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));
   }

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.
@@ -661,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
@@ -720,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),
@@ -855,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, {
@@ -871,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,
@@ -907,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",
@@ -935,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",

package/src/whisper-backend.ts

@@ -0,0 +1,103 @@
+import type { OssclipConfig } from "@ossclip/core";
+
+/**
+ * Which transcription backend a run uses — local whisper.cpp (the default,
+ * forever) or an OpenAI-compatible `/v1/audio/transcriptions` server.
+ *
+ * Why (2026-09-01 field report): on a weak CPU — an i3 2nd gen — whisper is
+ * the dominant cost of a produce run, and Groq's free tier makes it seconds.
+ * Remote is OPT-IN: presence of a URL is the switch, so nobody's existing
+ * install changes behavior by upgrading.
+ *
+ * `publishConfigured`'s mould (publish.ts), with one deliberate difference:
+ * the API key is OPTIONAL. Self-hosted servers (speaches, whisper.cpp
+ * server) run keyless, so requiring a key the way publish does would lock
+ * out the privacy-minded half of the audience.
+ *
+ * Pure over (flag, config, env) so the whole matrix is testable without a
+ * config file or a poked process.env.
+ */
+
+/** Env-only, like every other secret (env.ts's rule): keys never live in config.json. */
+export const WHISPER_API_KEY_ENV = "OSSCLIP_WHISPER_API_KEY";
+
+/**
+ * Groq's word-timestamped turbo model — the one the quickstart in the README
+ * points at. The default lives HERE rather than in config.ts's DEFAULTS
+ * because it is only meaningful once a remote URL exists, and a self-hosted
+ * box (whose model names look like "Systran/faster-whisper-large-v3") sets
+ * `whisperRemoteModel` anyway.
+ */
+export const DEFAULT_REMOTE_WHISPER_MODEL = "whisper-large-v3-turbo";
+
+export type WhisperBackend =
+  | { kind: "local" }
+  | { kind: "remote"; baseUrl: string; model: string; apiKey?: string };
+
+export type WhisperBackendResult =
+  | { ok: true; backend: WhisperBackend }
+  | { ok: false; message: string };
+
+/**
+ * `--whisper-backend` (already zod-parsed by program.ts) beats the config,
+ * and "local" ALWAYS wins — it is the escape hatch a user reaches for when
+ * the remote server is down or the audio must not leave the machine, so it
+ * can never be overridden by a URL sitting in config.json.
+ *
+ * A typed `--whisper-backend remote` with nothing configured is an ERROR
+ * naming both spellings, not a silent fall back to local: the user asked for
+ * remote precisely because local is what they are trying to avoid.
+ */
+export function resolveWhisperBackend(
+  flag: "local" | "remote" | undefined,
+  cfg: Pick<OssclipConfig, "whisperUrl" | "whisperRemoteModel">,
+  env: NodeJS.ProcessEnv,
+): WhisperBackendResult {
+  if (flag === "local") return { ok: true, backend: { kind: "local" } };
+  // typeof + trim, never truthiness: `whisperUrl: "  "` in a hand-edited
+  // config.json must read as "not configured", not as a URL we then POST to.
+  const url = typeof cfg.whisperUrl === "string" ? cfg.whisperUrl.trim() : "";
+  if (url.length === 0) {
+    if (flag === "remote") {
+      return {
+        ok: false,
+        message:
+          "--whisper-backend remote needs a transcription server: set OSSCLIP_WHISPER_URL in the " +
+          'environment (or ~/.ossclip/.env), or "whisperUrl" in ~/.ossclip/config.json — the ' +
+          "OpenAI-compatible base ending in /v1, e.g. https://api.groq.com/openai/v1.",
+      };
+    }
+    return { ok: true, backend: { kind: "local" } };
+  }
+  const model =
+    typeof cfg.whisperRemoteModel === "string" && cfg.whisperRemoteModel.trim().length > 0
+      ? cfg.whisperRemoteModel.trim()
+      : DEFAULT_REMOTE_WHISPER_MODEL;
+  const key = env[WHISPER_API_KEY_ENV]?.trim() ?? "";
+  return {
+    ok: true,
+    backend: {
+      kind: "remote",
+      baseUrl: url,
+      model,
+      // Omitted rather than "" when unset, so the provider sends NO
+      // Authorization header at all — a keyless self-hosted server is a
+      // supported configuration, not a missing key.
+      ...(key.length > 0 ? { apiKey: key } : {}),
+    },
+  };
+}
+
+/**
+ * The host for a one-line stage/status label. Falls back to the raw string
+ * when `new URL` refuses it: the value is user-typed config, and a stage line
+ * must never be the thing that throws — the POST that follows will report a
+ * bad URL with far better context.
+ */
+export function remoteWhisperHost(baseUrl: string): string {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+}