ossclip 0.1.36 → 0.1.38

package/editor-dist/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ossclip editor</title>
-    <script type="module" crossorigin src="/assets/index-pWbFr8vc.js"></script>
+    <script type="module" crossorigin src="/assets/index-DpySfDtS.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Bx2VQLP8.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "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/core": "0.1.38",
+    "@ossclip/scenes": "0.1.38",
+    "@ossclip/renderer": "0.1.38"
   },
   "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));
   }