Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

feat(bridge): transcribe local files for the CLI with the app's models (#2121)

Gabriel Stein92d40172d947
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 65d9c201e..150cd5a94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- **Transcribe files from the terminal with your local models.** The CLI bridge gains `POST /v1/transcribe`, which takes a file path and runs whichever local model the app is set to use (whisper.cpp, Parakeet, Nemotron, or Cohere), and `GET /v1/transcribe/models`, which lists downloaded models. Audio never crosses the bridge; the app reads the file itself. Powers `openwhispr transcribe <file>` in `@openwhispr/cli` 0.3.0.
+
### Changed
- **Automatic updates replace the update popup.** A new Automatic updates toggle under Settings → System downloads updates in the background and installs them when the app next quits. It is on for new installs; existing installs keep today's flow until they opt in: the app still checks for updates, and the sidebar Update Available button and Settings → System let you download and install by hand. The update-available popup window and the App updates notification toggle are gone. On Linux the toggle and the check only appear for AppImage installs, since deb, rpm and tar.gz packages are updated by the package manager.
diff --git a/CLAUDE.md b/CLAUDE.md
index 6ab436e88..68f4d3d19 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -161,7 +161,7 @@ OpenWhispr is an Electron-based desktop dictation application that uses whisper.
- **vectorIndex.js**: Qdrant collection management — upsert, delete, search, batch reindex
- **windowConfig.js**: Centralized window configuration
- **windowManager.js**: Window creation and lifecycle management
-- **cliBridge.js**: Loopback HTTP server on ports 8200–8219, bearer-token auth (token at `~/.openwhispr/cli-bridge.json`), 127.0.0.1-only. Used by the unified CLI to talk to a running desktop app.
+- **cliBridge.js**: Loopback HTTP server on ports 8200–8219, bearer-token auth (token at `~/.openwhispr/cli-bridge.json`), 127.0.0.1-only. Used by the unified CLI to talk to a running desktop app. `POST /v1/transcribe` takes a file **path** (never audio) and runs the user's downloaded local model through `IPCHandlers.transcribeLocalFile`, approving the path with `approveAudioPath` first; `GET /v1/transcribe/models` lists local models with download state and the app's default (`localTranscriptionModels.js`, read from the `.env` pre-warm values).
- **postMigrationDetector.js**: Detects users returning from the pre-Gizmo bundle ID via a `.bundle-migrated` sentinel in userData; consumed by `ipcHandlers.js` to drive the `PostMigrationOnboarding` modal
### React Components (src/components/)
diff --git a/src/constants/apiKeys.ts b/src/constants/apiKeys.ts
index 469cf918e..21ca09c58 100644
--- a/src/constants/apiKeys.ts
+++ b/src/constants/apiKeys.ts
@@ -9,6 +9,7 @@ export const API_SCOPES = [
"dictionary:write",
"snippets:read",
"snippets:write",
+ "transcriptions:write",
] as const;
export type ApiScope = (typeof API_SCOPES)[number];
@@ -32,6 +33,7 @@ export const API_SCOPE_I18N_KEY: Record<ApiScope, string> = {
"dictionary:write": "dictionaryWrite",
"snippets:read": "snippetsRead",
"snippets:write": "snippetsWrite",
+ "transcriptions:write": "transcriptionsWrite",
};
export interface ApiKeyExpiryOption {
diff --git a/src/helpers/cliBridge.js b/src/helpers/cliBridge.js
index 2594418e4..b3e18a858 100644
--- a/src/helpers/cliBridge.js
+++ b/src/helpers/cliBridge.js
@@ -308,6 +308,58 @@ class CliBridge {
return value;
};
+ const requireAudioFile = (value) => {
+ if (typeof value !== "string" || !value.trim()) {
+ const err = new Error("'path' must be the path of an audio file");
+ err.code = "VALIDATION";
+ throw err;
+ }
+ let stat;
+ try {
+ stat = fs.statSync(value);
+ } catch {
+ const err = new Error(`No file at ${value}`);
+ err.code = "NOT_FOUND";
+ throw err;
+ }
+ if (!stat.isFile()) {
+ const err = new Error("'path' must point to a file, not a directory");
+ err.code = "VALIDATION";
+ throw err;
+ }
+ return fs.realpathSync(value);
+ };
+
+ // Picks the requested model, or the one the app is set to use, and refuses
+ // anything not on disk so the engines' own errors stay genuine failures.
+ const requireLocalModel = (models, requested) => {
+ if (requested !== undefined && typeof requested !== "string") {
+ const err = new Error("'model' must be a string");
+ err.code = "VALIDATION";
+ throw err;
+ }
+ const match = requested
+ ? models.find((m) => m.model === requested)
+ : models.find((m) => m.default);
+ if (!match) {
+ const err = new Error(
+ requested
+ ? `Unknown model '${requested}'. Available: ${models.map((m) => m.model).join(", ")}`
+ : "No local transcription model is selected. Choose one in OpenWhispr under Settings → Transcription, or pass 'model'."
+ );
+ err.code = "VALIDATION";
+ throw err;
+ }
+ if (!match.downloaded) {
+ const err = new Error(
+ `Model '${match.model}' is not downloaded. Open OpenWhispr and download it under Settings → Transcription.`
+ );
+ err.code = "VALIDATION";
+ throw err;
+ }
+ return match;
+ };
+
const requireSuccess = (result, message) => {
if (!result?.success) {
const err = new Error(result?.error || message);
@@ -448,6 +500,28 @@ class CliBridge {
},
};
}),
+ exact("GET", "/v1/transcribe/models", () => ({ data: ipc.listLocalTranscriptionModels() })),
+ // The CLI runs on this machine, so it sends a path and the app reads the
+ // file itself: no audio crosses the bridge and the user's downloaded
+ // models do the work.
+ exact("POST", "/v1/transcribe", async ({ body }) => {
+ const real = requireAudioFile(body?.path);
+ const { provider, model } = requireLocalModel(
+ ipc.listLocalTranscriptionModels(),
+ body?.model
+ );
+ const language =
+ typeof body?.language === "string" && body.language ? body.language : undefined;
+ ipc.approveAudioPath(real);
+ const result = await ipc.transcribeLocalFile(real, { provider, model, language });
+ if (!result?.success) {
+ if (result?.code === "NO_SPEECH_DETECTED" || result?.message === "No audio detected") {
+ return { data: { text: "", provider, model, warning: "No speech detected" } };
+ }
+ throw new Error(result?.error || result?.message || "Local transcription failed");
+ }
+ return { data: { text: result.text, provider, model } };
+ }),
exact("GET", "/v1/transcriptions/list", ({ query }) => {
const limit = query.get("limit") ? Number(query.get("limit")) : 50;
return {
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 10ab0a155..666720655 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -266,6 +266,7 @@ const {
formatSpeakerTranscript,
} = require("./speakerMerge");
const { timestampRequestFields, mapVerboseSegments } = require("./uploadTimestamps");
+const { listLocalTranscriptionModels } = require("./localTranscriptionModels");
// Canonicalize allowed dirs so realpath'd inputs match on macOS (/var -> /private/var).
// Deliberately narrow: user-picked paths anywhere else are approved individually via
@@ -763,6 +764,30 @@ class IPCHandlers {
return this._getWhisperVadSettings();
}
+ // Shared by the upload IPC handler and the CLI bridge. `filePath` must
+ // already have passed resolveAllowedAudioPath (or approveAudioPath).
+ async transcribeLocalFile(filePath, options = {}) {
+ const audioBuffer = fs.readFileSync(filePath);
+ if (isSherpaLocalProvider(options.provider)) {
+ return this.parakeetManager.transcribeLocalParakeet(audioBuffer, options);
+ }
+ return this.whisperManager.transcribeLocalWhisper(audioBuffer, {
+ ...options,
+ ...this._resolveWhisperVadOptions("noteRecording"),
+ });
+ }
+
+ approveAudioPath(filePath) {
+ approveAudioPath(filePath);
+ }
+
+ listLocalTranscriptionModels() {
+ return listLocalTranscriptionModels({
+ whisperManager: this.whisperManager,
+ parakeetManager: this.parakeetManager,
+ });
+ }
+
_resolveWhisperVadOptions(context) {
const settings = this._getWhisperVadSettings();
const {
@@ -2814,7 +2839,6 @@ class IPCHandlers {
});
ipcMain.handle("transcribe-audio-file", async (event, filePath, options = {}) => {
- const fs = require("fs");
// Uploads pass a requestId so cancel-upload-transcription can abort the
// local decode; flows without one (voice drafts) register nothing.
const { signal, release } = this._uploadCancelRegistry.register(options.requestId);
@@ -2824,21 +2848,7 @@ class IPCHandlers {
}
const real = resolveAllowedAudioPath(filePath);
if (!real) return { success: false, error: "File path not allowed" };
- const audioBuffer = fs.readFileSync(real);
- if (isSherpaLocalProvider(options.provider)) {
- const result = await this.parakeetManager.transcribeLocalParakeet(audioBuffer, {
- ...options,
- signal,
- });
- return result;
- }
- const vadOptions = this._resolveWhisperVadOptions("noteRecording");
- const result = await this.whisperManager.transcribeLocalWhisper(audioBuffer, {
- ...options,
- ...vadOptions,
- signal,
- });
- return result;
+ return await this.transcribeLocalFile(real, { ...options, signal });
} catch (error) {
if (error?.name === "AbortError" || signal?.aborted) {
debugLogger.debug("Local audio file transcription cancelled", {
diff --git a/src/helpers/localTranscriptionModels.js b/src/helpers/localTranscriptionModels.js
new file mode 100644
index 000000000..a72f00b5e
--- /dev/null
+++ b/src/helpers/localTranscriptionModels.js
@@ -0,0 +1,33 @@
+const modelRegistryData = require("../models/modelRegistryData.json");
+const { getModelType } = require("./parakeetModelInfo");
+
+// Every local speech-to-text model the registry knows, with whether it is on
+// disk and whether it is the one the app is set to use. The "default" comes
+// from the .env values the renderer persists for server pre-warming, which is
+// the only copy of that setting the main process has.
+function listLocalTranscriptionModels({ whisperManager, parakeetManager, env = process.env }) {
+ const configuredProvider = env.LOCAL_TRANSCRIPTION_PROVIDER || "";
+ const configuredModel =
+ configuredProvider === "whisper" ? env.LOCAL_WHISPER_MODEL || "" : env.PARAKEET_MODEL || "";
+ const isDefault = (provider, model) =>
+ provider === configuredProvider && model === configuredModel;
+
+ const whisper = Object.keys(modelRegistryData.whisperModels).map((model) => ({
+ provider: "whisper",
+ model,
+ downloaded: whisperManager.isModelDownloaded(model),
+ default: isDefault("whisper", model),
+ }));
+ const sherpa = Object.keys(modelRegistryData.parakeetModels).map((model) => {
+ const provider = getModelType(model) === "cohere-transcribe" ? "cohere" : "nvidia";
+ return {
+ provider,
+ model,
+ downloaded: parakeetManager.isModelDownloaded(model),
+ default: isDefault(provider, model),
+ };
+ });
+ return [...whisper, ...sherpa];
+}
+
+module.exports = { listLocalTranscriptionModels };
diff --git a/src/helpers/parakeet.js b/src/helpers/parakeet.js
index 6d19f81f6..1a0960d2e 100644
--- a/src/helpers/parakeet.js
+++ b/src/helpers/parakeet.js
@@ -64,6 +64,10 @@ class ParakeetManager {
return path.join(this.getModelsDir(), modelName);
}
+ isModelDownloaded(modelName) {
+ return this.serverManager.isModelDownloaded(modelName);
+ }
+
// Cohere models keep their weights in encoder.int8.onnx.data; transducers in
// encoder.int8.onnx. Used as the reported on-disk size of a model.
_getModelWeightsSize(modelDir) {
diff --git a/src/helpers/whisper.js b/src/helpers/whisper.js
index 6c48409ed..98c02cac9 100644
--- a/src/helpers/whisper.js
+++ b/src/helpers/whisper.js
@@ -133,6 +133,10 @@ class WhisperManager {
return path.join(this.getModelsDir(), config.fileName);
}
+ isModelDownloaded(modelName) {
+ return fs.existsSync(this.getModelPath(modelName));
+ }
+
getVadModelPath() {
if (this.cachedVadModelPath !== undefined) return this.cachedVadModelPath;
diff --git a/src/locales/ar/translation.json b/src/locales/ar/translation.json
index 6c5d13fe3..9a59599db 100644
--- a/src/locales/ar/translation.json
+++ b/src/locales/ar/translation.json
@@ -1065,7 +1065,8 @@
"dictionaryRead": "قراءة القاموس",
"dictionaryWrite": "تعديل القاموس",
"snippetsRead": "قراءة المقتطفات",
- "snippetsWrite": "تعديل المقتطفات"
+ "snippetsWrite": "تعديل المقتطفات",
+ "transcriptionsWrite": "تحويل الصوت إلى نص"
},
"revoke": {
"button": "إبطال",
diff --git a/src/locales/de/translation.json b/src/locales/de/translation.json
index 02e53704b..41aeb19c2 100644
--- a/src/locales/de/translation.json
+++ b/src/locales/de/translation.json
@@ -1259,7 +1259,8 @@
"dictionaryRead": "Wörterbuch lesen",
"dictionaryWrite": "Wörterbuch bearbeiten",
"snippetsRead": "Snippets lesen",
- "snippetsWrite": "Snippets bearbeiten"
+ "snippetsWrite": "Snippets bearbeiten",
+ "transcriptionsWrite": "Audio transkribieren"
},
"revoke": {
"button": "Widerrufen",
diff --git a/src/locales/en/translation.json b/src/locales/en/translation.json
index 582cd02f7..0ca1a9e2e 100644
--- a/src/locales/en/translation.json
+++ b/src/locales/en/translation.json
@@ -1259,7 +1259,8 @@
"dictionaryRead": "Read dictionary",
"dictionaryWrite": "Edit dictionary",
"snippetsRead": "Read snippets",
- "snippetsWrite": "Edit snippets"
+ "snippetsWrite": "Edit snippets",
+ "transcriptionsWrite": "Transcribe audio"
},
"revoke": {
"button": "Revoke",
diff --git a/src/locales/es/translation.json b/src/locales/es/translation.json
index 4afd70c8f..cb541656b 100644
--- a/src/locales/es/translation.json
+++ b/src/locales/es/translation.json
@@ -1218,7 +1218,8 @@
"dictionaryRead": "Leer diccionario",
"dictionaryWrite": "Editar diccionario",
"snippetsRead": "Leer snippets",
- "snippetsWrite": "Editar snippets"
+ "snippetsWrite": "Editar snippets",
+ "transcriptionsWrite": "Transcribir audio"
},
"revoke": {
"button": "Revocar",
diff --git a/src/locales/fr/translation.json b/src/locales/fr/translation.json
index 18559d5f8..870dc2f10 100644
--- a/src/locales/fr/translation.json
+++ b/src/locales/fr/translation.json
@@ -1259,7 +1259,8 @@
"dictionaryRead": "Lire le dictionnaire",
"dictionaryWrite": "Modifier le dictionnaire",
"snippetsRead": "Lire les snippets",
- "snippetsWrite": "Modifier les snippets"
+ "snippetsWrite": "Modifier les snippets",
+ "transcriptionsWrite": "Transcrire l'audio"
},
"revoke": {
"button": "Révoquer",
diff --git a/src/locales/it/translation.json b/src/locales/it/translation.json
index 31cb5983c..1d69a11da 100644
--- a/src/locales/it/translation.json
+++ b/src/locales/it/translation.json
@@ -3894,7 +3894,8 @@
"dictionaryRead": "Leggi dizionario",
"dictionaryWrite": "Modifica dizionario",
"snippetsRead": "Leggi snippet",
- "snippetsWrite": "Modifica snippet"
+ "snippetsWrite": "Modifica snippet",
+ "transcriptionsWrite": "Trascrivi audio"
},
"revoke": {
"button": "Revoca",
diff --git a/src/locales/ja/translation.json b/src/locales/ja/translation.json
index 71af41a42..9dc341e82 100644
--- a/src/locales/ja/translation.json
+++ b/src/locales/ja/translation.json
@@ -3894,7 +3894,8 @@
"dictionaryRead": "辞書を読み取り",
"dictionaryWrite": "辞書を編集",
"snippetsRead": "スニペットを読み取り",
- "snippetsWrite": "スニペットを編集"
+ "snippetsWrite": "スニペットを編集",
+ "transcriptionsWrite": "音声を文字起こし"
},
"revoke": {
"button": "取り消し",
diff --git a/src/locales/pt/translation.json b/src/locales/pt/translation.json
index 26feec944..b6080a833 100644
--- a/src/locales/pt/translation.json
+++ b/src/locales/pt/translation.json
@@ -3894,7 +3894,8 @@
"dictionaryRead": "Ler dicionário",
"dictionaryWrite": "Editar dicionário",
"snippetsRead": "Ler snippets",
- "snippetsWrite": "Editar snippets"
+ "snippetsWrite": "Editar snippets",
+ "transcriptionsWrite": "Transcrever áudio"
},
"revoke": {
"button": "Revogar",
diff --git a/src/locales/ru/translation.json b/src/locales/ru/translation.json
index 5376e0647..d690e389d 100644
--- a/src/locales/ru/translation.json
+++ b/src/locales/ru/translation.json
@@ -3940,7 +3940,8 @@
"dictionaryRead": "Чтение словаря",
"dictionaryWrite": "Изменение словаря",
"snippetsRead": "Чтение сниппетов",
- "snippetsWrite": "Изменение сниппетов"
+ "snippetsWrite": "Изменение сниппетов",
+ "transcriptionsWrite": "Транскрибировать аудио"
},
"revoke": {
"button": "Отозвать",
diff --git a/src/locales/zh-CN/translation.json b/src/locales/zh-CN/translation.json
index fc77f5447..f6175d261 100644
--- a/src/locales/zh-CN/translation.json
+++ b/src/locales/zh-CN/translation.json
@@ -3894,7 +3894,8 @@
"dictionaryRead": "读取词典",
"dictionaryWrite": "编辑词典",
"snippetsRead": "读取片段",
- "snippetsWrite": "编辑片段"
+ "snippetsWrite": "编辑片段",
+ "transcriptionsWrite": "转录音频"
},
"revoke": {
"button": "撤销",
diff --git a/src/locales/zh-TW/translation.json b/src/locales/zh-TW/translation.json
index ab63f8f5c..46d23012e 100644
--- a/src/locales/zh-TW/translation.json
+++ b/src/locales/zh-TW/translation.json
@@ -3894,7 +3894,8 @@
"dictionaryRead": "讀取字典",
"dictionaryWrite": "編輯字典",
"snippetsRead": "讀取片段",
- "snippetsWrite": "編輯片段"
+ "snippetsWrite": "編輯片段",
+ "transcriptionsWrite": "轉錄音訊"
},
"revoke": {
"button": "撤銷",
diff --git a/test/helpers/cliBridgeTranscribe.test.js b/test/helpers/cliBridgeTranscribe.test.js
new file mode 100644
index 000000000..47b739324
--- /dev/null
+++ b/test/helpers/cliBridgeTranscribe.test.js
@@ -0,0 +1,152 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const Module = require("node:module");
+
+const originalLoad = Module._load;
+Module._load = function patchedLoad(request, parent, isMain) {
+ if (request === "electron") {
+ return { app: { getPath: () => os.tmpdir(), getAppPath: () => process.cwd() } };
+ }
+ if (request === "./windowBroadcast") return { broadcastToWindows() {} };
+ return originalLoad.call(this, request, parent, isMain);
+};
+
+const CliBridge = require("../../src/helpers/cliBridge.js");
+
+const MODELS = [
+ { provider: "whisper", model: "base", downloaded: true, default: true },
+ { provider: "whisper", model: "large", downloaded: false, default: false },
+ { provider: "nvidia", model: "parakeet-tdt-0.6b-v3", downloaded: true, default: false },
+];
+
+function createBridge(models = MODELS) {
+ const calls = { approved: [], transcribed: [] };
+ const bridge = new CliBridge({
+ databaseManager: {},
+ listLocalTranscriptionModels: () => models,
+ approveAudioPath: (p) => calls.approved.push(p),
+ transcribeLocalFile: async (p, options) => {
+ calls.transcribed.push({ path: p, options });
+ return { success: true, text: "hello from disk" };
+ },
+ });
+ return { bridge, calls };
+}
+
+function call(bridge, method, pathname, body) {
+ for (const route of bridge.routes) {
+ if (route.method !== method) continue;
+ const params = route.match(pathname);
+ if (!params) continue;
+ return route.handler({ params, query: new URLSearchParams(), body });
+ }
+ throw new Error(`No route for ${method} ${pathname}`);
+}
+
+function audioFile() {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "openwhispr-cli-transcribe-"));
+ const file = path.join(dir, "memo.wav");
+ fs.writeFileSync(file, "RIFF....WAVE");
+ return { dir, file };
+}
+
+test("GET /v1/transcribe/models lists every local model with its state", () => {
+ const { bridge } = createBridge();
+ assert.deepEqual(call(bridge, "GET", "/v1/transcribe/models"), { data: MODELS });
+});
+
+test("POST /v1/transcribe approves the real path and runs the app's default model", async () => {
+ const { bridge, calls } = createBridge();
+ const { file } = audioFile();
+
+ const result = await call(bridge, "POST", "/v1/transcribe", { path: file });
+
+ assert.deepEqual(result, {
+ data: { text: "hello from disk", provider: "whisper", model: "base" },
+ });
+ assert.deepEqual(calls.approved, [fs.realpathSync(file)]);
+ assert.deepEqual(calls.transcribed, [
+ {
+ path: fs.realpathSync(file),
+ options: { provider: "whisper", model: "base", language: undefined },
+ },
+ ]);
+});
+
+test("POST /v1/transcribe honors an explicit model and language", async () => {
+ const { bridge, calls } = createBridge();
+ const { file } = audioFile();
+
+ await call(bridge, "POST", "/v1/transcribe", {
+ path: file,
+ model: "parakeet-tdt-0.6b-v3",
+ language: "de",
+ });
+
+ assert.deepEqual(calls.transcribed[0].options, {
+ provider: "nvidia",
+ model: "parakeet-tdt-0.6b-v3",
+ language: "de",
+ });
+});
+
+test("POST /v1/transcribe reports silence as empty text, not an error", async () => {
+ const { bridge } = createBridge();
+ bridge.ipcHandlers.transcribeLocalFile = async () => ({
+ success: false,
+ code: "NO_SPEECH_DETECTED",
+ message: "No audio detected",
+ });
+ const { file } = audioFile();
+
+ const result = await call(bridge, "POST", "/v1/transcribe", { path: file });
+
+ assert.deepEqual(result, {
+ data: { text: "", provider: "whisper", model: "base", warning: "No speech detected" },
+ });
+});
+
+test("POST /v1/transcribe refuses models that are unknown or not downloaded", async () => {
+ const { bridge, calls } = createBridge();
+ const { file } = audioFile();
+
+ await assert.rejects(call(bridge, "POST", "/v1/transcribe", { path: file, model: "large" }), {
+ code: "VALIDATION",
+ message: /not downloaded/,
+ });
+ await assert.rejects(call(bridge, "POST", "/v1/transcribe", { path: file, model: "nope" }), {
+ code: "VALIDATION",
+ message: /Unknown model 'nope'. Available: base, large, parakeet-tdt-0.6b-v3/,
+ });
+ assert.equal(calls.approved.length, 0);
+});
+
+test("POST /v1/transcribe explains when the app has no local model selected", async () => {
+ const { bridge } = createBridge(MODELS.map((m) => ({ ...m, default: false })));
+ const { file } = audioFile();
+
+ await assert.rejects(call(bridge, "POST", "/v1/transcribe", { path: file }), {
+ code: "VALIDATION",
+ message: /No local transcription model is selected/,
+ });
+});
+
+test("POST /v1/transcribe validates the path before touching anything", async () => {
+ const { bridge, calls } = createBridge();
+ const { dir } = audioFile();
+
+ await assert.rejects(call(bridge, "POST", "/v1/transcribe", {}), { code: "VALIDATION" });
+ await assert.rejects(call(bridge, "POST", "/v1/transcribe", { path: dir }), {
+ code: "VALIDATION",
+ message: /not a directory/,
+ });
+ await assert.rejects(
+ call(bridge, "POST", "/v1/transcribe", { path: path.join(dir, "missing.wav") }),
+ { code: "NOT_FOUND" }
+ );
+ assert.equal(calls.approved.length, 0);
+ assert.equal(calls.transcribed.length, 0);
+});
diff --git a/test/helpers/localTranscriptionModels.test.js b/test/helpers/localTranscriptionModels.test.js
new file mode 100644
index 000000000..ce3e59504
--- /dev/null
+++ b/test/helpers/localTranscriptionModels.test.js
@@ -0,0 +1,49 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { listLocalTranscriptionModels } = require("../../src/helpers/localTranscriptionModels.js");
+const registry = require("../../src/models/modelRegistryData.json");
+
+const managers = (downloaded) => ({
+ whisperManager: { isModelDownloaded: (m) => downloaded.has(m) },
+ parakeetManager: { isModelDownloaded: (m) => downloaded.has(m) },
+});
+
+test("lists every registry model with provider, download state, and the app's default", () => {
+ const models = listLocalTranscriptionModels({
+ ...managers(new Set(["base", "cohere-transcribe-03-2026"])),
+ env: { LOCAL_TRANSCRIPTION_PROVIDER: "whisper", LOCAL_WHISPER_MODEL: "base" },
+ });
+
+ const whisperCount = Object.keys(registry.whisperModels).length;
+ const sherpaCount = Object.keys(registry.parakeetModels).length;
+ assert.equal(models.length, whisperCount + sherpaCount);
+
+ const base = models.find((m) => m.model === "base");
+ assert.deepEqual(base, { provider: "whisper", model: "base", downloaded: true, default: true });
+
+ const cohere = models.find((m) => m.model === "cohere-transcribe-03-2026");
+ assert.equal(cohere.provider, "cohere");
+ assert.equal(cohere.downloaded, true);
+ assert.equal(cohere.default, false);
+
+ assert.equal(models.filter((m) => m.default).length, 1);
+ assert.ok(models.some((m) => m.provider === "nvidia"));
+});
+
+test("a sherpa default is read from PARAKEET_MODEL, and cloud mode yields no default", () => {
+ const withParakeet = listLocalTranscriptionModels({
+ ...managers(new Set()),
+ env: { LOCAL_TRANSCRIPTION_PROVIDER: "nvidia", PARAKEET_MODEL: "parakeet-tdt-0.6b-v3" },
+ });
+ assert.deepEqual(
+ withParakeet.filter((m) => m.default).map((m) => m.model),
+ ["parakeet-tdt-0.6b-v3"]
+ );
+
+ const cloudMode = listLocalTranscriptionModels({ ...managers(new Set()), env: {} });
+ assert.equal(
+ cloudMode.some((m) => m.default),
+ false
+ );
+});