Skip to content

Write HTML. Render video. Built for agents.

11.1 KB
Raw Blame
// fallow-ignore-file code-duplication complexity
import { execFileSync } from "node:child_process";
import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
import { homedir, platform } from "node:os";
import { join } from "node:path";
import { findFFmpeg } from "../browser/ffmpeg.js";
import { downloadFile } from "../utils/download.js";
import { stoppableExecFile } from "../utils/stoppableExecFile.js";
import { verifies, type ModelFile } from "./modelFile.js";

const MODELS_DIR = join(homedir(), ".cache", "hyperframes", "whisper", "models");
const DEFAULT_MODEL = "small.en";

export type WhisperSource = "env" | "system" | "brew" | "build";

export interface WhisperResult {
  executablePath: string;
  source: WhisperSource;
}

// A missing/uninstallable whisper-cpp is an environment prerequisite gap (no
// binary, no Homebrew, no compiler toolchain), not a transcription bug. Callers
// that treat captions as optional (init, skill pipelines) skip on this and keep
// going; explicit `transcribe` still fails, but it is reported as a setup
// condition rather than a command crash.
export class WhisperUnavailableError extends Error {
  readonly code = "WHISPER_UNAVAILABLE" as const;
  constructor(message: string) {
    super(message);
    this.name = "WhisperUnavailableError";
  }
}

export function isWhisperUnavailable(err: unknown): err is WhisperUnavailableError {
  if (err instanceof WhisperUnavailableError) return true;
  return err instanceof Error && "code" in err && err.code === "WHISPER_UNAVAILABLE";
}

const MODEL_REVISION = "5359861c739e955e79d9a303bcbc70fb988958b1";

function getModelUrl(model: string): string {
  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/${MODEL_REVISION}/ggml-${model}.bin`;
}

const pinned = (model: string, bytes: number, sha256: string): [string, ModelFile] => [
  model,
  { name: `ggml-${model}.bin`, bytes, sha256 },
];

/** Sizes and sha256 at MODEL_REVISION; a model not listed here is used as downloaded. */
const PINNED_MODELS: ReadonlyMap<string, ModelFile> = new Map([
  pinned("tiny", 77_691_713, "be07e048e1e599ad46341c8d2a135645097a538221678b7acdd1b1919c6e1b21"),
  pinned("tiny.en", 77_704_715, "921e4cf8686fdd993dcd081a5da5b6c365bfde1162e72b08d75ac75289920b1f"),
  pinned("base", 147_951_465, "60ed5bc3dd14eea856493d334349b405782ddcaf0028d4b5df4088345fba2efe"),
  pinned(
    "base.en",
    147_964_211,
    "a03779c86df3323075f5e796cb2ce5029f00ec8869eee3fdfb897afe36c6d002",
  ),
  pinned("small", 487_601_967, "1be3a9b2063867b937e64e2ec7483364a79917e157fa98c5d94b5c1fffea987b"),
  pinned(
    "small.en",
    487_614_201,
    "c6138d6d58ecc8322097e0f987c32f1be8bb0a18532a3f88f734d1bbf9c41e5d",
  ),
  pinned(
    "medium",
    1_533_763_059,
    "6c14d5adee5f86394037b4e4e8b59f1673b6cee10e3cf0b11bbdbee79c156208",
  ),
  pinned(
    "medium.en",
    1_533_774_781,
    "cc37e93478338ec7700281a7ac30a10128929eb8f427dda2e865faa8f6da4356",
  ),
  pinned(
    "large-v1",
    3_094_623_691,
    "7d99f41a10525d0206bddadd86760181fa920438b6b33237e3118ff6c83bb53d",
  ),
  pinned(
    "large-v2",
    3_094_623_691,
    "9a423fe4d40c82774b6af34115b8b935f34152246eb19e80e376071d3f999487",
  ),
  pinned(
    "large-v3",
    3_095_033_483,
    "64d182b440b98d5203c4f9bd541544d84c605196c4f7b845dfa11fb23594d1e2",
  ),
  pinned(
    "large-v3-turbo",
    1_624_555_275,
    "1fc70f774d38eb169993ac391eea357ef47c88757ef72ee5943879b7e8e2bc69",
  ),
]);

export function pinnedWhisperModel(model: string): ModelFile | undefined {
  return PINNED_MODELS.get(model);
}

// --- Find helpers -----------------------------------------------------------

function whichBinary(name: string): string | undefined {
  try {
    const cmd = process.platform === "win32" ? "where" : "which";
    const output = execFileSync(cmd, [name], {
      encoding: "utf-8",
      stdio: ["pipe", "pipe", "pipe"],
      timeout: 5000,
    });
    const first = output
      .split(/\r?\n/)
      .map((s) => s.trim())
      .find(Boolean);
    return first || undefined;
  } catch {
    return undefined;
  }
}

function findFromEnv(): WhisperResult | undefined {
  const envPath = process.env["HYPERFRAMES_WHISPER_PATH"];
  if (envPath && existsSync(envPath)) {
    return { executablePath: envPath, source: "env" };
  }
  return undefined;
}

function findFromSystem(): WhisperResult | undefined {
  // `whisper` is the OpenAI Python CLI; only whisper.cpp's binary accepts our flags.
  const path = whichBinary("whisper-cli");
  if (path) return { executablePath: path, source: "system" };

  // Check brew paths directly on macOS
  if (platform() === "darwin") {
    for (const p of ["/opt/homebrew/bin/whisper-cli", "/usr/local/bin/whisper-cli"]) {
      if (existsSync(p)) return { executablePath: p, source: "system" };
    }
  }

  return undefined;
}

// --- Build from source ------------------------------------------------------

const BUILD_DIR = join(homedir(), ".cache", "hyperframes", "whisper", "whisper.cpp");
const WHISPER_REPO = "https://github.com/ggml-org/whisper.cpp.git";

function findBuiltBinary(): WhisperResult | undefined {
  for (const p of [
    join(BUILD_DIR, "build", "bin", "whisper-cli"),
    join(BUILD_DIR, "build", "whisper-cli"),
  ]) {
    if (existsSync(p)) return { executablePath: p, source: "build" };
  }
  return undefined;
}

async function buildFromSource(
  onProgress?: (msg: string) => void,
  signal?: AbortSignal,
): Promise<WhisperResult> {
  // Clean stale builds — if BUILD_DIR exists but has no binary, nuke and re-clone
  if (existsSync(BUILD_DIR) && !findBuiltBinary()) {
    rmSync(BUILD_DIR, { recursive: true, force: true });
  }

  if (!existsSync(BUILD_DIR)) {
    onProgress?.("Downloading whisper.cpp...");
    mkdirSync(join(homedir(), ".cache", "hyperframes", "whisper"), {
      recursive: true,
    });
    await stoppableExecFile("git", ["clone", "--depth", "1", WHISPER_REPO, BUILD_DIR], {
      stdio: "ignore",
      timeout: 60_000,
      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
      signal,
    });
  }

  onProgress?.("Building whisper.cpp (this may take a minute)...");
  try {
    await stoppableExecFile("cmake", ["-B", "build"], {
      cwd: BUILD_DIR,
      stdio: ["pipe", "pipe", "pipe"],
      timeout: 120_000,
      signal,
    });
    await stoppableExecFile("cmake", ["--build", "build", "--config", "Release", "-j"], {
      cwd: BUILD_DIR,
      stdio: ["pipe", "pipe", "pipe"],
      timeout: 300_000,
      signal,
    });
  } catch (err: unknown) {
    // Build failed — capture diagnostics, then clean up so next attempt starts fresh
    let detail = "";
    if (err && typeof err === "object" && "stderr" in err) {
      const stderr = String(err.stderr).trim();
      if (stderr) detail = `\n${stderr.slice(-500)}`;
    }
    rmSync(BUILD_DIR, { recursive: true, force: true });
    throw new Error(
      `whisper-cpp build failed. Ensure cmake and a C compiler are installed.${detail}`,
    );
  }

  const result = findBuiltBinary();
  if (!result) throw new Error("Build completed but whisper-cli not found");
  return result;
}

// --- Public API -------------------------------------------------------------

export function findWhisper(): WhisperResult | undefined {
  return findFromEnv() ?? findFromSystem() ?? findBuiltBinary();
}

export function listWhisperModels(): { model: string; path: string }[] {
  if (!existsSync(MODELS_DIR)) return [];
  return readdirSync(MODELS_DIR)
    .flatMap((file) => {
      const model = /^ggml-(.+)\.bin$/.exec(file)?.[1];
      const path = join(MODELS_DIR, file);
      return model && existsSync(path) ? [{ model, path }] : [];
    })
    .sort((a, b) => a.model.localeCompare(b.model));
}

export function getInstallInstructions(): string {
  if (platform() === "darwin") {
    return "brew install whisper-cpp";
  }
  if (platform() === "linux") {
    return "Build from source: https://github.com/ggml-org/whisper.cpp#building (requires cmake and a C compiler)";
  }
  if (platform() === "win32") {
    return "Build with cmake: https://github.com/ggml-org/whisper.cpp#building";
  }
  return "See https://github.com/ggml-org/whisper.cpp#building";
}

function hasBrew(): boolean {
  return whichBinary("brew") !== undefined;
}

function hasGit(): boolean {
  return whichBinary("git") !== undefined;
}

function hasCmake(): boolean {
  return whichBinary("cmake") !== undefined;
}

export async function ensureWhisper(options?: {
  installRuntime?: boolean;
  onProgress?: (msg: string) => void;
  /** Aborting it stops an install in progress and rejects with the reason, trying nothing else. */
  signal?: AbortSignal;
}): Promise<WhisperResult> {
  const signal = options?.signal;
  // 1. Already installed?
  const existing = findWhisper();
  if (existing) return existing;
  if (options?.installRuntime === false) {
    throw new WhisperUnavailableError(
      "whisper-cpp not found; runtime installation is disabled by --no-runtime-install.",
    );
  }

  // 2. Try brew (macOS, fastest — pre-built bottle)
  if (platform() === "darwin" && hasBrew()) {
    options?.onProgress?.("Installing whisper-cpp via Homebrew...");
    try {
      await stoppableExecFile("brew", ["install", "whisper-cpp"], {
        stdio: "ignore",
        timeout: 300_000,
        signal,
      });
      const installed = findFromSystem();
      if (installed) return { ...installed, source: "brew" };
    } catch {
      // brew failed — fall through
    }
    signal?.throwIfAborted();
  }

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

  // 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?: {
    signal?: AbortSignal;
    onProgress?: (message: string) => void;
    onDownloadProgress?: (receivedBytes: number, totalBytes: number | null) => void;
  },
): Promise<string> {
  const modelPath = join(MODELS_DIR, `ggml-${model}.bin`);
  const pin = PINNED_MODELS.get(model);
  const cachedBytes = statSync(modelPath, { throwIfNoEntry: false })?.size;
  if (cachedBytes !== undefined && (!pin || cachedBytes === pin.bytes)) return modelPath;

  mkdirSync(MODELS_DIR, { recursive: true });
  rmSync(modelPath, { force: true });
  options?.onProgress?.(
    cachedBytes === undefined
      ? `Downloading model ${model}...`
      : `Model ${model} is incomplete; downloading it again...`,
  );
  const downloaded = `${modelPath}.${process.pid}.download`;
  try {
    await downloadFile(getModelUrl(model), downloaded, {
      signal: options?.signal,
      onProgress: options?.onDownloadProgress,
    });
    if (pin && !(await verifies(downloaded, pin))) {
      throw new Error(
        `${pin.name} did not match its pinned size and sha256, so it was discarded. Re-run to retry.`,
      );
    }
    renameSync(downloaded, modelPath);
  } finally {
    rmSync(downloaded, { force: true });
  }
  return modelPath;
}

export function hasFFmpeg(): boolean {
  return findFFmpeg() !== undefined;
}

export { MODELS_DIR, DEFAULT_MODEL };