Skip to content

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

36.2 KB
Raw Blame
const fs = require("fs");
const fsPromises = require("fs").promises;
const path = require("path");
const debugLogger = require("./debugLogger");
const { warnGpuFallback } = require("./gpuFallbackLog");
const {
  downloadFile,
  createDownloadSignal,
  createDownloadInProgressError,
  validateFileSize,
  cleanupStaleDownloads,
  checkDiskSpace,
} = require("./downloadUtils");
const WhisperServerManager = require("./whisperServer");
const { createAbortError } = require("./abortError");
const {
  getCacheRoot,
  getModelsDirForService,
  pathHasProblematicChars,
} = require("./modelDirUtils");

const modelRegistryData = require("../models/modelRegistryData.json");

const CACHE_TTL_MS = 30000;

function getWhisperModelConfig(modelName) {
  const modelInfo = modelRegistryData.whisperModels[modelName];
  if (!modelInfo) return null;
  return {
    url: modelInfo.downloadUrl,
    size: modelInfo.expectedSizeBytes || modelInfo.sizeMb * 1_000_000,
    fileName: modelInfo.fileName,
  };
}

function getValidModelNames() {
  return Object.keys(modelRegistryData.whisperModels);
}

// whisper-server reads its arguments in the Windows ANSI code page and crashes
// on a non-ASCII --vad-model path, as on the model paths #1514 moved (#1208).
// An install under such a folder bundles the VAD model there, so it is copied
// into the ASCII-safe cache root. The copy follows pathHasProblematicChars, the
// rule #1514 uses for the cache root, so a path with spaces is copied too. That
// root can be the shared ProgramData folder, so an existing copy is reused only
// when its bytes match, and a new one is renamed into place: a write cut short
// there would leave a file other accounts can neither use nor replace.
function asciiSafeVadModelPath(bundledPath) {
  if (process.platform !== "win32" || !pathHasProblematicChars(bundledPath)) return bundledPath;

  const copyPath = path.join(getCacheRoot(), "whisper-vad", path.basename(bundledPath));
  const tempPath = `${copyPath}.${process.pid}.tmp`;
  try {
    const model = fs.readFileSync(bundledPath);
    if (!fs.existsSync(copyPath) || !fs.readFileSync(copyPath).equals(model)) {
      fs.mkdirSync(path.dirname(copyPath), { recursive: true });
      fs.writeFileSync(tempPath, model);
      fs.renameSync(tempPath, copyPath);
    }
    return copyPath;
  } catch (error) {
    try {
      fs.rmSync(tempPath, { force: true });
    } catch {}
    debugLogger.warn("Could not copy the VAD model to an ASCII-safe path", {
      error: error.message,
    });
    // Spaces alone don't crash whisper-server, so such a path keeps VAD working.
    return /^[\x20-\x7E]*$/.test(bundledPath) ? bundledPath : null;
  }
}

// WHISPER_GPU_FAILED holds a comma-separated list of backends that fell back
// to CPU on this machine (e.g. "cuda" or "cuda,vulkan")
function resolveFailedGpuBackends(value) {
  return String(value || "")
    .split(",")
    .map((entry) => entry.trim())
    .filter(Boolean);
}

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 || useVulkan) && !!modelName && !transcribing && !rewarmInFlight;
}

class WhisperManager {
  constructor() {
    this.cachedFFmpegPath = null;
    this.currentDownloadProcess = null;
    this.ffmpegAvailabilityCache = { result: null, expiresAt: 0 };
    this.isInitialized = false;
    // Server manager for HTTP-based transcription
    this.serverManager = new WhisperServerManager();
    this.currentServerModel = null;
    this.cachedVadModelPath = undefined;
    this._transcribing = false;
    this._rewarmInFlight = false;
    this._cudaBinaryManager = null;
    this._vulkanBinaryManager = null;
  }

  setGpuBinaryManagers({ cuda, vulkan }) {
    this._cudaBinaryManager = cuda || null;
    this._vulkanBinaryManager = vulkan || null;
  }

  // The GPU backend for every server start is resolved fresh from the current
  // env + installed packs, so enabling or removing a pack applies immediately
  // instead of after an app restart. A pack on disk implies intent: the user
  // downloaded it, so it engages unless WHISPER_*_ENABLED is explicitly set to
  // "false" (case-insensitive; an opt-out that survives without deleting the
  // pack). Requiring the flag to be present stranded downloaded packs on
  // silent CPU whenever the .env line was lost (#1340). WHISPER_GPU_FAILED
  // lists backends that crashed on this machine (persisted by ipcHandlers
  // when the server falls back to CPU); they stay off until the user retries
  // or re-downloads, so a doomed backend isn't re-attempted — and its model
  // reload re-paid — on every launch.
  resolveGpuStartOptions() {
    const failed = resolveFailedGpuBackends(process.env.WHISPER_GPU_FAILED);
    const useCuda =
      (process.env.WHISPER_CUDA_ENABLED || "").toLowerCase() !== "false" &&
      !failed.includes("cuda") &&
      !!this._cudaBinaryManager?.isDownloaded();
    const vulkanAvailable =
      (process.env.WHISPER_VULKAN_ENABLED || "").toLowerCase() !== "false" &&
      !failed.includes("vulkan") &&
      !!this._vulkanBinaryManager?.isDownloaded();
    // Always set fallbackToVulkan: callers merge this over the last start's
    // options, so an omitted false would keep a stale true
    return {
      useCuda,
      useVulkan: !useCuda && vulkanAvailable,
      fallbackToVulkan: useCuda && vulkanAvailable,
    };
  }

  // Why a backend the user wants can't be used, or null when it isn't wanted.
  // Like resolveGpuStartOptions, an unset flag still wants a pack on disk.
  _gpuFallbackReason(envVar, manager, backend) {
    const flag = (process.env[envVar] || "").toLowerCase();
    if (flag === "false") return null;
    const needsUpdate = !!manager?.needsUpdate?.();
    const downloaded = !!manager?.isDownloaded?.();
    if (flag !== "true" && !needsUpdate && !downloaded) return null;
    if (needsUpdate) return "pack needs update";
    if (!downloaded) return "pack not installed or missing required libraries";
    // A wanted, downloaded pack is skipped only after it failed on this machine.
    return resolveFailedGpuBackends(process.env.WHISPER_GPU_FAILED).includes(backend)
      ? "previous failure recorded"
      : null;
  }

  _warnIfGpuFallback() {
    const { useCuda, useVulkan } = this.resolveGpuStartOptions();
    if (useCuda) return;
    const runningOn = useVulkan ? "Vulkan" : "CPU";
    const cudaReason = this._gpuFallbackReason(
      "WHISPER_CUDA_ENABLED",
      this._cudaBinaryManager,
      "cuda"
    );
    const vulkanReason = this._gpuFallbackReason(
      "WHISPER_VULKAN_ENABLED",
      this._vulkanBinaryManager,
      "vulkan"
    );
    const [label, pack, reason] = cudaReason
      ? ["CUDA", "CUDA whisper", cudaReason]
      : ["Vulkan", "Vulkan whisper", vulkanReason];
    if (!reason) return;

    const key = `${pack}:${reason}:${runningOn}`;
    if (this._lastGpuFallbackWarning === key) return;
    this._lastGpuFallbackWarning = key;
    warnGpuFallback(`Whisper ${label} enabled but cannot be used, falling back to ${runningOn}`, {
      pack,
      reason,
    });
  }

  // The pack the settings card describes, so the card never disagrees with the
  // server (#1736): the pack every server start picks now (a GPU server always
  // runs on it; while a pack change restarts the server, it names the target),
  // else the installed pack that fell back to CPU, CUDA first, so its reason
  // and Retry show. null when neither applies (no pack, or a pack opted out
  // with WHISPER_*_ENABLED=false that never failed): the card then chooses
  // which pack to offer.
  resolveGpuPackInUse() {
    const { useCuda, useVulkan } = this.resolveGpuStartOptions();
    if (useCuda) return "cuda";
    if (useVulkan) return "vulkan";
    const failed = resolveFailedGpuBackends(process.env.WHISPER_GPU_FAILED);
    if (failed.includes("cuda") && this._cudaBinaryManager?.isDownloaded()) return "cuda";
    if (failed.includes("vulkan") && this._vulkanBinaryManager?.isDownloaded()) return "vulkan";
    return null;
  }

  // Re-resolve GPU options and reload the server in place. Used after a GPU
  // pack download, delete, or failure-retry so the change takes effect without
  // an app restart. Callers that had to stop the server before touching pack
  // files pass the model they captured first; no-op when none was loaded.
  async restartServerWithGpuPreference(modelName = this.currentServerModel) {
    if (!modelName || this.serverManager.isRemote) return { success: true, restarted: false };

    const options = { ...this.serverManager.lastStartOptions, ...this.resolveGpuStartOptions() };
    await this.stopServer();
    const result = await this.startServer(modelName, options);
    return { ...result, restarted: true };
  }

  getModelsDir() {
    return getModelsDirForService("whisper");
  }

  validateModelName(modelName) {
    // Only allow known model names to prevent path traversal attacks
    const validModels = getValidModelNames();
    if (!validModels.includes(modelName)) {
      throw new Error(`Invalid model name: ${modelName}. Valid models: ${validModels.join(", ")}`);
    }
    return true;
  }

  getModelPath(modelName) {
    this.validateModelName(modelName);
    const config = getWhisperModelConfig(modelName);
    return path.join(this.getModelsDir(), config.fileName);
  }

  isModelDownloaded(modelName) {
    return fs.existsSync(this.getModelPath(modelName));
  }

  getVadModelPath() {
    if (this.cachedVadModelPath !== undefined) return this.cachedVadModelPath;

    const fileName = "ggml-silero-v5.1.2.bin";
    const candidates = [];

    if (process.resourcesPath) {
      candidates.push(path.join(process.resourcesPath, "bin", "whisper-vad", fileName));
    }
    candidates.push(path.join(__dirname, "..", "..", "resources", "bin", "whisper-vad", fileName));

    const resolved = candidates.find((p) => fs.existsSync(p)) || null;
    const vadModelPath = resolved && asciiSafeVadModelPath(resolved);
    // A failed copy is retried on the next request rather than kept for the session.
    if (vadModelPath || !resolved) this.cachedVadModelPath = vadModelPath;
    return vadModelPath;
  }

  async initializeAtStartup(settings = {}) {
    const startTime = Date.now();

    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;
      const gpuOptions = this.resolveGpuStartOptions();
      const { useCuda, useVulkan } = gpuOptions;

      if (
        localTranscriptionProvider === "whisper" &&
        whisperModel &&
        this.serverManager.isAvailable()
      ) {
        const modelPath = this.getModelPath(whisperModel);

        if (fs.existsSync(modelPath)) {
          this._warnIfGpuFallback();
          debugLogger.info("Pre-warming whisper-server", {
            model: whisperModel,
            modelPath,
            cuda: useCuda,
            vulkan: useVulkan,
          });

          try {
            const serverStartTime = Date.now();
            await this.serverManager.start(modelPath, gpuOptions);
            this.currentServerModel = whisperModel;

            debugLogger.info("whisper-server pre-warmed successfully", {
              model: whisperModel,
              startupTimeMs: Date.now() - serverStartTime,
              port: this.serverManager.port,
            });
          } catch (err) {
            debugLogger.warn("Server pre-warm failed (will start on first use)", {
              error: err.message,
              model: whisperModel,
            });
            // Non-fatal: server will start on first transcription
          }
        } else {
          debugLogger.debug("Skipping server pre-warm: model not downloaded", {
            model: whisperModel,
            modelPath,
          });
        }
      } else {
        debugLogger.debug("Skipping server pre-warm", {
          reason:
            localTranscriptionProvider !== "whisper"
              ? "provider not whisper"
              : !whisperModel
                ? "no model selected"
                : "server binary not available",
        });
      }
    } catch (error) {
      debugLogger.warn("Whisper initialization error", {
        error: error.message,
      });
      this.isInitialized = true; // Mark initialized even on error
    }

    debugLogger.info("Whisper initialization complete", {
      totalTimeMs: Date.now() - startTime,
      serverRunning: this.serverManager.ready,
    });

    // Log dependency status for debugging
    await this.logDependencyStatus();
  }

  async logDependencyStatus() {
    const status = {
      whisperServer: {
        available: this.serverManager.isAvailable(),
        path: this.serverManager.getServerBinaryPath(),
      },
      ffmpeg: {
        available: false,
        path: null,
      },
      models: [],
    };

    // Check FFmpeg
    try {
      const ffmpegPath = await this.getFFmpegPath();
      status.ffmpeg.available = !!ffmpegPath;
      status.ffmpeg.path = ffmpegPath;
    } catch {
      // FFmpeg not available
    }

    // Check downloaded models
    for (const modelName of getValidModelNames()) {
      const modelPath = this.getModelPath(modelName);
      if (fs.existsSync(modelPath)) {
        try {
          const stats = fs.statSync(modelPath);
          status.models.push({
            name: modelName,
            size: `${Math.round(stats.size / (1024 * 1024))}MB`,
          });
        } catch {
          // Skip if can't stat
        }
      }
    }

    debugLogger.info("OpenWhispr dependency check", status);

    // Log a summary for easy scanning
    const serverStatus = status.whisperServer.available
      ? `✓ ${status.whisperServer.path}`
      : "✗ Not found";
    const ffmpegStatus = status.ffmpeg.available ? `✓ ${status.ffmpeg.path}` : "✗ Not found";
    const modelsStatus =
      status.models.length > 0
        ? status.models.map((m) => `${m.name} (${m.size})`).join(", ")
        : "None downloaded";

    debugLogger.info(`[Dependencies] whisper-server: ${serverStatus}`);
    debugLogger.info(`[Dependencies] FFmpeg: ${ffmpegStatus}`);
    debugLogger.info(`[Dependencies] Models: ${modelsStatus}`);
  }

  async startServer(modelName, options = {}) {
    if (!this.serverManager.isAvailable()) {
      return { success: false, reason: "whisper-server binary not found" };
    }

    const modelPath = this.getModelPath(modelName);
    if (!fs.existsSync(modelPath)) {
      return { success: false, reason: `Model "${modelName}" not downloaded` };
    }

    try {
      await this.serverManager.start(modelPath, options);
      this.currentServerModel = modelName;
      debugLogger.info("whisper-server started", {
        model: modelName,
        port: this.serverManager.port,
      });
      return { success: true, port: this.serverManager.port };
    } catch (error) {
      debugLogger.error("Failed to start whisper-server", { error: error.message });
      return { success: false, reason: error.message };
    }
  }

  async stopServer() {
    await this.serverManager.stop();
    this.currentServerModel = null;
  }

  async onWakeFromSleep() {
    const sm = this.serverManager;
    const modelName = this.currentServerModel;
    if (
      !shouldRewarmOnWake({
        isRemote: sm.isRemote,
        useCuda: sm.useCuda,
        useVulkan: sm.useVulkan,
        modelName,
        transcribing: this._transcribing,
        rewarmInFlight: this._rewarmInFlight,
      })
    ) {
      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. GPU flags are re-resolved so a backend
    // that failed since is not re-attempted.
    const options = { ...sm.lastStartOptions, ...this.resolveGpuStartOptions() };
    this._rewarmInFlight = true;
    try {
      debugLogger.info("Re-warming whisper-server after wake from sleep", { model: modelName });
      await this.stopServer();
      const result = await this.startServer(modelName, options);
      if (!result?.success) {
        debugLogger.warn("whisper-server wake re-warm failed", { reason: result?.reason });
        return false;
      }
      return true;
    } finally {
      this._rewarmInFlight = false;
    }
  }

  getServerStatus() {
    return this.serverManager.getStatus();
  }

  async checkWhisperInstallation() {
    const serverPath = this.serverManager.getServerBinaryPath();
    if (!serverPath) {
      return { installed: false, working: false };
    }

    return {
      installed: true,
      working: this.serverManager.isAvailable(),
      path: serverPath,
    };
  }

  async transcribeLocalWhisper(audioBlob, options = {}) {
    debugLogger.logWhisperPipeline("transcribeLocalWhisper - start", {
      options,
      audioBlobType: audioBlob?.constructor?.name,
      audioBlobSize: audioBlob?.byteLength || audioBlob?.size || 0,
      serverAvailable: this.serverManager.isAvailable(),
      serverReady: this.serverManager.ready,
    });

    // Server mode required
    if (!this.serverManager.isAvailable()) {
      throw new Error(
        "whisper-server binary not found. Please ensure the app is installed correctly."
      );
    }

    const model = options.model || "base";
    const language = options.language || null;
    const initialPrompt = options.initialPrompt || null;
    const vadEnabled = options.vadEnabled === true;
    const vadConfig = options.vadConfig || null;
    const modelPath = this.getModelPath(model);

    if (!fs.existsSync(modelPath)) {
      throw new Error(`Whisper model "${model}" not downloaded. Please download it from Settings.`);
    }

    return await this.transcribeViaServer(audioBlob, model, language, initialPrompt, {
      vadEnabled,
      vadConfig,
      signal: options.signal,
      skipDecoderThresholds: options.skipDecoderThresholds === true,
    });
  }

  async transcribeViaServer(audioBlob, model, language, initialPrompt = null, options = {}) {
    // Mark the server busy so a wake re-warm doesn't kill an in-flight dictation. See #766.
    this._transcribing = true;
    try {
      return await this._runServerTranscription(audioBlob, model, language, initialPrompt, options);
    } finally {
      this._transcribing = false;
    }
  }

  async _runServerTranscription(audioBlob, model, language, initialPrompt = null, options = {}) {
    // An already-cancelled upload skips the server boot entirely.
    if (options.signal?.aborted) {
      throw createAbortError("whisper-server transcription cancelled");
    }

    debugLogger.info("Transcription mode: SERVER", { model, language: language || "auto" });
    const modelPath = this.getModelPath(model);

    const vadEnabled = options.vadEnabled === true;
    const vadModelPath = vadEnabled ? this.getVadModelPath() : null;
    if (vadEnabled && !vadModelPath) {
      debugLogger.warn("VAD requested but ggml-silero model unavailable; running without VAD");
    }

    this._warnIfGpuFallback();
    await this.serverManager.start(modelPath, {
      ...this.resolveGpuStartOptions(),
      vadEnabled,
      vadModelPath,
      vadConfig: options.vadConfig || null,
    });
    this.currentServerModel = model;

    // Convert audioBlob to Buffer if needed
    let audioBuffer;
    if (Buffer.isBuffer(audioBlob)) {
      audioBuffer = audioBlob;
    } else if (ArrayBuffer.isView(audioBlob)) {
      audioBuffer = Buffer.from(audioBlob.buffer, audioBlob.byteOffset, audioBlob.byteLength);
    } else if (audioBlob instanceof ArrayBuffer) {
      audioBuffer = Buffer.from(audioBlob);
    } else if (typeof audioBlob === "string") {
      audioBuffer = Buffer.from(audioBlob, "base64");
    } else if (audioBlob && audioBlob.buffer && typeof audioBlob.byteLength === "number") {
      audioBuffer = Buffer.from(audioBlob.buffer, audioBlob.byteOffset || 0, audioBlob.byteLength);
    } else {
      throw new Error(`Unsupported audio data type: ${typeof audioBlob}`);
    }

    if (!audioBuffer || audioBuffer.length === 0) {
      throw new Error("Audio buffer is empty - no audio data received");
    }

    debugLogger.logWhisperPipeline("transcribeViaServer - sending to server", {
      bufferSize: audioBuffer.length,
      model,
      language,
      port: this.serverManager.port,
    });

    const startTime = Date.now();
    const result = await this.serverManager.transcribe(audioBuffer, {
      language,
      initialPrompt,
      signal: options.signal,
      skipDecoderThresholds: options.skipDecoderThresholds,
    });
    const elapsed = Date.now() - startTime;

    debugLogger.logWhisperPipeline("transcribeViaServer - completed", {
      elapsed,
      resultKeys: Object.keys(result),
    });

    return this.parseWhisperResult(result);
  }

  async transcribeViaLan(audioBlob, url, options = {}) {
    debugLogger.info("Transcription mode: LAN", { url, language: options.language || "auto" });

    await this.serverManager.connectRemote(url);

    let audioBuffer;
    if (Buffer.isBuffer(audioBlob)) {
      audioBuffer = audioBlob;
    } else if (ArrayBuffer.isView(audioBlob)) {
      audioBuffer = Buffer.from(audioBlob.buffer, audioBlob.byteOffset, audioBlob.byteLength);
    } else if (audioBlob instanceof ArrayBuffer) {
      audioBuffer = Buffer.from(audioBlob);
    } else if (typeof audioBlob === "string") {
      audioBuffer = Buffer.from(audioBlob, "base64");
    } else if (audioBlob && audioBlob.buffer && typeof audioBlob.byteLength === "number") {
      audioBuffer = Buffer.from(audioBlob.buffer, audioBlob.byteOffset || 0, audioBlob.byteLength);
    } else {
      throw new Error(`Unsupported audio data type: ${typeof audioBlob}`);
    }

    if (!audioBuffer || audioBuffer.length === 0) {
      throw new Error("Audio buffer is empty - no audio data received");
    }

    debugLogger.logWhisperPipeline("transcribeViaLan - sending to server", {
      bufferSize: audioBuffer.length,
      url,
      language: options.language,
    });

    const startTime = Date.now();
    const result = await this.serverManager.transcribe(audioBuffer, {
      language: options.language || null,
      initialPrompt: options.initialPrompt || null,
    });
    const elapsed = Date.now() - startTime;

    debugLogger.logWhisperPipeline("transcribeViaLan - completed", {
      elapsed,
      resultKeys: Object.keys(result),
    });

    return this.parseWhisperResult(result);
  }

  // Normalize whitespace: replace newlines with spaces and collapse multiple spaces
  // whisper.cpp returns text with \n between audio segments which causes formatting issues
  normalizeWhitespace(text) {
    return text.replace(/\n/g, " ").replace(/\s+/g, " ").trim();
  }

  parseWhisperResult(output) {
    // Handle both string (from CLI) and object (from server) inputs
    let result;
    if (typeof output === "string") {
      debugLogger.logWhisperPipeline("Parsing result (string)", { length: output.length });
      try {
        result = JSON.parse(output);
      } catch (parseError) {
        // Try parsing as plain text (non-JSON output)
        const text = this.normalizeWhitespace(output);
        if (text && !this.isBlankAudioMarker(text)) {
          return { success: true, text };
        }
        throw new Error(`Failed to parse Whisper output: ${parseError.message}`);
      }
    } else if (typeof output === "object" && output !== null) {
      debugLogger.logWhisperPipeline("Parsing result (object)", { keys: Object.keys(output) });
      result = output;
    } else {
      throw new Error(`Unexpected Whisper output type: ${typeof output}`);
    }

    // Handle whisper.cpp JSON format (CLI mode)
    if (result.transcription && Array.isArray(result.transcription)) {
      const text = this.normalizeWhitespace(result.transcription.map((seg) => seg.text).join(""));
      if (!text || this.isBlankAudioMarker(text)) {
        return { success: false, message: "No audio detected" };
      }
      return { success: true, text };
    }

    // Handle whisper-server format (has "text" field directly)
    if (result.text !== undefined) {
      const text = typeof result.text === "string" ? this.normalizeWhitespace(result.text) : "";
      if (!text || this.isBlankAudioMarker(text)) {
        return { success: false, message: "No audio detected" };
      }
      return { success: true, text };
    }

    // A response with neither shape is a broken backend, not silence. Reporting it
    // as "No audio detected" sends users chasing their microphone when the engine
    // is at fault, so surface it as the transcription failure it is.
    const serverError = typeof result.error === "string" && result.error.trim();
    return {
      success: false,
      error: "invalid_response",
      message: serverError
        ? `Transcription engine error: ${serverError}`
        : "Transcription engine returned an unexpected response",
    };
  }

  // Check if text is a whisper.cpp blank audio marker
  isBlankAudioMarker(text) {
    // whisper.cpp outputs "[BLANK_AUDIO]" when there's silence or insufficient audio
    const normalized = text.trim().toLowerCase();
    return normalized === "[blank_audio]" || normalized === "[ blank_audio ]";
  }

  async downloadWhisperModel(modelName, progressCallback = null) {
    this.validateModelName(modelName);
    const modelConfig = getWhisperModelConfig(modelName);

    const modelPath = this.getModelPath(modelName);
    const modelsDir = this.getModelsDir();

    if (fs.existsSync(modelPath)) {
      const stats = await fsPromises.stat(modelPath);
      return {
        model: modelName,
        downloaded: true,
        path: modelPath,
        size_bytes: stats.size,
        size_mb: Math.round(stats.size / (1024 * 1024)),
        success: true,
      };
    }

    if (this.currentDownloadProcess) {
      throw createDownloadInProgressError(modelName, this.currentDownloadProcess.model);
    }

    const { signal, abort } = createDownloadSignal();
    const downloadProcess = {
      abort,
      model: modelName,
      phase: "progress",
      percentage: 0,
      downloadedBytes: 0,
      totalBytes: 0,
    };
    this.currentDownloadProcess = downloadProcess;

    try {
      await fsPromises.mkdir(modelsDir, { recursive: true });

      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.`
        );
      }

      await downloadFile(modelConfig.url, modelPath, {
        timeout: 600000,
        signal,
        expectedSize: modelConfig.size,
        onProgress: (downloadedBytes, totalBytes) => {
          downloadProcess.percentage =
            totalBytes > 0 ? Math.round((downloadedBytes / totalBytes) * 100) : 0;
          downloadProcess.downloadedBytes = downloadedBytes;
          downloadProcess.totalBytes = totalBytes;
          if (progressCallback) {
            progressCallback({
              type: "progress",
              model: modelName,
              downloaded_bytes: downloadedBytes,
              total_bytes: totalBytes,
              percentage: totalBytes > 0 ? Math.round((downloadedBytes / totalBytes) * 100) : 0,
            });
          }
        },
      });

      await validateFileSize(modelPath, modelConfig.size);

      const stats = await fsPromises.stat(modelPath);

      if (progressCallback) {
        progressCallback({ type: "complete", model: modelName, percentage: 100 });
      }

      return {
        model: modelName,
        downloaded: true,
        path: modelPath,
        size_bytes: stats.size,
        size_mb: Math.round(stats.size / (1024 * 1024)),
        success: true,
      };
    } catch (error) {
      if (error.isAbort) {
        throw Object.assign(new Error("Download interrupted by user"), {
          code: "DOWNLOAD_CANCELLED",
        });
      }
      throw error;
    } finally {
      if (this.currentDownloadProcess === downloadProcess) {
        this.currentDownloadProcess = null;
      }
    }
  }

  async cancelDownload() {
    if (this.currentDownloadProcess) {
      this.currentDownloadProcess.abort();
      return { success: true, message: "Download cancelled" };
    }
    return { success: false, error: "No active download to cancel" };
  }

  async checkModelStatus(modelName) {
    const modelPath = this.getModelPath(modelName);
    const activeDownload = this.currentDownloadProcess?.model === modelName;
    const downloadStatus = {
      isDownloading: activeDownload,
      isInstalling: false,
      downloadProgress: activeDownload ? this.currentDownloadProcess.percentage : 0,
      downloadedBytes: activeDownload ? this.currentDownloadProcess.downloadedBytes : 0,
      totalBytes: activeDownload ? this.currentDownloadProcess.totalBytes : 0,
    };

    if (fs.existsSync(modelPath)) {
      const stats = await fsPromises.stat(modelPath);
      return {
        model: modelName,
        downloaded: true,
        path: modelPath,
        size_bytes: stats.size,
        size_mb: Math.round(stats.size / (1024 * 1024)),
        success: true,
        ...downloadStatus,
      };
    }

    return { model: modelName, downloaded: false, success: true, ...downloadStatus };
  }

  async listWhisperModels() {
    const models = getValidModelNames();
    const modelInfo = [];

    for (const model of models) {
      const status = await this.checkModelStatus(model);
      modelInfo.push(status);
    }

    return {
      models: modelInfo,
      cache_dir: this.getModelsDir(),
      success: true,
    };
  }

  async deleteWhisperModel(modelName) {
    const modelPath = this.getModelPath(modelName);

    if (fs.existsSync(modelPath)) {
      const stats = await fsPromises.stat(modelPath);
      await fsPromises.unlink(modelPath);
      return {
        model: modelName,
        deleted: true,
        freed_bytes: stats.size,
        freed_mb: Math.round(stats.size / (1024 * 1024)),
        success: true,
      };
    }

    return { model: modelName, deleted: false, error: "Model not found", success: false };
  }

  async deleteAllWhisperModels() {
    const modelsDir = this.getModelsDir();
    let totalFreed = 0;
    let deletedCount = 0;

    try {
      if (!fs.existsSync(modelsDir)) {
        return { success: true, deleted_count: 0, freed_bytes: 0, freed_mb: 0 };
      }

      const files = await fsPromises.readdir(modelsDir);
      for (const file of files) {
        if (file.endsWith(".bin")) {
          const filePath = path.join(modelsDir, file);
          try {
            const stats = await fsPromises.stat(filePath);
            await fsPromises.unlink(filePath);
            totalFreed += stats.size;
            deletedCount++;
          } catch {
            // Continue with other files if one fails
          }
        }
      }

      return {
        success: true,
        deleted_count: deletedCount,
        freed_bytes: totalFreed,
        freed_mb: Math.round(totalFreed / (1024 * 1024)),
      };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // FFmpeg methods (still needed for audio format conversion)
  async getFFmpegPath() {
    if (this.cachedFFmpegPath) {
      return this.cachedFFmpegPath;
    }

    let ffmpegPath;

    try {
      ffmpegPath = require("ffmpeg-static");
      ffmpegPath = path.normalize(ffmpegPath);

      if (process.platform === "win32" && !ffmpegPath.endsWith(".exe")) {
        ffmpegPath += ".exe";
      }

      debugLogger.debug("FFmpeg static path from module", { ffmpegPath });

      // Try unpacked ASAR path first (production builds unpack ffmpeg-static)
      // Handle both forward slashes and backslashes for cross-platform compatibility
      const unpackedPath = ffmpegPath.includes("app.asar")
        ? ffmpegPath.replace(/app\.asar([/\\])/, "app.asar.unpacked$1")
        : null;

      if (unpackedPath) {
        debugLogger.debug("Checking unpacked ASAR path", { unpackedPath });
        if (fs.existsSync(unpackedPath)) {
          if (process.platform !== "win32") {
            try {
              fs.accessSync(unpackedPath, fs.constants.X_OK);
            } catch {
              debugLogger.debug("FFmpeg not executable, attempting chmod", { unpackedPath });
              try {
                fs.chmodSync(unpackedPath, 0o755);
              } catch (chmodErr) {
                debugLogger.warn("Failed to chmod FFmpeg", { error: chmodErr.message });
              }
            }
          }
          debugLogger.debug("Found FFmpeg in unpacked ASAR", { path: unpackedPath });
          this.cachedFFmpegPath = unpackedPath;
          return unpackedPath;
        } else {
          debugLogger.warn("Unpacked ASAR path does not exist", { unpackedPath });
        }
      }

      // Try original path (development or if not in ASAR)
      if (fs.existsSync(ffmpegPath)) {
        if (process.platform !== "win32") {
          fs.accessSync(ffmpegPath, fs.constants.X_OK);
        }
        debugLogger.debug("Found FFmpeg at bundled path", { path: ffmpegPath });
        this.cachedFFmpegPath = ffmpegPath;
        return ffmpegPath;
      } else {
        debugLogger.warn("Bundled FFmpeg path does not exist", { ffmpegPath });
      }
    } catch (err) {
      debugLogger.warn("Bundled FFmpeg not available", { error: err.message });
    }

    // Try system FFmpeg paths
    const systemCandidates =
      process.platform === "darwin"
        ? ["/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"]
        : process.platform === "win32"
          ? ["C:\\ffmpeg\\bin\\ffmpeg.exe"]
          : ["/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg"];

    debugLogger.debug("Trying system FFmpeg candidates", { candidates: systemCandidates });

    for (const candidate of systemCandidates) {
      if (fs.existsSync(candidate)) {
        debugLogger.debug("Found system FFmpeg", { path: candidate });
        this.cachedFFmpegPath = candidate;
        return candidate;
      }
    }

    debugLogger.error("FFmpeg not found anywhere");
    return null;
  }

  async checkFFmpegAvailability() {
    const now = Date.now();
    if (
      this.ffmpegAvailabilityCache.result !== null &&
      now < this.ffmpegAvailabilityCache.expiresAt
    ) {
      return this.ffmpegAvailabilityCache.result;
    }

    const ffmpegPath = await this.getFFmpegPath();
    const result = ffmpegPath
      ? { available: true, path: ffmpegPath }
      : { available: false, error: "FFmpeg not found" };

    this.ffmpegAvailabilityCache = { result, expiresAt: now + CACHE_TTL_MS };
    return result;
  }

  async getDiagnostics() {
    const diagnostics = {
      platform: process.platform,
      arch: process.arch,
      resourcesPath: process.resourcesPath || null,
      isPackaged: !!process.resourcesPath && !process.resourcesPath.includes("node_modules"),
      ffmpeg: { available: false, path: null, error: null },
      whisperServer: { available: false, path: null },
      modelsDir: this.getModelsDir(),
      models: [],
    };

    // Check FFmpeg
    try {
      this.cachedFFmpegPath = null; // Clear cache for fresh check
      const ffmpegPath = await this.getFFmpegPath();
      if (ffmpegPath) {
        diagnostics.ffmpeg = { available: true, path: ffmpegPath, error: null };
      } else {
        diagnostics.ffmpeg = { available: false, path: null, error: "Not found" };
      }
    } catch (err) {
      diagnostics.ffmpeg = { available: false, path: null, error: err.message };
    }

    // Check whisper server
    if (this.serverManager) {
      const serverPath = this.serverManager.getServerBinaryPath?.();
      diagnostics.whisperServer = {
        available: this.serverManager.isAvailable(),
        path: serverPath || null,
      };
    }

    // Check downloaded models
    try {
      const modelsDir = this.getModelsDir();
      if (fs.existsSync(modelsDir)) {
        const files = fs.readdirSync(modelsDir);
        diagnostics.models = files
          .filter((f) => f.startsWith("ggml-") && f.endsWith(".bin"))
          .map((f) => f.replace("ggml-", "").replace(".bin", ""));
      }
    } catch {
      // Ignore errors reading models dir
    }

    return diagnostics;
  }
}

module.exports = WhisperManager;
module.exports.shouldRewarmOnWake = shouldRewarmOnWake;
module.exports.resolveFailedGpuBackends = resolveFailedGpuBackends;