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
feat: smart error CTA for failed transcriptions
Gabriel Stein7c0429f05b8a
diff --git a/src/components/ui/TranscriptionItem.tsx b/src/components/ui/TranscriptionItem.tsxindex e726f82ad..eb1f0ff9d 100644--- a/src/components/ui/TranscriptionItem.tsx+++ b/src/components/ui/TranscriptionItem.tsx@@ -3,7 +3,10 @@ import { useTranslation } from "react-i18next";import { Button } from "./button";import { Tooltip } from "./tooltip";import { Copy, Trash2, FileText, FolderOpen, RotateCcw, Loader2, AlertCircle } from "lucide-react";-import type { TranscriptionItem as TranscriptionItemType } from "../../types/electron";+import type {+ TranscriptionItem as TranscriptionItemType,+ TranscriptionErrorCode,+} from "../../types/electron";import { cn } from "../lib/utils";import { getCachedPlatform } from "../../utils/platform";@@ -61,6 +64,15 @@ export default function TranscriptionItem({const hasAudio = item.has_audio === 1;const showUtilityGroup = hasRawText || hasAudio;+ const errorCode = item.error_code as TranscriptionErrorCode;+ const isConfigError =+ errorCode === "API_KEY_MISSING" ||+ errorCode === "INVALID_KEY" ||+ errorCode === "MODEL_NOT_AVAILABLE";+ const isAuthError = errorCode === "AUTH_EXPIRED" || errorCode === "AUTH_REQUIRED";+ const isLimitError = errorCode === "LIMIT_REACHED";+ const isOfflineError = errorCode === "OFFLINE";+return (<divclassName={cn(@@ -91,26 +103,48 @@ export default function TranscriptionItem({{item.error_message}</p>)}- <p className="text-xs text-muted-foreground mt-1">- {hasAudio ? (- <>+ {isConfigError && (+ <p className="text-xs text-muted-foreground mt-1">+ {hasAudio ? (+ <>+ <button+ onClick={() => onOpenSettings?.()}+ className="text-primary hover:underline cursor-pointer"+ >+ {t("controlPanel.history.failedCtaSettings")}+ </button>{" "}+ {t("controlPanel.history.failedCtaAndRetry")}+ </>+ ) : (<buttononClick={() => onOpenSettings?.()}className="text-primary hover:underline cursor-pointer">- {t("controlPanel.history.failedCtaSettings")}- </button>{" "}- {t("controlPanel.history.failedCtaAndRetry")}- </>- ) : (+ {t("controlPanel.history.failedCtaSettingsOnly")}+ </button>+ )}+ </p>+ )}+ {isAuthError && (+ <p className="text-xs text-muted-foreground mt-1"><buttononClick={() => onOpenSettings?.()}className="text-primary hover:underline cursor-pointer">- {t("controlPanel.history.failedCtaSettingsOnly")}+ {t("controlPanel.history.failedCtaSignIn")}</button>- )}- </p>+ </p>+ )}+ {isLimitError && (+ <p className="text-xs text-muted-foreground mt-1">+ {t("controlPanel.history.failedLimitReached")}+ </p>+ )}+ {isOfflineError && (+ <p className="text-xs text-muted-foreground mt-1">+ {t("controlPanel.history.failedOffline")}+ </p>+ )}</div></div>) : (diff --git a/src/helpers/audioManager.js b/src/helpers/audioManager.jsindex 44cfd8bab..457b0e244 100644--- a/src/helpers/audioManager.js+++ b/src/helpers/audioManager.js@@ -594,7 +594,7 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);// Save failed transcription with audio so the user can retry laterif (this.lastAudioBlob) {- this.saveFailedTranscription(error.message, metadata);+ this.saveFailedTranscription(error.message, error.code || null, metadata);}}} finally {@@ -816,7 +816,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);apiKey = await window.electronAPI.getMistralKey?.();}if (!isValidApiKey(apiKey, "mistral")) {- throw new Error("Mistral API key not found. Please set your API key in the Control Panel.");+ const err = new Error(+ "Mistral API key not found. Please set your API key in the Control Panel."+ );+ err.code = "API_KEY_MISSING";+ throw err;}} else if (provider === "groq") {// Prefer store value (user-entered via UI) over main process (.env)@@ -825,7 +829,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);apiKey = await window.electronAPI.getGroqKey?.();}if (!isValidApiKey(apiKey, "groq")) {- throw new Error("Groq API key not found. Please set your API key in the Control Panel.");+ const err = new Error(+ "Groq API key not found. Please set your API key in the Control Panel."+ );+ err.code = "API_KEY_MISSING";+ throw err;}} else {// Default to OpenAI@@ -836,9 +844,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);apiKey = await window.electronAPI.getOpenAIKey();}if (!isValidApiKey(apiKey, "openai")) {- throw new Error(+ const err = new Error("OpenAI API key not found. Please set your API key in the .env file or Control Panel.");+ err.code = "API_KEY_MISSING";+ throw err;}}@@ -1511,7 +1521,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);},"transcription");- throw new Error(`API Error: ${response.status} ${errorText}`);+ const err = new Error(`API Error: ${response.status} ${errorText}`);+ if (response.status === 401) err.code = "INVALID_KEY";+ else if (response.status === 429) err.code = "LIMIT_REACHED";+ else if (response.status >= 500) err.code = "SERVER_ERROR";+ throw err;}let result;@@ -1860,7 +1874,7 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);}}- async saveFailedTranscription(errorMessage, metadata = {}) {+ async saveFailedTranscription(errorMessage, errorCode = null, metadata = {}) {if (!getSettings().dataRetentionEnabled) {logger.debug("Skipping failed transcription save — data retention disabled", {}, "audio");this.lastAudioBlob = null;@@ -1872,6 +1886,7 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);const result = await window.electronAPI.saveTranscription("", null, {status: "failed",errorMessage,+ errorCode,});if (result?.id && this.lastAudioBlob) {diff --git a/src/helpers/database.js b/src/helpers/database.jsindex a84bdf2fa..3a831f8f5 100644--- a/src/helpers/database.js+++ b/src/helpers/database.js@@ -67,6 +67,11 @@ class DatabaseManager {} catch (err) {if (!err.message.includes("duplicate column")) throw err;}+ try {+ this.db.exec("ALTER TABLE transcriptions ADD COLUMN error_code TEXT");+ } catch (err) {+ if (!err.message.includes("duplicate column")) throw err;+ }this.db.exec(`CREATE TABLE IF NOT EXISTS custom_dictionary (@@ -390,15 +395,19 @@ class DatabaseManager {}}- saveTranscription(text, rawText = null, { status = "completed", errorMessage = null } = {}) {+ saveTranscription(+ text,+ rawText = null,+ { status = "completed", errorMessage = null, errorCode = null } = {}+ ) {try {if (!this.db) {throw new Error("Database not initialized");}const stmt = this.db.prepare(- "INSERT INTO transcriptions (text, raw_text, status, error_message) VALUES (?, ?, ?, ?)"+ "INSERT INTO transcriptions (text, raw_text, status, error_message, error_code) VALUES (?, ?, ?, ?, ?)");- const result = stmt.run(text, rawText, status, errorMessage);+ const result = stmt.run(text, rawText, status, errorMessage, errorCode);const fetchStmt = this.db.prepare("SELECT * FROM transcriptions WHERE id = ?");const transcription = fetchStmt.get(result.lastInsertRowid);@@ -478,13 +487,13 @@ class DatabaseManager {}}- updateTranscriptionStatus(id, status, errorMessage = null) {+ updateTranscriptionStatus(id, status, errorMessage = null, errorCode = null) {try {if (!this.db) throw new Error("Database not initialized");const stmt = this.db.prepare(- "UPDATE transcriptions SET status = ?, error_message = ? WHERE id = ?"+ "UPDATE transcriptions SET status = ?, error_message = ?, error_code = ? WHERE id = ?");- stmt.run(status, errorMessage, id);+ stmt.run(status, errorMessage, errorCode, id);return { success: true };} catch (error) {debugLogger.error(diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.jsindex 1e4ebaa53..dfefdeea2 100644--- a/src/helpers/ipcHandlers.js+++ b/src/helpers/ipcHandlers.js@@ -55,7 +55,7 @@ function buildMultipartBody(fileBuffer, fileName, contentType, fields = {}) {return { body: Buffer.concat(bodyParts), boundary };}-function postMultipart(url, body, boundary, headers = {}) {+function postMultipart(url, body, boundary, headers = {}, timeoutMs = 60000) {const httpModule = url.protocol === "https:" ? https : http;return new Promise((resolve, reject) => {const req = httpModule.request(@@ -64,6 +64,7 @@ function postMultipart(url, body, boundary, headers = {}) {port: url.port || (url.protocol === "https:" ? 443 : 80),path: url.pathname,method: "POST",+ timeout: timeoutMs,headers: {"Content-Type": `multipart/form-data; boundary=${boundary}`,"Content-Length": body.length,@@ -82,6 +83,12 @@ function postMultipart(url, body, boundary, headers = {}) {});});+ req.on("timeout", () => {+ req.destroy();+ const err = new Error("Cloud request timed out");+ err.code = "TIMEOUT";+ reject(err);+ });req.on("error", reject);req.write(body);req.end();@@ -1599,9 +1606,13 @@ class IPCHandlers {if (!info?.hotkey) continue;if (!usesNativeListener(info.hotkey)) {- debugLogger.log(`[IPC] Unregistering globalShortcut "${info.hotkey}" (slot "${slot}") for capture mode`);+ debugLogger.log(+ `[IPC] Unregistering globalShortcut "${info.hotkey}" (slot "${slot}") for capture mode`+ );const { globalShortcut } = require("electron");- try { globalShortcut.unregister(info.hotkey); } catch {}+ try {+ globalShortcut.unregister(info.hotkey);+ } catch {}}}@@ -1614,7 +1625,9 @@ class IPCHandlers {// On GNOME, unregister all native keybindings during captureif (hotkeyManager.isUsingGnome() && hotkeyManager.gnomeManager) {for (const slot of [...hotkeyManager.gnomeManager.registeredSlots]) {- debugLogger.log(`[IPC] Unregistering GNOME keybinding (slot "${slot}") for capture mode`);+ debugLogger.log(+ `[IPC] Unregistering GNOME keybinding (slot "${slot}") for capture mode`+ );await hotkeyManager.gnomeManager.unregisterKeybinding(slot).catch((err) => {debugLogger.warn(`[IPC] Failed to unregister GNOME slot "${slot}":`, err.message);});@@ -1641,7 +1654,10 @@ class IPCHandlers {} else {// Exiting capture mode - re-register globalShortcut if not already registered// Skip for KDE/GNOME/Hyprland — updateHotkey handles re-registration via native path- const usesNativePath = hotkeyManager.isUsingKDE() || hotkeyManager.isUsingGnome() || hotkeyManager.isUsingHyprland();+ const usesNativePath =+ hotkeyManager.isUsingKDE() ||+ hotkeyManager.isUsingGnome() ||+ hotkeyManager.isUsingHyprland();if (effectiveHotkey && !usesNativeListener(effectiveHotkey) && !usesNativePath) {const { globalShortcut } = require("electron");const accelerator = effectiveHotkey.startsWith("Fn+")@@ -1709,18 +1725,28 @@ class IPCHandlers {`[IPC] Re-registering KDE keybinding "${effectiveHotkey}" after capture mode`);const callback = this.windowManager.createHotkeyCallback();- const result = await hotkeyManager.kdeManager.registerKeybinding(effectiveHotkey, "dictation", callback);+ const result = await hotkeyManager.kdeManager.registerKeybinding(+ effectiveHotkey,+ "dictation",+ callback+ );if (result === true) {hotkeyManager.currentHotkey = effectiveHotkey;} else {- debugLogger.warn(`[IPC] Failed to re-register KDE keybinding "${effectiveHotkey}" after capture mode`, { result });+ debugLogger.warn(+ `[IPC] Failed to re-register KDE keybinding "${effectiveHotkey}" after capture mode`,+ { result }+ );}}// Re-register non-dictation slots (meeting, agent) that were unregistered on capture enterfor (const [slot, info] of hotkeyManager.slots) {- if (slot === "dictation" || slot === "cancel" || !info?.hotkey || !info?.callback) continue;- debugLogger.log(`[IPC] Re-registering slot "${slot}" ("${info.hotkey}") after capture mode`);+ if (slot === "dictation" || slot === "cancel" || !info?.hotkey || !info?.callback)+ continue;+ debugLogger.log(+ `[IPC] Re-registering slot "${slot}" ("${info.hotkey}") after capture mode`+ );await hotkeyManager.registerSlot(slot, info.hotkey, info.callback).catch((err) => {debugLogger.warn(`[IPC] Failed to re-register slot "${slot}":`, err.message);});@@ -2610,7 +2636,9 @@ class IPCHandlers {};}if (data.statusCode !== 200) {- throw new Error(data.data?.error || `API error: ${data.statusCode}`);+ const err = new Error(data.data?.error || `API error: ${data.statusCode}`);+ err.code = "SERVER_ERROR";+ throw err;}return {@@ -2629,7 +2657,7 @@ class IPCHandlers {};} catch (error) {debugLogger.error("Cloud transcription error", { error: error.message }, "cloud-api");- return { success: false, error: error.message };+ return { success: false, error: error.message, code: error.code || null };}});@@ -2743,7 +2771,9 @@ class IPCHandlers {endpoint = "https://api.openai.com/v1/audio/transcriptions";}if (!apiKey && provider !== "custom") {- throw new Error(`${provider} API key not configured`);+ const err = new Error(`${provider} API key not configured`);+ err.code = "API_KEY_MISSING";+ throw err;}const formData = new FormData();@@ -2759,7 +2789,11 @@ class IPCHandlers {const response = await fetch(endpoint, { method: "POST", headers, body: formData });if (!response.ok) {const errorText = await response.text();- throw new Error(`${provider} API Error: ${response.status} ${errorText}`);+ const err = new Error(`${provider} API Error: ${response.status} ${errorText}`);+ if (response.status === 401) err.code = "INVALID_KEY";+ else if (response.status === 429) err.code = "LIMIT_REACHED";+ else if (response.status >= 500) err.code = "SERVER_ERROR";+ throw err;}const data = await response.json();if (data?.text) {@@ -2794,6 +2828,12 @@ class IPCHandlers {{ id, error: error.message },"audio-storage");+ this.databaseManager.updateTranscriptionStatus(+ id,+ "failed",+ error.message,+ error.code || null+ );return { success: false, error: error.message };}});diff --git a/src/locales/de/translation.json b/src/locales/de/translation.jsonindex ca6a7edb3..e53870254 100644--- a/src/locales/de/translation.json+++ b/src/locales/de/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "Richten Sie Ihren Transkriptionsanbieter ein","failedCtaAndRetry": "und klicken Sie dann auf Wiederholen","failedCtaSettingsOnly": "Richten Sie Ihren Transkriptionsanbieter in den Einstellungen ein",+ "failedCtaSignIn": "Erneut anmelden",+ "failedLimitReached": "Tageslimit erreicht",+ "failedOffline": "Offline","clearAll": "Alle löschen","clearAllTitle": "Alle Transkriptionen löschen","clearAllDescription": "Alle Transkriptionen und Audiodateien werden dauerhaft entfernt.",diff --git a/src/locales/en/translation.json b/src/locales/en/translation.jsonindex 74ea9ef32..f04a0552d 100644--- a/src/locales/en/translation.json+++ b/src/locales/en/translation.json@@ -263,6 +263,9 @@"failedCtaSettings": "Set up your transcription provider","failedCtaAndRetry": "then click retry","failedCtaSettingsOnly": "Set up your transcription provider in Settings",+ "failedCtaSignIn": "Sign in again",+ "failedLimitReached": "Daily limit reached",+ "failedOffline": "You're offline","rawTranscript": "Raw Transcript","clearAll": "Clear all","clearAllTitle": "Clear All Transcriptions",diff --git a/src/locales/es/translation.json b/src/locales/es/translation.jsonindex 334b024ae..28bcb2799 100644--- a/src/locales/es/translation.json+++ b/src/locales/es/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "Configura tu proveedor de transcripción","failedCtaAndRetry": "y luego haz clic en reintentar","failedCtaSettingsOnly": "Configura tu proveedor de transcripción en Ajustes",+ "failedCtaSignIn": "Iniciar sesión de nuevo",+ "failedLimitReached": "Límite diario alcanzado",+ "failedOffline": "Sin conexión","clearAll": "Borrar todo","clearAllTitle": "Borrar todas las transcripciones","clearAllDescription": "Todas las transcripciones y archivos de audio se eliminarán permanentemente.",diff --git a/src/locales/fr/translation.json b/src/locales/fr/translation.jsonindex 7e947a130..e766f31eb 100644--- a/src/locales/fr/translation.json+++ b/src/locales/fr/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "Configurez votre fournisseur de transcription","failedCtaAndRetry": "puis cliquez sur réessayer","failedCtaSettingsOnly": "Configurez votre fournisseur de transcription dans les Paramètres",+ "failedCtaSignIn": "Se reconnecter",+ "failedLimitReached": "Limite quotidienne atteinte",+ "failedOffline": "Hors ligne","clearAll": "Tout effacer","clearAllTitle": "Effacer toutes les transcriptions","clearAllDescription": "Toutes les transcriptions et fichiers audio seront définitivement supprimés.",diff --git a/src/locales/it/translation.json b/src/locales/it/translation.jsonindex 54b8a9e20..d024a12b6 100644--- a/src/locales/it/translation.json+++ b/src/locales/it/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "Configura il tuo provider di trascrizione","failedCtaAndRetry": "poi clicca su riprova","failedCtaSettingsOnly": "Configura il tuo provider di trascrizione nelle Impostazioni",+ "failedCtaSignIn": "Accedi di nuovo",+ "failedLimitReached": "Limite giornaliero raggiunto",+ "failedOffline": "Offline","clearAll": "Cancella tutto","clearAllTitle": "Cancella tutte le trascrizioni","clearAllDescription": "Tutte le trascrizioni e i file audio verranno rimossi definitivamente.",diff --git a/src/locales/pt/translation.json b/src/locales/pt/translation.jsonindex e3cb7b8ae..369262cf6 100644--- a/src/locales/pt/translation.json+++ b/src/locales/pt/translation.json@@ -223,6 +223,9 @@"failedCtaSettings": "Configure seu provedor de transcrição","failedCtaAndRetry": "e depois clique em tentar novamente","failedCtaSettingsOnly": "Configure seu provedor de transcrição nas Configurações",+ "failedCtaSignIn": "Entrar novamente",+ "failedLimitReached": "Limite diário atingido",+ "failedOffline": "Sem conexão","clearAll": "Limpar tudo","clearAllTitle": "Limpar todas as transcrições","clearAllDescription": "Todas as transcrições e arquivos de áudio serão removidos permanentemente.",diff --git a/src/locales/ru/translation.json b/src/locales/ru/translation.jsonindex ab8792311..4426a4919 100644--- a/src/locales/ru/translation.json+++ b/src/locales/ru/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "Настройте провайдер транскрипции","failedCtaAndRetry": "затем нажмите повторить","failedCtaSettingsOnly": "Настройте провайдер транскрипции в Настройках",+ "failedCtaSignIn": "Войти снова",+ "failedLimitReached": "Дневной лимит достигнут",+ "failedOffline": "Нет подключения","clearAll": "Очистить все","clearAllTitle": "Очистить все транскрипции","clearAllDescription": "Все транскрипции и аудиофайлы будут безвозвратно удалены.",diff --git a/src/locales/zh-CN/translation.json b/src/locales/zh-CN/translation.jsonindex 37bd22eee..40b2cb374 100644--- a/src/locales/zh-CN/translation.json+++ b/src/locales/zh-CN/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "设置您的转录服务商","failedCtaAndRetry": "然后点击重试","failedCtaSettingsOnly": "在设置中配置您的转录服务商",+ "failedCtaSignIn": "重新登录",+ "failedLimitReached": "已达每日限额",+ "failedOffline": "离线","clearAll": "全部清除","clearAllTitle": "清除所有转录","clearAllDescription": "所有转录和音频文件将被永久删除。",diff --git a/src/locales/zh-TW/translation.json b/src/locales/zh-TW/translation.jsonindex ee72b743e..9916e2ff4 100644--- a/src/locales/zh-TW/translation.json+++ b/src/locales/zh-TW/translation.json@@ -251,6 +251,9 @@"failedCtaSettings": "設定您的轉錄服務供應商","failedCtaAndRetry": "然後點擊重試","failedCtaSettingsOnly": "在設定中配置您的轉錄服務供應商",+ "failedCtaSignIn": "重新登入",+ "failedLimitReached": "已達每日限額",+ "failedOffline": "離線","clearAll": "全部清除","clearAllTitle": "清除所有轉錄","clearAllDescription": "所有轉錄和音訊檔案將被永久刪除。",diff --git a/src/types/electron.ts b/src/types/electron.tsindex 8d3051e85..2dbb3d49c 100644--- a/src/types/electron.ts+++ b/src/types/electron.ts@@ -2,6 +2,19 @@ export type LocalTranscriptionProvider = "whisper" | "nvidia";export type TranscriptionStatus = "completed" | "failed" | "pending";+export type TranscriptionErrorCode =+ | "TIMEOUT"+ | "NETWORK"+ | "SERVER_ERROR"+ | "OFFLINE"+ | "AUTH_EXPIRED"+ | "AUTH_REQUIRED"+ | "LIMIT_REACHED"+ | "API_KEY_MISSING"+ | "INVALID_KEY"+ | "MODEL_NOT_AVAILABLE"+ | null;+export interface TranscriptionItem {id: number;text: string;@@ -14,6 +27,7 @@ export interface TranscriptionItem {model: string | null;status: TranscriptionStatus;error_message: string | null;+ error_code: TranscriptionErrorCode;}export interface NoteItem {