heygen-com/hyperframes · error · WhisperUnavailableError

WHISPER_UNAVAILABLE

WHISPER_UNAVAILABLE

Error message

whisper-cpp not found. Install: ${getInstallInstructions()}

What it means

Thrown as WhisperUnavailableError (with code 'WHISPER_UNAVAILABLE') when all four whisper-cpp resolution strategies have been exhausted: no existing binary found (env, system, brew, build), Homebrew install failed or is unavailable, and source build failed or prerequisites are missing. The error includes platform-specific install instructions. Callers that treat captions as optional can detect this via the exported isWhisperUnavailable type guard and skip gracefully.

Source

Thrown at packages/cli/src/whisper/manager.ts:210

      });
      const installed = findFromSystem();
      if (installed) return { ...installed, source: "brew" };
    } catch {
      // brew failed — fall through
    }
  }

  // 3. Build from source (needs git + cmake + C compiler)
  if (hasGit() && hasCmake()) {
    try {
      return buildFromSource(options?.onProgress);
    } catch {
      // build failed — fall through
    }
  }

  // 4. Give up — tell the user how
  throw new WhisperUnavailableError(`whisper-cpp not found. Install: ${getInstallInstructions()}`);
}

export async function ensureModel(
  model: string = DEFAULT_MODEL,
  options?: { onProgress?: (message: string) => void },
): Promise<string> {
  const modelPath = join(MODELS_DIR, `ggml-${model}.bin`);
  if (existsSync(modelPath)) return modelPath;

  mkdirSync(MODELS_DIR, { recursive: true });

  options?.onProgress?.(`Downloading model ${model}...`);
  await downloadFile(getModelUrl(model), modelPath);

  if (!existsSync(modelPath)) {
    throw new Error(`Model download failed: ${model}`);
  }

View on GitHub (pinned to c2996c8626)

Solutions

1. Follow the platform-specific instructions in the error message (brew install whisper-cpp on macOS, or install cmake + build-essential and retry).
2. Install whisper-cpp manually and set HYPERFRAMES_WHISPER to the binary path.
3. If using the Parakeet engine instead, ensure parakeet-mlx is installed and pass --engine parakeet.
4. If captions are optional for your workflow, catch WhisperUnavailableError via isWhisperUnavailable and skip transcription.

Example fix

// Catch and skip when captions are optional
import { isWhisperUnavailable } from "@hyperframes/cli/whisper/manager";
try {
  await ensureWhisper();
} catch (err) {
  if (isWhisperUnavailable(err)) {
    console.warn("whisper-cpp unavailable — skipping captions");
    return;
  }
  throw err;
}

import { findWhisper } from "./manager.js";

const existing = findWhisper();
if (!existing) {
  console.warn("whisper-cpp not installed. Captions will be skipped.");
}

import { isWhisperUnavailable } from "./manager.js";

// isWhisperUnavailable is the exported guard — use it to detect this error
function isOptionalCaptions(err: unknown): boolean {
  return isWhisperUnavailable(err);
}

import { isWhisperUnavailable } from "./manager.js";

try {
  await ensureWhisper({ onProgress: console.log });
} catch (err) {
  if (isWhisperUnavailable(err)) {
    // Captions are optional for this workflow — skip gracefully
    console.warn("whisper-cpp unavailable — skipping transcription.");
    return null;
  }
  throw err;
}

When it happens

Trigger: Calling ensureWhisper on a system with no whisper-cpp installed, no Homebrew, and no cmake/C compiler toolchain; all resolution paths (findFromEnv, findFromSystem, findFromSystem via brew, buildFromSource) returned null or threw.

Common situations: First-time use on a minimal Linux server or CI container without build tools; Windows without a pre-built binary or compiler; a system where whisper-cpp was previously installed but has since been removed.

Related errors

• parakeet-mlx not found. Enable the Parakeet engine with: $
• FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}
• whisper-cpp build failed. Ensure cmake and a C compiler are
• ffmpeg is required to extract audio from video. Install: ${g
• ffmpeg is required to prepare audio. Install: ${getFFmpegIns

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/6898bf2ec08730ba. Report an issue: GitHub.