Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
const http = require("http");
const fs = require("fs");
const os = require("os");
const path = require("path");
const crypto = require("crypto");
const debugLogger = require("./debugLogger");
const { isPortAvailable } = require("../utils/serverUtils");
const { broadcastToWindows } = require("./windowBroadcast");
const { NOTE_TEXT_FIELDS } = require("./noteFieldSync");
const PORT_RANGE_START = 8200;
const PORT_RANGE_END = 8219;
const HOST = "127.0.0.1";
const BRIDGE_FILE_VERSION = 1;
const MAX_REQUEST_BODY_BYTES = 1 * 1024 * 1024;
const LOOPBACK_ADDRESSES = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
const NO_CONTENT = Symbol("CliBridge.NoContent");
function getBridgeFilePath() {
return path.join(os.homedir(), ".openwhispr", "cli-bridge.json");
}
async function findAvailablePort() {
for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
if (await isPortAvailable(port)) return port;
}
throw new Error(`No available ports in range ${PORT_RANGE_START}-${PORT_RANGE_END}`);
}
function readJsonBody(req) {
return new Promise((resolve, reject) => {
// Buffer the raw chunks and decode once at the end: decoding per chunk
// corrupts multibyte sequences split across chunk boundaries.
const chunks = [];
let receivedBytes = 0;
let rejected = false;
req.on("data", (chunk) => {
if (rejected) return;
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
receivedBytes += buffer.length;
if (receivedBytes > MAX_REQUEST_BODY_BYTES) {
rejected = true;
reject(new Error("Request body too large"));
req.destroy();
return;
}
chunks.push(buffer);
});
req.on("end", () => {
if (rejected) return;
const raw = Buffer.concat(chunks, receivedBytes).toString("utf8");
if (!raw) return resolve({});
try {
resolve(JSON.parse(raw));
} catch {
reject(new Error("Invalid JSON payload"));
}
});
req.on("error", reject);
});
}
function sendJson(res, statusCode, payload) {
const body = JSON.stringify(payload);
res.writeHead(statusCode, {
"Content-Type": "application/json; charset=utf-8",
"Content-Length": Buffer.byteLength(body),
});
res.end(body);
}
function sendNoContent(res) {
res.writeHead(204);
res.end();
}
function sendV1Error(res, statusCode, code, message) {
sendJson(res, statusCode, { error: { code, message } });
}
function parseIdParam(value) {
const id = Number(value);
if (!Number.isInteger(id) || id <= 0) return null;
return id;
}
function parsePositiveIntQuery(query, key, fallback) {
const raw = query.get(key);
if (raw === null || raw === "") return fallback;
const num = parseIdParam(raw);
if (num === null) {
const err = new Error(`Query parameter '${key}' must be a positive integer`);
err.code = "VALIDATION";
throw err;
}
return num;
}
function unwrapMutationResult(result, label) {
if (!result?.success || !result[label]) {
throw new Error(result?.error || `Failed to write ${label}`);
}
return result[label];
}
// The public v1 contract: a provided blank content or enhanced_content clears
// that field. updateNote treats a bare blank as unconfirmed (never synced as a
// clear), so the bridge states the intent; updateNote still validates it.
function withProvidedBlanksCleared(body) {
const blanks = NOTE_TEXT_FIELDS.filter(
(field) =>
field in body &&
(body[field] == null || (typeof body[field] === "string" && !body[field].trim()))
);
if (blanks.length === 0 || (body.clear_fields !== undefined && !Array.isArray(body.clear_fields)))
return body;
return { ...body, clear_fields: [...new Set([...(body.clear_fields ?? []), ...blanks])] };
}
class CliBridge {
constructor(ipcHandlers) {
this.ipcHandlers = ipcHandlers;
this.server = null;
this.port = null;
this.token = null;
this.bridgeFilePath = getBridgeFilePath();
this.routes = this._buildRouteTable();
}
async start() {
if (this.server) return;
this.token = crypto.randomBytes(32).toString("hex");
this.port = await findAvailablePort();
this.server = http.createServer((req, res) => {
this._handleRequest(req, res).catch((err) => {
debugLogger.error("CLI bridge handler error", { error: err.message }, "cli-bridge");
if (!res.headersSent) {
sendV1Error(res, 500, "internal_error", "Internal server error");
}
});
});
await new Promise((resolve, reject) => {
const onError = (err) => {
this.server = null;
reject(err);
};
this.server.once("error", onError);
this.server.listen(this.port, HOST, () => {
this.server.removeListener("error", onError);
resolve();
});
});
this._writeBridgeFile();
debugLogger.info("CLI bridge started", { port: this.port }, "cli-bridge");
}
async stop() {
if (!this.server) return;
await new Promise((resolve) => {
this.server.close(() => resolve());
});
this.server = null;
this.port = null;
this.token = null;
this._removeBridgeFile();
debugLogger.info("CLI bridge stopped", {}, "cli-bridge");
}
_writeBridgeFile() {
const dir = path.dirname(this.bridgeFilePath);
fs.mkdirSync(dir, { recursive: true });
const payload = JSON.stringify({
version: BRIDGE_FILE_VERSION,
port: this.port,
token: this.token,
});
fs.writeFileSync(this.bridgeFilePath, payload, { mode: 0o600 });
// Re-apply mode in case the filesystem ignored the mode arg on create.
// No-op on Windows ACLs but harmless; swallow errors from exotic filesystems.
try {
fs.chmodSync(this.bridgeFilePath, 0o600);
} catch (err) {
debugLogger.debug("CLI bridge chmod failed", { error: err.message }, "cli-bridge");
}
}
_removeBridgeFile() {
try {
fs.unlinkSync(this.bridgeFilePath);
} catch (err) {
if (err.code !== "ENOENT") {
debugLogger.debug("CLI bridge file removal failed", { error: err.message }, "cli-bridge");
}
}
}
async _handleRequest(req, res) {
const remote = req.socket?.remoteAddress;
if (!remote || !LOOPBACK_ADDRESSES.has(remote)) {
sendV1Error(res, 403, "forbidden", "Forbidden");
return;
}
const auth = req.headers["authorization"] || "";
const expected = `Bearer ${this.token}`;
if (
auth.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(auth), Buffer.from(expected))
) {
sendV1Error(res, 401, "unauthorized", "Unauthorized");
return;
}
const url = new URL(req.url || "/", `http://${HOST}:${this.port}`);
const route = this._matchRoute(req.method, url.pathname);
if (!route) {
sendV1Error(res, 404, "not_found", "Not found");
return;
}
let body = {};
if (req.method !== "GET" && req.method !== "DELETE") {
try {
body = await readJsonBody(req);
} catch (err) {
sendV1Error(res, 400, "validation_error", err.message);
return;
}
}
try {
const result = await route.handler({ params: route.params, query: url.searchParams, body });
if (result === NO_CONTENT) {
sendNoContent(res);
return;
}
const status = route.status || 200;
sendJson(res, status, result);
} catch (err) {
this._sendError(res, err);
}
}
_sendError(res, err) {
if (err.code === "NOT_FOUND") {
sendV1Error(res, 404, "not_found", err.message);
return;
}
if (err.code === "VALIDATION") {
sendV1Error(res, 400, "validation_error", err.message);
return;
}
debugLogger.error("CLI bridge route error", { error: err.message }, "cli-bridge");
sendV1Error(res, 500, "internal_error", err.message || "Internal server error");
}
_matchRoute(method, pathname) {
for (const route of this.routes) {
if (route.method !== method) continue;
const params = route.match(pathname);
if (params) return { ...route, params };
}
return null;
}
_buildRouteTable() {
const exact = (method, path, handler, status) => ({
method,
match: (p) => (p === path ? {} : null),
handler,
status,
});
const param = (method, prefix, suffix, paramName, handler, status) => ({
method,
match: (p) => {
if (!p.startsWith(prefix)) return null;
const rest = p.slice(prefix.length);
if (suffix) {
if (!rest.endsWith(suffix)) return null;
const value = rest.slice(0, rest.length - suffix.length);
if (!value || value.includes("/")) return null;
return { [paramName]: value };
}
if (rest.includes("/")) return null;
return { [paramName]: rest };
},
handler,
status,
});
const db = this.ipcHandlers.databaseManager;
const ipc = this.ipcHandlers;
const requireId = (params, label) => {
const id = parseIdParam(params.id);
if (id == null) {
const err = new Error(`Invalid ${label} id`);
err.code = "NOT_FOUND";
throw err;
}
return id;
};
const requireWordList = (value, field) => {
if (value === undefined || value === null) return [];
if (!Array.isArray(value) || value.some((w) => typeof w !== "string")) {
const err = new Error(`'${field}' must be an array of strings`);
err.code = "VALIDATION";
throw err;
}
return value;
};
const requireSnippetList = (value) => {
if (value === undefined || value === null) return [];
const valid =
Array.isArray(value) &&
value.every(
(s) =>
s &&
typeof s.trigger === "string" &&
s.trigger.trim() &&
typeof s.replacement === "string" &&
s.replacement.trim()
);
if (!valid) {
const err = new Error("'add' must be an array of { trigger, replacement } strings");
err.code = "VALIDATION";
throw err;
}
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);
err.code = "NOT_FOUND";
throw err;
}
};
return [
exact("GET", "/v1/health", () => ({ data: { ok: true, version: 1 } })),
exact("GET", "/v1/notes/list", ({ query }) => {
const noteType = query.get("note_type") || null;
const limit = parsePositiveIntQuery(query, "limit", 100);
const folderId = parsePositiveIntQuery(query, "folder_id", null);
const notes = db.getNotes(noteType, limit, folderId);
return { data: notes, has_more: false, next_cursor: null };
}),
exact("GET", "/v1/notes/search", ({ query }) => {
const q = query.get("q") || "";
if (!q.trim()) {
const err = new Error("Search query is required");
err.code = "VALIDATION";
throw err;
}
const limit = parsePositiveIntQuery(query, "limit", 20);
const notes = db.searchNotes(q, limit);
return { data: notes, has_more: false, next_cursor: null };
}),
param("GET", "/v1/notes/", "", "id", ({ params }) => {
const id = requireId(params, "note");
const note = db.getNote(id);
if (!note || note.deleted_at) {
const err = new Error(`Note ${id} not found`);
err.code = "NOT_FOUND";
throw err;
}
return { data: note };
}),
exact(
"POST",
"/v1/notes/create",
({ body }) => {
const result = db.saveNote(
body.title ?? "Untitled Note",
body.content ?? "",
body.note_type ?? "personal",
body.source_file ?? null,
body.audio_duration_seconds ?? null,
body.folder_id ?? null
);
const note = unwrapMutationResult(result, "note");
setImmediate(() => broadcastToWindows("note-added", note));
ipc.notifyVectorChanges();
ipc._asyncMirrorWrite(note);
return { data: note };
},
201
),
param("PATCH", "/v1/notes/", "", "id", ({ params, body }) => {
const id = requireId(params, "note");
const existing = db.getNote(id);
if (!existing || existing.deleted_at) {
const err = new Error(`Note ${id} not found`);
err.code = "NOT_FOUND";
throw err;
}
const result = db.updateNote(id, withProvidedBlanksCleared(body || {}));
// The note exists, so a remaining error names a folder or space that doesn't.
if (result.error) {
const err = new Error(result.error);
err.code = "VALIDATION";
throw err;
}
const note = unwrapMutationResult(result, "note");
setImmediate(() => broadcastToWindows("note-updated", note));
ipc.notifyVectorChanges();
ipc._asyncMirrorWrite(note);
return { data: note };
}),
param("DELETE", "/v1/notes/", "", "id", ({ params }) => {
const id = requireId(params, "note");
const result = ipc.deleteNoteInternal(id);
requireSuccess(result, `Note ${id} not found`);
return NO_CONTENT;
}),
exact("GET", "/v1/folders/list", () => {
return { data: db.getFolders(), has_more: false, next_cursor: null };
}),
exact(
"POST",
"/v1/folders/create",
({ body }) => {
const result = db.createFolder(body?.name);
const folder = unwrapMutationResult(result, "folder");
setImmediate(() => broadcastToWindows("folder-created", folder));
return { data: folder };
},
201
),
exact("GET", "/v1/dictionary/list", () => {
return { data: db.getDictionary(), has_more: false, next_cursor: null };
}),
// Bulk edits without writing to SQLite by hand, which lost rows on the
// next launch and never reached the cloud (#1295). Takes a delta, so an
// import cannot delete words it didn't name.
exact("POST", "/v1/dictionary/update", ({ body }) => {
const add = requireWordList(body?.add, "add");
const remove = requireWordList(body?.remove, "remove");
if (add.length === 0 && remove.length === 0) {
const err = new Error("Provide at least one word in 'add' or 'remove'");
err.code = "VALIDATION";
throw err;
}
const result = db.applyDictionaryChanges({ add, remove });
const words = db.getDictionary();
setImmediate(() => broadcastToWindows("dictionary-updated", words));
return { data: { words, added: result.added, removed: result.removed } };
}),
exact("GET", "/v1/snippets/list", () => {
return { data: db.getSnippets(), has_more: false, next_cursor: null };
}),
// Same delta shape as the dictionary route: an add with an existing
// trigger replaces that snippet's text, and removes are by trigger.
exact("POST", "/v1/snippets/update", ({ body }) => {
const add = requireSnippetList(body?.add);
const remove = requireWordList(body?.remove, "remove");
if (add.length === 0 && remove.length === 0) {
const err = new Error("Provide at least one snippet in 'add' or trigger in 'remove'");
err.code = "VALIDATION";
throw err;
}
const lower = (trigger) => trigger.trim().toLowerCase();
const removeKeys = new Set(remove.map(lower));
const addKeys = new Set(add.map((s) => lower(s.trigger)));
const current = db.getSnippets();
const kept = current.filter(
(s) => !removeKeys.has(lower(s.trigger)) && !addKeys.has(lower(s.trigger))
);
db.setSnippets([...kept, ...add]);
const snippets = db.getSnippets();
setImmediate(() => broadcastToWindows("snippets-updated", snippets));
// setSnippets drops entries it cannot store (e.g. over-long triggers),
// so count what landed rather than what was sent.
const storedKeys = new Set(snippets.map((s) => lower(s.trigger)));
return {
data: {
snippets,
added: add.filter((s) => storedKeys.has(lower(s.trigger))).length,
removed: current.filter((s) => removeKeys.has(lower(s.trigger))).length,
},
};
}),
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 = parsePositiveIntQuery(query, "limit", 50);
return {
data: db.getTranscriptions(limit),
has_more: false,
next_cursor: null,
};
}),
param("GET", "/v1/transcriptions/", "", "id", ({ params }) => {
const id = requireId(params, "transcription");
const transcription = db.getTranscriptionById(id);
if (!transcription || transcription.deleted_at) {
const err = new Error(`Transcription ${id} not found`);
err.code = "NOT_FOUND";
throw err;
}
return { data: transcription };
}),
param("DELETE", "/v1/transcriptions/", "", "id", ({ params }) => {
const id = requireId(params, "transcription");
const result = ipc.deleteTranscriptionInternal(id);
requireSuccess(result, `Transcription ${id} not found`);
return NO_CONTENT;
}),
param("DELETE", "/v1/transcriptions/", "/audio", "id", ({ params }) => {
const id = requireId(params, "transcription");
const result = ipc.audioStorageManager.deleteAudio(id);
if (!result?.success) {
throw new Error(`Failed to delete audio for transcription ${id}`);
}
db.updateTranscriptionAudio(id, {
hasAudio: 0,
audioDurationMs: null,
provider: null,
model: null,
});
return NO_CONTENT;
}),
];
}
}
module.exports = CliBridge;
module.exports.getBridgeFilePath = getBridgeFilePath;