ossclip 0.1.24 → 0.1.26

package/src/program.ts

@@ -7,8 +7,9 @@ import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { ExportFormatSchema, runAnalyze } from "./analyze";
+import { expandHome } from "./paths";
 import { phaseBucketProps } from "./phase-timing";
-import { produce } from "./produce";
+import { dictionaryFlag, jumpCutsFlag, produce } from "./produce";
 // The one interactive import that is STATIC rather than `await import()`: the
 // `resetInputSource()` run boundary in `buildProgram` has to run synchronously
 // while the program is being built, and `buildProgram` cannot await. The graph
@@ -38,6 +39,27 @@ import {
 // order in `defaultProviderName`, which decides which model runs.
 const envFiles = loadEnvFiles();
 
+/**
+ * `--concurrency <n>` → a positive whole number of browser tabs (§93a: reject
+ * rather than coerce, the `--clip` idiom). A typo'd `--concurrency 4x` must
+ * not become NaN and reach Remotion as "however many you like" — the flag
+ * exists precisely because the automatic count killed a browser (2026-08-19
+ * field case; `resolveRenderConcurrency` has it). `Number`, not `parseInt`,
+ * so "4.5" and "" are errors rather than a silent 4 and a silent 0.
+ *
+ * Exported so the rejection matrix is testable without commander's exit
+ * behaviour in the way.
+ */
+export function concurrencyFlag(v: string): number {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new InvalidArgumentError(
+      `--concurrency wants a positive whole number of browser tabs, got "${v}"`,
+    );
+  }
+  return n;
+}
+
 /**
  * Every command this CLI has, built onto a fresh instance.
  *
@@ -160,6 +182,11 @@ export function buildProgram(): Command {
           modelDir: cfg.modelDir,
           input: path,
           watermark: cfg.watermark,
+          // The youtube follow-ups skip what the config already supplies
+          // (youtubeFollowups) — same reason speaker prefills above.
+          audience: cfg.audience,
+          portrait: cfg.portrait,
+          thumbnailBrief: cfg.thumbnailBrief,
         });
         console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
         setReplayArgv(argv); // §129
@@ -195,6 +222,9 @@ export function buildProgram(): Command {
         speaker: cfg.speaker,
         modelDir: cfg.modelDir,
         watermark: cfg.watermark,
+        audience: cfg.audience,
+        portrait: cfg.portrait,
+        thumbnailBrief: cfg.thumbnailBrief,
       });
       console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
       setReplayArgv(argv); // §129
@@ -286,6 +316,17 @@ export function buildProgram(): Command {
       "--whisper-language <code>",
       "transcription language code for a multilingual model, e.g. ur | de | auto (whisper defaults to en)",
     )
+    // 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.
+    .option(
+      "--dictionary <terms>",
+      'comma-separated terms of art the speaker uses, e.g. "JSON, ossclip, Genkit" — ' +
+        "biases transcription toward these spellings, vouches them for repair, and " +
+        "canonicalizes their casing in captions. Replaces the config's dictionary for " +
+        "this run. Needs a whisper-cli new enough to know --prompt (older builds " +
+        "reject it with their own error)",
+    )
     .option(
       "--force-component <id>",
       "debug: render every graphic with this component (e.g. FlowDiagram) to exercise it on real copy",
@@ -308,8 +349,9 @@ export function buildProgram(): Command {
     )
     .option(
       "--collapse-retakes",
-      "deterministically collapse consecutive near-identical sentences, keeping only " +
-        "the last complete attempt — the flub the speaker did NOT mark. Off by default",
+      "legacy no-op: retake collapsing runs automatically with --blooper-marker " +
+        "(bloopers and retakes go hand-in-hand — no marker, no retake cuts). " +
+        "Kept parseable so recorded command.json replays don't error",
       false,
     )
     // Declared as the same tri-state pair as --open-editor/--no-open-editor:
@@ -323,6 +365,35 @@ export function buildProgram(): Command {
     )
     .option("--no-watermark", "no wordmark, even when the config turns it on")
     // 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
+    // --no-youtube still beats a config-on.
+    .option(
+      "--youtube",
+      "write a YouTube pack beside the video: SEO title options, description, hashtags " +
+        "and comma-separated tags (<out>.youtube.md), plus an AI thumbnail " +
+        "(set it once with youtube: true in ~/.ossclip/config.json)",
+    )
+    .option("--no-youtube", "no YouTube pack, even when the config turns it on")
+    .option(
+      "--portrait <path>",
+      "your portrait photo, the likeness reference for the --youtube AI thumbnail " +
+        "(default: `portrait` in ~/.ossclip/config.json; without one the frame-grab " +
+        "cover stands)",
+    )
+    .option(
+      "--audience <text>",
+      'who watches the channel, e.g. "junior web devs learning AI tooling" — steers ' +
+        "the --youtube pack's titles/tags and the AI thumbnail's concept " +
+        "(default: `audience` in ~/.ossclip/config.json)",
+    )
+    .option(
+      "--thumbnail-brief <text>",
+      "a standing instruction the AI thumbnail concept must honor, e.g. " +
+        '"always show the terminal, never stock imagery" ' +
+        "(default: `thumbnailBrief` in ~/.ossclip/config.json)",
+    )
+    // Same tri-state shape as --watermark above (positive declared first so
     // commander's default stays undefined = "not typed"), though captions
     // have no config key to fill the gap: the tri-state exists so
     // command.json can pin the resolved flag state for replay determinism
@@ -336,6 +407,24 @@ export function buildProgram(): Command {
       "--no-captions",
       "no burned-in captions. The CTA keyword styling rides the caption track, so it goes too",
     )
+    // A tri-state like --watermark/--captions above, but on TWO commander
+    // keys instead of one: the positive is spelled --add-jump-cuts (bare
+    // "--jump-cuts" would read as adding CUTS, not the concealing zooms), so
+    // commander cannot fold the pair onto one key — --no-jump-cuts creates
+    // `jumpCuts` defaulting TRUE, --add-jump-cuts lands on `addJumpCuts`,
+    // and the action below reunites them via jumpCutsFlag, reading
+    // getOptionValueSource to tell a typed --no-jump-cuts from the default.
+    .option(
+      "--add-jump-cuts",
+      "force the subtle punch-in zooms that conceal jump cuts (already the default). " +
+        "The face-only guard still applies — a screen share is never punched, because " +
+        "the zoom slides its content — this only beats a config that turns them off",
+    )
+    .option(
+      "--no-jump-cuts",
+      "no punch-in zooms at cut boundaries. Narrower than --no-zoom, which kills ALL " +
+        "camera motion (the idle push included), not just the cut punch-in",
+    )
     .option("--no-cover", "skip the cover image written beside the video")
     .option(
       "--no-zoom",
@@ -350,6 +439,20 @@ export function buildProgram(): Command {
     )
     .option("--editor-port <n>", "port for the editor started by --open-editor",
       (v) => Number.parseInt(v, 10), 5174)
+    // No default: undefined = "not typed" is what lets the config's
+    // renderConcurrency (and then the cpus-2 guess) supply the value —
+    // resolveRenderConcurrency owns the precedence. Recorded runs need nothing
+    // special to replay it: command.json stores the argv verbatim
+    // (recordedProduceArgs), so a typed --concurrency is already in there, and
+    // the editor's Render replays it through THIS parse.
+    .option(
+      "--concurrency <n>",
+      "how many browser tabs render frames in parallel (default: CPU cores - 2, " +
+        "floor 2). Turn it DOWN if the render logs 'The browser crashed while " +
+        "rendering frame N' — that is the whole browser running out of memory, " +
+        "not one frame failing",
+      concurrencyFlag,
+    )
     .action(async (input: string | undefined, opts, command: Command) => {
       if (input === undefined) {
         // commander 12's parseAsync does not reset option state between calls,
@@ -377,6 +480,9 @@ export function buildProgram(): Command {
           speaker: cfg.speaker,
           modelDir: cfg.modelDir,
           watermark: cfg.watermark,
+          audience: cfg.audience,
+          portrait: cfg.portrait,
+          thumbnailBrief: cfg.thumbnailBrief,
         });
         console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
         // Re-entering the SAME parse the flags take: the zod checks below run
@@ -413,6 +519,15 @@ export function buildProgram(): Command {
         opts.whisperLanguage !== undefined
           ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
           : 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
+      // carries, and throws on the contradiction of typing both — the same
+      // loud-error posture as every parse above.
+      const jumpCuts = jumpCutsFlag(
+        opts.addJumpCuts,
+        command.getOptionValueSource("jumpCuts") === "cli",
+      );
       // Wall clock around produce() only — the editor offer below can sit at
       // an interactive prompt for as long as the user thinks, and think-time
       // would poison the duration metric (FINDINGS §134).
@@ -439,6 +554,9 @@ export function buildProgram(): Command {
           repair: opts.repair,
           whisperModel: opts.whisperModel,
           whisperLanguage,
+          // Split/trim/drop-empties (dictionaryFlag) — undefined stays
+          // undefined so the config's dictionary can supply the default.
+          dictionary: dictionaryFlag(opts.dictionary),
           forceComponent,
           // commander gives `--no-cover` as cover:false and `--cover <path>` as a
           // string on the same key.
@@ -450,13 +568,29 @@ export function buildProgram(): Command {
           zoom: opts.zoom,
           // undefined = "not typed", so produce can let the config decide.
           watermark: opts.watermark,
+          // 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.
+          youtube: opts.youtube,
+          portrait: opts.portrait,
+          // Typed-beats-config strings like --portrait: untyped = undefined
+          // lets the config's `audience`/`thumbnailBrief` supply them; the
+          // `typeof === "string"` validation lives at the use site.
+          audience: opts.audience,
+          thumbnailBrief: opts.thumbnailBrief,
           // undefined = "not typed" here too — the default (ON) is applied at
           // the pin site, not coerced in transit.
           captions: opts.captions,
+          // The reunited tri-state (jumpCutsFlag above): undefined = "not
+          // typed" = auto, the face-only default.
+          jumpCuts,
           cover: opts.cover !== false,
           coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
           clip: opts.clip,
           clipWindow: opts.clipWindow,
+          // Validated by concurrencyFlag at parse time; undefined = "not
+          // typed", which is what lets the config supply it.
+          concurrency: opts.concurrency,
         });
         // Counts, buckets and names only — the duration crosses the wire as a
         // bucket, and nothing here can carry a path (assertSafeProps enforces
@@ -576,7 +710,7 @@ export function buildProgram(): Command {
     )
     .option(
       "--collapse-retakes",
-      "also mark consecutive near-identical sentences, keeping only the last complete attempt",
+      "legacy no-op: retake marking runs automatically with --blooper-marker",
       false,
     )
     .option("--sort <order>", "folder input: clip order, name | mtime", "name")
@@ -630,8 +764,10 @@ export function buildProgram(): Command {
     .argument("<renderProps>", "path to a work dir's render-props.json")
     .option("--video-dir <dir>", "directory containing the source video (public dir)")
     .action(async (renderProps: string, opts) => {
-      const propsPath = resolve(renderProps);
-      const publicDir = opts.videoDir ? resolve(opts.videoDir) : dirname(propsPath);
+      // expandHome before resolve on both user-typed paths (2026-08-16 rule,
+      // paths.ts) — a `~/` here must not resolve against cwd.
+      const propsPath = resolve(expandHome(renderProps));
+      const publicDir = opts.videoDir ? resolve(expandHome(opts.videoDir)) : dirname(propsPath);
       // Resolve Remotion's CLI through module resolution instead of spawning
       // `pnpm` — a global `npm i -g ossclip` has no pnpm and no workspace, and
       // Windows would need the .cmd shim. `@remotion/cli` is a dependency of

package/src/replay-argv.ts

@@ -17,6 +17,10 @@
  * the direct path byte-identical to what it always wrote.
  */
 
+// Type-only, so no runtime edge back into produce.ts (which imports this
+// module): the tri-state's vocabulary belongs to its resolver.
+import type { JumpCutsMode } from "./produce";
+
 let stashed: string[] | null = null;
 
 /**
@@ -53,6 +57,16 @@ export function recordedProduceArgs(pins: {
   clipWindow?: string;
   watermark?: boolean;
   captions?: boolean;
+  jumpCuts?: JumpCutsMode;
+  /** The RESOLVED dictionary terms — pinned only when non-empty. */
+  dictionary?: string[];
+  youtube?: boolean;
+  /** The RESOLVED portrait path — a path, never a secret. */
+  portrait?: string;
+  /** The RESOLVED audience text — pinned only when non-empty. */
+  audience?: string;
+  /** The RESOLVED thumbnail brief — pinned only when non-empty. */
+  thumbnailBrief?: string;
 }): string[] {
   const args = consumeReplayArgv() ?? process.argv.slice(2);
   if (pins.llm !== undefined && !args.includes("--llm")) {
@@ -89,5 +103,66 @@ export function recordedProduceArgs(pins: {
   if (pins.captions !== undefined && !args.includes("--captions") && !args.includes("--no-captions")) {
     args.push(pins.captions ? "--captions" : "--no-captions");
   }
+  // The jump-cuts pin covers the two TYPED states only — force spells
+  // --add-jump-cuts, off spells --no-jump-cuts, and either typed flag
+  // settles the tri-state, so the includes-guard checks BOTH spellings
+  // before appending either. "auto" stays UNPINNED, which is the captions
+  // rationale run in reverse: there is no flag that SPELLS auto to pin
+  // with, and with no config input today an argv carrying neither flag
+  // replays as auto identically everywhere. The captions comment's warning
+  // still applies — the day a jumpCuts config key lands, auto records made
+  // after it must pin their resolved on/off like the watermark's, and the
+  // old unpinned auto records are the accepted cost of a flag pair that
+  // reserves both spellings for the typed states.
+  if (
+    pins.jumpCuts !== undefined &&
+    pins.jumpCuts !== "auto" &&
+    !args.includes("--add-jump-cuts") &&
+    !args.includes("--no-jump-cuts")
+  ) {
+    args.push(pins.jumpCuts === "force" ? "--add-jump-cuts" : "--no-jump-cuts");
+  }
+  // The dictionary pin (review finding, F4 follow-up): the resolved terms may
+  // have come from ~/.ossclip/config.json, and the dictionary feeds the
+  // whisper prompt, the repair vouched set and caption casing — so an
+  // unpinned record replays a DIFFERENT transcript the moment that config is
+  // edited. Comma-joined into one value, the exact spelling `--dictionary`
+  // takes (dictionaryFlag re-splits and trims on replay). Empty stays
+  // unpinned: there is no flag spelling for "no terms", and `--dictionary ""`
+  // would split to [] anyway — an argv without the flag replays as "config
+  // decides", the accepted cost mirroring jump-cuts' unpinnable auto.
+  if (pins.dictionary !== undefined && pins.dictionary.length > 0 && !args.includes("--dictionary")) {
+    args.push("--dictionary", pins.dictionary.join(", "));
+  }
+  // The youtube pin — the watermark's rationale verbatim: its effective
+  // default is config-dependent (`youtube: true` in ~/.ossclip/config.json),
+  // so every record carries the RESOLVED state in BOTH directions, or a
+  // later config edit silently changes what the editor's Render writes
+  // beside the replayed video.
+  if (pins.youtube !== undefined && !args.includes("--youtube") && !args.includes("--no-youtube")) {
+    args.push(pins.youtube ? "--youtube" : "--no-youtube");
+  }
+  // The portrait pin: the resolved PATH (never a secret — the API key stays
+  // in the environment), so a replay renders the thumbnail from the same
+  // face the run did even after the config's `portrait` moves.
+  if (pins.portrait !== undefined && !args.includes("--portrait")) {
+    args.push("--portrait", pins.portrait);
+  }
+  // Audience and thumbnail-brief pins, the portrait's rationale exactly: the
+  // resolved values may have come from ~/.ossclip/config.json, and both steer
+  // LLM prompts (the youtube pack, the thumbnail concept) — an unpinned
+  // record would replay different metadata after a config edit. Empty stays
+  // unpinned, the dictionary's rule: there is no flag spelling for "no
+  // steer", and an argv without the flag replays as "config decides".
+  if (pins.audience !== undefined && pins.audience.length > 0 && !args.includes("--audience")) {
+    args.push("--audience", pins.audience);
+  }
+  if (
+    pins.thumbnailBrief !== undefined &&
+    pins.thumbnailBrief.length > 0 &&
+    !args.includes("--thumbnail-brief")
+  ) {
+    args.push("--thumbnail-brief", pins.thumbnailBrief);
+  }
   return args;
 }

package/src/setup/manifest.ts

@@ -13,6 +13,9 @@
  * platform×arch resolves to either an asset or an explicit manual hint.
  */
 
+import { basename, isAbsolute, join } from "node:path";
+import { z } from "zod/v4";
+
 export interface BinaryAsset {
   url: string;
   sha256: string;
@@ -135,10 +138,24 @@ export function whisperAsset(platform: NodeJS.Platform, arch: string): BinaryAss
  * models/README.md — upstream publishes SHA-1, so that's what we verify;
  * it's an integrity check against truncated downloads, not a security
  * boundary (the download is already pinned to a host and path over HTTPS).
+ *
+ * Curated fine-tunes ride the same table: `url` points at their own host
+ * (ggerganov's mirror only carries the stock models — the old hardcoded URL
+ * 404'd for every custom name, and the suggested `curl -L` then saved the
+ * 404 HTML as a fake model), and `language` records what the fine-tune
+ * decodes so produce can imply `-l` when nothing else sets one (an Urdu
+ * fine-tune without `-l ur` silently decodes English garbage — Urdu field
+ * test 2026-08-05).
  */
 export interface ModelInfo {
-  sizeMB: number;
-  sha1: string;
+  sizeMB?: number;
+  sha1?: string;
+  /** Direct download URL for models the ggerganov mirror doesn't host. */
+  url?: string;
+  /** The language the fine-tune decodes — implied `-l` when neither flag nor config sets one. */
+  language?: string;
+  /** Provenance, printed by setup at download time and shown as the wizard hint. */
+  note?: string;
 }
 
 export const MODELS: Record<string, ModelInfo> = {
@@ -146,10 +163,82 @@ export const MODELS: Record<string, ModelInfo> = {
   "base.en": { sizeMB: 142, sha1: "137c40403d78fd54d454da0f9bd998f78703390c" },
   "small.en": { sizeMB: 466, sha1: "db8a495a91d927739e50b3fc1cc4c6b8f6c2d022" },
   "medium.en": { sizeMB: 1536, sha1: "8c30f0e44ce9560643ebd10bbe50cd20eafd3723" },
+  // URL pending the author's upload (2026-08-17) — sha1 added when the file
+  // is published; setup already warns-and-continues without a checksum.
+  "medium-urdu": {
+    sizeMB: 1463,
+    // sha1 computed 2026-08-17 from the author's converted file BEFORE the HF
+    // upload — same bytes, so the pin is valid the moment the file publishes,
+    // and a corrupted/tampered mirror download fails the checksum loudly.
+    sha1: "59769d590f62eeeb3bc3f5b82ce8c03b6e96831e",
+    language: "ur",
+    note: "community Urdu fine-tune (Abdul145/whisper-medium-urdu-custom, Apache-2.0), converted to GGML",
+    url: "https://huggingface.co/CodeWithAhsan/whisper-medium-urdu-ggml/resolve/main/ggml-medium-urdu.bin",
+  },
 };
 
-export function modelUrl(name: string): string {
-  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${name}.bin`;
+/**
+ * A model pick reduced to its bare name: basename, minus the optional ggml-
+ * prefix and .bin suffix. Exists because classifying on the raw value
+ * misreads paths — an absolute /x/ggml-small.en.bin ends in ".bin", so the
+ * wizard's `.endsWith(".en")` language heuristic prefilled `auto` for an
+ * ENGLISH model (review fix, Urdu field test 2026-08-05) — and the MODELS
+ * lookups below must find `medium-urdu` inside either spelling.
+ */
+export function bareWhisperModelName(nameOrPath: string): string {
+  const base = basename(nameOrPath);
+  const m = /^(?:ggml-)?(.+?)(?:\.bin)?$/.exec(base);
+  return m?.[1] ?? base;
+}
+
+/**
+ * The language a model pick implies when the user set none: the curated
+ * table's `language`, keyed on the bare name so `--whisper-model medium-urdu`
+ * and an absolute /x/ggml-medium-urdu.bin both resolve it. Undefined for
+ * stock models and unknown fine-tunes — whisper's own en default stands.
+ */
+export function modelImpliedLanguage(nameOrPath: string): string | undefined {
+  return MODELS[bareWhisperModelName(nameOrPath)]?.language;
+}
+
+/**
+ * THE model-download URL — the single source produce's missing-model error,
+ * doctor's fix line, and setup's download all read (they used to hold string
+ * dupes of the ggerganov URL, which 404'd for any custom name). Precedence:
+ * the config's `modelSources` entry (a user's own fine-tune is one config
+ * line) > the curated table's `url` > the ggerganov default mirror.
+ */
+export function modelUrl(name: string, sources?: Record<string, string>): string {
+  return (
+    sources?.[name] ??
+    MODELS[name]?.url ??
+    `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${name}.bin`
+  );
+}
+
+/**
+ * The one model-path resolution rule, extracted from its three duplicated
+ * sites (produce's transcription step, doctor's model check, setup's plan):
+ * an absolute model is a file path used verbatim, a bare name lives in
+ * modelDir as ggml-<name>.bin.
+ */
+export function whisperModelPath(model: string, modelDir: string): string {
+  return isAbsolute(model) ? model : join(modelDir, `ggml-${model}.bin`);
+}
+
+/**
+ * Consumer-side vetting for the config's `modelSources` key — the
+ * `validDictionary` posture (produce.ts) applied to a record: the value
+ * comes from a hand-editable JSON file loadConfig doesn't zod-parse, so a
+ * non-object, a non-string URL, or a URL that trims to nothing means the
+ * whole key is ignored (`undefined`) and the call site warns once.
+ * All-or-nothing on purpose: half a typo'd map would download some models
+ * from a source the user never reviewed.
+ */
+export function validModelSources(value: unknown): Record<string, string> | undefined {
+  const parsed = z.record(z.string(), z.string().trim().min(1)).safeParse(value);
+  if (!parsed.success || Object.keys(parsed.data).length === 0) return undefined;
+  return parsed.data;
 }
 
 /** The exact build recipe printed when no prebuilt fits — one copy, not four. */

package/src/setup/plan.ts

@@ -1,6 +1,14 @@
 import { isAbsolute, join } from "node:path";
 import type { OssclipConfig } from "@ossclip/core";
-import { type BinaryAsset, MODELS, ffmpegAsset, modelUrl, whisperAsset } from "./manifest";
+import {
+  type BinaryAsset,
+  MODELS,
+  ffmpegAsset,
+  modelUrl,
+  validModelSources,
+  whisperAsset,
+  whisperModelPath,
+} from "./manifest";
 
 /**
  * The planning half of `ossclip setup` — pure over injected probes, like
@@ -137,11 +145,11 @@ export async function planSetup(
     }
   }
 
-  // The model: same resolution produce and doctor use — absolute is a file
-  // path, a bare name lives in modelDir as ggml-<name>.bin. `--force` never
-  // re-downloads a present model; a corrupt one is deleted by hand.
+  // The model: same resolution produce and doctor use (whisperModelPath).
+  // `--force` never re-downloads a present model; a corrupt one is deleted
+  // by hand.
   const model = opts.model;
-  const modelPath = isAbsolute(model) ? model : join(cfg.modelDir, `ggml-${model}.bin`);
+  const modelPath = whisperModelPath(model, cfg.modelDir);
   const known = MODELS[model];
   if (p.exists(modelPath)) {
     steps.push({ kind: "model", status: "satisfied", detail: modelPath });
@@ -156,7 +164,10 @@ export async function planSetup(
     steps.push({
       kind: "model",
       status: "download",
-      detail: `${modelUrl(model)} → ${modelPath}`,
+      // The config's modelSources beats the curated/default hosts here for
+      // the same reason it does at download time — the plan must name the
+      // URL setup will actually fetch.
+      detail: `${modelUrl(model, validModelSources(cfg.modelSources))} → ${modelPath}`,
       sizeMB: known?.sizeMB,
     });
   }

package/src/setup/setup.ts

@@ -1,9 +1,16 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { basename, isAbsolute, join } from "node:path";
+import { basename, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { CONFIG_DIR, loadConfig, saveConfigPatch, type OssclipConfig } from "@ossclip/core";
-import { MODELS, WHISPER_BUILD_HINT, modelUrl, type BinaryAsset } from "./manifest";
+import {
+  MODELS,
+  WHISPER_BUILD_HINT,
+  modelUrl,
+  validModelSources,
+  whisperModelPath,
+  type BinaryAsset,
+} from "./manifest";
 import { formatPlan, managedBinDir, planSetup, type SetupProbes, type SetupStep } from "./plan";
 import { download, progressLine } from "./download";
 import { extractArchive, findFile, markExecutable } from "./extract";
@@ -130,17 +137,31 @@ export async function setup(
           break;
         case "model":
           if (step.status === "download") {
-            const modelPath = isAbsolute(model)
-              ? model
-              : join(cfg.modelDir, `ggml-${model}.bin`);
+            const modelPath = whisperModelPath(model, cfg.modelDir);
             const info = MODELS[model];
+            // Provenance out loud for a curated fine-tune — the user is about
+            // to fetch a community model, and the note says whose.
+            if (info?.note) console.log(`▸ ${model}: ${info.note}`);
             if (!info) {
               console.log(
                 `▸ ${model} isn't in the pinned table — downloading without a checksum.`,
               );
+            } else if (!info.sha1) {
+              // A curated entry can predate its published checksum (the URL
+              // is pinned before the upstream upload settles) — disclose the
+              // unverified download the same way an off-table name does.
+              console.log(`▸ ${model} has no pinned checksum yet — downloading without one.`);
             }
-            console.log(`▸ downloading ggml-${model}.bin${info ? ` (~${info.sizeMB} MB)` : ""}…`);
-            await download(modelUrl(model), modelPath, {
+            const sources = validModelSources(cfg.modelSources);
+            if (cfg.modelSources !== undefined && sources === undefined) {
+              console.log(
+                "⚠ config modelSources ignored — expected an object of name → URL strings",
+              );
+            }
+            console.log(
+              `▸ downloading ggml-${model}.bin${info?.sizeMB ? ` (~${info.sizeMB} MB)` : ""}…`,
+            );
+            await download(modelUrl(model, sources), modelPath, {
               sha1: info?.sha1,
               onProgress: progressLine(`ggml-${model}.bin`),
             });