Skip to content

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

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.js
index 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 hours
const 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, startOffs
let 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, startOffs
return;
}
+ 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.js
index 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.js
index 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 background
this.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.js
index 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 directory
await fsPromises.rm(extractDir, { recursive: true, force: true });
diff --git a/src/helpers/whisper.js b/src/helpers/whisper.js
index 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.ts
index 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.json
index 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.ts
index 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 {