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: harden model download pipeline with stall detection, disk space checks, and file validation (#248)
Gabriel Stein4affd21f9009
diff --git a/src/helpers/downloadUtils.js b/src/helpers/downloadUtils.jsindex 9a4f87771..326099be3 100644--- a/src/helpers/downloadUtils.js+++ b/src/helpers/downloadUtils.js@@ -1,5 +1,6 @@const fs = require("fs");const { promises: fsPromises } = require("fs");+const path = require("path");const https = require("https");const http = require("http");const { pipeline } = require("stream");@@ -11,6 +12,8 @@ const MAX_REDIRECTS = 5;const DEFAULT_TIMEOUT = 60000;const DEFAULT_MAX_RETRIES = 3;const MAX_BACKOFF_MS = 30000;+const STALL_TIMEOUT_MS = 30000;+const STALE_TMP_AGE_MS = 24 * 60 * 60 * 1000; // 24 hoursconst RETRYABLE_CODES = new Set(["ECONNRESET",@@ -20,6 +23,7 @@ const RETRYABLE_CODES = new Set(["ECONNREFUSED","ENOTFOUND","ERR_STREAM_PREMATURE_CLOSE",+ "ERR_DOWNLOAD_INCOMPLETE",]);function isRetryable(error) {@@ -111,8 +115,13 @@ function downloadAttempt(url, tempPath, { timeout, onProgress, signal, startOffslet totalSize = 0;let lastProgressUpdate = 0;let request = null;+ let stallTimer = null;const cleanup = () => {+ if (stallTimer) {+ clearTimeout(stallTimer);+ stallTimer = null;+ }if (request) {request.destroy();request = null;@@ -165,16 +174,35 @@ function downloadAttempt(url, tempPath, { timeout, onProgress, signal, startOffsreturn;}+ const resetStallTimer = () => {+ if (stallTimer) clearTimeout(stallTimer);+ stallTimer = setTimeout(() => {+ cleanup();+ reject(+ Object.assign(new Error("Download stalled — no data received for 30s"), {+ code: "ETIMEDOUT",+ })+ );+ }, STALL_TIMEOUT_MS);+ };++ resetStallTimer();+response.on("data", (chunk) => {if (signal?.aborted) {cleanup();return;}downloadedSize += chunk.length;+ resetStallTimer();emitProgress();});pipeline(response, activeFile, (err) => {+ if (stallTimer) {+ clearTimeout(stallTimer);+ stallTimer = null;+ }if (signal) signal.onAbort = null;if (err) {if (signal?.aborted) {@@ -182,6 +210,13 @@ function downloadAttempt(url, tempPath, { timeout, onProgress, signal, startOffs} else {reject(err);}+ } else if (totalSize > 0 && downloadedSize < totalSize) {+ reject(+ Object.assign(+ new Error(`Download incomplete: received ${downloadedSize} of ${totalSize} bytes`),+ { code: "ERR_DOWNLOAD_INCOMPLETE" }+ )+ );} else {resolve({ downloadedSize, totalSize });}@@ -316,4 +351,63 @@ function createDownloadSignal() {};}-module.exports = { downloadFile, createDownloadSignal };+async function validateFileSize(filePath, expectedSizeBytes, tolerancePercent = 10) {+ const stats = await fsPromises.stat(filePath);+ const minSize = expectedSizeBytes * (1 - tolerancePercent / 100);+ if (stats.size < minSize) {+ await fsPromises.unlink(filePath).catch(() => {});+ throw Object.assign(+ new Error(+ `Download appears corrupted: file is ${Math.round(stats.size / 1_000_000)}MB, ` ++ `expected at least ${Math.round(minSize / 1_000_000)}MB`+ ),+ { code: "ERR_FILE_TOO_SMALL" }+ );+ }+ return stats.size;+}++async function cleanupStaleDownloads(directory) {+ try {+ const entries = await fsPromises.readdir(directory);+ const now = Date.now();+ for (const entry of entries) {+ if (!entry.endsWith(".tmp") && !entry.startsWith("temp-extract-")) continue;+ const fullPath = path.join(directory, entry);+ try {+ const stats = await fsPromises.stat(fullPath);+ if (now - stats.mtimeMs > STALE_TMP_AGE_MS) {+ if (stats.isDirectory()) {+ await fsPromises.rm(fullPath, { recursive: true, force: true });+ } else {+ await fsPromises.unlink(fullPath);+ }+ debugLogger.info("Cleaned up stale download artifact", { path: fullPath });+ }+ } catch {+ // Skip files we can't stat or delete+ }+ }+ } catch {+ // Directory may not exist yet+ }+}++async function checkDiskSpace(directory, requiredBytes) {+ try {+ const stats = await fsPromises.statfs(directory);+ const availableBytes = stats.bavail * stats.bsize;+ return { ok: availableBytes >= requiredBytes, availableBytes };+ } catch {+ // statfs not supported or directory doesn't exist — skip check+ return { ok: true, availableBytes: Infinity };+ }+}++module.exports = {+ downloadFile,+ createDownloadSignal,+ validateFileSize,+ cleanupStaleDownloads,+ checkDiskSpace,+};diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.jsindex a48cca329..61c44db86 100644--- a/src/helpers/ipcHandlers.js+++ b/src/helpers/ipcHandlers.js@@ -278,9 +278,28 @@ class IPCHandlers {});ipcMain.handle("download-whisper-model", async (event, modelName) => {- return this.whisperManager.downloadWhisperModel(modelName, (progressData) => {- event.sender.send("whisper-download-progress", progressData);- });+ try {+ const result = await this.whisperManager.downloadWhisperModel(modelName, (progressData) => {+ if (!event.sender.isDestroyed()) {+ event.sender.send("whisper-download-progress", progressData);+ }+ });+ return result;+ } catch (error) {+ if (!event.sender.isDestroyed()) {+ event.sender.send("whisper-download-progress", {+ type: "error",+ model: modelName,+ error: error.message,+ code: error.code || "DOWNLOAD_FAILED",+ });+ }+ return {+ success: false,+ error: error.message,+ code: error.code || "DOWNLOAD_FAILED",+ };+ }});ipcMain.handle("check-model-status", async (event, modelName) => {@@ -372,9 +391,31 @@ class IPCHandlers {});ipcMain.handle("download-parakeet-model", async (event, modelName) => {- return this.parakeetManager.downloadParakeetModel(modelName, (progressData) => {- event.sender.send("parakeet-download-progress", progressData);- });+ try {+ const result = await this.parakeetManager.downloadParakeetModel(+ modelName,+ (progressData) => {+ if (!event.sender.isDestroyed()) {+ event.sender.send("parakeet-download-progress", progressData);+ }+ }+ );+ return result;+ } catch (error) {+ if (!event.sender.isDestroyed()) {+ event.sender.send("parakeet-download-progress", {+ type: "error",+ model: modelName,+ error: error.message,+ code: error.code || "DOWNLOAD_FAILED",+ });+ }+ return {+ success: false,+ error: error.message,+ code: error.code || "DOWNLOAD_FAILED",+ };+ }});ipcMain.handle("check-parakeet-model-status", async (_event, modelName) => {@@ -600,12 +641,14 @@ class IPCHandlers {const result = await modelManager.downloadModel(modelId,(progress, downloadedSize, totalSize) => {- event.sender.send("model-download-progress", {- modelId,- progress,- downloadedSize,- totalSize,- });+ if (!event.sender.isDestroyed()) {+ event.sender.send("model-download-progress", {+ modelId,+ progress,+ downloadedSize,+ totalSize,+ });+ }});return { success: true, path: result };diff --git a/src/helpers/modelManagerBridge.js b/src/helpers/modelManagerBridge.jsindex 7f52b67ad..16d3f906b 100644--- a/src/helpers/modelManagerBridge.js+++ b/src/helpers/modelManagerBridge.js@@ -2,7 +2,12 @@ const path = require("path");const fs = require("fs");const { promises: fsPromises } = require("fs");const { app } = require("electron");-const { downloadFile: sharedDownloadFile, createDownloadSignal } = require("./downloadUtils");+const {+ downloadFile: sharedDownloadFile,+ createDownloadSignal,+ cleanupStaleDownloads,+ checkDiskSpace,+} = require("./downloadUtils");const modelRegistryData = require("../models/modelRegistryData.json");const LlamaServerManager = require("./llamaServer");@@ -63,6 +68,7 @@ class ModelManager {this._initialized = true;// Don't await - let this run in backgroundthis.ensureModelsDirExists();+ cleanupStaleDownloads(this.modelsDir);}getModelsDir() {@@ -187,6 +193,20 @@ class ModelManager {try {await this.ensureModelsDirExists();++ const requiredBytes = model.sizeBytes || model.sizeMb * 1_000_000 || 0;+ if (requiredBytes > 0) {+ const spaceCheck = await checkDiskSpace(this.modelsDir, requiredBytes * 1.2);+ if (!spaceCheck.ok) {+ throw new ModelError(+ `Not enough disk space. Need ~${Math.round((requiredBytes * 1.2) / 1_000_000)}MB, ` ++ `only ${Math.round(spaceCheck.availableBytes / 1_000_000)}MB available.`,+ "INSUFFICIENT_DISK_SPACE",+ { required: requiredBytes, available: spaceCheck.availableBytes }+ );+ }+ }+const downloadUrl = this.getDownloadUrl(provider, model);await sharedDownloadFile(downloadUrl, modelPath, {diff --git a/src/helpers/parakeet.js b/src/helpers/parakeet.jsindex 4f89a4dce..4069dce75 100644--- a/src/helpers/parakeet.js+++ b/src/helpers/parakeet.js@@ -3,7 +3,13 @@ const fsPromises = require("fs").promises;const path = require("path");const { spawn } = require("child_process");const debugLogger = require("./debugLogger");-const { downloadFile, createDownloadSignal } = require("./downloadUtils");+const {+ downloadFile,+ createDownloadSignal,+ validateFileSize,+ cleanupStaleDownloads,+ checkDiskSpace,+} = require("./downloadUtils");const ParakeetServerManager = require("./parakeetServer");const { getModelsDirForService } = require("./modelDirUtils");@@ -14,7 +20,7 @@ function getParakeetModelConfig(modelName) {if (!modelInfo) return null;return {url: modelInfo.downloadUrl,- size: modelInfo.sizeMb * 1_000_000,+ size: modelInfo.expectedSizeBytes || modelInfo.sizeMb * 1_000_000,language: modelInfo.language,supportedLanguages: modelInfo.supportedLanguages || [],extractDir: modelInfo.extractDir,@@ -57,6 +63,8 @@ class ParakeetManager {try {this.isInitialized = true;+ await cleanupStaleDownloads(this.getModelsDir());+await this.logDependencyStatus();const { localTranscriptionProvider, parakeetModel } = settings;@@ -266,6 +274,14 @@ class ParakeetManager {return { model: modelName, downloaded: true, path: modelPath, success: true };}+ const spaceCheck = await checkDiskSpace(modelsDir, modelConfig.size * 2.5);+ if (!spaceCheck.ok) {+ throw new Error(+ `Not enough disk space to download and extract model. Need ~${Math.round((modelConfig.size * 2.5) / 1_000_000)}MB, ` ++ `only ${Math.round(spaceCheck.availableBytes / 1_000_000)}MB available.`+ );+ }+const archivePath = path.join(modelsDir, `${modelName}.tar.bz2`);const { signal, abort } = createDownloadSignal();this.currentDownloadProcess = { abort };@@ -287,6 +303,8 @@ class ParakeetManager {},});+ await validateFileSize(archivePath, modelConfig.size, 15);+if (progressCallback) {progressCallback({ type: "installing", model: modelName, percentage: 100 });}@@ -366,6 +384,11 @@ class ParakeetManager {}}+ const encoderPath = path.join(targetDir, "encoder.int8.onnx");+ if (!fs.existsSync(encoderPath)) {+ throw new Error("Extracted model is missing required files (encoder.int8.onnx)");+ }+// Cleanup temp directoryawait fsPromises.rm(extractDir, { recursive: true, force: true });diff --git a/src/helpers/whisper.js b/src/helpers/whisper.jsindex f8eab4857..2d57fc608 100644--- a/src/helpers/whisper.js+++ b/src/helpers/whisper.js@@ -2,7 +2,13 @@ const fs = require("fs");const fsPromises = require("fs").promises;const path = require("path");const debugLogger = require("./debugLogger");-const { downloadFile, createDownloadSignal } = require("./downloadUtils");+const {+ downloadFile,+ createDownloadSignal,+ validateFileSize,+ cleanupStaleDownloads,+ checkDiskSpace,+} = require("./downloadUtils");const WhisperServerManager = require("./whisperServer");const { getModelsDirForService } = require("./modelDirUtils");@@ -15,7 +21,7 @@ function getWhisperModelConfig(modelName) {if (!modelInfo) return null;return {url: modelInfo.downloadUrl,- size: modelInfo.sizeMb * 1_000_000,+ size: modelInfo.expectedSizeBytes || modelInfo.sizeMb * 1_000_000,fileName: modelInfo.fileName,};}@@ -60,6 +66,8 @@ class WhisperManager {try {this.isInitialized = true;+ await cleanupStaleDownloads(this.getModelsDir());+// Pre-warm whisper-server if local mode enabled (eliminates 2-5s cold-start delay)const { localTranscriptionProvider, whisperModel } = settings;@@ -382,6 +390,14 @@ class WhisperManager {};}+ const spaceCheck = await checkDiskSpace(modelsDir, modelConfig.size * 1.2);+ if (!spaceCheck.ok) {+ throw new Error(+ `Not enough disk space to download model. Need ~${Math.round((modelConfig.size * 1.2) / 1_000_000)}MB, ` ++ `only ${Math.round(spaceCheck.availableBytes / 1_000_000)}MB available.`+ );+ }+const { signal, abort } = createDownloadSignal();this.currentDownloadProcess = { abort };@@ -402,6 +418,8 @@ class WhisperManager {},});+ await validateFileSize(modelPath, modelConfig.size);+const stats = await fsPromises.stat(modelPath);if (progressCallback) {diff --git a/src/hooks/useModelDownload.ts b/src/hooks/useModelDownload.tsindex 65d127879..40410d114 100644--- a/src/hooks/useModelDownload.ts+++ b/src/hooks/useModelDownload.ts@@ -36,6 +36,21 @@ export function formatETA(seconds: number): string {return `${minutes}m ${remainingSeconds}s`;}+function getDownloadErrorMessage(error: string, code?: string): string {+ if (code === "ETIMEDOUT" || error.includes("timeout") || error.includes("stalled"))+ return "Download timed out. Check your internet connection and try again.";+ if (code === "ENOTFOUND" || error.includes("ENOTFOUND"))+ return "Could not reach the download server. Check your internet connection.";+ if (error.includes("disk space")) return error;+ if (error.includes("corrupted") || error.includes("incomplete") || error.includes("too small"))+ return "Download was incomplete or corrupted. Please try again.";+ if (error.includes("HTTP 429") || error.includes("rate limit"))+ return "Download server is rate limiting. Please wait a few minutes and try again.";+ if (error.includes("HTTP 4") || error.includes("HTTP 5"))+ return `Server error (${error}). Please try again later.`;+ return `Download failed: ${error}`;+}+export function useModelDownload({modelType,onDownloadComplete,@@ -49,14 +64,20 @@ export function useModelDownload({});const [isCancelling, setIsCancelling] = useState(false);const [isInstalling, setIsInstalling] = useState(false);+ const [downloadError, setDownloadError] = useState<string | null>(null);const isCancellingRef = useRef(false);const lastProgressUpdateRef = useRef(0);const { showAlertDialog } = useDialogs();const { toast } = useToast();+ const showAlertDialogRef = useRef(showAlertDialog);const onDownloadCompleteRef = useRef(onDownloadComplete);const onModelsClearedRef = useRef(onModelsCleared);+ useEffect(() => {+ showAlertDialogRef.current = showAlertDialog;+ }, [showAlertDialog]);+useEffect(() => {onDownloadCompleteRef.current = onDownloadComplete;}, [onDownloadComplete]);@@ -90,6 +111,14 @@ export function useModelDownload({setDownloadingModel(null);setDownloadProgress({ percentage: 0, downloadedBytes: 0, totalBytes: 0 });onDownloadCompleteRef.current?.();+ } else if (data.type === "error") {+ if (isCancellingRef.current) return;+ const msg = getDownloadErrorMessage(data.error || "Unknown error", data.code);+ setDownloadError(msg);+ showAlertDialogRef.current({ title: "Download Failed", description: msg });+ setIsInstalling(false);+ setDownloadingModel(null);+ setDownloadProgress({ percentage: 0, downloadedBytes: 0, totalBytes: 0 });}},[]@@ -140,6 +169,7 @@ export function useModelDownload({try {setDownloadingModel(modelId);+ setDownloadError(null);setDownloadProgress({ percentage: 0, downloadedBytes: 0, totalBytes: 0 });lastProgressUpdateRef.current = 0; // Reset throttle timer@@ -148,32 +178,29 @@ export function useModelDownload({if (modelType === "whisper") {const result = await window.electronAPI?.downloadWhisperModel(modelId);if (!result?.success && !result?.error?.includes("interrupted by user")) {- showAlertDialog({- title: "Download Failed",- description: `Failed to download model: ${result?.error}`,- });+ const msg = getDownloadErrorMessage(result?.error || "Unknown error", result?.code);+ setDownloadError(msg);+ showAlertDialog({ title: "Download Failed", description: msg });} else {success = result?.success ?? false;}} else if (modelType === "parakeet") {const result = await window.electronAPI?.downloadParakeetModel(modelId);if (!result?.success && !result?.error?.includes("interrupted by user")) {- showAlertDialog({- title: "Download Failed",- description: `Failed to download model: ${result?.error}`,- });+ const msg = getDownloadErrorMessage(result?.error || "Unknown error", result?.code);+ setDownloadError(msg);+ showAlertDialog({ title: "Download Failed", description: msg });} else {success = result?.success ?? false;}} else {const result = (await window.electronAPI?.modelDownload?.(modelId)) as unknown as- | { success: boolean; error?: string }+ | { success: boolean; error?: string; code?: string }| undefined;if (result && !result.success && result.error) {- showAlertDialog({- title: "Download Failed",- description: `Failed to download model: ${result.error}`,- });+ const msg = getDownloadErrorMessage(result.error, result.code);+ setDownloadError(msg);+ showAlertDialog({ title: "Download Failed", description: msg });} else {success = result?.success ?? false;}@@ -193,10 +220,9 @@ export function useModelDownload({!errorMessage.includes("cancelled by user") &&!errorMessage.includes("DOWNLOAD_CANCELLED")) {- showAlertDialog({- title: "Download Failed",- description: `Failed to download model: ${errorMessage}`,- });+ const msg = getDownloadErrorMessage(errorMessage);+ setDownloadError(msg);+ showAlertDialog({ title: "Download Failed", description: msg });}} finally {setIsInstalling(false);@@ -282,6 +308,7 @@ export function useModelDownload({return {downloadingModel,downloadProgress,+ downloadError,isDownloading,isDownloadingModel,isInstalling,diff --git a/src/models/modelRegistryData.json b/src/models/modelRegistryData.jsonindex 104e63025..355f79792 100644--- a/src/models/modelRegistryData.json+++ b/src/models/modelRegistryData.json@@ -5,6 +5,7 @@"description": "Fast multilingual ASR with auto language detection (25 languages)","size": "680MB","sizeMb": 680,+ "expectedSizeBytes": 680000000,"language": "multilingual","supportedLanguages": ["bg",@@ -44,6 +45,7 @@"description": "Fastest, lower quality","size": "75MB","sizeMb": 75,+ "expectedSizeBytes": 78000000,"fileName": "ggml-tiny.bin","downloadUrl": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin"},@@ -52,6 +54,7 @@"description": "Good balance","size": "142MB","sizeMb": 142,+ "expectedSizeBytes": 148000000,"fileName": "ggml-base.bin","downloadUrl": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin","recommended": true@@ -61,6 +64,7 @@"description": "Better quality, slower","size": "466MB","sizeMb": 466,+ "expectedSizeBytes": 488000000,"fileName": "ggml-small.bin","downloadUrl": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"},@@ -69,6 +73,7 @@"description": "High quality","size": "1.5GB","sizeMb": 1500,+ "expectedSizeBytes": 1570000000,"fileName": "ggml-medium.bin","downloadUrl": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin"},@@ -77,6 +82,7 @@"description": "Best quality, slowest","size": "3GB","sizeMb": 3000,+ "expectedSizeBytes": 3140000000,"fileName": "ggml-large-v3.bin","downloadUrl": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin"},@@ -85,6 +91,7 @@"description": "Fast with good quality","size": "1.6GB","sizeMb": 1600,+ "expectedSizeBytes": 1670000000,"fileName": "ggml-large-v3-turbo.bin","downloadUrl": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin"}diff --git a/src/types/electron.ts b/src/types/electron.tsindex 68c52fe80..448773ef3 100644--- a/src/types/electron.ts+++ b/src/types/electron.ts@@ -19,6 +19,7 @@ export interface WhisperModelResult {downloaded: boolean;size_mb?: number;error?: string;+ code?: string;}export interface WhisperModelDeleteResult {@@ -85,12 +86,13 @@ export interface AppVersionResult {}export interface WhisperDownloadProgressData {- type: string;+ type: "progress" | "installing" | "complete" | "error";model: string;percentage?: number;downloaded_bytes?: number;total_bytes?: number;error?: string;+ code?: string;result?: any;}@@ -108,6 +110,7 @@ export interface ParakeetModelResult {size_bytes?: number;size_mb?: number;error?: string;+ code?: string;}export interface ParakeetModelDeleteResult {@@ -126,12 +129,13 @@ export interface ParakeetModelsListResult {}export interface ParakeetDownloadProgressData {- type: string;+ type: "progress" | "installing" | "complete" | "error";model: string;percentage?: number;downloaded_bytes?: number;total_bytes?: number;error?: string;+ code?: string;}export interface ParakeetTranscriptionResult {