Skip to content

Write HTML. Render video. Built for agents.

26.7 KB
Raw Blame
// fallow-ignore-file complexity
import { execFile, execFileSync } from "node:child_process";
import { once } from "node:events";
import { createInterface } from "node:readline";
import type { Readable } from "node:stream";
import { existsSync, readFileSync, mkdirSync, rmSync, statSync, unlinkSync } from "node:fs";
import { basename, join, extname } from "node:path";
import { homedir, tmpdir } from "node:os";
import { randomUUID } from "node:crypto";
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
import { stoppedByCancelSignal } from "../utils/renderCancellation.js";
import { stoppableExecFile } from "../utils/stoppableExecFile.js";
import {
  ensureWhisper,
  ensureModel,
  hasFFmpeg,
  pinnedWhisperModel,
  DEFAULT_MODEL,
  type WhisperResult,
} from "./manager.js";
import { sha256File } from "./modelFile.js";
import { initialModelForLanguage } from "./modelForLanguage.js";
import { TRANSCRIPT_FILE } from "./transcriptFile.js";
import { findWavChunk } from "./wav.js";
import type { Word } from "./normalize.js";
import { emitWords } from "./progress.js";

export { initialModelForLanguage };

const WHISPER_TIMEOUT_FLOOR_MS = 300_000;
const WHISPER_TIMEOUT_PER_AUDIO_SECOND_MS = 10_000;
const WHISPER_TIMEOUT_CAP_MS = 43_200_000;
const AUDIO_PREPARATION_TIMEOUT_FLOOR_MS = 120_000;
const AUDIO_PREPARATION_TIMEOUT_PER_MEDIA_SECOND_MS = 500;
const AUDIO_PREPARATION_TIMEOUT_CAP_MS = 21_600_000;

/**
 * Model-specific slowdown factors relative to the `small.en` default. whisper.cpp's
 * per-token inference cost scales with model size — `medium` runs ~2x slower than
 * `small`, and the `large` family ~4x slower — so the 10x-realtime baseline that
 * comfortably covers `small.en` can still time out on `medium.en`/`large-v3` when
 * the CPU itself is slow. Applying the factor keeps the historical safety window
 * for the default model while giving heavier models the headroom they need on
 * emulated arm64/x64 hardware (field-signal ts=1784165471: Snapdragon emulating
 * x64 saw ~13x realtime on medium.en for a 63s clip).
 *
 * Values are conservative bounds, not tight upper bounds — the auto-scaled
 * timeout is still capped at 12h and gated by an explicit `--timeout` override.
 */
const WHISPER_MODEL_SLOWDOWN_FACTORS: Readonly<Record<string, number>> = {
  tiny: 0.5,
  "tiny.en": 0.5,
  base: 0.7,
  "base.en": 0.7,
  small: 1,
  "small.en": 1,
  medium: 2,
  "medium.en": 2,
  "large-v1": 4,
  "large-v2": 4,
  "large-v3": 4,
  "large-v3-turbo": 2,
};

// Unknown model names fall back to the `small.en` baseline so the returned
// timeout never dips below the historical safe window for a novel/custom model.
const DEFAULT_MODEL_SLOWDOWN_FACTOR = 1;

/**
 * Look up the auto-scale slowdown factor for a whisper model name. Case-
 * insensitive. Unknown names fall back to the `small.en` baseline (factor 1)
 * rather than a smaller factor so unknown models never accidentally shorten
 * the safety window.
 */
export function whisperModelSlowdownFactor(model: string): number {
  return WHISPER_MODEL_SLOWDOWN_FACTORS[model.toLowerCase()] ?? DEFAULT_MODEL_SLOWDOWN_FACTOR;
}

export interface ResolveWhisperTimeoutOptions {
  /** Whisper model name (e.g. `small.en`, `medium.en`, `large-v3`). Selects the slowdown factor. */
  model?: string;
  /**
   * Explicit override in milliseconds. Bypasses duration+model auto-scaling.
   * Still clamped to the 12h cap so a runaway value can't hang the process
   * indefinitely; validation of the lower bound is the caller's responsibility.
   */
  overrideMs?: number;
}

/**
 * Give long recordings enough time to transcribe while retaining a bounded
 * failure window. Short recordings keep the historical five-minute floor.
 *
 * Formula: `clamp(FLOOR, duration * PER_SECOND * modelFactor, CAP)`.
 * An explicit `overrideMs` bypasses the formula entirely (still capped at 12h).
 */
export function resolveWhisperTimeoutMs(
  durationSeconds: number | null,
  options?: ResolveWhisperTimeoutOptions,
): number {
  // Explicit override wins — respect the caller's exact value (still capped at
  // the 12h ceiling so a runaway value can't leave the process hung forever).
  // We do NOT re-apply the floor here: a user who deliberately passed
  // `--timeout 30000` on a 3s clip meant 30 seconds, not five minutes.
  if (
    options?.overrideMs != null &&
    Number.isFinite(options.overrideMs) &&
    options.overrideMs > 0
  ) {
    return Math.min(WHISPER_TIMEOUT_CAP_MS, options.overrideMs);
  }

  const factor = options?.model ? whisperModelSlowdownFactor(options.model) : 1;

  if (durationSeconds === null || !Number.isFinite(durationSeconds) || durationSeconds <= 0) {
    // Duration unknown: keep the historical five-minute floor for the default
    // model, but scale it up for heavier models so `medium`/`large` still get
    // a proportionate window when ffprobe can't read the WAV header.
    return Math.min(WHISPER_TIMEOUT_CAP_MS, Math.ceil(WHISPER_TIMEOUT_FLOOR_MS * factor));
  }

  return Math.min(
    WHISPER_TIMEOUT_CAP_MS,
    Math.max(
      WHISPER_TIMEOUT_FLOOR_MS,
      Math.ceil(durationSeconds * WHISPER_TIMEOUT_PER_AUDIO_SECOND_MS * factor),
    ),
  );
}

/**
 * Bound FFmpeg audio preparation while allowing long recordings to scale past
 * the historical two-minute timeout. The half-realtime allowance is generous
 * for audio-only extraction without inheriting Whisper's much larger window.
 */
export function resolveAudioPreparationTimeoutMs(durationSeconds: number | null): number {
  if (durationSeconds === null || !Number.isFinite(durationSeconds) || durationSeconds <= 0) {
    return AUDIO_PREPARATION_TIMEOUT_FLOOR_MS;
  }

  return Math.min(
    AUDIO_PREPARATION_TIMEOUT_CAP_MS,
    Math.max(
      AUDIO_PREPARATION_TIMEOUT_FLOOR_MS,
      Math.ceil(durationSeconds * AUDIO_PREPARATION_TIMEOUT_PER_MEDIA_SECOND_MS),
    ),
  );
}

export function getMediaDurationSeconds(filePath: string): number | null {
  try {
    const ffprobePath = findFFprobe();
    if (!ffprobePath) return null;
    const raw = execFileSync(
      ffprobePath,
      [
        "-v",
        "error",
        "-show_entries",
        "format=duration",
        "-of",
        "default=noprint_wrappers=1:nokey=1",
        "--",
        filePath,
      ],
      { encoding: "utf-8", timeout: 10_000 },
    );
    const durationSeconds = Number.parseFloat(raw.trim());
    return Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : null;
  } catch {
    return null;
  }
}

/** A prepared WAV is 16 kHz mono s16, so its size gives the length (the header adds a few ms). */
export function getPreparedWavDurationSeconds(wavPath: string): number | null {
  try {
    return statSync(wavPath).size / (16_000 * 2);
  } catch {
    return null;
  }
}

/**
 * Detect when speech begins in a 16kHz mono WAV by finding the first
 * sustained energy jump above the track's median RMS. Returns onset time in
 * seconds, or null if the track has consistent energy throughout.
 */
// fallow-ignore-next-line complexity
export function detectSpeechOnset(wavPath: string): number | null {
  const SAMPLE_RATE = 16000;
  const WINDOW_SECONDS = 0.5;
  const WINDOW_SAMPLES = SAMPLE_RATE * WINDOW_SECONDS;
  const SUSTAINED_WINDOWS = 3; // 1.5s above threshold to count as onset
  const SILENCE_THRESHOLD_RATIO = 0.6;
  const MIN_INTRO_SECONDS = 3; // don't strip if onset is very early

  try {
    const buf = readFileSync(wavPath);
    const dataChunk = findWavChunk(buf, "data");
    if (!dataChunk) return null;
    const pcm = new Int16Array(buf.buffer, buf.byteOffset + dataChunk.offset, dataChunk.size / 2);
    const totalWindows = Math.floor(pcm.length / WINDOW_SAMPLES);
    if (totalWindows < 10) return null;

    const rmsValues: number[] = [];
    for (let i = 0; i < totalWindows; i++) {
      const start = i * WINDOW_SAMPLES;
      let sumSq = 0;
      for (let j = start; j < start + WINDOW_SAMPLES; j++) {
        const sample = pcm[j] ?? 0;
        sumSq += sample * sample;
      }
      rmsValues.push(Math.sqrt(sumSq / WINDOW_SAMPLES));
    }

    const sorted = [...rmsValues].sort((a, b) => a - b);
    const median = sorted[Math.floor(sorted.length / 2)] ?? 0;
    const threshold = median * SILENCE_THRESHOLD_RATIO;

    // Check if energy is fairly consistent (no clear intro) — ratio of
    // first 10s average to median. If it's already close, no onset to detect.
    const introAvg =
      rmsValues.slice(0, Math.min(20, rmsValues.length)).reduce((a, b) => a + b, 0) /
      Math.min(20, rmsValues.length);
    if (introAvg >= threshold) return null;

    let consecutive = 0;
    for (let i = 0; i < rmsValues.length; i++) {
      if ((rmsValues[i] ?? 0) >= threshold) {
        consecutive++;
        if (consecutive >= SUSTAINED_WINDOWS) {
          const onsetSeconds = (i - SUSTAINED_WINDOWS + 1) * WINDOW_SECONDS;
          return onsetSeconds >= MIN_INTRO_SECONDS ? onsetSeconds : null;
        }
      } else {
        consecutive = 0;
      }
    }
  } catch {
    // Can't read WAV — skip onset detection
  }
  return null;
}

const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac"]);
const VIDEO_EXTENSIONS = new Set([".mp4", ".webm", ".mov", ".mkv", ".avi"]);

export type TranscribeProgress =
  | {
      type: "progress";
      phase: "download";
      model: string;
      receivedBytes: number;
      totalBytes: number | null;
    }
  | {
      type: "progress";
      phase: "transcription";
      model: string;
      status: "started" | "completed";
      durationSeconds?: number | null;
    }
  /** Words heard so far, before the final transcript replaces them; `through` is audio seconds done. */
  | { type: "words"; model: string; words: Word[]; through: number };

export interface WhisperOptions {
  installRuntime?: boolean;
  model?: string;
  language?: string;
  onProgress?: (message: string) => void;
  onEvent?: (event: TranscribeProgress) => void;
  /** Called as whisper starts, so a stop during install or download still ends the CLI at once. */
  startCancellation?: () => AbortSignal;
  signal?: AbortSignal;
  /**
   * Explicit whisper spawn timeout in ms. Overrides the duration+model auto-
   * scaled default. Callers that leave this undefined get the auto-scaled
   * default derived from prepared WAV duration and the selected model.
   */
  timeoutMs?: number;
}

export interface RunnerResult {
  model: string;
  detectedLanguage: string | null;
  transcriptPath: string;
  wordCount: number;
  durationSeconds: number;
  speechOnsetSeconds: number | null;
}

function isAudioFile(filePath: string): boolean {
  return AUDIO_EXTENSIONS.has(extname(filePath).toLowerCase());
}

function isVideoFile(filePath: string): boolean {
  return VIDEO_EXTENSIONS.has(extname(filePath).toLowerCase());
}

/**
 * Unique path for the temporary 16kHz mono WAV fed to whisper.
 *
 * MUST be unique per call AND per process: callers run many `transcribe`
 * invocations in parallel (e.g. an audio pipeline that spawns one
 * `hyperframes transcribe` per scene at once). A `Date.now()`-based name
 * collides when two conversions land in the same millisecond — they clobber
 * each other's WAV in the shared tmpdir, so whisper transcribes the wrong
 * scene's audio and every colliding scene gets identical word timings.
 */
function tempWavPath(): string {
  return join(tmpdir(), `hyperframes-audio-${process.pid}-${randomUUID()}.wav`);
}

async function runFfmpeg(
  ffmpegPath: string,
  args: string[],
  output: string,
  timeout: number,
  signal?: AbortSignal,
): Promise<void> {
  try {
    await stoppableExecFile(ffmpegPath, ["-nostats", "-hide_banner", ...args, "-y", output], {
      stdio: ["ignore", "ignore", "pipe"],
      maxBuffer: 64 * 1024 * 1024,
      timeout,
      signal,
    });
  } catch (err) {
    rmSync(output, { force: true });
    if (signal?.aborted) throw err;
    const stop = err as { code?: string; signal?: string; stderr?: Buffer };
    // A code means Node stopped it; ffmpeg traps Ctrl-C and says so (exit 255 is EPERM too on 7+).
    if (stop.code) throw err;
    const said = String(stop.stderr ?? "").trim();
    const cancelled = /Exiting normally, received signal/.test(said) || stoppedByCancelSignal(stop);
    const reason = said.split("\n").at(-1) || (err as Error).message;
    // stderr: the command shows its last lines, where ffmpeg names the cause above its summary line.
    const failure = new Error(`ffmpeg failed: ${reason}`, { cause: err });
    throw Object.assign(failure, { cancelled, stderr: said });
  }
}

/**
 * Extract audio from a video file as 16kHz mono WAV (whisper requirement).
 */
async function extractAudio(videoPath: string, signal?: AbortSignal): Promise<string> {
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath) {
    throw new Error(
      `ffmpeg is required to extract audio from video. Install: ${getFFmpegInstallHint()}`,
    );
  }
  const wavPath = tempWavPath();
  await runFfmpeg(
    ffmpegPath,
    ["-i", videoPath, "-vn", "-ar", "16000", "-ac", "1", "-f", "wav"],
    wavPath,
    resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(videoPath)),
    signal,
  );
  return wavPath;
}

interface AudioStream {
  codec_type?: string;
  codec_name?: string;
  sample_rate?: string;
  channels?: number;
}

/** 16-bit PCM only: sherpa-onnx cannot read 24-bit WAV, so anything else goes through ffmpeg. */
export function isPcm16kMono(stream: AudioStream | undefined): boolean {
  return (
    stream?.codec_name === "pcm_s16le" && stream.sample_rate === "16000" && stream.channels === 1
  );
}

/**
 * Check if a WAV file is already 16kHz mono via ffprobe.
 */
function isWav16kMono(filePath: string): boolean {
  try {
    const ffprobePath = findFFprobe();
    if (!ffprobePath) return false;
    const raw = execFileSync(
      ffprobePath,
      ["-v", "quiet", "-print_format", "json", "-show_streams", "--", filePath],
      { encoding: "utf-8", timeout: 10_000 },
    );
    const parsed: { streams?: AudioStream[] } = JSON.parse(raw);
    return isPcm16kMono(parsed.streams?.find((s) => s.codec_type === "audio"));
  } catch {
    return false;
  }
}

/**
 * Convert audio file to 16kHz mono WAV if not already in that format.
 */
async function prepareAudio(audioPath: string, signal?: AbortSignal): Promise<string> {
  if (extname(audioPath).toLowerCase() === ".wav" && isWav16kMono(audioPath)) {
    return audioPath;
  }

  // Convert to whisper-compatible WAV
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath) {
    throw new Error(`ffmpeg is required to prepare audio. Install: ${getFFmpegInstallHint()}`);
  }
  const wavPath = tempWavPath();
  await runFfmpeg(
    ffmpegPath,
    ["-i", audioPath, "-ar", "16000", "-ac", "1", "-f", "wav"],
    wavPath,
    resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(audioPath)),
    signal,
  );
  return wavPath;
}

/** Aborting `signal` stops ffmpeg, removes its partial WAV and rejects with the reason. */
export async function prepareWav(
  inputPath: string,
  onProgress?: (message: string) => void,
  signal?: AbortSignal,
): Promise<string> {
  if (isAudioFile(inputPath)) {
    onProgress?.("Preparing audio...");
    return prepareAudio(inputPath, signal);
  }
  if (isVideoFile(inputPath)) {
    if (!hasFFmpeg()) {
      throw new Error(
        `ffmpeg is required to extract audio from video. Install: ${getFFmpegInstallHint()}`,
      );
    }
    onProgress?.("Extracting audio from video...");
    return extractAudio(inputPath, signal);
  }
  throw new Error(`Unsupported file type: ${extname(inputPath).toLowerCase()}`);
}

/**
 * Transcribe an audio or video file and save transcript.json to the output directory.
 */
// fallow-ignore-next-line complexity
export async function transcribe(
  inputPath: string,
  outputDir: string,
  options?: WhisperOptions,
): Promise<RunnerResult> {
  const model = initialModelForLanguage(options?.model ?? DEFAULT_MODEL, options?.language);

  const signal = options?.signal;
  // 1. Ensure whisper binary
  signal?.throwIfAborted();
  options?.onProgress?.("Checking whisper...");
  const whisper = await ensureWhisper({
    onProgress: options?.onProgress,
    installRuntime: options?.installRuntime,
    signal,
  });

  // 2. Ensure model
  signal?.throwIfAborted();
  options?.onProgress?.("Checking model...");
  const modelPath = await ensureModel(model, {
    signal,
    onProgress: options?.onProgress,
    onDownloadProgress: options?.onEvent
      ? (receivedBytes, totalBytes) =>
          options.onEvent?.({
            type: "progress",
            phase: "download",
            model,
            receivedBytes,
            totalBytes,
          })
      : undefined,
  });

  // 3. Prepare audio
  signal?.throwIfAborted();
  const wavPath = await prepareWav(inputPath, options?.onProgress, signal);
  signal?.throwIfAborted();

  const automaticLanguage = options?.language === undefined && !model.endsWith(".en");
  const language = options?.language ?? (automaticLanguage ? "auto" : "en");
  options?.onProgress?.("Transcribing...");
  const wavSeconds = getPreparedWavDurationSeconds(wavPath);
  options?.onEvent?.({
    type: "progress",
    phase: "transcription",
    model,
    status: "started",
    durationSeconds: wavSeconds,
  });
  const outputBase = join(outputDir, basename(TRANSCRIPT_FILE, ".json"));
  mkdirSync(outputDir, { recursive: true });

  const whisperArgs = [
    "--model",
    modelPath,
    "--output-json-full",
    "--output-file",
    outputBase,
    "--suppress-nst",
  ];
  whisperArgs.push("--language", language);
  const onEvent = options?.onEvent;
  if (onEvent) whisperArgs.push("--print-progress");
  whisperArgs.push(wavPath);

  const whisperTimeoutMs = resolveWhisperTimeoutMs(wavSeconds, {
    model,
    overrideMs: options?.timeoutMs,
  });
  let through = 0;
  const heard = (words: Word[], at: number) => {
    if (!onEvent || (words.length === 0 && at <= through)) return;
    through = Math.max(through, at);
    emitWords(onEvent, model, words, through);
  };
  try {
    await runWhisper(whisper.executablePath, whisperArgs, {
      timeoutMs: whisperTimeoutMs,
      signal: options?.startCancellation?.(),
      onStdout:
        onEvent &&
        ((line) => {
          const segment = segmentWords(line);
          if (segment) heard(segment.words, segment.end);
        }),
      onStderr:
        onEvent && wavSeconds
          ? (line) => {
              const percent = /progress =\s*(\d+)%/.exec(line)?.[1];
              if (percent) heard([], (Number(percent) / 100) * wavSeconds);
            }
          : undefined,
    });
  } catch (err) {
    // Surface the timeout knob when the child was killed by our own timeout —
    // otherwise the reporter sees a bare ETIMEDOUT / SIGTERM with no hint that
    // `--timeout` even exists. Any other failure names the build, model and stderr.
    if (isWhisperTimeoutError(err) || stoppedByCancelSignal(err as { signal?: string })) {
      throw wrapWhisperTimeoutError(err, {
        effectiveTimeoutMs: whisperTimeoutMs,
        model,
        wasOverride: options?.timeoutMs != null,
      });
    }
    throw await diagnoseWhisperFailure(err, whisper, modelPath, model);
  }

  // 6. Read and validate output
  const transcriptPath = `${outputBase}.json`;
  if (!existsSync(transcriptPath)) {
    throw new Error("Whisper did not produce output. Check the input file.");
  }

  const transcript = JSON.parse(readFileSync(transcriptPath, "utf-8"));
  const reportedLanguage: unknown = transcript.result?.language;
  const detectedLanguage =
    automaticLanguage && typeof reportedLanguage === "string" && reportedLanguage.length > 0
      ? reportedLanguage
      : null;
  const segments = transcript.transcription ?? [];

  let wordCount = 0;
  let maxEnd = 0;
  for (const seg of segments) {
    for (const token of seg.tokens ?? []) {
      const text = (token.text ?? "").trim();
      if (text && !text.startsWith("[_") && !text.startsWith("[BLANK")) wordCount++;
      if (token.offsets?.to > maxEnd) maxEnd = token.offsets.to;
    }
  }

  // 7. Detect speech onset before cleaning up the WAV
  options?.onProgress?.("Detecting speech onset...");
  const speechOnsetSeconds = detectSpeechOnset(wavPath);

  // Clean up temp WAV if we created one
  if (wavPath !== inputPath) {
    try {
      unlinkSync(wavPath);
    } catch {
      // ignore
    }
  }

  options?.onEvent?.({ type: "progress", phase: "transcription", model, status: "completed" });
  return {
    model,
    detectedLanguage,
    transcriptPath,
    wordCount,
    durationSeconds: maxEnd / 1000,
    speechOnsetSeconds,
  };
}

const SEGMENT_LINE = /^\[(\d+):(\d+):([\d.]+) --> (\d+):(\d+):([\d.]+)\]\s*(.*)$/;
const toSeconds = (h: string, m: string, s: string) =>
  Number(h) * 3600 + Number(m) * 60 + Number(s);
const toMs = (seconds: number) => Math.round(seconds * 1000) / 1000;

/** A segment line whisper-cli prints as it decodes; word times are spread by length until the JSON's. */
function segmentWords(line: string): { words: Word[]; end: number } | null {
  const m = SEGMENT_LINE.exec(line);
  if (!m) return null;
  const start = toSeconds(m[1]!, m[2]!, m[3]!);
  const end = toSeconds(m[4]!, m[5]!, m[6]!);
  const texts = m[7]!
    .split(/\s+/)
    .filter((t) => t && !t.startsWith("[_") && !t.startsWith("[BLANK"));
  const letters = texts.reduce((n, t) => n + t.length, 0);
  let at = start;
  const words = texts.map((text) => {
    const from = at;
    at += ((end - start) * text.length) / letters;
    return { text, start: toMs(from), end: toMs(at) };
  });
  return { words, end };
}

/** Resolves once whisper exits and both its streams are read, so no printed line is lost. */
async function runWhisper(
  executable: string,
  args: string[],
  options: {
    timeoutMs: number;
    signal?: AbortSignal;
    onStdout?: (line: string) => void;
    onStderr?: (line: string) => void;
  },
): Promise<void> {
  let stdout: Readable | null = null;
  let stderr: Readable | null = null;
  const exited = new Promise<void>((resolve, reject) => {
    const child = execFile(
      executable,
      args,
      { timeout: options.timeoutMs, signal: options.signal, maxBuffer: 256 * 1024 * 1024 },
      (err, _out, errText) => {
        if (!err) return resolve();
        // execFileSync named its own timeout ETIMEDOUT; execFile only marks the child killed.
        const timedOut = err.killed && err.signal === "SIGTERM" && !options.signal?.aborted;
        // execFile appends all of stderr to the message; the command shows its last lines instead.
        err.message = err.message.split("\n")[0]!;
        reject(Object.assign(err, { stderr: errText }, timedOut ? { code: "ETIMEDOUT" } : {}));
      },
    );
    stdout = child.stdout;
    stderr = child.stderr;
  });
  const read = (stream: Readable | null, onLine?: (line: string) => void) =>
    stream && onLine ? once(createInterface({ input: stream }).on("line", onLine), "close") : null;
  await Promise.all([exited, read(stdout, options.onStdout), read(stderr, options.onStderr)]);
}

/** Every absolute path becomes its file name, so a pasted error names no user or folder. */
export function withoutPaths(text: string): string {
  return text
    .split(homedir())
    .join("~")
    .replace(/(?<=^|[\s'"(=:[])(?:~|[A-Za-z]:)?[\\/](?:[^\s'"`\\/]+[\\/])*([^\s'"`\\/]+)/g, "$1");
}

function whisperVersion(executable: string): string {
  try {
    const said = execFileSync(executable, ["--version"], {
      encoding: "utf-8",
      stdio: ["ignore", "pipe", "pipe"],
      timeout: 5000,
    });
    return /version:?\s*(\S+)/i.exec(said)?.[1] ?? "unknown version";
  } catch {
    return "unknown version";
  }
}

async function describeModel(modelPath: string, model: string): Promise<string> {
  const bytes = statSync(modelPath, { throwIfNoEntry: false })?.size;
  if (bytes === undefined) return `model ${model}: file missing`;
  const sha256 = await sha256File(modelPath).catch(() => "unreadable");
  const pin = pinnedWhisperModel(model);
  const verdict = !pin
    ? "not a pinned model"
    : pin.bytes === bytes && pin.sha256 === sha256
      ? "matches the pinned file"
      : `damaged: expected ${pin.bytes} bytes, sha256 ${pin.sha256.slice(0, 12)}; delete it and re-run`;
  return `model ${model}: ${bytes} bytes, sha256 ${sha256.slice(0, 12)} (${verdict})`;
}

/** A whisper-cli failure that says which build, which model file and what whisper printed, for a bug report. */
async function diagnoseWhisperFailure(
  err: unknown,
  whisper: WhisperResult,
  modelPath: string,
  model: string,
): Promise<Error> {
  const failed = err as { code?: unknown; signal?: string | null; stderr?: unknown };
  const how = failed.signal
    ? `crashed (${failed.signal})`
    : typeof failed.code === "number"
      ? `exited with code ${failed.code}`
      : `failed: ${withoutPaths(err instanceof Error ? err.message : String(err))}`;
  const said = withoutPaths(String(failed.stderr ?? ""))
    .trim()
    .split("\n")
    .slice(-12)
    .join("\n");
  const lines = [
    `whisper-cli ${how}.`,
    `whisper-cli ${whisperVersion(whisper.executablePath)} (${whisper.source}: ${basename(whisper.executablePath)})`,
    await describeModel(modelPath, model),
    said ? `whisper-cli said:\n${said}` : "whisper-cli printed nothing.",
  ];
  return new Error(lines.join("\n"), { cause: err });
}

// ---------------------------------------------------------------------------
// Timeout error discoverability
// ---------------------------------------------------------------------------

// execFileSync's own timeout sets code ETIMEDOUT (and SIGTERM); a bare SIGTERM is someone stopping it.
export function isWhisperTimeoutError(err: unknown): boolean {
  return err instanceof Error && (err as { code?: unknown }).code === "ETIMEDOUT";
}

export interface WrapWhisperTimeoutOptions {
  effectiveTimeoutMs: number;
  model: string;
  /** True when the timeout was set via `--timeout`; false when it was auto-scaled. */
  wasOverride: boolean;
}

/**
 * Wrap a whisper spawn error with a discoverability hint when the child was
 * killed by our timeout. Names the effective timeout, the CLI flag, and the
 * env var so slow-CPU users see the knob rather than a bare `ETIMEDOUT`.
 * Non-timeout errors flow through unchanged (as `Error` for well-typed
 * downstream handling).
 */
export function wrapWhisperTimeoutError(err: unknown, options: WrapWhisperTimeoutOptions): Error {
  if (!isWhisperTimeoutError(err)) {
    return err instanceof Error ? err : new Error(String(err));
  }

  const seconds = Math.round(options.effectiveTimeoutMs / 1000);
  const source = options.wasOverride
    ? `explicit --timeout ${options.effectiveTimeoutMs}ms`
    : `auto-scaled default for model ${options.model}`;
  const message =
    `Whisper transcription exceeded ${seconds}s (${source}). ` +
    `Raise --timeout <ms> or set HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS. ` +
    `Slow CPUs (e.g. emulated arm64/x64, low-power laptops) may need many ` +
    `multiples of realtime on heavier models — medium.en can run ~10-15x ` +
    `realtime on constrained hardware.`;
  const wrapped = new Error(message);
  (wrapped as { cause?: unknown }).cause = err;
  return wrapped;
}