ossclip 0.1.36 → 0.1.38

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;
+  }
+}