Skip to content

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

feat(whisper): Vulkan GPU acceleration for AMD/Intel GPUs (#1185)

Gabriel Stein36df3a81fef2
diff --git a/main.js b/main.js
index 5f2679a6f..6ebda5d29 100644
--- a/main.js
+++ b/main.js
@@ -279,6 +279,7 @@ const WindowsKeyManager = require("./src/helpers/windowsKeyManager");
const LinuxKeyManager = require("./src/helpers/linuxKeyManager");
const TextEditMonitor = require("./src/helpers/textEditMonitor");
const WhisperCudaManager = require("./src/helpers/whisperCudaManager");
+const WhisperVulkanManager = require("./src/helpers/whisperVulkanManager");
const GoogleCalendarManager = require("./src/helpers/googleCalendarManager");
const MeetingProcessDetector = require("./src/helpers/meetingProcessDetector");
const AudioActivityDetector = require("./src/helpers/audioActivityDetector");
@@ -309,6 +310,7 @@ let windowsKeyManager = null;
let linuxKeyManager = null;
let textEditMonitor = null;
let whisperCudaManager = null;
+let whisperVulkanManager = null;
let googleCalendarManager = null;
let meetingDetectionEngine = null;
let audioTapManager = null;
@@ -391,6 +393,7 @@ function initializeCoreManagers() {
whisperManager = new WhisperManager();
if (process.platform !== "darwin") {
whisperCudaManager = new WhisperCudaManager();
+ whisperVulkanManager = new WhisperVulkanManager();
}
parakeetManager = new ParakeetManager();
diarizationManager = new DiarizationManager();
@@ -435,6 +438,7 @@ function initializeCoreManagers() {
linuxKeyManager,
textEditMonitor,
whisperCudaManager,
+ whisperVulkanManager,
googleCalendarManager,
meetingDetectionEngine,
audioTapManager,
@@ -958,11 +962,16 @@ async function startApp() {
}, WHISPER_WAKE_REWARM_DELAY_MS);
});
- // Non-blocking server pre-warming
+ // Non-blocking server pre-warming. CUDA wins when both GPU backends are enabled.
+ const useCuda = process.env.WHISPER_CUDA_ENABLED === "true" && whisperCudaManager?.isDownloaded();
const whisperSettings = {
localTranscriptionProvider: process.env.LOCAL_TRANSCRIPTION_PROVIDER || "",
whisperModel: process.env.LOCAL_WHISPER_MODEL,
- useCuda: process.env.WHISPER_CUDA_ENABLED === "true" && whisperCudaManager?.isDownloaded(),
+ useCuda,
+ useVulkan:
+ !useCuda &&
+ process.env.WHISPER_VULKAN_ENABLED === "true" &&
+ whisperVulkanManager?.isDownloaded(),
};
whisperManager.initializeAtStartup(whisperSettings).catch((err) => {
debugLogger.debug("Whisper startup init error (non-fatal)", { error: err.message });
diff --git a/preload.js b/preload.js
index 828a3cabe..7a14650c1 100644
--- a/preload.js
+++ b/preload.js
@@ -274,6 +274,20 @@ contextBridge.exposeInMainWorld("electronAPI", {
(callback) => () => callback()
),
+ // Vulkan GPU acceleration (whisper on AMD/Intel GPUs)
+ getVulkanWhisperStatus: () => ipcRenderer.invoke("get-vulkan-whisper-status"),
+ downloadVulkanWhisperBinary: () => ipcRenderer.invoke("download-vulkan-whisper-binary"),
+ cancelVulkanWhisperDownload: () => ipcRenderer.invoke("cancel-vulkan-whisper-download"),
+ deleteVulkanWhisperBinary: () => ipcRenderer.invoke("delete-vulkan-whisper-binary"),
+ onVulkanWhisperDownloadProgress: registerListener(
+ "vulkan-whisper-download-progress",
+ (callback) => (_event, data) => callback(data)
+ ),
+ onGpuFallbackNotification: registerListener(
+ "gpu-fallback-notification",
+ (callback) => () => callback()
+ ),
+
// Local Parakeet (NVIDIA) functions
transcribeLocalParakeet: (audioBlob, options) =>
ipcRenderer.invoke("transcribe-local-parakeet", audioBlob, options),
diff --git a/src/components/ControlPanel.tsx b/src/components/ControlPanel.tsx
index 7a3d4bd9d..d63e84761 100644
--- a/src/components/ControlPanel.tsx
+++ b/src/components/ControlPanel.tsx
@@ -99,9 +99,12 @@ export default function ControlPanel({ initialSettingsSection }: ControlPanelPro
folderId: number;
event: any;
} | null>(null);
- const [gpuAccelAvailable, setGpuAccelAvailable] = useState<{ cuda: boolean; vulkan: boolean }>({
- cuda: false,
- vulkan: false,
+ const [gpuAccelAvailable, setGpuAccelAvailable] = useState<{
+ transcription: boolean;
+ intelligence: boolean;
+ }>({
+ transcription: false,
+ intelligence: false,
});
const [gpuBannerDismissed, setGpuBannerDismissed] = useState(
() => localStorage.getItem("gpuBannerDismissedUnified") === "true"
@@ -292,11 +295,16 @@ export default function ControlPanel({ initialSettingsSection }: ControlPanelPro
useEffect(() => {
if (platform === "darwin" || gpuBannerDismissed) return;
const detect = async () => {
- const results = { cuda: false, vulkan: false };
+ const results = { transcription: false, intelligence: false };
if (useLocalWhisper && localTranscriptionProvider === "whisper") {
try {
const status = await window.electronAPI?.getCudaWhisperStatus?.();
- if (status?.gpuInfo.hasNvidiaGpu && !status.downloaded) results.cuda = true;
+ if (status?.gpuInfo.hasNvidiaGpu) {
+ if (!status.downloaded) results.transcription = true;
+ } else {
+ const vulkan = await window.electronAPI?.getVulkanWhisperStatus?.();
+ if (vulkan?.vulkan.available && !vulkan.downloaded) results.transcription = true;
+ }
} catch {}
}
if (useCleanupModel) {
@@ -305,7 +313,7 @@ export default function ControlPanel({ initialSettingsSection }: ControlPanelPro
window.electronAPI?.detectVulkanGpu?.(),
window.electronAPI?.getLlamaVulkanStatus?.(),
]);
- if (gpu?.available && !vulkan?.downloaded) results.vulkan = true;
+ if (gpu?.available && !vulkan?.downloaded) results.intelligence = true;
} catch {}
}
setGpuAccelAvailable(results);
@@ -837,7 +845,7 @@ export default function ControlPanel({ initialSettingsSection }: ControlPanelPro
</div>
</div>
)}
- {(gpuAccelAvailable.cuda || gpuAccelAvailable.vulkan) &&
+ {(gpuAccelAvailable.transcription || gpuAccelAvailable.intelligence) &&
activeView === "home" &&
!gpuBannerDismissed && (
<div className="max-w-3xl mx-auto w-full mb-3">
@@ -860,7 +868,7 @@ export default function ControlPanel({ initialSettingsSection }: ControlPanelPro
className="h-7 text-xs"
onClick={() => {
setSettingsSection(
- gpuAccelAvailable.cuda ? "transcription" : "intelligence"
+ gpuAccelAvailable.transcription ? "transcription" : "intelligence"
);
setShowSettings(true);
}}
diff --git a/src/components/TranscriptionModelPicker.tsx b/src/components/TranscriptionModelPicker.tsx
index 1d9095a4c..4753c7bfb 100644
--- a/src/components/TranscriptionModelPicker.tsx
+++ b/src/components/TranscriptionModelPicker.tsx
@@ -30,7 +30,6 @@ import { createExternalLinkHandler } from "../utils/externalLinks";
import { API_ENDPOINTS, normalizeBaseUrl } from "../config/constants";
import { GetApiKeyLink } from "./ui/GetApiKeyLink";
import { getCachedPlatform } from "../utils/platform";
-import type { CudaWhisperStatus } from "../types/electron";
import logger from "../utils/logger";
interface LocalModel {
@@ -365,14 +364,15 @@ export default function TranscriptionModelPicker({
const [internalLocalProvider, setInternalLocalProvider] = useState(selectedLocalProvider);
const hasLoadedRef = useRef(false);
const hasLoadedParakeetRef = useRef(false);
- const [cudaStatus, setCudaStatus] = useState<CudaWhisperStatus | null>(null);
- const [cudaDownloading, setCudaDownloading] = useState(false);
- const [cudaProgress, setCudaProgress] = useState<DownloadProgress>({
+ const [gpuBackend, setGpuBackend] = useState<"cuda" | "vulkan" | null>(null);
+ const [gpuDownloaded, setGpuDownloaded] = useState(false);
+ const [gpuDownloading, setGpuDownloading] = useState(false);
+ const [gpuProgress, setGpuProgress] = useState<DownloadProgress>({
downloadedBytes: 0,
totalBytes: 0,
percentage: 0,
});
- const [cudaDismissed, setCudaDismissed] = useState(false);
+ const [gpuDismissed, setGpuDismissed] = useState(false);
useEffect(() => {
if (selectedLocalProvider !== internalLocalProvider) {
@@ -537,42 +537,58 @@ export default function TranscriptionModelPicker({
useEffect(() => {
if (!effectiveLocal || internalLocalProvider !== "whisper") return;
if (getCachedPlatform() === "darwin") return;
- window.electronAPI
- ?.getCudaWhisperStatus?.()
- ?.then(setCudaStatus)
- .catch(() => {});
+ const detect = async () => {
+ try {
+ const cuda = await window.electronAPI?.getCudaWhisperStatus?.();
+ if (cuda?.gpuInfo.hasNvidiaGpu) {
+ setGpuBackend("cuda");
+ setGpuDownloaded(cuda.downloaded);
+ return;
+ }
+ const vulkan = await window.electronAPI?.getVulkanWhisperStatus?.();
+ if (vulkan?.vulkan.available) {
+ setGpuBackend("vulkan");
+ setGpuDownloaded(vulkan.downloaded);
+ }
+ } catch {}
+ };
+ detect();
}, [effectiveLocal, internalLocalProvider]);
useEffect(() => {
- if (!cudaDownloading) return;
- const cleanup = window.electronAPI?.onCudaDownloadProgress?.((data) => {
- setCudaProgress(data);
- });
- return cleanup;
- }, [cudaDownloading]);
-
- const handleCudaDownload = async () => {
- setCudaDownloading(true);
+ if (!gpuDownloading || !gpuBackend) return;
+ const subscribe =
+ gpuBackend === "cuda"
+ ? window.electronAPI?.onCudaDownloadProgress
+ : window.electronAPI?.onVulkanWhisperDownloadProgress;
+ return subscribe?.((data) => setGpuProgress(data));
+ }, [gpuDownloading, gpuBackend]);
+
+ const handleGpuDownload = async () => {
+ setGpuDownloading(true);
try {
- const result = await window.electronAPI?.downloadCudaWhisperBinary?.();
- if (result?.success) {
- const status = await window.electronAPI?.getCudaWhisperStatus?.();
- setCudaStatus(status || null);
- }
+ const result =
+ gpuBackend === "cuda"
+ ? await window.electronAPI?.downloadCudaWhisperBinary?.()
+ : await window.electronAPI?.downloadVulkanWhisperBinary?.();
+ if (result?.success) setGpuDownloaded(true);
} finally {
- setCudaDownloading(false);
+ setGpuDownloading(false);
}
};
- const handleCudaDelete = async () => {
- await window.electronAPI?.deleteCudaWhisperBinary?.();
- const status = await window.electronAPI?.getCudaWhisperStatus?.();
- setCudaStatus(status || null);
+ const handleGpuDelete = async () => {
+ const result =
+ gpuBackend === "cuda"
+ ? await window.electronAPI?.deleteCudaWhisperBinary?.()
+ : await window.electronAPI?.deleteVulkanWhisperBinary?.();
+ if (result?.success) setGpuDownloaded(false);
};
- const handleCudaCancel = async () => {
- await window.electronAPI?.cancelCudaWhisperDownload?.();
- setCudaDownloading(false);
+ const handleGpuCancel = async () => {
+ if (gpuBackend === "cuda") await window.electronAPI?.cancelCudaWhisperDownload?.();
+ else await window.electronAPI?.cancelVulkanWhisperDownload?.();
+ setGpuDownloading(false);
};
const {
@@ -1057,34 +1073,33 @@ export default function TranscriptionModelPicker({
{progressDisplay}
- {cudaDownloading && internalLocalProvider === "whisper" && (
+ {gpuDownloading && internalLocalProvider === "whisper" && (
<div>
- <DownloadProgressBar modelName="GPU acceleration" progress={cudaProgress} />
+ <DownloadProgressBar modelName="GPU acceleration" progress={gpuProgress} />
<div className="px-2.5 pb-1 flex justify-end">
<button
- onClick={handleCudaCancel}
+ onClick={handleGpuCancel}
className="text-xs text-muted-foreground hover:text-foreground transition-colors"
>
- Cancel
+ {t("gpu.cancel")}
</button>
</div>
</div>
)}
{internalLocalProvider === "whisper" &&
- !cudaDismissed &&
- !cudaDownloading &&
- getCachedPlatform() !== "darwin" &&
- cudaStatus?.gpuInfo.hasNvidiaGpu && (
+ !gpuDismissed &&
+ !gpuDownloading &&
+ gpuBackend && (
<div className="rounded-md border border-border bg-surface-1 p-2.5">
- {cudaStatus.downloaded ? (
+ {gpuDownloaded ? (
<div className="flex items-center justify-between">
<div className="flex items-center gap-1.5">
<Check size={13} className="text-success" />
<span className="text-xs font-medium text-foreground">{t("gpu.active")}</span>
</div>
<Button
- onClick={handleCudaDelete}
+ onClick={handleGpuDelete}
size="sm"
variant="ghost"
className="h-6 px-2 text-xs text-muted-foreground hover:text-destructive"
@@ -1101,7 +1116,7 @@ export default function TranscriptionModelPicker({
</p>
<div className="flex items-center gap-2 mt-1.5">
<Button
- onClick={handleCudaDownload}
+ onClick={handleGpuDownload}
size="sm"
variant="default"
className="h-6 px-2.5 text-xs"
@@ -1109,7 +1124,7 @@ export default function TranscriptionModelPicker({
{t("gpu.enableButton")}
</Button>
<button
- onClick={() => setCudaDismissed(true)}
+ onClick={() => setGpuDismissed(true)}
className="text-xs text-muted-foreground hover:text-foreground transition-colors"
>
{t("gpu.dismiss")}
diff --git a/src/helpers/environment.js b/src/helpers/environment.js
index e4a23f9ae..5fba38f5b 100644
--- a/src/helpers/environment.js
+++ b/src/helpers/environment.js
@@ -45,6 +45,7 @@ const PERSISTED_KEYS = [
"START_MINIMIZED",
"UI_LANGUAGE",
"WHISPER_CUDA_ENABLED",
+ "WHISPER_VULKAN_ENABLED",
"WHISPER_THREADS",
"TRANSCRIPTION_GPU_UUID",
"INTELLIGENCE_GPU_UUID",
diff --git a/src/helpers/gpuBinaryManager.js b/src/helpers/gpuBinaryManager.js
new file mode 100644
index 000000000..99f4da9f8
--- /dev/null
+++ b/src/helpers/gpuBinaryManager.js
@@ -0,0 +1,246 @@
+const fs = require("fs");
+const { promises: fsPromises } = require("fs");
+const { createHash } = require("crypto");
+const path = require("path");
+const { app } = require("electron");
+const debugLogger = require("./debugLogger");
+const {
+ downloadFile,
+ fetchJson,
+ createDownloadSignal,
+ checkDiskSpace,
+ cleanupStaleDownloads,
+ extractArchive,
+ findFile,
+ findFiles,
+} = require("./downloadUtils");
+const { getSafeTempDir } = require("./safeTempDir");
+
+const DISK_SPACE_MULTIPLIER = 2.5;
+const FALLBACK_ASSET_SIZE = 100_000_000;
+
+function githubReleaseHeaders() {
+ const headers = { Accept: "application/vnd.github+json" };
+ const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+ if (token) headers.Authorization = `Bearer ${token}`;
+ return headers;
+}
+
+function sha256File(filePath) {
+ return new Promise((resolve, reject) => {
+ const hash = createHash("sha256");
+ fs.createReadStream(filePath)
+ .on("data", (chunk) => hash.update(chunk))
+ .on("end", () => resolve(hash.digest("hex")))
+ .on("error", reject);
+ });
+}
+
+// Shared download/install pipeline for GPU server binaries fetched from GitHub
+// releases (whisper CUDA, whisper Vulkan, llama Vulkan). Subclasses configure
+// the release URL and per-`${platform}-${arch}` assets (exact assetName or
+// assetPattern regex; optional libPattern for companion libs). Archives are
+// sha256-verified against expectedDigests, falling back to the digest the
+// GitHub API reports.
+class GpuBinaryManager {
+ constructor(config) {
+ this.config = config;
+ this._binDir = null;
+ this._downloadSignal = null;
+ this._downloading = false;
+ }
+
+ get binDir() {
+ if (!this._binDir) {
+ this._binDir = path.join(app.getPath("userData"), "bin");
+ }
+ return this._binDir;
+ }
+
+ _getAssetConfig() {
+ return this.config.assets[`${process.platform}-${process.arch}`] || null;
+ }
+
+ isSupported() {
+ return this._getAssetConfig() !== null;
+ }
+
+ getBinaryPath() {
+ const assetConfig = this._getAssetConfig();
+ if (!assetConfig) return null;
+ const binaryPath = path.join(this.binDir, assetConfig.outputName);
+ try {
+ if (fs.existsSync(binaryPath)) return binaryPath;
+ } catch {}
+ return null;
+ }
+
+ isDownloaded() {
+ return this.getBinaryPath() !== null;
+ }
+
+ isDownloading() {
+ return this._downloading;
+ }
+
+ getStatus() {
+ return {
+ supported: this.isSupported(),
+ downloaded: this.isDownloaded(),
+ downloading: this._downloading,
+ };
+ }
+
+ async _resolveAsset(assetConfig) {
+ const release = await fetchJson(this.config.releaseUrl, { headers: githubReleaseHeaders() });
+ if (!release?.assets) throw new Error(`Could not fetch ${this.config.name} release info`);
+
+ const asset = release.assets.find((a) =>
+ assetConfig.assetName
+ ? a.name === assetConfig.assetName
+ : assetConfig.assetPattern.test(a.name)
+ );
+ if (!asset) {
+ throw new Error(
+ `No ${this.config.name} asset found in release` +
+ (assetConfig.assetName ? ` (expected ${assetConfig.assetName})` : "")
+ );
+ }
+ return { asset, version: release.tag_name };
+ }
+
+ // The binaries are unsigned and release assets are mutable — fail closed on mismatch
+ async _verifyDigest(asset, archivePath) {
+ const pinned = this.config.expectedDigests?.[asset.name];
+ const expected = pinned || (asset.digest || "").replace(/^sha256:/, "");
+ if (!expected) return;
+
+ const actual = await sha256File(archivePath);
+ if (actual !== expected) {
+ throw new Error(
+ `${this.config.name} download failed integrity check ` +
+ `(sha256 ${actual}, expected ${expected})`
+ );
+ }
+ }
+
+ async download(onProgress) {
+ if (this._downloading) throw new Error("Download already in progress");
+ const assetConfig = this._getAssetConfig();
+ if (!assetConfig) {
+ throw new Error(
+ `${this.config.name} binaries not available for ${process.platform}-${process.arch}`
+ );
+ }
+
+ this._downloading = true;
+ const { signal, abort } = createDownloadSignal();
+ this._downloadSignal = { abort };
+
+ const tempDir = getSafeTempDir();
+ let archivePath = null;
+ let extractDir = null;
+
+ try {
+ await fsPromises.mkdir(this.binDir, { recursive: true });
+ await cleanupStaleDownloads(this.binDir);
+
+ const { asset, version } = await this._resolveAsset(assetConfig);
+
+ const requiredBytes = (asset.size || FALLBACK_ASSET_SIZE) * DISK_SPACE_MULTIPLIER;
+ const spaceCheck = await checkDiskSpace(this.binDir, requiredBytes);
+ if (!spaceCheck.ok) {
+ throw new Error(
+ `Not enough disk space. Need ~${Math.round(requiredBytes / 1_000_000)}MB, ` +
+ `only ${Math.round(spaceCheck.availableBytes / 1_000_000)}MB available.`
+ );
+ }
+
+ debugLogger.info(`${this.config.name} binary download starting`, {
+ version,
+ asset: asset.name,
+ size: asset.size,
+ });
+
+ archivePath = path.join(tempDir, asset.name);
+ extractDir = path.join(tempDir, `temp-extract-${Date.now()}`);
+
+ await downloadFile(asset.browser_download_url, archivePath, {
+ signal,
+ expectedSize: asset.size,
+ onProgress,
+ });
+
+ await this._verifyDigest(asset, archivePath);
+
+ await fsPromises.mkdir(extractDir, { recursive: true });
+ await extractArchive(archivePath, extractDir);
+
+ const binaryPath = await findFile(extractDir, assetConfig.binaryName);
+ if (!binaryPath) throw new Error(`${assetConfig.binaryName} not found in archive`);
+
+ const outputPath = path.join(this.binDir, assetConfig.outputName);
+ await fsPromises.copyFile(binaryPath, outputPath);
+ if (process.platform !== "win32") await fsPromises.chmod(outputPath, 0o755);
+
+ if (assetConfig.libPattern) {
+ const libs = await findFiles(extractDir, assetConfig.libPattern);
+ for (const lib of libs) {
+ const dest = path.join(this.binDir, path.basename(lib));
+ await fsPromises.copyFile(lib, dest);
+ if (process.platform !== "win32") await fsPromises.chmod(dest, 0o755);
+ }
+ }
+
+ debugLogger.info(`${this.config.name} binary installed`, { version, path: outputPath });
+ return { version };
+ } finally {
+ this._downloading = false;
+ this._downloadSignal = null;
+ if (archivePath) await fsPromises.unlink(archivePath).catch(() => {});
+ if (extractDir) {
+ await fsPromises.rm(extractDir, { recursive: true, force: true }).catch(() => {});
+ }
+ }
+ }
+
+ cancelDownload() {
+ if (this._downloadSignal) {
+ this._downloadSignal.abort();
+ this._downloadSignal = null;
+ return true;
+ }
+ return false;
+ }
+
+ async delete() {
+ const assetConfig = this._getAssetConfig();
+ if (!assetConfig) return { deletedCount: 0, freedBytes: 0 };
+
+ let deletedCount = 0;
+ let freedBytes = 0;
+
+ try {
+ const entries = await fsPromises.readdir(this.binDir);
+ for (const entry of entries) {
+ if (entry !== assetConfig.outputName && !assetConfig.libPattern?.test(entry)) continue;
+ const filePath = path.join(this.binDir, entry);
+ try {
+ const stats = await fsPromises.stat(filePath);
+ await fsPromises.unlink(filePath);
+ freedBytes += stats.size;
+ deletedCount++;
+ } catch {
+ // Continue with remaining files
+ }
+ }
+ } catch {
+ // Directory may not exist
+ }
+
+ debugLogger.info(`${this.config.name} binary deleted`, { deletedCount, freedBytes });
+ return { deletedCount, freedBytes };
+ }
+}
+
+module.exports = GpuBinaryManager;
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 142d6de68..f56eca0f5 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -405,6 +405,7 @@ class IPCHandlers {
this.textEditMonitor = managers.textEditMonitor;
this.getTrayManager = managers.getTrayManager;
this.whisperCudaManager = managers.whisperCudaManager;
+ this.whisperVulkanManager = managers.whisperVulkanManager;
this.googleCalendarManager = managers.googleCalendarManager;
this.meetingDetectionEngine = managers.meetingDetectionEngine;
this.audioTapManager = managers.audioTapManager;
@@ -450,6 +451,9 @@ class IPCHandlers {
this.whisperManager.serverManager.on("cuda-fallback", () => {
this.broadcastToWindows("cuda-fallback-notification", {});
});
+ this.whisperManager.serverManager.on("gpu-fallback", () => {
+ this.broadcastToWindows("gpu-fallback-notification", {});
+ });
}
}
@@ -2052,7 +2056,11 @@ class IPCHandlers {
ipcMain.handle("whisper-server-start", async (event, modelName) => {
const useCuda =
process.env.WHISPER_CUDA_ENABLED === "true" && this.whisperCudaManager?.isDownloaded();
- return this.whisperManager.startServer(modelName, { useCuda });
+ const useVulkan =
+ !useCuda &&
+ process.env.WHISPER_VULKAN_ENABLED === "true" &&
+ this.whisperVulkanManager?.isDownloaded();
+ return this.whisperManager.startServer(modelName, { useCuda, useVulkan });
});
ipcMain.handle("whisper-server-stop", async () => {
@@ -2158,12 +2166,12 @@ class IPCHandlers {
return { success: false, error: "CUDA not supported on this platform" };
}
try {
- await this.whisperCudaManager.download((progress) => {
- if (progress.type === "progress" && !event.sender.isDestroyed()) {
+ await this.whisperCudaManager.download((downloaded, total) => {
+ if (!event.sender.isDestroyed()) {
event.sender.send("cuda-download-progress", {
- downloadedBytes: progress.downloaded_bytes,
- totalBytes: progress.total_bytes,
- percentage: progress.percentage,
+ downloadedBytes: downloaded,
+ totalBytes: total,
+ percentage: total > 0 ? Math.round((downloaded / total) * 100) : 0,
});
}
});
@@ -2187,15 +2195,68 @@ class IPCHandlers {
ipcMain.handle("delete-cuda-whisper-binary", async () => {
if (!this.whisperCudaManager) return { success: false };
+ // Stop the server first so the running binary can be deleted on Windows
+ await this.whisperManager.stopServer().catch(() => {});
const result = await this.whisperCudaManager.delete();
if (result.success) {
this._syncStartupEnv({}, ["WHISPER_CUDA_ENABLED"]);
- // Restart whisper-server so it falls back to CPU binary
- await this.whisperManager.stopServer().catch(() => {});
}
return result;
});
+ ipcMain.handle("get-vulkan-whisper-status", async () => {
+ const { detectVulkanGpu } = require("../utils/vulkanDetection");
+ const { detectNvidiaGpu } = require("../utils/gpuDetection");
+ const [vulkan, gpuInfo] = await Promise.all([detectVulkanGpu(), detectNvidiaGpu()]);
+ return {
+ downloaded: this.whisperVulkanManager?.isDownloaded() ?? false,
+ downloading: this.whisperVulkanManager?.isDownloading() ?? false,
+ vulkan,
+ hasNvidiaGpu: gpuInfo.hasNvidiaGpu,
+ };
+ });
+
+ ipcMain.handle("download-vulkan-whisper-binary", async (event) => {
+ if (!this.whisperVulkanManager) {
+ return { success: false, error: "Vulkan not supported on this platform" };
+ }
+ try {
+ // Stop the server first: overwriting a running binary EBUSYs on Windows
+ await this.whisperManager.stopServer().catch(() => {});
+ await this.whisperVulkanManager.download((downloaded, total) => {
+ if (!event.sender.isDestroyed()) {
+ event.sender.send("vulkan-whisper-download-progress", {
+ downloadedBytes: downloaded,
+ totalBytes: total,
+ percentage: total > 0 ? Math.round((downloaded / total) * 100) : 0,
+ });
+ }
+ });
+ this._syncStartupEnv({ WHISPER_VULKAN_ENABLED: "true" });
+ return { success: true };
+ } catch (error) {
+ debugLogger.error("Vulkan whisper binary download failed", {
+ error: error.message,
+ stack: error.stack,
+ });
+ return { success: false, error: error.message };
+ }
+ });
+
+ ipcMain.handle("cancel-vulkan-whisper-download", async () => {
+ if (!this.whisperVulkanManager) return { success: false };
+ return { success: this.whisperVulkanManager.cancelDownload() };
+ });
+
+ ipcMain.handle("delete-vulkan-whisper-binary", async () => {
+ if (!this.whisperVulkanManager) return { success: false };
+ // Stop the server first so the running binary can be deleted on Windows
+ await this.whisperManager.stopServer().catch(() => {});
+ const { deletedCount } = await this.whisperVulkanManager.delete();
+ this._syncStartupEnv({}, ["WHISPER_VULKAN_ENABLED"]);
+ return { success: true, deletedCount };
+ });
+
ipcMain.handle("check-ffmpeg-availability", async (event) => {
return this.whisperManager.checkFFmpegAvailability();
});
diff --git a/src/helpers/llamaVulkanManager.js b/src/helpers/llamaVulkanManager.js
index 15e1c6ce4..dfbb29015 100644
--- a/src/helpers/llamaVulkanManager.js
+++ b/src/helpers/llamaVulkanManager.js
@@ -1,185 +1,43 @@
-const fs = require("fs");
-const { promises: fsPromises } = require("fs");
-const path = require("path");
-const { app } = require("electron");
-const debugLogger = require("./debugLogger");
-const {
- downloadFile,
- fetchJson,
- createDownloadSignal,
- checkDiskSpace,
- cleanupStaleDownloads,
- extractArchive,
- findFile,
- findFiles,
-} = require("./downloadUtils");
-
-function githubReleaseHeaders() {
- const headers = { Accept: "application/vnd.github+json" };
- const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
- if (token) headers.Authorization = `Bearer ${token}`;
- return headers;
-}
+const GpuBinaryManager = require("./gpuBinaryManager");
// Pinned to the same build as the bundled CPU binary (download-llama-server.js).
// Overridable via LLAMA_CPP_VERSION so GPU and CPU stay on one tested llama.cpp.
const LLAMA_CPP_TAG = process.env.LLAMA_CPP_VERSION || "b9763";
-const GITHUB_RELEASE_URL = `https://api.github.com/repos/ggml-org/llama.cpp/releases/tags/${LLAMA_CPP_TAG}`;
-
-const VULKAN_ASSETS = {
- "win32-x64": {
- assetPattern: /^llama-.*-bin-win-vulkan-x64\.zip$/,
- binaryName: "llama-server.exe",
- outputName: "llama-server-vulkan.exe",
- libPattern: /\.dll$/i,
- },
- "linux-x64": {
- assetPattern: /^llama-.*-bin-ubuntu-vulkan-x64\.tar\.gz$/,
- binaryName: "llama-server",
- outputName: "llama-server-vulkan",
- libPattern: /\.so(\.\d+)*$/,
- },
-};
-class LlamaVulkanManager {
+class LlamaVulkanManager extends GpuBinaryManager {
constructor() {
- this._binDir = null;
- this._downloadSignal = null;
- this._downloading = false;
- }
-
- get binDir() {
- if (!this._binDir) {
- this._binDir = path.join(app.getPath("userData"), "bin");
- }
- return this._binDir;
- }
-
- _getConfig() {
- return VULKAN_ASSETS[`${process.platform}-${process.arch}`] || null;
- }
-
- isSupported() {
- return this._getConfig() !== null;
- }
-
- getBinaryPath() {
- const config = this._getConfig();
- if (!config) return null;
- const p = path.join(this.binDir, config.outputName);
- try {
- if (fs.existsSync(p)) return p;
- } catch {}
- return null;
- }
-
- isDownloaded() {
- return this.getBinaryPath() !== null;
- }
-
- getStatus() {
- return {
- supported: this.isSupported(),
- downloaded: this.isDownloaded(),
- downloading: this._downloading,
- };
+ super({
+ name: "Vulkan llama",
+ releaseUrl: `https://api.github.com/repos/ggml-org/llama.cpp/releases/tags/${LLAMA_CPP_TAG}`,
+ assets: {
+ "win32-x64": {
+ assetPattern: /^llama-.*-bin-win-vulkan-x64\.zip$/,
+ binaryName: "llama-server.exe",
+ outputName: "llama-server-vulkan.exe",
+ libPattern: /\.dll$/i,
+ },
+ "linux-x64": {
+ assetPattern: /^llama-.*-bin-ubuntu-vulkan-x64\.tar\.gz$/,
+ binaryName: "llama-server",
+ outputName: "llama-server-vulkan",
+ libPattern: /\.so(\.\d+)*$/,
+ },
+ },
+ });
}
async download(onProgress) {
- if (this._downloading) throw new Error("Download already in progress");
- if (!this.isSupported()) throw new Error("Vulkan not available for this platform");
-
- this._downloading = true;
- const { signal, abort } = createDownloadSignal();
- this._downloadSignal = { abort };
-
try {
- await fsPromises.mkdir(this.binDir, { recursive: true });
- await cleanupStaleDownloads(this.binDir);
-
- const release = await fetchJson(GITHUB_RELEASE_URL, { headers: githubReleaseHeaders() });
- if (!release?.assets) throw new Error("Could not fetch llama.cpp release info");
-
- const config = this._getConfig();
- const asset = release.assets.find((a) => config.assetPattern.test(a.name));
- if (!asset) throw new Error("Vulkan binary not found in latest release");
-
- const spaceCheck = await checkDiskSpace(this.binDir, (asset.size || 100_000_000) * 2.5);
- if (!spaceCheck.ok) {
- throw new Error(
- `Not enough disk space. Need ~${Math.round(((asset.size || 100_000_000) * 2.5) / 1_000_000)}MB, ` +
- `only ${Math.round(spaceCheck.availableBytes / 1_000_000)}MB available.`
- );
- }
-
- const archivePath = path.join(this.binDir, asset.name);
- await downloadFile(asset.browser_download_url, archivePath, {
- signal,
- expectedSize: asset.size,
- onProgress,
- });
-
- const extractDir = path.join(this.binDir, `temp-vulkan-${Date.now()}`);
- await fsPromises.mkdir(extractDir, { recursive: true });
-
- try {
- await extractArchive(archivePath, extractDir);
-
- const binaryPath = await findFile(extractDir, config.binaryName);
- if (!binaryPath) throw new Error(`${config.binaryName} not found in archive`);
-
- const outputPath = path.join(this.binDir, config.outputName);
- await fsPromises.copyFile(binaryPath, outputPath);
- if (process.platform !== "win32") await fsPromises.chmod(outputPath, 0o755);
-
- const libs = await findFiles(extractDir, config.libPattern);
- for (const lib of libs) {
- const dest = path.join(this.binDir, path.basename(lib));
- await fsPromises.copyFile(lib, dest);
- if (process.platform !== "win32") await fsPromises.chmod(dest, 0o755);
- }
-
- debugLogger.info("Vulkan llama-server installed", { path: outputPath });
- } finally {
- await fsPromises.rm(extractDir, { recursive: true, force: true }).catch(() => {});
- await fsPromises.unlink(archivePath).catch(() => {});
- }
-
+ await super.download(onProgress);
return { success: true };
} catch (error) {
if (error.isAbort) return { success: false, cancelled: true };
throw error;
- } finally {
- this._downloading = false;
- this._downloadSignal = null;
}
}
- cancelDownload() {
- if (this._downloadSignal) {
- this._downloadSignal.abort();
- this._downloadSignal = null;
- return true;
- }
- return false;
- }
-
async deleteBinary() {
- const config = this._getConfig();
- if (!config) return { success: true };
-
- let deletedCount = 0;
- try {
- const entries = await fsPromises.readdir(this.binDir);
- for (const entry of entries) {
- if (entry === config.outputName || config.libPattern.test(entry)) {
- await fsPromises.unlink(path.join(this.binDir, entry)).catch(() => {});
- deletedCount++;
- }
- }
- } catch {}
-
- debugLogger.info("Vulkan llama-server deleted", { deletedCount });
+ const { deletedCount } = await this.delete();
return { success: true, deletedCount };
}
}
diff --git a/src/helpers/whisper.js b/src/helpers/whisper.js
index dd7d8de54..a235bd221 100644
--- a/src/helpers/whisper.js
+++ b/src/helpers/whisper.js
@@ -30,11 +30,18 @@ function getValidModelNames() {
return Object.keys(modelRegistryData.whisperModels);
}
-function shouldRewarmOnWake({ isRemote, useCuda, modelName, transcribing, rewarmInFlight }) {
- // Only re-warm a running local CUDA whisper-server: sleep evicts its model from
+function shouldRewarmOnWake({
+ isRemote,
+ useCuda,
+ useVulkan,
+ modelName,
+ transcribing,
+ rewarmInFlight,
+}) {
+ // Only re-warm a running local GPU whisper-server: sleep evicts its model from
// VRAM. Skip remote/CPU servers, and skip while a transcription (already warming
// the server) or another re-warm is in flight. See #766.
- return !isRemote && !!useCuda && !!modelName && !transcribing && !rewarmInFlight;
+ return !isRemote && !!(useCuda || useVulkan) && !!modelName && !transcribing && !rewarmInFlight;
}
class WhisperManager {
@@ -95,7 +102,7 @@ class WhisperManager {
await cleanupStaleDownloads(this.getModelsDir());
// Pre-warm whisper-server if local mode enabled (eliminates 2-5s cold-start delay)
- const { localTranscriptionProvider, whisperModel, useCuda } = settings;
+ const { localTranscriptionProvider, whisperModel, useCuda, useVulkan } = settings;
if (
localTranscriptionProvider === "whisper" &&
@@ -109,11 +116,15 @@ class WhisperManager {
model: whisperModel,
modelPath,
cuda: !!useCuda,
+ vulkan: !!useVulkan,
});
try {
const serverStartTime = Date.now();
- await this.serverManager.start(modelPath, { useCuda: !!useCuda });
+ await this.serverManager.start(modelPath, {
+ useCuda: !!useCuda,
+ useVulkan: !!useVulkan,
+ });
this.currentServerModel = whisperModel;
debugLogger.info("whisper-server pre-warmed successfully", {
@@ -251,6 +262,7 @@ class WhisperManager {
!shouldRewarmOnWake({
isRemote: sm.isRemote,
useCuda: sm.useCuda,
+ useVulkan: sm.useVulkan,
modelName,
transcribing: this._transcribing,
rewarmInFlight: this._rewarmInFlight,
@@ -259,10 +271,11 @@ class WhisperManager {
return false;
}
- // Replay the last start options (VAD, threads) so the reloaded server matches the
- // signature the next dictation will use; a bare start would otherwise be rejected
- // by start()'s no-op guard and reload the model on the first dictation. See #766.
- const options = { ...sm.lastStartOptions, useCuda: true };
+ // Replay the last start options (VAD, threads, GPU backend) so the reloaded
+ // server matches the signature the next dictation will use; a bare start would
+ // otherwise be rejected by start()'s no-op guard and reload the model on the
+ // first dictation. See #766.
+ const options = { ...sm.lastStartOptions };
this._rewarmInFlight = true;
try {
debugLogger.info("Re-warming whisper-server after wake from sleep", { model: modelName });
@@ -350,6 +363,7 @@ class WhisperManager {
await this.serverManager.start(modelPath, {
useCuda: this.serverManager.useCuda,
+ useVulkan: this.serverManager.useVulkan,
vadEnabled,
vadModelPath,
vadConfig: options.vadConfig || null,
diff --git a/src/helpers/whisperCudaManager.js b/src/helpers/whisperCudaManager.js
index 8c08389eb..a77824cc5 100644
--- a/src/helpers/whisperCudaManager.js
+++ b/src/helpers/whisperCudaManager.js
@@ -1,238 +1,54 @@
-const fs = require("fs");
-const { promises: fsPromises } = require("fs");
-const path = require("path");
-const { app } = require("electron");
-const debugLogger = require("./debugLogger");
-const {
- downloadFile,
- fetchJson,
- createDownloadSignal,
- checkDiskSpace,
- cleanupStaleDownloads,
- extractArchive,
- findFile,
- findFiles,
-} = require("./downloadUtils");
-const { getSafeTempDir } = require("./safeTempDir");
+const GpuBinaryManager = require("./gpuBinaryManager");
const GITHUB_RELEASE_URL = "https://api.github.com/repos/OpenWhispr/whisper.cpp/releases/latest";
-const PLATFORM_BINARY_NAMES = {
- linux: "whisper-server-linux-x64-cuda",
- win32: "whisper-server-win32-x64-cuda.exe",
-};
-
-const PLATFORM_ASSET_NAMES = {
- linux: "whisper-server-linux-x64-cuda.zip",
- win32: "whisper-server-win32-x64-cuda.zip",
-};
-
-const COMPANION_PATTERNS = {
- linux: /\.so(\.\d+)*$/,
- win32: /\.dll$/i,
-};
-
-function isSupportedPlatform() {
- return process.platform === "linux" || process.platform === "win32";
-}
-
-class WhisperCudaManager {
+class WhisperCudaManager extends GpuBinaryManager {
constructor() {
- this._binDir = null;
- this._downloadSignal = null;
- this._downloading = false;
- }
-
- getCudaBinaryDir() {
- if (!this._binDir) {
- this._binDir = path.join(app.getPath("userData"), "bin");
- fs.mkdirSync(this._binDir, { recursive: true });
- }
- return this._binDir;
+ super({
+ name: "CUDA whisper",
+ releaseUrl: GITHUB_RELEASE_URL,
+ assets: {
+ "win32-x64": {
+ assetName: "whisper-server-win32-x64-cuda.zip",
+ binaryName: "whisper-server-win32-x64-cuda.exe",
+ outputName: "whisper-server-win32-x64-cuda.exe",
+ libPattern: /\.dll$/i,
+ },
+ "linux-x64": {
+ assetName: "whisper-server-linux-x64-cuda.zip",
+ binaryName: "whisper-server-linux-x64-cuda",
+ outputName: "whisper-server-linux-x64-cuda",
+ libPattern: /\.so(\.\d+)*$/,
+ },
+ },
+ });
}
getCudaBinaryPath() {
- if (!isSupportedPlatform()) return null;
-
- const binaryName = PLATFORM_BINARY_NAMES[process.platform];
- const binaryPath = path.join(this.getCudaBinaryDir(), binaryName);
- return fs.existsSync(binaryPath) ? binaryPath : null;
- }
-
- isDownloaded() {
- return !!this.getCudaBinaryPath();
- }
-
- isDownloading() {
- return this._downloading;
- }
-
- async fetchReleaseInfo() {
- if (!isSupportedPlatform()) {
- throw new Error(`CUDA binaries not available for ${process.platform}`);
- }
-
- const release = await fetchJson(GITHUB_RELEASE_URL, {
- headers: { Accept: "application/vnd.github+json" },
- });
- const assetName = PLATFORM_ASSET_NAMES[process.platform];
- const asset = release.assets?.find((a) => a.name === assetName);
-
- if (!asset) {
- throw new Error(`No CUDA asset found for ${process.platform} (expected ${assetName})`);
- }
-
- return {
- url: asset.browser_download_url,
- size: asset.size,
- version: release.tag_name,
- };
+ return this.getBinaryPath();
}
- async download(progressCallback) {
- if (this._downloading) throw new Error("Download already in progress");
- if (!isSupportedPlatform()) {
- throw new Error(`CUDA binaries not available for ${process.platform}`);
- }
-
- this._downloading = true;
-
- let zipPath = null;
- let extractDir = null;
-
+ async download(onProgress) {
try {
- const releaseInfo = await this.fetchReleaseInfo();
- debugLogger.info("CUDA binary download starting", {
- version: releaseInfo.version,
- size: releaseInfo.size,
- });
-
- const binDir = this.getCudaBinaryDir();
-
- const spaceCheck = await checkDiskSpace(binDir, releaseInfo.size * 2);
- if (!spaceCheck.ok) {
- throw new Error(
- `Not enough disk space. Need ~${Math.round((releaseInfo.size * 2) / 1_000_000)}MB, ` +
- `only ${Math.round(spaceCheck.availableBytes / 1_000_000)}MB available.`
- );
- }
-
- await cleanupStaleDownloads(binDir);
-
- const { signal, abort } = createDownloadSignal();
- this._downloadSignal = { abort };
-
- const tempDir = getSafeTempDir();
- zipPath = path.join(tempDir, `cuda-download-${Date.now()}.zip`);
- extractDir = path.join(tempDir, `temp-extract-${Date.now()}`);
-
- await downloadFile(releaseInfo.url, zipPath, {
- timeout: 600000,
- signal,
- expectedSize: releaseInfo.size,
- onProgress: (downloaded, total) => {
- if (progressCallback) {
- progressCallback({
- type: "progress",
- downloaded_bytes: downloaded,
- total_bytes: total,
- percentage: total > 0 ? Math.round((downloaded / total) * 100) : 0,
- });
- }
- },
- });
-
- await fsPromises.mkdir(extractDir, { recursive: true });
- await extractArchive(zipPath, extractDir);
-
- const binaryName = PLATFORM_BINARY_NAMES[process.platform];
- const companionPattern = COMPANION_PATTERNS[process.platform];
-
- const binaryPath = await findFile(extractDir, binaryName);
- if (!binaryPath) {
- throw new Error(`Extraction completed but binary "${binaryName}" not found in archive`);
- }
-
- const dest = path.join(binDir, binaryName);
- await fsPromises.copyFile(binaryPath, dest);
- if (process.platform === "linux") {
- await fsPromises.chmod(dest, 0o755);
- }
-
- const libs = await findFiles(extractDir, companionPattern);
- for (const lib of libs) {
- const libDest = path.join(binDir, path.basename(lib));
- await fsPromises.copyFile(lib, libDest);
- if (process.platform === "linux") {
- await fsPromises.chmod(libDest, 0o755);
- }
- }
-
- debugLogger.info("CUDA binary download complete", {
- version: releaseInfo.version,
- path: this.getCudaBinaryPath(),
- });
-
- if (progressCallback) {
- progressCallback({ type: "complete", percentage: 100 });
- }
+ await super.download(onProgress);
} catch (error) {
- if (error.isAbort) {
- throw new Error("Download cancelled by user");
- }
+ if (error.isAbort) throw new Error("Download cancelled by user");
throw error;
- } finally {
- this._downloading = false;
- this._downloadSignal = null;
- if (zipPath) await fsPromises.unlink(zipPath).catch(() => {});
- if (extractDir)
- await fsPromises.rm(extractDir, { recursive: true, force: true }).catch(() => {});
}
}
async cancelDownload() {
- if (this._downloadSignal) {
- this._downloadSignal.abort();
- this._downloadSignal = null;
+ if (super.cancelDownload()) {
return { success: true, message: "Download cancelled" };
}
return { success: false, error: "No active download to cancel" };
}
async delete() {
- if (!isSupportedPlatform()) {
+ if (!this.isSupported()) {
return { success: false, error: "Not supported on this platform" };
}
-
- const binDir = this.getCudaBinaryDir();
- const binaryName = PLATFORM_BINARY_NAMES[process.platform];
- const companionPattern = COMPANION_PATTERNS[process.platform];
-
- let deletedCount = 0;
- let freedBytes = 0;
-
- try {
- const entries = await fsPromises.readdir(binDir);
-
- for (const entry of entries) {
- if (entry === binaryName || companionPattern.test(entry)) {
- const filePath = path.join(binDir, entry);
- try {
- const stats = await fsPromises.stat(filePath);
- await fsPromises.unlink(filePath);
- freedBytes += stats.size;
- deletedCount++;
- } catch {
- // Continue with remaining files
- }
- }
- }
- } catch {
- // Directory may not exist
- }
-
- debugLogger.info("CUDA binary deleted", { deletedCount, freedBytes });
-
+ const { deletedCount, freedBytes } = await super.delete();
return {
success: deletedCount > 0,
deleted_count: deletedCount,
diff --git a/src/helpers/whisperServer.js b/src/helpers/whisperServer.js
index 3db11f064..d83001438 100644
--- a/src/helpers/whisperServer.js
+++ b/src/helpers/whisperServer.js
@@ -16,6 +16,8 @@ const { sanitizeWhisperVadConfig, DEFAULT_WHISPER_VAD_CONFIG } = require("./whis
const PORT_RANGE_START = 8178;
const PORT_RANGE_END = 8199;
const STARTUP_TIMEOUT_MS = 30000;
+// Vulkan cold starts compile shaders and load the full model before the port binds. See #698.
+const VULKAN_STARTUP_TIMEOUT_MS = 120000;
const HEALTH_CHECK_INTERVAL_MS = 5000;
const HEALTH_CHECK_TIMEOUT_MS = 2000;
const DEFAULT_WHISPER_THREADS = 4;
@@ -174,6 +176,8 @@ class WhisperServerManager extends EventEmitter {
this.cachedFFmpegPath = null;
this.canConvert = false;
this.useCuda = false;
+ this.useVulkan = false;
+ this._abortStartup = false;
this.vadSignature = "vad:off";
this.threadSignature = "threads:default";
this.lastStartOptions = {};
@@ -270,11 +274,12 @@ class WhisperServerManager extends EventEmitter {
}
getServerBinaryPath(options = {}) {
- if (options.preferCuda) {
+ const gpuBackend = options.preferCuda ? "cuda" : options.preferVulkan ? "vulkan" : null;
+ if (gpuBackend) {
const ext = process.platform === "win32" ? ".exe" : "";
- const cudaBinary = `whisper-server-${process.platform}-${process.arch}-cuda${ext}`;
- const cudaPath = path.join(app.getPath("userData"), "bin", cudaBinary);
- if (fs.existsSync(cudaPath)) return cudaPath;
+ const gpuBinary = `whisper-server-${process.platform}-${process.arch}-${gpuBackend}${ext}`;
+ const gpuPath = path.join(app.getPath("userData"), "bin", gpuBinary);
+ if (fs.existsSync(gpuPath)) return gpuPath;
}
if (this.cachedServerBinaryPath) return this.cachedServerBinaryPath;
@@ -408,14 +413,19 @@ class WhisperServerManager extends EventEmitter {
async _doStart(modelPath, options = {}) {
const usingCuda = options.useCuda || false;
+ const usingVulkan = !usingCuda && (options.useVulkan || false);
const threadResolution = options.threadResolution || resolveWhisperThreads(options);
- const serverBinary = this.getServerBinaryPath(usingCuda ? { preferCuda: true } : {});
+ const serverBinary = this.getServerBinaryPath(
+ usingCuda ? { preferCuda: true } : usingVulkan ? { preferVulkan: true } : {}
+ );
if (!serverBinary) throw new Error("whisper-server binary not found");
if (!fs.existsSync(modelPath)) throw new Error(`Model file not found: ${modelPath}`);
this.port = await this.findAvailablePort();
this.modelPath = modelPath;
this.useCuda = usingCuda;
+ this.useVulkan = usingVulkan;
+ this._abortStartup = false;
// Check for FFmpeg first - only use --convert flag if FFmpeg is available
const ffmpegPath = this.getFFmpegPath();
@@ -465,6 +475,7 @@ class WhisperServerManager extends EventEmitter {
args,
cwd: serverBinaryDir,
cuda: usingCuda,
+ vulkan: usingVulkan,
threads: threadResolution,
});
@@ -508,8 +519,25 @@ class WhisperServerManager extends EventEmitter {
});
try {
- await this.waitForReady(() => ({ stderr: stderrBuffer, exitCode }));
+ await this.waitForReady(
+ () => ({ stderr: stderrBuffer, exitCode }),
+ usingVulkan ? VULKAN_STARTUP_TIMEOUT_MS : STARTUP_TIMEOUT_MS
+ );
} catch (err) {
+ // An intentional stop() during startup is not a GPU/thread failure
+ if (err.isStopped) throw err;
+ if (usingVulkan) {
+ // Fall back on ANY startup rejection — Vulkan can die late (VRAM OOM
+ // mid-model-load) or hang, not just exit early like the CUDA rule below
+ debugLogger.warn("Vulkan whisper-server failed, falling back to CPU", {
+ error: err.message,
+ exitCode,
+ stderr: stderrBuffer.slice(0, 200),
+ });
+ this.emit("gpu-fallback");
+ await this.stop();
+ return this._doStart(modelPath, { ...options, useCuda: false, useVulkan: false });
+ }
if (usingCuda && earlyExit) {
debugLogger.warn("CUDA whisper-server failed, falling back to CPU", {
exitCode,
@@ -545,13 +573,14 @@ class WhisperServerManager extends EventEmitter {
port: this.port,
model: path.basename(modelPath),
cuda: this.useCuda,
+ vulkan: this.useVulkan,
threads: threadResolution.threads || DEFAULT_WHISPER_THREADS,
threadSource: threadResolution.source,
availableParallelism: threadResolution.availableParallelism,
});
}
- async waitForReady(getProcessInfo) {
+ async waitForReady(getProcessInfo, timeoutMs = STARTUP_TIMEOUT_MS) {
const startTime = Date.now();
let pollCount = 0;
@@ -559,7 +588,12 @@ class WhisperServerManager extends EventEmitter {
// This saves 0-400ms average vs 500ms polling
const STARTUP_POLL_INTERVAL_MS = 100;
- while (Date.now() - startTime < STARTUP_TIMEOUT_MS) {
+ while (Date.now() - startTime < timeoutMs) {
+ if (this._abortStartup) {
+ throw Object.assign(new Error("whisper-server startup interrupted by stop"), {
+ isStopped: true,
+ });
+ }
if (!this.process || this.process.killed) {
const info = getProcessInfo ? getProcessInfo() : {};
const stderr = info.stderr ? info.stderr.trim().slice(0, 200) : "";
@@ -582,7 +616,7 @@ class WhisperServerManager extends EventEmitter {
await new Promise((resolve) => setTimeout(resolve, STARTUP_POLL_INTERVAL_MS));
}
- throw new Error(`whisper-server failed to start within ${STARTUP_TIMEOUT_MS}ms`);
+ throw new Error(`whisper-server failed to start within ${timeoutMs}ms`);
}
checkHealth() {
@@ -773,6 +807,7 @@ class WhisperServerManager extends EventEmitter {
}
async stop() {
+ this._abortStartup = true;
this.stopHealthCheck();
if (this.isRemote) {
diff --git a/src/helpers/whisperVulkanManager.js b/src/helpers/whisperVulkanManager.js
new file mode 100644
index 000000000..fa7bfc367
--- /dev/null
+++ b/src/helpers/whisperVulkanManager.js
@@ -0,0 +1,39 @@
+const GpuBinaryManager = require("./gpuBinaryManager");
+
+// Pinned so untested future binaries never auto-ship; bump together with the digests below
+const WHISPER_CPP_TAG = process.env.WHISPER_CPP_VERSION || "0.0.8";
+
+// sha256 per release tag; tags without an entry fall back to the API-reported digest
+const EXPECTED_DIGESTS = {
+ "0.0.8": {
+ "whisper-server-win32-x64-vulkan.zip":
+ "d5f6188bb6561e66a9b7886ca0448d5927cb9713a02d311b87a20e33eb038222",
+ "whisper-server-linux-x64-vulkan.zip":
+ "6e3e355dff3a1e96550d63445dc1ba4a881c2e63fe93be6a4f5ed946a204be27",
+ },
+};
+
+// Statically linked — no companion libs to copy, nothing to clobber in userData/bin
+class WhisperVulkanManager extends GpuBinaryManager {
+ constructor() {
+ super({
+ name: "Vulkan whisper",
+ releaseUrl: `https://api.github.com/repos/OpenWhispr/whisper.cpp/releases/tags/${WHISPER_CPP_TAG}`,
+ expectedDigests: EXPECTED_DIGESTS[WHISPER_CPP_TAG],
+ assets: {
+ "win32-x64": {
+ assetName: "whisper-server-win32-x64-vulkan.zip",
+ binaryName: "whisper-server-win32-x64-vulkan.exe",
+ outputName: "whisper-server-win32-x64-vulkan.exe",
+ },
+ "linux-x64": {
+ assetName: "whisper-server-linux-x64-vulkan.zip",
+ binaryName: "whisper-server-linux-x64-vulkan",
+ outputName: "whisper-server-linux-x64-vulkan",
+ },
+ },
+ });
+ }
+}
+
+module.exports = WhisperVulkanManager;
diff --git a/src/types/electron.ts b/src/types/electron.ts
index 5fc79d0fe..b8803c57c 100644
--- a/src/types/electron.ts
+++ b/src/types/electron.ts
@@ -246,10 +246,18 @@ export interface GpuInfo {
export interface CudaWhisperStatus {
downloaded: boolean;
+ downloading: boolean;
path: string | null;
gpuInfo: GpuInfo;
}
+export interface VulkanWhisperStatus {
+ downloaded: boolean;
+ downloading: boolean;
+ vulkan: VulkanGpuResult;
+ hasNvidiaGpu: boolean;
+}
+
export interface WhisperCheckResult {
installed: boolean;
working: boolean;
@@ -823,6 +831,20 @@ declare global {
) => () => void;
onCudaFallbackNotification: (callback: () => void) => () => void;
+ // Vulkan GPU acceleration (whisper on AMD/Intel GPUs)
+ getVulkanWhisperStatus: () => Promise<VulkanWhisperStatus>;
+ downloadVulkanWhisperBinary: () => Promise<{ success: boolean; error?: string }>;
+ cancelVulkanWhisperDownload: () => Promise<{ success: boolean }>;
+ deleteVulkanWhisperBinary: () => Promise<{ success: boolean; deletedCount?: number }>;
+ onVulkanWhisperDownloadProgress: (
+ callback: (data: {
+ downloadedBytes: number;
+ totalBytes: number;
+ percentage: number;
+ }) => void
+ ) => () => void;
+ onGpuFallbackNotification: (callback: () => void) => () => void;
+
// Parakeet operations (NVIDIA via sherpa-onnx)
transcribeLocalParakeet: (
audioBlob: ArrayBuffer,
diff --git a/test/helpers/gpuBinaryManager.test.js b/test/helpers/gpuBinaryManager.test.js
new file mode 100644
index 000000000..7475c4446
--- /dev/null
+++ b/test/helpers/gpuBinaryManager.test.js
@@ -0,0 +1,336 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+
+// Characterization tests for the shared GPU binary download pipeline and the
+// divergent cancel/delete semantics its wrappers preserve. Runs outside
+// Electron: electron and the download/extract layer are stubbed before loading.
+
+let userDataDir = null;
+let tempDir = null;
+
+require.cache[require.resolve("electron")] = {
+ exports: { app: { getPath: () => userDataDir } },
+};
+require.cache[require.resolve("../../src/helpers/safeTempDir.js")] = {
+ exports: { getSafeTempDir: () => tempDir },
+};
+
+// Pin to linux-x64 so asset-config resolution behaves identically on any host
+Object.defineProperty(process, "platform", { value: "linux" });
+Object.defineProperty(process, "arch", { value: "x64" });
+
+const state = {};
+
+function sha256(content) {
+ return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function walk(dir) {
+ const results = [];
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) results.push(...walk(full));
+ else results.push(full);
+ }
+ return results;
+}
+
+require.cache[require.resolve("../../src/helpers/downloadUtils.js")] = {
+ exports: {
+ fetchJson: async (url) => {
+ state.fetchedUrls.push(url);
+ return state.release;
+ },
+ downloadFile: async (url, dest, opts) => {
+ state.downloads.push({ url, dest, opts });
+ await state.downloadImpl(url, dest, opts);
+ return dest;
+ },
+ createDownloadSignal: () => {
+ const signal = { aborted: false, onAbort: null };
+ return {
+ signal,
+ abort() {
+ signal.aborted = true;
+ if (typeof signal.onAbort === "function") signal.onAbort();
+ },
+ };
+ },
+ checkDiskSpace: async () => state.diskSpace,
+ cleanupStaleDownloads: async () => {},
+ extractArchive: async (archivePath, destDir) => {
+ state.extractDirs.push(destDir);
+ await state.extractImpl(archivePath, destDir);
+ },
+ findFile: async (dir, name) => walk(dir).find((f) => path.basename(f) === name) || null,
+ findFiles: async (dir, pattern) => walk(dir).filter((f) => pattern.test(path.basename(f))),
+ },
+};
+
+const GpuBinaryManager = require("../../src/helpers/gpuBinaryManager.js");
+const WhisperCudaManager = require("../../src/helpers/whisperCudaManager.js");
+const LlamaVulkanManager = require("../../src/helpers/llamaVulkanManager.js");
+const WhisperVulkanManager = require("../../src/helpers/whisperVulkanManager.js");
+
+function makeRelease(assetName, overrides = {}) {
+ return {
+ tag_name: "test-tag",
+ assets: [
+ { name: "unrelated.txt", browser_download_url: "https://dl/unrelated", size: 1 },
+ {
+ name: assetName,
+ browser_download_url: `https://dl/${assetName}`,
+ size: 1000,
+ ...overrides,
+ },
+ ],
+ };
+}
+
+test.beforeEach(() => {
+ userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "gpuBinaryManager-user-"));
+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "gpuBinaryManager-tmp-"));
+ state.release = null;
+ state.fetchedUrls = [];
+ state.downloads = [];
+ state.extractDirs = [];
+ state.diskSpace = { ok: true, availableBytes: Infinity };
+ state.archiveContent = "archive-bytes";
+ state.downloadImpl = async (_url, dest) => fs.writeFileSync(dest, state.archiveContent);
+ state.extractedFiles = {};
+ state.extractImpl = async (_archivePath, destDir) => {
+ for (const [name, content] of Object.entries(state.extractedFiles)) {
+ fs.writeFileSync(path.join(destDir, name), content);
+ }
+ };
+});
+
+test.afterEach(() => {
+ fs.rmSync(userDataDir, { recursive: true, force: true });
+ fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+test("CUDA: resolves its exact asset from releases/latest and installs binary + companion libs", async () => {
+ state.release = makeRelease("whisper-server-linux-x64-cuda.zip");
+ state.extractedFiles = {
+ "whisper-server-linux-x64-cuda": "binary",
+ "libggml-cuda.so": "lib",
+ "README.md": "doc",
+ };
+
+ const manager = new WhisperCudaManager();
+ await manager.download();
+
+ assert.match(state.fetchedUrls[0], /OpenWhispr\/whisper\.cpp\/releases\/latest$/);
+ assert.equal(state.downloads[0].url, "https://dl/whisper-server-linux-x64-cuda.zip");
+
+ const binDir = path.join(userDataDir, "bin");
+ const binaryPath = path.join(binDir, "whisper-server-linux-x64-cuda");
+ assert.ok(fs.existsSync(binaryPath));
+ assert.ok(fs.statSync(binaryPath).mode & 0o100, "binary is executable");
+ assert.ok(fs.existsSync(path.join(binDir, "libggml-cuda.so")), "companion lib copied");
+ assert.ok(!fs.existsSync(path.join(binDir, "README.md")), "unrelated files not copied");
+ assert.equal(manager.getCudaBinaryPath(), binaryPath);
+ assert.equal(manager.isDownloaded(), true);
+});
+
+test("llama Vulkan: resolves asset by regex from the pinned tag", async () => {
+ state.release = makeRelease("llama-b9763-bin-ubuntu-vulkan-x64.tar.gz");
+ state.extractedFiles = { "llama-server": "binary", "libvulkan.so.1": "lib" };
+
+ const manager = new LlamaVulkanManager();
+ const result = await manager.download();
+
+ assert.deepEqual(result, { success: true });
+ assert.match(state.fetchedUrls[0], /ggml-org\/llama\.cpp\/releases\/tags\/b9763$/);
+ assert.ok(fs.existsSync(path.join(userDataDir, "bin", "llama-server-vulkan")), "renamed output");
+ assert.ok(fs.existsSync(path.join(userDataDir, "bin", "libvulkan.so.1")));
+});
+
+test("whisper Vulkan: pinned asset, no companion libs, rejects a digest mismatch (fail closed)", async () => {
+ state.release = makeRelease("whisper-server-linux-x64-vulkan.zip");
+ state.extractedFiles = { "whisper-server-linux-x64-vulkan": "binary" };
+
+ const manager = new WhisperVulkanManager();
+ await assert.rejects(() => manager.download(), { message: /integrity check/ });
+
+ assert.equal(manager.isDownloaded(), false);
+ assert.equal(state.extractDirs.length, 0, "mismatched archive is never extracted");
+ const archivePath = path.join(tempDir, "whisper-server-linux-x64-vulkan.zip");
+ assert.ok(!fs.existsSync(archivePath), "archive cleaned up after failure");
+});
+
+test("digest: pinned match installs; API-reported digest is the fallback and also fails closed", async () => {
+ const config = (expectedDigests) => ({
+ name: "test",
+ releaseUrl: "https://api.github.com/repos/x/y/releases/latest",
+ expectedDigests,
+ assets: {
+ "linux-x64": { assetName: "bin.zip", binaryName: "server", outputName: "server-out" },
+ },
+ });
+ state.extractedFiles = { server: "binary" };
+ const goodDigest = sha256(state.archiveContent);
+
+ state.release = makeRelease("bin.zip");
+ await new GpuBinaryManager(config({ "bin.zip": goodDigest })).download();
+ assert.ok(fs.existsSync(path.join(userDataDir, "bin", "server-out")));
+
+ state.release = makeRelease("bin.zip", { digest: `sha256:${goodDigest}` });
+ await new GpuBinaryManager(config(undefined)).download();
+
+ state.release = makeRelease("bin.zip", { digest: `sha256:${"0".repeat(64)}` });
+ await assert.rejects(() => new GpuBinaryManager(config(undefined)).download(), {
+ message: /integrity check/,
+ });
+});
+
+test("progress: raw (downloaded, total) callback passes straight through", async () => {
+ state.release = makeRelease("llama-b9763-bin-ubuntu-vulkan-x64.tar.gz");
+ state.extractedFiles = { "llama-server": "binary" };
+ state.downloadImpl = async (_url, dest, opts) => {
+ opts.onProgress(50, 100);
+ opts.onProgress(100, 100);
+ fs.writeFileSync(dest, state.archiveContent);
+ };
+
+ const calls = [];
+ await new LlamaVulkanManager().download((downloaded, total) => calls.push([downloaded, total]));
+ assert.deepEqual(calls, [
+ [50, 100],
+ [100, 100],
+ ]);
+});
+
+test("cancel semantics: CUDA throws, llama returns { cancelled: true }", async () => {
+ const abortError = () => Object.assign(new Error("Download cancelled"), { isAbort: true });
+ state.release = makeRelease("whisper-server-linux-x64-cuda.zip");
+ state.downloadImpl = async () => {
+ throw abortError();
+ };
+ await assert.rejects(() => new WhisperCudaManager().download(), {
+ message: "Download cancelled by user",
+ });
+
+ state.release = makeRelease("llama-b9763-bin-ubuntu-vulkan-x64.tar.gz");
+ const result = await new LlamaVulkanManager().download();
+ assert.deepEqual(result, { success: false, cancelled: true });
+});
+
+test("cancelDownload aborts only when a download is active", async () => {
+ const manager = new WhisperCudaManager();
+ assert.deepEqual(await manager.cancelDownload(), {
+ success: false,
+ error: "No active download to cancel",
+ });
+
+ state.release = makeRelease("whisper-server-linux-x64-cuda.zip");
+ let abortedSignal = null;
+ let releaseDownload;
+ const gate = new Promise((resolve) => (releaseDownload = resolve));
+ state.downloadImpl = async (_url, dest, opts) => {
+ abortedSignal = opts.signal;
+ await gate;
+ if (opts.signal.aborted) {
+ throw Object.assign(new Error("Download cancelled"), { isAbort: true });
+ }
+ fs.writeFileSync(dest, state.archiveContent);
+ };
+
+ const downloadPromise = manager.download();
+ while (!abortedSignal) await new Promise((resolve) => setImmediate(resolve));
+ assert.deepEqual(await manager.cancelDownload(), {
+ success: true,
+ message: "Download cancelled",
+ });
+ assert.equal(abortedSignal.aborted, true);
+ releaseDownload();
+ await assert.rejects(() => downloadPromise, { message: "Download cancelled by user" });
+});
+
+test("guard: a second download while one is in flight throws", async () => {
+ state.release = makeRelease("whisper-server-linux-x64-cuda.zip");
+ let releaseDownload;
+ const gate = new Promise((resolve) => (releaseDownload = resolve));
+ state.downloadImpl = async (_url, dest) => {
+ await gate;
+ fs.writeFileSync(dest, state.archiveContent);
+ };
+ state.extractedFiles = { "whisper-server-linux-x64-cuda": "binary" };
+
+ const manager = new WhisperCudaManager();
+ const first = manager.download();
+ await assert.rejects(() => manager.download(), { message: "Download already in progress" });
+ releaseDownload();
+ await first;
+});
+
+test("cleanup on failure: archive and extract dir removed, next download can start", async () => {
+ state.release = makeRelease("whisper-server-linux-x64-cuda.zip");
+ state.extractImpl = async () => {
+ throw new Error("Extraction failed: corrupt");
+ };
+
+ const manager = new WhisperCudaManager();
+ await assert.rejects(() => manager.download(), { message: /Extraction failed/ });
+
+ assert.equal(fs.readdirSync(tempDir).length, 0, "temp artifacts removed");
+ assert.equal(manager.isDownloading(), false);
+
+ state.extractImpl = async (_archivePath, destDir) => {
+ fs.writeFileSync(path.join(destDir, "whisper-server-linux-x64-cuda"), "binary");
+ };
+ await manager.download();
+ assert.equal(manager.isDownloaded(), true);
+});
+
+test("disk space: failure surfaces the friendly error with the 2.5x requirement", async () => {
+ state.release = makeRelease("whisper-server-linux-x64-cuda.zip", { size: 100_000_000 });
+ state.diskSpace = { ok: false, availableBytes: 5_000_000 };
+
+ await assert.rejects(() => new WhisperCudaManager().download(), {
+ message: "Not enough disk space. Need ~250MB, only 5MB available.",
+ });
+});
+
+test("delete: removes binary + matching libs only; whisper Vulkan leaves shared DLL-space alone", async () => {
+ const binDir = path.join(userDataDir, "bin");
+ fs.mkdirSync(binDir, { recursive: true });
+ const seed = (name) => fs.writeFileSync(path.join(binDir, name), "x");
+ seed("whisper-server-linux-x64-cuda");
+ seed("libggml-cuda.so");
+ seed("llama-server-vulkan");
+ seed("whisper-server-linux-x64-vulkan");
+
+ const cudaResult = await new WhisperCudaManager().delete();
+ assert.equal(cudaResult.success, true);
+ assert.equal(cudaResult.deleted_count, 2);
+ assert.ok(!fs.existsSync(path.join(binDir, "whisper-server-linux-x64-cuda")));
+ assert.ok(!fs.existsSync(path.join(binDir, "libggml-cuda.so")));
+ assert.ok(fs.existsSync(path.join(binDir, "llama-server-vulkan")), "other backends untouched");
+
+ const vulkanResult = await new WhisperVulkanManager().delete();
+ assert.equal(vulkanResult.deletedCount, 1);
+ assert.ok(!fs.existsSync(path.join(binDir, "whisper-server-linux-x64-vulkan")));
+
+ const llamaResult = await new LlamaVulkanManager().deleteBinary();
+ assert.deepEqual(llamaResult, { success: true, deletedCount: 1 });
+});
+
+test("getStatus reflects supported/downloaded/downloading", async () => {
+ const manager = new WhisperVulkanManager();
+ assert.deepEqual(manager.getStatus(), {
+ supported: true,
+ downloaded: false,
+ downloading: false,
+ });
+
+ const binDir = path.join(userDataDir, "bin");
+ fs.mkdirSync(binDir, { recursive: true });
+ fs.writeFileSync(path.join(binDir, "whisper-server-linux-x64-vulkan"), "x");
+ assert.equal(manager.getStatus().downloaded, true);
+});
diff --git a/test/helpers/whisperWakeRewarm.test.js b/test/helpers/whisperWakeRewarm.test.js
index 8a5cb7587..b4de2fb13 100644
--- a/test/helpers/whisperWakeRewarm.test.js
+++ b/test/helpers/whisperWakeRewarm.test.js
@@ -15,6 +15,10 @@ test("re-warms a running local CUDA whisper-server after wake", () => {
assert.equal(shouldRewarmOnWake(base), true);
});
+test("re-warms a running local Vulkan whisper-server after wake", () => {
+ assert.equal(shouldRewarmOnWake({ ...base, useCuda: false, useVulkan: true }), true);
+});
+
test("skips CPU whisper-server (model survives sleep in RAM)", () => {
assert.equal(shouldRewarmOnWake({ ...base, useCuda: false }), false);
});