@autoaiai/aicut 0.0.0-stage → 0.1.7

package/studio/server/providers/local-whisper.mjs

@@ -0,0 +1,847 @@
+// @ts-check
+/**
+ * The local recognizers: transcription on this computer, no key and no bill. Two of them, each a provider of its own
+ * in Settings → Providers — Whisper (本地), with Whisper small, medium or large-v3, and SenseVoice Small — and Studio
+ * downloads what runs the one the person wants (and, once, the command itself) into ~/.aicut/whisper. A run is
+ * that command on a 16 kHz WAV of the speech, read back from its JSON.
+ *
+ * Two commands, one per provider: whisper.cpp for the Whisper models, sherpa-onnx for SenseVoiceSmall (whisper.cpp
+ * cannot run it — it is a different kind of model). Which one a run needs is the model's `engine`, which is also
+ * what says whose row it is listed in.
+ *
+ * The models come from the ggml-org/whisper.cpp collection and from Hugging Face's copy of SenseVoiceSmall; the
+ * commands come from the whisper.cpp and sherpa-onnx releases on GitHub. None of those sites answers on every
+ * network (this one included), so SenseVoice is taken from a ModelScope copy first — the only source that comes down
+ * at speed from here, two minutes instead of forty — and a GitHub release through gh-proxy; Xget (the engine behind
+ * the Xget Now extension) is the way round to Hugging Face, and every list ends with the site itself. Every download
+ * lands as `.part` first and is renamed only when whole, so a broken download never looks like a model (and a
+ * `.part` that stopped half way is taken up where it stopped rather than from nothing).
+ */
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { mkdtemp, open, readdir, readFile, rm, stat, rename, mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { cpus, tmpdir } from 'node:os';
+import { pipeline } from 'node:stream/promises';
+import { Readable, Transform } from 'node:stream';
+import { extractTarBz2 } from './tar-bz2.mjs';
+import { studioHome } from '../projects.mjs';
+
+/** @typedef {import('./contract.mjs').Provider} Provider */
+
+/** Who owns each family of models: the provider ids, each with the row Settings gives it. */
+const WHISPER = /** @type {const} */ ('local-whisper');
+const SENSEVOICE = /** @type {const} */ ('local-sensevoice');
+const NAME = 'Whisper (本地)';
+const SENSE_NAME = 'SenseVoice Small';
+/** the name of the provider that runs a model. @param {Model} model */
+const nameOf = (model) => (model.owner === SENSEVOICE ? SENSE_NAME : NAME);
+/** where everything of the local recognizers is kept */
+const home = () => join(studioHome(), 'whisper');
+const binDir = () => join(home(), 'bin');
+const modelsDir = () => join(home(), 'models');
+
+/* ── where a download comes from ─────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * ModelScope (魔搭) is the one place a model comes down fast from a Chinese network — 2.5 MB/s against the 0.08 MB/s
+ * Xget gives here, which is the difference between two minutes and forty. It is tried first, for the files it is
+ * known to carry, and only those: what it carries was put there by someone else, so each file it serves is checked
+ * against the size the model is known to be (`partsOf`'s `exact`), and a copy of another build fails that check and
+ * loses to the address that has the right one. `AICUT_MODELSCOPE` names another site of its own (`=off` leaves it
+ * out).
+ */
+const modelscopeBase = () => {
+  const set = process.env.AICUT_MODELSCOPE?.trim();
+  if (set === 'off') return '';
+  return (set || 'https://modelscope.cn').replace(/\/+$/, '');
+};
+
+/**
+ * Where a file of `repo` is on ModelScope (its `master` revision, which is what these copies publish as).
+ * @param {string} repo the ModelScope repository, `owner/name`
+ * @param {string} file the path inside it
+ * @returns {string[]}
+ */
+function viaModelScope(repo, file) {
+  const base = modelscopeBase();
+  return base ? [`${base}/models/${repo}/resolve/master/${file}`] : [];
+}
+
+/**
+ * Xget (xget.xi-xu.me — the engine the Xget Now browser extension hands downloads to) takes the original address
+ * after a prefix of its own, `/gh/` for GitHub and `/hf/` for Hugging Face, and fetches it from an edge that reaches
+ * where this computer cannot: github.com and huggingface.co time out here, and hf-mirror has been answering nothing
+ * at all, so for a Hugging Face file it is the only way there is. Two public instances are listed because the first
+ * one rate-limits a burst of requests (429) and the second usually has not — `AICUT_XGET` names one's own
+ * instead (several, comma by comma, same way round, no trailing slash); `AICUT_XGET=off` leaves Xget out.
+ */
+const XGET = 'https://xget.xi-xu.me,https://xget.yage.eu.org';
+
+/** The Xget instances to go through, in the order tried (none with it switched off). @returns {string[]} */
+function xgetBases() {
+  const set = process.env.AICUT_XGET?.trim();
+  if (set === 'off') return [];
+  return (set || XGET).split(',').map((one) => one.trim().replace(/\/+$/, '')).filter(Boolean);
+}
+
+/** The prefixes of that engine, by the site an address is on. */
+const XGET_PREFIX = [
+  ['https://github.com/', 'gh'],
+  ['https://huggingface.co/', 'hf'],
+];
+
+/**
+ * The address of a file on each Xget instance — the original address after the prefix of the site it is on — and
+ * none for a site that has no prefix there. @param {string} url @returns {string[]}
+ */
+function throughXget(url) {
+  const site = XGET_PREFIX.find(([prefix]) => url.startsWith(prefix));
+  if (!site) return [];
+  return xgetBases().map((base) => `${base}/${site[1]}/${url.slice(site[0].length)}`);
+}
+
+/**
+ * The addresses one file is tried at, best first. Two orders, because the two things are not equally served by the
+ * same mirror: a GitHub release (a command, 9–23 MB) comes down at 0.4 MB/s through gh-proxy and stalls at nothing
+ * through Xget, so gh-proxy goes first and Xget is the way round if it refuses; a Hugging Face file has no such
+ * mirror left (hf-mirror answers nothing here), so Xget is the only one that works and goes first.
+ *
+ * The site itself is always last — the address that always exists, and the one to copy into a browser when every
+ * mirror is down. `fetchTo` waits out the ones that say "not now" before going round again.
+ *
+ * Exported because the separator (local-mdx.mjs) downloads its model from a GitHub release too, and the mirrors that
+ * work from a Chinese network are the same ones: one list, both downloads.
+ * @param {string} url
+ */
+export const mirrorsOf = (url) => {
+  if (url.startsWith('https://huggingface.co/')) {
+    return [
+      ...throughXget(url),
+      url.replace('https://huggingface.co/', 'https://hf-mirror.com/'),
+      url,
+    ];
+  }
+  return [`https://gh-proxy.com/${url}`, `https://ghproxy.net/${url}`, ...throughXget(url), url];
+};
+
+/** The command that transcribes, and where it comes from. */
+const CLI_RELEASE = 'https://github.com/ggml-org/whisper.cpp/releases/download/b5454/whisper-bin-x64.zip';
+const CLI_URLS = mirrorsOf(CLI_RELEASE);
+const CLI_NAME = process.platform === 'win32' ? 'whisper-cli.exe' : 'whisper-cli';
+
+/* ── sherpa-onnx, for SenseVoice ─────────────────────────────────────────────────────────────────────────────────── */
+
+/** SenseVoiceSmall in sherpa-onnx's own form: the int8 model and its tokens, one folder's worth. */
+const SENSE_VOICE_REPO = 'csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17';
+const SENSE_VOICE_DIR = 'sense-voice';
+
+/**
+ * That same export, put on ModelScope by someone else and byte for byte the same (239,233,841 and 315,894 — checked
+ * against the sizes `partsOf` insists on). It is what makes SenseVoice a two-minute download here instead of a
+ * forty-minute one: the two files sit at the repository's root, with no folder of their own.
+ */
+const SENSE_VOICE_MIRROR = 'poloniumrock/SenseVoiceSmallOnnx';
+
+/**
+ * Where sherpa-onnx's command comes from: its release page, one archive per system. The `no-tts` ones (it does not
+ * speak, only listens), except the arm64 Linux build, which comes only whole.
+ */
+const SHERPA_VERSION = '1.13.8';
+const SHERPA_ASSETS = /** @type {Record<string, string>} */ ({
+  'win32-x64': `sherpa-onnx-v${SHERPA_VERSION}-win-x64-shared-MT-Release-no-tts.tar.bz2`,
+  'darwin-arm64': `sherpa-onnx-v${SHERPA_VERSION}-osx-arm64-shared-no-tts.tar.bz2`,
+  'darwin-x64': `sherpa-onnx-v${SHERPA_VERSION}-osx-x64-shared-no-tts.tar.bz2`,
+  'linux-x64': `sherpa-onnx-v${SHERPA_VERSION}-linux-x64-shared-no-tts.tar.bz2`,
+  'linux-arm64': `sherpa-onnx-v${SHERPA_VERSION}-linux-aarch64-shared-cpu.tar.bz2`,
+});
+const SHERPA_NAME = process.platform === 'win32' ? 'sherpa-onnx-offline.exe' : 'sherpa-onnx-offline';
+/** where the archive is unpacked: its `bin/` (the command and the libraries it needs) lands here */
+const sherpaDir = () => join(binDir(), 'sherpa');
+const sherpaBin = () => join(sherpaDir(), 'bin');
+
+/* ── the models ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   name: string,
+ *   engine: 'whisper' | 'sherpa',
+ *   owner: string,
+ *   bytes: number,
+ *   vram?: number,
+ *   file?: string,
+ *   languages?: readonly string[],
+ * }} Model
+ */
+
+/**
+ * The models, each in the row of the provider that runs it. `owner` is that provider's id: SenseVoice Small is a
+ * provider of its own, not a model lent to Whisper — it runs on a different command, and downloads on its own.
+ *
+ * The file a model lands as, how big it is, and `vram`, the memory it takes while it runs, in GB — about 1.3–1.5
+ * times the file: the model itself, then the f16 copy and the decoder's state on top.
+ * It is the graphics card's memory when whisper.cpp runs on the GPU, and plain RAM when it runs on the CPU (the
+ * command this Studio downloads is the CPU build) — SenseVoice runs on the CPU only, so it says no amount.
+ *
+ * `languages` are the ones a model hears well, as tabs a page translates (Settings → Providers shows them under its
+ * name): SenseVoiceSmall hears five, and hears Chinese and Cantonese better than any Whisper that fits in a download.
+ */
+const MODELS = /** @type {Model[]} */ ([
+  {
+    id: 'sensevoice-small',
+    name: 'SenseVoice Small',
+    engine: 'sherpa',
+    owner: SENSEVOICE,
+    /* model.int8.onnx + tokens.txt */
+    bytes: 239_549_735,
+    languages: ['zh', 'yue', 'en', 'ja', 'ko'],
+  },
+  { id: 'small', name: 'Whisper Small', engine: 'whisper', owner: WHISPER, file: 'ggml-small.bin', bytes: 487_601_967, vram: 1.5 },
+  /* the smallest one whose Chinese is worth the subtitles: small drops and swaps characters */
+  { id: 'medium', name: 'Whisper Medium', engine: 'whisper', owner: WHISPER, file: 'ggml-medium.bin', bytes: 1_533_763_059, vram: 3 },
+  { id: 'large-v3', name: 'Whisper Large v3', engine: 'whisper', owner: WHISPER, file: 'ggml-large-v3.bin', bytes: 3_095_033_483, vram: 6 },
+]);
+
+/** The models of one provider, in the order Settings lists them. @param {string} owner */
+const modelsOf = (owner) => MODELS.filter((m) => m.owner === owner);
+
+/** The provider whose command runs a model, by model id: null when no local model has that id. @param {string} id */
+export const ownerOfModel = (/** @type {string} */ id) => MODELS.find((m) => m.id === id)?.owner ?? null;
+
+/**
+ * The same ggml models, put on ModelScope by someone else. Checked the loud way rather than by size: the small one
+ * was downloaded from here and loaded by the whisper.cpp command this Studio downloads (b5454), which read it and
+ * transcribed — so it is the same format, whatever its build. It is what makes 465 MB three minutes instead of an
+ * hour and a half. The sizes below are what these files are.
+ */
+const WHISPER_MIRROR = 'cjc1887415157/whisper.cpp';
+
+/**
+ * Where a Whisper model comes from: ModelScope first (the only one that comes down at speed from here), then the
+ * addresses that reach Hugging Face's copy, the last of which is the site itself.
+ */
+const modelUrls = (/** @type {string} */ file) => [
+  ...viaModelScope(WHISPER_MIRROR, file),
+  ...mirrorsOf(`https://huggingface.co/ggerganov/whisper.cpp/resolve/main/${file}`),
+];
+
+/**
+ * Where a piece of SenseVoice comes from, the same way round: the ModelScope copy first, then the addresses that
+ * reach Hugging Face. These two are the ones whose size is known to the byte, so a copy that is another build of the
+ * same name loses to the one that is right.
+ */
+const senseVoiceUrls = (/** @type {string} */ file) => [
+  ...viaModelScope(SENSE_VOICE_MIRROR, file),
+  ...mirrorsOf(`https://huggingface.co/${SENSE_VOICE_REPO}/resolve/main/${file}`),
+];
+
+/**
+ * What a model is made of: each file it needs, where it comes from, and where it lands under the models folder.
+ * Whisper models are one file; SenseVoice is the model and the tokens it reads them with. `exact` says the size is
+ * the truth and not an approximation — the two of SenseVoice are, which is what lets a copy taken from ModelScope be
+ * told apart from another build of the same name.
+ * @param {Model} model
+ */
+function partsOf(model) {
+  if (model.engine === 'sherpa') {
+    return [
+      { path: `${SENSE_VOICE_DIR}/model.int8.onnx`, bytes: 239_233_841, exact: true, urls: senseVoiceUrls('model.int8.onnx') },
+      { path: `${SENSE_VOICE_DIR}/tokens.txt`, bytes: 315_894, exact: true, urls: senseVoiceUrls('tokens.txt') },
+    ];
+  }
+  const file = model.file ?? '';
+  return [{ path: file, bytes: model.bytes, urls: modelUrls(file) }];
+}
+
+/** The downloads running now (and the last that failed): id → how far it has gone, 0..1. */
+const downloads = new Map();
+
+/** Whether a path exists. @param {string} path */
+const there = async (path) => { try { await stat(path); return true; } catch { return false; } };
+
+/** Whether every file of a model is here. @param {Model} model */
+async function whole(model) {
+  for (const one of partsOf(model)) if (!await there(join(modelsDir(), one.path))) return false;
+  return true;
+}
+
+/* ── the commands ───────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The whisper.cpp command, found once where it was unpacked (or set in AICUT_WHISPER_CLI). */
+let whisperAt = '';
+async function whisperCli() {
+  const set = process.env.AICUT_WHISPER_CLI?.trim();
+  if (set) return set;
+  if (whisperAt && await there(whisperAt)) return whisperAt;
+  const direct = join(binDir(), CLI_NAME);
+  if (await there(direct)) return (whisperAt = direct);
+  /* unpacked one folder deep: find it */
+  try {
+    for (const one of await readdir(binDir(), { withFileTypes: true })) {
+      const found = one.isDirectory() ? join(binDir(), one.name, CLI_NAME) : '';
+      if (found && await there(found)) return (whisperAt = found);
+    }
+  } catch { /* no bin yet */ }
+  return '';
+}
+
+/** The sherpa-onnx command, found once where it was unpacked (or set in AICUT_SHERPA_CLI). */
+let sherpaAt = '';
+async function sherpaCli() {
+  const set = process.env.AICUT_SHERPA_CLI?.trim();
+  if (set) return set;
+  if (sherpaAt && await there(sherpaAt)) return sherpaAt;
+  const direct = join(sherpaBin(), SHERPA_NAME);
+  if (await there(direct)) return (sherpaAt = direct);
+  /* unpacked with its own folder kept: find it one deep */
+  try {
+    for (const one of await readdir(sherpaBin(), { withFileTypes: true })) {
+      const found = one.isDirectory() ? join(sherpaBin(), one.name, SHERPA_NAME) : '';
+      if (found && await there(found)) return (sherpaAt = found);
+    }
+  } catch { /* no bin yet */ }
+  return '';
+}
+
+/** Whether whisper.cpp's command is here (the models are asked about separately). */
+export const hasCli = async () => Boolean(await whisperCli());
+
+/* ── what Settings shows ────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * What one of the two shows in Settings: whether its command is here, and each of its models with whether it is
+ * here, the languages it hears, and how far the one downloading has gone.
+ * @param {string} [owner] the provider id — Whisper's when none is named
+ */
+export async function status(owner = WHISPER) {
+  const models = modelsOf(owner);
+  const command = owner === SENSEVOICE ? await sherpaCli() : await whisperCli();
+  return {
+    bin: Boolean(command),
+    path: command || null,
+    models: await Promise.all(models.map(async (m) => ({
+      id: m.id,
+      name: m.name,
+      bytes: m.bytes,
+      ...(m.vram !== undefined ? { vram: m.vram } : {}),
+      ...(m.languages ? { languages: [...m.languages] } : {}),
+      downloaded: await whole(m),
+      progress: downloads.get(m.id)?.progress ?? null,
+      error: downloads.get(m.id)?.error ?? null,
+    }))),
+  };
+}
+
+/**
+ * The model a run uses: the one asked for when it is here; any that is here when it is not (a model downloaded and
+ * then moved is not worth failing over while another can hear); else the one asked for, or the smallest of its
+ * provider, so the message can name what to download.
+ * @param {string} owner @param {string} [modelId]
+ */
+async function pick(owner, modelId) {
+  const own = modelsOf(owner);
+  const asked = own.find((m) => m.id === modelId);
+  if (asked && await whole(asked)) return asked;
+  for (const m of own) if (await whole(m)) return m;
+  return asked ?? own.find((m) => m.id === 'small') ?? own[0];
+}
+
+/** Whether a run could go now: the command its model needs, and that model, are here. @param {string} modelId */
+export async function usable(modelId) {
+  const model = MODELS.find((m) => m.id === modelId);
+  if (!model || !await whole(model)) return false;
+  return Boolean(model.engine === 'sherpa' ? await sherpaCli() : await whisperCli());
+}
+
+/** Whether any model of that provider is here (whether it counts as connected). @param {string} [owner] */
+export async function anyModel(owner = WHISPER) {
+  for (const m of modelsOf(owner)) if (await whole(m)) return true;
+  return false;
+}
+
+/* ── downloads ──────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** Whether a mirror's answer is "not now" rather than "not here". */
+const WAIT = new Set([408, 425, 429, 500, 502, 503, 504]);
+/** How long a wait comes before the addresses are gone round again (milliseconds, one per round). */
+const BACKOFF = [2000, 8000, 20000];
+/** The longest a mirror can ask to be left alone for (`Retry-After`): past that the next address is worth a try. */
+const LONGEST_WAIT = 30_000;
+
+/**
+ * One fetch of a big file, to `.part` and renamed when whole; how far it has gone goes to `downloads` (or wherever
+ * `onProgress` puts it, a model of several files being more than one number). The first address that answers wins.
+ *
+ * The addresses are gone round until one answers or none can: an address that says "not now" — Xget's public
+ * instances rate-limit a burst of requests with 429 — leaves what it already sent in `.part`, the next address is
+ * tried, and after a wait the same ones are asked again; the request that follows asks for a range, so a 240 MB
+ * model cut off at 200 MB costs the last 40 rather than the whole. An address that says "not here" (404, 403) is
+ * written off at once. A connection that broke keeps its bytes, and is gone round for again only when it had been
+ * sending something — an address that answers nothing at all never will, and is not worth the wait.
+ *
+ * Exported for the test: it is the one part of a download that needs no model and no command, so a stand-in server
+ * can say what a mirror says and the answer be checked.
+ * @param {string} id what the download is called in `downloads`
+ * @param {string[]} urls the addresses tried in order
+ * @param {string} to the file it lands as
+ * @param {(seen: number, total: number) => void} [onProgress]
+ * @param {number} [expect] the size this file is, when that is known exactly: what a copy taken from a mirror
+ *   someone else made is checked against, so another build of the same name loses to the address that has the right
+ *   one instead of becoming a model that will not load
+ */
+export async function fetchTo(id, urls, to, onProgress, expect) {
+  await mkdir(dirname(to), { recursive: true });
+  const part = `${to}.part`;
+  const report = onProgress ?? ((seen, total) => { if (total) downloads.set(id, { progress: Math.min(0.99, seen / total) }); });
+  /** what `.part` holds: what the last try sent, which the next one goes on from */
+  const held = async () => { try { return (await stat(part)).size; } catch { return 0; } };
+  let last = null;
+  for (let round = 0; ; round += 1) {
+    const before = await held();
+    /** whether anything this round said "not now": the only reason to go round again */
+    let again = false;
+    /** and whether a connection broke — worth another round only if it had been sending something */
+    let broken = false;
+    /** the longest any of them asked to be left alone for */
+    let after = 0;
+    for (const url of urls) {
+      try {
+        const have = await held();
+        const res = await fetch(url, { redirect: 'follow', headers: have > 0 ? { range: `bytes=${have}-` } : {} });
+        if (res.status === 416) {
+          /* `.part` is already all of it (or more than all of it): start over rather than stitch a lie together */
+          await rm(part, { force: true });
+          throw Object.assign(new Error('HTTP 416'), { status: 416 });
+        }
+        if (!res.ok || !res.body) {
+          /* how long it wants to be left alone, when it says (Xget does, with a 429) */
+          const seconds = Number(res.headers.get('retry-after')) || 0;
+          await res.body?.cancel();
+          throw Object.assign(new Error(`HTTP ${res.status}`), {
+            status: res.status,
+            ...(seconds > 0 ? { after: Math.min(LONGEST_WAIT, seconds * 1000) } : {}),
+          });
+        }
+        const more = res.status === 206 && have > 0;
+        const whole = Number(res.headers.get('content-range')?.split('/')[1]) || 0;
+        const total = whole || (Number(res.headers.get('content-length')) || 0) + (more ? have : 0);
+        /* a copy someone else put up under the same name can be another build of it: its size says which one */
+        if (expect && whole && whole !== expect) throw new Error(`不是同一个文件（${whole} 字节，应当是 ${expect}）`);
+        let seen = more ? have : 0;
+        const counted = new Transform({
+          transform(chunk, _encoding, done) {
+            seen += /** @type {Buffer} */ (chunk).length;
+            report(seen, total);
+            done(null, chunk);
+          },
+        });
+        await pipeline(
+          Readable.fromWeb(/** @type {import('node:stream/web').ReadableStream} */ (res.body)),
+          counted,
+          createWriteStream(part, { flags: more ? 'a' : 'w' }),
+        );
+        const landed = (await stat(part)).size;
+        if (expect && landed !== expect) {
+          await rm(part, { force: true });
+          throw new Error(`下到的不是同一个文件（${landed} 字节，应当是 ${expect}）`);
+        }
+        await rename(part, to);
+        return;
+      } catch (e) {
+        last = e;
+        const { status, after: wanted } = /** @type {{ status?: number, after?: number }} */ (e) ?? {};
+        /* "not here" is the next address's business; "not now" is worth waiting out, its bytes kept; a connection
+           that broke is only worth another round if it was sending (an address that answers nothing never will) */
+        if (typeof status !== 'number') { broken = true; continue; }
+        if (!WAIT.has(status)) continue;
+        again = true;
+        if (wanted && wanted > after) after = wanted;
+      }
+    }
+    if (!again && broken && await held() > before) again = true;
+    const backoff = BACKOFF[round];
+    if (!again || backoff === undefined) break;
+    await new Promise((done) => setTimeout(done, Math.min(LONGEST_WAIT, Math.max(backoff, after))));
+  }
+  throw new Error(`下载失败（${String(/** @type {Error} */ (last)?.message ?? last)}）。检查网络后重试（未下完的部分留着，会接着下），或从 ${urls[0]} 手动下载后放到 ${to}。换源：AICUT_MODELSCOPE=off 关掉魔搭，AICUT_XGET=https://你的实例 换加速站`);
+}
+
+/**
+ * Every file of a model that is not here yet, one after the other, the one progress bar covering them all (each file
+ * counts for the bytes it is, not the same as the last). `from` is where on the bar these bytes start: the command a
+ * model needs comes first, and its download is a share of the wait too.
+ * @param {string} id @param {{ path: string, bytes: number, exact?: boolean, urls: string[] }[]} parts @param {number} total @param {number} [from]
+ */
+async function fetchParts(id, parts, total, from = 0) {
+  let base = 0;
+  /* the bar from `from` to just short of the end: 0.99 is as far as a download goes (unpacking comes after) */
+  const span = 0.99 - from;
+  for (const one of parts) {
+    const to = join(modelsDir(), one.path);
+    if (!await there(to)) {
+      await fetchTo(id, one.urls, to, (seen, all) => {
+        const done = base + (all ? Math.min(seen, one.bytes) : 0);
+        downloads.set(id, { progress: Math.min(0.99, from + (span * done) / total) });
+      }, one.exact ? one.bytes : undefined);
+    }
+    base += one.bytes;
+  }
+}
+
+/**
+ * The whisper.cpp command, downloaded and unpacked once. On Windows with PowerShell's own unzip (there is no tar that
+ * reads zip everywhere); elsewhere `unzip` or `tar`, whichever is there.
+ * @param {string} zip @param {string} to
+ */
+async function unpack(zip, to) {
+  const one = process.platform === 'win32'
+    ? spawn('powershell.exe', ['-NoProfile', '-Command', `Expand-Archive -LiteralPath "$env:WHISPER_ZIP" -DestinationPath "$env:WHISPER_TO" -Force`],
+        { windowsHide: true, stdio: 'ignore', env: { ...process.env, WHISPER_ZIP: zip, WHISPER_TO: to } })
+    : spawn('sh', ['-c', 'unzip -o "$1" -d "$2" || tar -xf "$1" -C "$2"', 'sh', zip, to], { stdio: 'ignore' });
+  await new Promise((done, fail) => {
+    one.on('error', fail);
+    one.on('close', (code) => (code === 0 ? done(undefined) : fail(new Error(`解压失败（exit ${code}）`))));
+  });
+}
+
+/**
+ * An archive unpacked without the folder it came in, so what lies inside lands where it was told to.
+ *
+ * It used to be `tar -xjf` on this file's input, and `spawn('tar')` answered ENOENT: this machine's System32 has no
+ * `tar.exe` at all, so the archive came down whole and then could not be opened. `tar-bz2.mjs` reads the format here
+ * instead, which needs nothing installed on the machine.
+ * @param {string} file @param {string} to
+ */
+async function untar(file, to) {
+  await extractTarBz2(file, to);
+}
+
+/** The whisper.cpp command, downloaded and unpacked once. @param {(fraction: number) => void} [onProgress] */
+async function fetchCli(onProgress) {
+  if (process.env.AICUT_WHISPER_CLI?.trim() || await whisperCli()) return;
+  await mkdir(binDir(), { recursive: true });
+  const zip = join(binDir(), 'whisper-bin.zip');
+  try {
+    await fetchTo('cli', CLI_URLS, zip, (seen, all) => onProgress?.(all ? Math.min(1, seen / all) : 0));
+  } catch (e) {
+    throw new Error(`识别程序下载失败：${String(/** @type {Error} */ (e)?.message ?? e)}`);
+  }
+  try {
+    await unpack(zip, binDir());
+  } catch (e) {
+    throw new Error(`${String(/** @type {Error} */ (e)?.message ?? e)}：可手动把 ${CLI_RELEASE} 解压到 ${binDir()}`);
+  }
+  await rm(zip, { force: true });
+  if (!await whisperCli()) throw new Error(`解压后没有找到 ${CLI_NAME}（在 ${binDir()}）`);
+}
+
+/** The sherpa-onnx command, downloaded and unpacked once (what runs SenseVoice). @param {(fraction: number) => void} [onProgress] */
+async function fetchSherpa(onProgress) {
+  if (process.env.AICUT_SHERPA_CLI?.trim() || await sherpaCli()) return;
+  const asset = SHERPA_ASSETS[`${process.platform}-${process.arch}`];
+  if (!asset) {
+    throw new Error(`SenseVoice 还没有 ${process.platform} ${process.arch} 上的现成程序：改用 Whisper 模型，或自己编译 sherpa-onnx 后用 AICUT_SHERPA_CLI 指定它。`);
+  }
+  const release = `https://github.com/k2-fsa/sherpa-onnx/releases/download/v${SHERPA_VERSION}/${asset}`;
+  await mkdir(sherpaBin(), { recursive: true });
+  const tar = join(binDir(), 'sherpa-onnx.tar.bz2');
+  try {
+    await fetchTo('cli', mirrorsOf(release), tar,
+      (seen, all) => onProgress?.(all ? Math.min(1, seen / all) : 0));
+  } catch (e) {
+    throw new Error(`识别程序下载失败：${String(/** @type {Error} */ (e)?.message ?? e)}`);
+  }
+  try {
+    await untar(tar, sherpaDir());
+  } catch (e) {
+    throw new Error(`${String(/** @type {Error} */ (e)?.message ?? e)}：可手动把 ${release} 解压到 ${sherpaDir()}`);
+  }
+  await rm(tar, { force: true });
+  if (!await sherpaCli()) throw new Error(`解压后没有找到 ${SHERPA_NAME}（在 ${sherpaDir()}）`);
+}
+
+/**
+ * A model (or, with it, the command) downloaded in the background; the Settings page watches `status()` for how far
+ * it has gone. The promise settles when it is done or has failed; the failure is also kept for the page to show.
+ *
+ * The bar is on from the first moment — before the command is fetched, before a byte of the model is — so a press
+ * that started something is never a press that looks like it did nothing (a model of several files, one of which is
+ * a 22 MB command, can be quiet for a while otherwise).
+ * @param {string} modelId
+ */
+export function download(modelId) {
+  const want = MODELS.find((m) => m.id === modelId);
+  if (!want) throw new Error(`no such local model: ${modelId}`);
+  const run = (async () => {
+    try {
+      downloads.set(want.id, { progress: 0 });
+      /* the command is the first tenth of the wait (it is unpacked after, which the bar holds at that tenth until
+         the model itself starts coming) */
+      const program = (/** @type {number} */ fraction) => downloads.set(want.id, { progress: Math.min(0.09, fraction * 0.09) });
+      if (want.engine === 'sherpa') await fetchSherpa(program);
+      else await fetchCli(program);
+      await fetchParts(want.id, partsOf(want), want.bytes, 0.09);
+      downloads.delete(want.id);
+      /* the first model here is transcription working out of the box: a kind with no choice goes to it, and to the
+         model that came when none was named (a download is not a choice made yet) */
+      const { readSettings, changeSettings } = await import('../keys.mjs');
+      const s = await readSettings();
+      if (!s.use.asr || !s.model.asr) {
+        await changeSettings((next) => {
+          if (!next.use.asr) next.use.asr = want.owner;
+          if (!next.model.asr) next.model.asr = want.id;
+        });
+      }
+    } catch (e) {
+      downloads.set(want.id, { progress: null, error: String(/** @type {Error} */ (e)?.message ?? e) });
+      throw e;
+    }
+  })();
+  run.catch(() => { /* the error stays in `downloads` for the page; the promise is not left to reject alone */ });
+  return run;
+}
+
+/** A model taken away (the command stays). @param {string} modelId */
+export async function remove(modelId) {
+  const want = MODELS.find((m) => m.id === modelId);
+  if (!want) throw new Error(`no such local model: ${modelId}`);
+  if (downloads.has(want.id)) throw new Error('正在下载，先等它完成');
+  for (const one of partsOf(want)) await rm(join(modelsDir(), one.path), { force: true });
+  /* a model that comes in its own folder takes the folder with it */
+  if (want.engine === 'sherpa') await rm(join(modelsDir(), SENSE_VOICE_DIR), { recursive: true, force: true });
+}
+
+/* ── hearing ───────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * A command, its whole output back — stdout and stderr together, these tools talking on both — and a non-zero exit
+ * thrown with the end of what it said (the end is where a failing tool says why).
+ * @param {string} command @param {string[]} args @param {import('./contract.mjs').RunContext} ctx @param {string} label
+ */
+function run(command, args, ctx, label) {
+  return new Promise((done, fail) => {
+    const one = spawn(command, args, { windowsHide: true });
+    /** @type {Buffer[]} */
+    const said = [];
+    one.stdout.on('data', (b) => said.push(b));
+    one.stderr.on('data', (b) => said.push(b));
+    one.on('error', fail);
+    one.on('close', (code) => {
+      const out = Buffer.concat(said).toString('utf8');
+      if (code === 0) done(out);
+      else fail(new Error(`${label} 结束于 ${code}：${out.slice(-400)}`));
+    });
+    ctx.signal.addEventListener('abort', () => { try { one.kill(); } catch { /* already gone */ } }, { once: true });
+  });
+}
+
+/**
+ * The speech of a project file, as a 16 kHz mono WAV at `to` (what both commands hear).
+ * @param {string} to @param {string} src @param {import('./contract.mjs').RunContext} ctx
+ */
+async function speechInto(to, src, ctx) {
+  const dir = dirname(to);
+  const raw = join(dir, basename(src) || 'speech.bin');
+  await writeFile(raw, await ctx.read(src));
+  await new Promise((done, fail) => {
+    spawn('ffmpeg', ['-y', '-v', 'error', '-i', raw, '-vn', '-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le', to],
+      { windowsHide: true, stdio: 'ignore' })
+      .on('close', (code) => (code === 0 ? done(undefined) : fail(new Error('转写需要 ffmpeg：请先安装（Windows: winget install ffmpeg）'))))
+      .on('error', () => fail(new Error('转写需要 ffmpeg：请先安装（Windows: winget install ffmpeg）')));
+  });
+  await rm(raw, { force: true });
+}
+
+/**
+ * How long a WAV is, from its own header: what its `data` chunk holds and how many bytes a second. 0 when that is not
+ * to be had (a shape this Studio did not write) — the end of the audio is then not held against a word.
+ * @param {string} file
+ */
+async function wavSeconds(file) {
+  const handle = await open(file, 'r');
+  try {
+    const head = Buffer.alloc(4096);
+    const { bytesRead } = await handle.read(head, 0, head.length, 0);
+    const said = head.subarray(0, bytesRead);
+    if (said.length < 12 || said.toString('ascii', 0, 4) !== 'RIFF' || said.toString('ascii', 8, 12) !== 'WAVE') return 0;
+    /* RIFF → WAVE, then its chunks: `fmt ` says how many bytes a second, `data` how many there are */
+    let rate = 0;
+    for (let at = 12; at + 8 <= said.length;) {
+      const id = said.toString('ascii', at, at + 4);
+      const size = said.readUInt32LE(at + 4);
+      if (id === 'fmt ' && at + 20 <= said.length) rate = said.readUInt32LE(at + 16);
+      if (id === 'data') {
+        const bytes = size && size !== 0xffff_ffff ? size : (await handle.stat()).size - at - 8;
+        return rate > 0 && bytes > 0 ? bytes / rate : 0;
+      }
+      at += 8 + size + (size % 2);
+    }
+    return 0;
+  } finally {
+    await handle.close();
+  }
+}
+
+/** The spoken words of whisper.cpp's full JSON, with its marker tokens (`[_BEG_]` and friends) left out. */
+const wordsOf = (/** @type {any} */ body) => (Array.isArray(body?.transcription) ? body.transcription : [])
+  .flatMap((/** @type {any} */ seg) => Array.isArray(seg?.tokens) ? seg.tokens : [])
+  .filter((/** @type {any} */ w) => typeof w?.offsets?.from === 'number' && typeof w?.offsets?.to === 'number'
+    && !(typeof w.text === 'string' && w.text.startsWith('[') && w.text.endsWith(']')))
+  .map((/** @type {any} */ w) => ({ token: String(w.text ?? '').trim(), start: w.offsets.from / 1000, end: w.offsets.to / 1000 }))
+  .filter((/** @type {{ token: string }} */ w) => w.token);
+
+/** The seconds, to a hundredth: what a subtitle can use and no more. */
+const hundredth = (/** @type {number} */ seconds) => Math.round(seconds * 100) / 100;
+
+/** A marker token of SenseVoice's own (`<|zh|>`, `<|NEUTRAL|>`, `<|Speech|>`): in the result's own fields, not the words. */
+const marker = /^<\|.*\|>$/;
+
+/** How long a token is taken to last when the model times only where it starts, and a pause follows it (seconds). */
+const TOKEN_MS = 0.4;
+
+/**
+ * SenseVoice's JSON read as timed words and text: one token each, timed where it starts, ended where the next begins
+ * (or, after the last, a token's worth on). A gap between tokens is the pause that follows one, not part of it, so no
+ * word is stretched past where a person stopped speaking.
+ * @param {any} body
+ * @returns {{ words: { token: string, start: number, end: number }[], text: string }}
+ */
+export function senseVoiceResult(body) {
+  const tokens = Array.isArray(body?.tokens) ? body.tokens : [];
+  const starts = Array.isArray(body?.timestamps) ? body.timestamps : [];
+  const lengths = Array.isArray(body?.durations) ? body.durations : [];
+  /** @type {{ token: string, start: number, end: number }[]} */
+  const words = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = String(tokens[i] ?? '').trim();
+    const start = Number(starts[i]);
+    if (!token || marker.test(token) || !Number.isFinite(start) || start < 0) continue;
+    const own = Number(lengths[i]);
+    const next = Number(starts[i + 1]);
+    const end = Number.isFinite(own) && own > 0 ? start + own
+      : Number.isFinite(next) && next > start ? Math.min(next, start + 0.5)
+      : start + TOKEN_MS;
+    words.push({ token, start: hundredth(start), end: hundredth(Math.max(end, start + 0.04)) });
+  }
+  const said = typeof body?.text === 'string' ? body.text : '';
+  return { words, text: (said.replace(/<\|[^|]*\|>/g, ' ').replace(/\s+/g, ' ').trim()) };
+}
+
+/** The JSON line sherpa-onnx writes among its chatter (the whole output, one line being the result). */
+function heardJson(/** @type {string} */ out) {
+  for (const line of out.split(/\r?\n/)) {
+    const one = line.trim();
+    if (!one.startsWith('{') || !one.endsWith('}')) continue;
+    try {
+      const body = JSON.parse(one);
+      if (typeof body?.text === 'string') return body;
+    } catch { /* not the one */ }
+  }
+  return null;
+}
+
+/**
+ * whisper.cpp on a WAV: the words it timed and the text.
+ * @param {Model} model @param {string} dir @param {string} wav @param {import('./contract.mjs').RunContext} ctx
+ * @returns {Promise<{ words: { token: string, start: number, end: number }[], text: string }>}
+ */
+async function whisperHeard(model, dir, wav, ctx) {
+  const command = await whisperCli();
+  if (!command) throw new Error(`${NAME} 还没有可运行的程序：在设置 → 服务商里下载一个模型（会连同程序一起下载）。`);
+  const out = join(dir, 'heard');
+  await run(command, ['-m', join(modelsDir(), model.file ?? ''), '-f', wav, '-ojf', '-of', out], ctx, 'whisper-cli');
+  const body = JSON.parse(await readFile(`${out}.json`, 'utf8'));
+  const words = wordsOf(body);
+  const text = (Array.isArray(body?.transcription) ? body.transcription : [])
+    .map((/** @type {any} */ s) => String(s?.text ?? '').trim()).filter(Boolean).join(' ');
+  return { words, text };
+}
+
+/**
+ * sherpa-onnx on a WAV: SenseVoice detects the language itself (普通话、粤语、英语、日语、韩语), and its JSON comes
+ * back with a time for every token.
+ * @param {Model} model @param {string} dir @param {string} wav @param {import('./contract.mjs').RunContext} ctx
+ */
+async function senseVoiceHeard(model, dir, wav, ctx) {
+  const command = await sherpaCli();
+  if (!command) throw new Error(`${SENSE_NAME} 还没有可运行的程序：在设置 → 服务商里下载 ${model.name}（会连同程序一起下载）。`);
+  const folder = join(modelsDir(), SENSE_VOICE_DIR);
+  const threads = Math.max(1, Math.min(4, cpus().length || 1));
+  const out = await run(command, [
+    `--tokens=${join(folder, 'tokens.txt')}`,
+    `--sense-voice-model=${join(folder, 'model.int8.onnx')}`,
+    '--sense-voice-language=auto',
+    '--sense-voice-use-itn=true',
+    `--num-threads=${threads}`,
+    wav,
+  ], ctx, SHERPA_NAME);
+  const body = heardJson(out);
+  if (!body) throw new Error(`${SHERPA_NAME} 没有给出结果：${out.trim().slice(-400)}`);
+  return senseVoiceResult(body);
+}
+
+/**
+ * Transcribes one file of the project: its speech alone (as `read` gives it) made into a 16 kHz WAV, the model's own
+ * command run on it, its JSON read back. Auto-detects the language; the words come timed.
+ * @param {string} root @param {string} src @param {import('./contract.mjs').RunContext} ctx
+ * @param {string} owner which of the two is asked for this file
+ */
+async function transcribe(root, src, ctx, owner) {
+  const model = await pick(owner, ctx.model);
+  if (!await whole(model)) {
+    throw new Error(`${nameOf(model)} 还没有下载 ${model.name}：在设置 → 服务商里下载，或换一个已下载的模型。`);
+  }
+  const dir = await mkdtemp(join(tmpdir(), 'aicut-whisper-'));
+  try {
+    const wav = join(dir, 'speech.wav');
+    await speechInto(wav, src, ctx);
+    const heard = model.engine === 'sherpa'
+      ? await senseVoiceHeard(model, dir, wav, ctx)
+      : await whisperHeard(model, dir, wav, ctx);
+    if (!heard.text) throw new Error('没有听到话（音频里没有可识别的语音）。');
+    /* a word cannot outlast the sound it was heard in: the last one of a run is taken to end where the audio does */
+    const length = await wavSeconds(wav);
+    const words = length > 0 ? heard.words.map((w) => (w.end > length ? { ...w, end: hundredth(length) } : w)) : heard.words;
+    const dur = words.length ? hundredth(words[words.length - 1].end) : undefined;
+    return {
+      files: [],
+      index: [{ src, ...(dur !== undefined ? { dur } : {}), text: heard.text, words, transcribed: true }],
+      receipt: { provider: owner, model: model.id, src, text: heard.text, words: words.length },
+      cost: { note: '本地运行，不花钱' },
+    };
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/** The provider both of them share, filled in for one: its id and name, and the models it runs. */
+function providerOf(/** @type {string} */ owner, /** @type {string} */ name, /** @type {string} */ env, /** @type {string} */ keysUrl) {
+  return /** @type {Provider} */ ({
+    id: owner,
+    name,
+    env,
+    keysUrl,
+    billingUrl: keysUrl,
+    local: true,
+    /* connected once a model of it (and the program that runs it) is here: index.mjs asks this before handing it a
+       file */
+    ready: async () => { for (const m of modelsOf(owner)) if (await whole(m) && await usable(m.id)) return true; return false; },
+    verbs: ['asr'],
+    models: { asr: modelsOf(owner).map(({ id, name: modelName }) => ({ id, name: modelName })) },
+    async run(verb, args, ctx) {
+      if (verb !== 'asr') throw new Error(`${name} only transcribes.`);
+      const src = String(args.src ?? '');
+      if (!src) throw new Error('which file? --src');
+      return transcribe(ctx.root, src, ctx, owner);
+    },
+  });
+}
+
+/** Whisper's own models, run by whisper.cpp. */
+export const whisper = providerOf(WHISPER, NAME, 'AICUT_WHISPER_CLI', 'https://github.com/ggml-org/whisper.cpp');
+
+/** SenseVoice Small, a provider of its own: run by sherpa-onnx, one model, five languages. */
+export const senseVoice = providerOf(SENSEVOICE, SENSE_NAME, 'AICUT_SHERPA_CLI', 'https://github.com/k2-fsa/sherpa-onnx');
+
+export default whisper;