Skip to content

Write HTML. Render video. Built for agents.

42.8 KB
Raw Blame
import { runCommand } from "citty";
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import childProcess from "node:child_process";
import fs from "node:fs";
import {
  chmodSync,
  mkdirSync,
  existsSync,
  writeFileSync,
  readFileSync,
  mkdtempSync,
  realpathSync,
  rmSync,
  statSync,
  symlinkSync,
} from "node:fs";
import { basename, dirname, join } from "node:path";
import { syncBuiltinESMExports } from "node:module";
import { tmpdir } from "node:os";
import { pathToFileURL } from "node:url";
import * as manager from "../whisper/manager.js";
import { WhisperUnavailableError } from "../whisper/manager.js";
import { formatVtt, loadTranscript } from "../whisper/normalize.js";
import * as parakeet from "../whisper/parakeet.js";
import * as sherpa from "../whisper/sherpa.js";
import * as whisper from "../whisper/transcribe.js";
import { CliRuntimeError, consumeCommandResult } from "../utils/commandResult.js";
import transcribeCmd from "./transcribe.js";

// Make the whisper core report "unavailable" so we exercise the soft-skip path.
const transcribeMock = vi.fn();
const prepareWavMock = vi.fn((input: string) => input);
let audioSeconds = 1;

// Engine selection: which runners look installed, and the sherpa decode child it spawns.
const runners: { sherpa: boolean; mlx: boolean; whisper?: boolean } = { sherpa: false, mlx: false };
let runtimeDir: string;
const realTranscribeWithSherpa = sherpa.transcribeWithSherpa;
const realTranscribeWithParakeet = parakeet.transcribeWithParakeet;
const realPrepareWav = whisper.prepareWav;
const mlxMock = vi.fn();
const execFileMock = vi.fn();

const trackTranscribeUnavailable = vi.fn();
vi.mock("../telemetry/events.js", () => ({
  trackTranscribeUnavailable: (...a: unknown[]) => trackTranscribeUnavailable(...a),
}));

/** The runners the command reaches, replaced for each test because afterEach restores every spy. */
function replaceRunners(): void {
  vi.spyOn(whisper, "transcribe").mockImplementation((...a) => transcribeMock(...a));
  vi.spyOn(whisper, "prepareWav").mockImplementation(async (input) => prepareWavMock(input));
  vi.spyOn(whisper, "getPreparedWavDurationSeconds").mockImplementation(() => audioSeconds);
  vi.spyOn(sherpa, "sherpaParakeetInstalled").mockImplementation(() => runners.sherpa);
  vi.spyOn(sherpa, "transcribeWithSherpa").mockImplementation((wavPath, dir, options) =>
    realTranscribeWithSherpa(wavPath, dir, {
      ...options,
      runtimeDir,
      cliUrl: pathToFileURL(join(runtimeDir, "dist", "cli.js")).href,
    }),
  );
  vi.spyOn(parakeet, "findParakeet").mockImplementation(() =>
    runners.mlx ? "/bin/parakeet-mlx" : undefined,
  );
  vi.spyOn(parakeet, "transcribeWithParakeet").mockImplementation((...a) => mlxMock(...a));
  vi.spyOn(manager, "findWhisper").mockImplementation(() =>
    runners.whisper ? { executablePath: "/bin/whisper-cli", source: "system" } : undefined,
  );
  vi.spyOn(childProcess, "execFile").mockImplementation(((...a: unknown[]) =>
    execFileMock(...a)) as unknown as typeof childProcess.execFile);
  // Node's named exports of a builtin follow its default export only once synced.
  syncBuiltinESMExports();
}

/** Makes each runner write a one-word transcript naming itself. */
function fakeTranscript(dir: string, text: string) {
  const transcriptPath = join(dir, "transcript.json");
  writeFileSync(transcriptPath, JSON.stringify([{ text, start: 0, end: 1 }]));
  return {
    model: text === "whisper" ? "small.en" : "parakeet-tdt-0.6b-v3",
    detectedLanguage: null,
    transcriptPath,
    wordCount: 1,
    durationSeconds: 1,
    speechOnsetSeconds: null,
  };
}

function lastJson(): Record<string, unknown> {
  return JSON.parse(String(vi.mocked(console.log).mock.calls.at(-1)?.[0]));
}

function dummyAudio(): { dir: string; input: string } {
  const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-test-"));
  const input = join(dir, "narration.wav");
  writeFileSync(input, "not-real-audio");
  return { dir, input };
}

describe("transcribe command", () => {
  let dirs: string[] = [];
  beforeEach(() => {
    dirs = [];
    consumeCommandResult();
    replaceRunners();
    transcribeMock.mockReset();
    prepareWavMock.mockReset().mockImplementation((input: string) => input);
    trackTranscribeUnavailable.mockReset();
    mlxMock.mockReset();
    Object.assign(runners, { sherpa: false, mlx: false, whisper: false });
    transcribeMock.mockRejectedValue(
      new WhisperUnavailableError("whisper-cpp not found. Install: brew install whisper-cpp"),
    );
    vi.spyOn(console, "log").mockImplementation(() => {});
  });

  afterEach(() => {
    consumeCommandResult();
    for (const d of dirs) rmSync(d, { recursive: true, force: true });
    vi.restoreAllMocks();
    syncBuiltinESMExports();
    vi.unstubAllEnvs();
  });

  it("keeps quiet Spanish words before the relative speech onset in transcript and captions", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const words = [
      { id: "w0", text: "Siempre", start: 0.2, end: 0.49 },
      { id: "w1", text: "que", start: 0.49, end: 0.7 },
      { id: "w2", text: "los", start: 0.7, end: 0.91 },
      { id: "w3", text: "nietos", start: 0.91, end: 1.33 },
      { id: "w4", text: "vecindario", start: 10.03, end: 11.02 },
    ];
    const htmlPath = join(dir, "index.html");
    writeFileSync(htmlPath, "<script>const TRANSCRIPT = [];</script>");
    transcribeMock.mockImplementation(async (_input, outputDir) => {
      const result = fakeTranscript(outputDir, "whisper");
      writeFileSync(result.transcriptPath, JSON.stringify(words));
      return { ...result, wordCount: 5, durationSeconds: 50, speechOnsetSeconds: 10 };
    });

    await runCommand(transcribeCmd, {
      rawArgs: [input, "--dir", dir, "--engine", "whisper", "--language", "es", "--json"],
    });

    expect(JSON.parse(readFileSync(join(dir, "transcript.json"), "utf8"))).toEqual(words);
    const captions = readFileSync(htmlPath, "utf8").match(/const TRANSCRIPT = ([\s\S]*?);/)![1]!;
    expect(JSON.parse(captions)).toEqual(words);
    expect(lastJson()).toMatchObject({ ok: true, wordCount: 5, speechOnsetSeconds: 10 });
  });

  it("keeps typed progress on stderr and reports resolved metadata in one stdout result", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    transcribeMock.mockImplementation(async (_input, outputDir, options) => {
      options.onEvent?.({
        type: "progress",
        phase: "download",
        model: "small",
        receivedBytes: 5,
        totalBytes: null,
      });
      options.onEvent?.({
        type: "progress",
        phase: "transcription",
        model: "small",
        status: "started",
      });
      options.onEvent?.({
        type: "progress",
        phase: "transcription",
        model: "small",
        status: "completed",
      });
      return { ...fakeTranscript(outputDir, "hola"), model: "small", detectedLanguage: "es" };
    });
    await transcribeCmd.run!({
      args: { input, dir, json: true, engine: "whisper", model: "small.en" },
    } as never);
    expect(console.log).toHaveBeenCalledTimes(1);
    expect(lastJson()).toMatchObject({ ok: true, model: "small", detectedLanguage: "es" });
    expect(stderr.mock.calls.map(([line]) => JSON.parse(String(line)))).toEqual([
      { type: "progress", phase: "download", model: "small", receivedBytes: 5, totalBytes: null },
      { type: "progress", phase: "transcription", model: "small", status: "started" },
      { type: "progress", phase: "transcription", model: "small", status: "completed" },
    ]);
    expect(JSON.parse(readFileSync(join(dir, "transcript.json"), "utf8"))).toEqual([
      { id: "w0", text: "hola", start: 0, end: 1 },
    ]);
  });

  it("explicit run exits non-zero and is NOT reported as a command failure", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    // Pin the engine. `auto` picks Parakeet whenever parakeet-mlx happens to be
    // installed, and only the whisper path is mocked here -- so on those
    // machines this test used to shell out to a real ASR binary, fail with
    // "Parakeet did not produce output", and land in the generic failure branch
    // instead of the soft-skip it is asserting.
    await transcribeCmd.run!({
      args: { input, json: true, optional: false, engine: "whisper" },
    } as never);

    expect(transcribeMock).toHaveBeenCalled();
    expect(consumeCommandResult().exitCode).toBe(1);
    expect(trackTranscribeUnavailable).toHaveBeenCalledWith({ optional: false });
  });

  it("--optional skips cleanly with exit 0", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    await transcribeCmd.run!({
      args: { input, json: true, optional: true, engine: "whisper" },
    } as never);

    // Asserting the mock ran is what keeps this honest: without it the test
    // passes on a machine with no Parakeet and silently tests nothing on one
    // that has it.
    expect(transcribeMock).toHaveBeenCalled();
    expect(prepareWavMock).not.toHaveBeenCalled();
    expect(consumeCommandResult().exitCode).toBe(0);
    expect(trackTranscribeUnavailable).toHaveBeenCalledWith({ optional: true });
  });

  describe("engine selection", () => {
    beforeEach(() => {
      runtimeDir = mkdtempSync(join(tmpdir(), "hf-transcribe-runtime-"));
      dirs.push(runtimeDir);
      const pkg = join(runtimeDir, "node_modules", "sherpa-onnx-node");
      mkdirSync(pkg, { recursive: true });
      writeFileSync(join(pkg, "package.json"), JSON.stringify({ main: "index.js" }));
      writeFileSync(join(pkg, "index.js"), "module.exports = {};");
      transcribeMock.mockImplementation(async (_in: string, dir: string) =>
        fakeTranscript(dir, "whisper"),
      );
      mlxMock.mockImplementation((_in: string, dir: string) => fakeTranscript(dir, "mlx"));
      execFileMock.mockReset();
      execFileMock.mockImplementation((_cmd, _args, _opts, done) => {
        const windows = [{ offset: 60, tokens: [" sherpa"], timestamps: [0.5], durations: [0.25] }];
        done(null, `HYPERFRAMES_PARAKEET_RESULT:${JSON.stringify(windows)}\n`, "");
      });
      vi.spyOn(console, "error").mockImplementation(() => {});
      vi.spyOn(process.report, "getReport").mockReturnValue({
        header: { glibcVersionRuntime: "2.36" },
      } as never);
    });

    async function transcribeWith(engine: string, installed: typeof runners, language?: string) {
      Object.assign(runners, installed);
      const { dir, input } = dummyAudio();
      dirs.push(dir);
      await transcribeCmd.run!({ args: { input, json: true, engine, language } } as never);
      const out = lastJson();
      const words = JSON.parse(readFileSync(String(out.transcriptPath), "utf-8"));
      return { engine: out.engine, model: out.model, word: words[0]?.text, start: words[0]?.start };
    }

    it("installs whisper's stop handling only when whisper starts, after any install or download", async () => {
      const run = transcribeMock.getMockImplementation()!;
      const handlers: number[] = [];
      let signal: unknown;
      transcribeMock.mockImplementationOnce(async (input, outputDir, options) => {
        handlers.push(process.listenerCount("SIGTERM"));
        signal = options.startCancellation();
        handlers.push(process.listenerCount("SIGTERM"));
        return run(input, outputDir, options);
      });
      await transcribeWith("whisper", { sherpa: false, mlx: false });
      expect(signal).toBeInstanceOf(AbortSignal);
      expect(handlers[1]).toBeGreaterThan(handlers[0]!);
    });

    it("auto and parakeet prefer sherpa-onnx, then parakeet-mlx, then whisper", async () => {
      const sherpa = {
        engine: "parakeet",
        model: "parakeet-tdt-0.6b-v3",
        word: "sherpa",
        start: 60.5,
      };
      expect(await transcribeWith("auto", { sherpa: true, mlx: true })).toEqual(sherpa);
      expect(await transcribeWith("parakeet", { sherpa: true, mlx: true })).toEqual(sherpa);
      expect(await transcribeWith("auto", { sherpa: false, mlx: true })).toMatchObject({
        engine: "parakeet",
        word: "mlx",
      });
      expect(await transcribeWith("auto", { sherpa: false, mlx: false })).toMatchObject({
        engine: "whisper",
        word: "whisper",
      });
      expect(await transcribeWith("whisper", { sherpa: true, mlx: true })).toMatchObject({
        engine: "whisper",
        word: "whisper",
      });
    });

    it.skipIf(process.platform === "win32")(
      "lets parakeet-mlx detect the language itself, since it has no --language option",
      async () => {
        // Rejects --language the way parakeet-mlx does, and writes one token otherwise.
        const runner = join(runtimeDir, "parakeet-mlx");
        writeFileSync(
          runner,
          `#!/bin/sh
[ "$1" = --help ] && exit 0
in="$1"
for a in "$@"; do [ "$a" = --language ] && { echo "Error: No such option: --language" >&2; exit 2; }; done
while [ "$1" != --output-dir ]; do shift; done
echo '{"sentences":[{"tokens":[{"text":" hola","start":0,"end":1}]}]}' > "$2/$(basename "$in" .wav).json"
`,
        );
        chmodSync(runner, 0o755);
        vi.stubEnv("HYPERFRAMES_PARAKEET", runner);
        mlxMock.mockImplementation(realTranscribeWithParakeet);

        expect(await transcribeWith("auto", { sherpa: false, mlx: true }, "es")).toMatchObject({
          engine: "parakeet",
          word: "hola",
        });
      },
    );

    it("auto uses Parakeet only for a language it transcribes", async () => {
      const both = { sherpa: true, mlx: true };
      expect(await transcribeWith("auto", both, "ja")).toMatchObject({ engine: "whisper" });
      expect(await transcribeWith("auto", both, "pt-BR")).toMatchObject({ engine: "parakeet" });
      expect(await transcribeWith("auto", both, "UK")).toMatchObject({ engine: "parakeet" });
      expect(transcribeMock).toHaveBeenCalledTimes(1);
    });

    it("sends a non-English language to an installed whisper, since Parakeet picks its own", async () => {
      const all = { sherpa: true, mlx: true, whisper: true };
      expect(await transcribeWith("auto", all, "fr")).toMatchObject({ engine: "whisper" });
      expect(await transcribeWith("parakeet", all, "es")).toMatchObject({ engine: "whisper" });
      expect(await transcribeWith("auto", all, "en-GB")).toMatchObject({ engine: "parakeet" });
      expect(await transcribeWith("auto", all)).toMatchObject({ engine: "parakeet" });
      const noWhisper = { sherpa: true, mlx: true, whisper: false };
      expect(await transcribeWith("auto", noWhisper, "fr")).toMatchObject({ engine: "parakeet" });

      Object.assign(runners, all);
      const { dir, input } = dummyAudio();
      dirs.push(dir);
      await transcribeCmd.run!({ args: { input, engine: "auto", language: "fr" } } as never);
      expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(
        "Parakeet chooses its own language, so whisper transcribes --language fr.",
      );
    });

    it("--engine parakeet with a language it does not transcribe fails without falling back", async () => {
      Object.assign(runners, { sherpa: true, mlx: true });
      const { exitCode, out } = await transcribeFails("parakeet", { language: "ja" });
      expect(exitCode).toBe(1);
      expect(out.error).toMatch(
        /^Parakeet does not transcribe --language ja; it covers en, es, .*uk\. Use --engine whisper\.$/,
      );
      expect(execFileMock).not.toHaveBeenCalled();
      expect(transcribeMock).not.toHaveBeenCalled();
    });

    it("listens for Ctrl-C from before audio prep until the run ends", async () => {
      const before = process.listenerCount("SIGINT");
      let duringPrep = 0;
      prepareWavMock.mockImplementation((input: string) => {
        duringPrep = process.listenerCount("SIGINT");
        return input;
      });
      expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({
        engine: "parakeet",
      });
      expect(duringPrep).toBe(before + 1);
      expect(process.listenerCount("SIGINT")).toBe(before);
    });

    it("exits 130 when Ctrl-C stops the whisper fallback too", async () => {
      crashChild("SIGABRT");
      // No signal reaches the listener in time: the synchronous whisper child's own signal decides.
      transcribeMock.mockImplementation(async () => {
        throw Object.assign(new Error("Command failed: whisper-cli"), { signal: "SIGINT" });
      });
      Object.assign(runners, { sherpa: true, mlx: false });
      const { exitCode, out } = await transcribeFails("auto");
      expect(exitCode).toBe(130);
      expect(out).toEqual({ ok: false, error: "Transcription cancelled" });
    });

    it("reports the fallback's own timeout as a failure, not a cancel", async () => {
      crashChild("SIGABRT");
      transcribeMock.mockImplementation(async () => {
        throw Object.assign(new Error("spawnSync whisper-cli ETIMEDOUT"), {
          code: "ETIMEDOUT",
          signal: "SIGTERM",
        });
      });
      Object.assign(runners, { sherpa: true, mlx: false });
      const { exitCode, out } = await transcribeFails("auto");
      expect(exitCode).toBe(1);
      expect(out.error).toMatch(/The whisper fallback failed too: spawnSync whisper-cli ETIMEDOUT/);
    });

    it("--engine parakeet with nothing installed names the install command", async () => {
      Object.assign(runners, { sherpa: false, mlx: false });
      const { dir, input } = dummyAudio();
      dirs.push(dir);
      await expect(
        transcribeCmd.run!({ args: { input, json: true, engine: "parakeet" } } as never),
      ).rejects.toThrow(CliRuntimeError);
      expect(lastJson().error).toContain("hyperframes models install parakeet");
      expect(transcribeMock).not.toHaveBeenCalled();
    });

    const crashChild = (signal: string, stderr = "") =>
      execFileMock.mockImplementation((_cmd, _args, _opts, done) => {
        done(Object.assign(new Error("Command failed"), { code: null, signal }), "", stderr);
      });

    async function transcribeFails(engine: string, extra: Record<string, unknown> = {}) {
      const { dir, input } = dummyAudio();
      dirs.push(dir);
      let exitCode = 0;
      try {
        await transcribeCmd.run!({ args: { input, json: true, engine, ...extra } } as never);
      } catch (err) {
        if (!(err instanceof CliRuntimeError)) throw err;
        exitCode = err.result.exitCode;
      }
      return { exitCode: exitCode || consumeCommandResult().exitCode, out: lastJson() };
    }

    it("auto names the Parakeet install when whisper is missing and Parakeet is not installed", async () => {
      transcribeMock.mockRejectedValue(new WhisperUnavailableError("whisper-cpp not found"));
      const { exitCode, out } = await transcribeFails("auto", { optional: true });
      expect(exitCode).toBe(0);
      expect(out).toEqual({
        ok: false,
        skipped: true,
        reason: "whisper_unavailable",
        install: "hyperframes models install parakeet",
      });
    });

    it.each([
      ["a language Parakeet does not transcribe", "auto", "ja"],
      ["an explicit --engine whisper", "whisper", undefined],
    ])("offers no Parakeet install for %s", async (_case, engine, language) => {
      transcribeMock.mockRejectedValue(new WhisperUnavailableError("whisper-cpp not found"));
      const { out } = await transcribeFails(engine, { optional: true, language });
      expect(out).toEqual({ ok: false, skipped: true, reason: "whisper_unavailable" });
    });

    it.each(["whisper", "auto"])(
      "--no-runtime-install reaches %s including the fallback",
      async (engine) => {
        crashChild("SIGABRT");
        Object.assign(runners, { sherpa: true, mlx: false });
        const { dir, input } = dummyAudio();
        dirs.push(dir);
        await runCommand(transcribeCmd, {
          rawArgs: [input, "--engine", engine, "--json", "--no-runtime-install"],
        });
        expect(transcribeMock.mock.calls.at(-1)?.[2]).toMatchObject({ installRuntime: false });
      },
    );

    it("auto falls back to whisper with one line naming the Parakeet error and the repair", async () => {
      crashChild("SIGABRT", "terminate called after throwing an instance of 'Ort::Exception'\n");
      expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({
        engine: "whisper",
        word: "whisper",
      });
      const warnings = vi.mocked(console.error).mock.calls.map(([line]) => String(line));
      expect(warnings).toHaveLength(1);
      expect(warnings[0]).toMatch(
        /^.*Parakeet failed: .*SIGABRT.*Ort::Exception.*hyperframes models install parakeet.*Using whisper/,
      );
    });

    it("an explicit --engine parakeet fails with the Parakeet error instead of falling back", async () => {
      crashChild("SIGABRT", "Protobuf parsing failed.\n");
      Object.assign(runners, { sherpa: true, mlx: false });
      const { exitCode, out } = await transcribeFails("parakeet");
      expect(exitCode).toBe(1);
      expect(out.error).toMatch(
        /^Parakeet failed: .*Protobuf parsing failed\. To repair it, run: hyperframes models install parakeet$/,
      );
      expect(transcribeMock).not.toHaveBeenCalled();
    });

    it("keeps a long decoder error whole up to a bound", async () => {
      crashChild(
        "SIGABRT",
        `HYPERFRAMES_PARAKEET_ERROR:${"a".repeat(590)} tail ${"b".repeat(2000)}\n`,
      );
      Object.assign(runners, { sherpa: true, mlx: false });
      const { out } = await transcribeFails("parakeet");
      expect(out.error).toContain(`${"a".repeat(590)} tail`);
      expect(out.error).toContain("b…. To repair it");
      expect(String(out.error).length).toBeLessThan(800);
    });

    it("reports the Parakeet error, not whisper_unavailable, when the fallback is missing too", async () => {
      crashChild("SIGABRT");
      transcribeMock.mockRejectedValue(new WhisperUnavailableError("whisper-cpp not found"));
      Object.assign(runners, { sherpa: true, mlx: false });
      const { exitCode, out } = await transcribeFails("auto", { optional: true });
      expect(exitCode).toBe(1);
      expect(out.skipped).toBeUndefined();
      expect(out.error).toMatch(/^Parakeet failed: .*install parakeet.*whisper-cpp not found/);
    });

    it("stops with exit 130 on Ctrl-C instead of falling back", async () => {
      crashChild("SIGINT");
      Object.assign(runners, { sherpa: true, mlx: false });
      const { exitCode, out } = await transcribeFails("auto");
      expect(exitCode).toBe(130);
      expect(out).toEqual({ ok: false, error: "Transcription cancelled" });
      expect(transcribeMock).not.toHaveBeenCalled();
    });

    describe.skipIf(process.platform === "win32")("when ffmpeg exits 255 while preparing", () => {
      it.each([
        ["Exiting normally, received signal 2.", 130, "Transcription cancelled"],
        [
          "Error opening input files: Operation not permitted",
          1,
          "ffmpeg failed: Error opening input files: Operation not permitted",
        ],
        [
          "Output file does not contain any stream\nError opening output files: Invalid argument",
          1,
          "ffmpeg failed: Error opening output files: Invalid argument\nOutput file does not contain any stream",
        ],
      ])("after saying %j, the run exits %i", async (said, code, error) => {
        vi.mocked(whisper.prepareWav).mockImplementation(realPrepareWav);
        const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-ffmpeg-"));
        dirs.push(dir);
        const ffmpeg = join(dir, "ffmpeg");
        const script = `process.stderr.write(${JSON.stringify(`${said}\n`)}); process.exit(255);`;
        writeFileSync(ffmpeg, `#!${process.execPath}\n${script}\n`);
        chmodSync(ffmpeg, 0o755);
        vi.stubEnv("HYPERFRAMES_FFMPEG_PATH", ffmpeg);
        Object.assign(runners, { sherpa: true, mlx: false });
        const { exitCode, out } = await transcribeFails("auto");
        expect(exitCode).toBe(code);
        expect(out).toEqual({ ok: false, error });
        expect(transcribeMock).not.toHaveBeenCalled();
      });
    });

    it("fails an unreadable input as an input error, with no Parakeet repair and no fallback", async () => {
      prepareWavMock.mockImplementation(() => {
        throw new Error("Command failed: ffmpeg -i silent.mp4 -vn -ar 16000");
      });
      Object.assign(runners, { sherpa: true, mlx: false });
      for (const optional of [false, true]) {
        const { exitCode, out } = await transcribeFails("auto", { optional });
        expect(exitCode).toBe(1);
        expect(out).toEqual({
          ok: false,
          error: "Command failed: ffmpeg -i silent.mp4 -vn -ar 16000",
        });
      }
      expect(execFileMock).not.toHaveBeenCalled();
      expect(transcribeMock).not.toHaveBeenCalled();
    });

    it("prepares the audio once, hands the same WAV to the fallback, and removes it", async () => {
      crashChild("SIGABRT");
      const prepared: string[] = [];
      prepareWavMock.mockImplementation((input: string) => {
        prepared.push(`${input}.16k.wav`);
        writeFileSync(prepared[0]!, "wav");
        return prepared[0]!;
      });
      expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({
        engine: "whisper",
      });
      expect(prepared).toHaveLength(1);
      const sherpaInput = JSON.parse(
        execFileMock.mock.calls[0]?.[2].env.HYPERFRAMES_PARAKEET_INPUT,
      );
      expect(sherpaInput.wavPath).toBe(prepared[0]);
      expect(transcribeMock.mock.calls[0]?.[0]).toBe(prepared[0]);
      expect(existsSync(prepared[0]!)).toBe(false);
    });

    it("gives the decode at least 30 minutes, and twice the audio length", async () => {
      Object.assign(runners, { sherpa: true, mlx: false });
      for (const [seconds, timeout] of [
        [60, 1_800_000],
        [3600, 7_200_000],
      ]) {
        audioSeconds = seconds!;
        const { dir, input } = dummyAudio();
        dirs.push(dir);
        await transcribeCmd.run!({ args: { input, json: true, engine: "auto" } } as never);
        expect(execFileMock.mock.calls.at(-1)?.[2]).toMatchObject({ timeout });
      }
      audioSeconds = 1;
    });

    it("succeeds with 0 words when the audio has no speech", async () => {
      execFileMock.mockImplementation((_cmd, _args, _opts, done) => {
        done(null, `HYPERFRAMES_PARAKEET_RESULT:${JSON.stringify([])}\n`, "");
      });
      Object.assign(runners, { sherpa: true, mlx: false });
      const { dir, input } = dummyAudio();
      dirs.push(dir);
      await transcribeCmd.run!({ args: { input, json: true, engine: "auto" } } as never);
      expect(lastJson()).toMatchObject({ ok: true, engine: "parakeet", wordCount: 0 });

      await transcribeCmd.run!({ args: { input, json: true, engine: "auto", to: "srt" } } as never);
      expect(lastJson()).toMatchObject({ ok: true, wordCount: 0, format: "srt" });
      expect(readFileSync(join(dir, "transcript.srt"), "utf-8")).toBe("");
    });

    it.runIf(process.platform === "linux" && process.arch === "x64")(
      "skips Parakeet when glibc is too old for sherpa-onnx, never naming the install command",
      async () => {
        vi.mocked(process.report.getReport).mockReturnValue({
          header: { glibcVersionRuntime: "2.31" },
        } as never);
        expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({
          engine: "whisper",
        });
        expect(execFileMock).not.toHaveBeenCalled();
        expect(console.error).not.toHaveBeenCalled();
        const { exitCode, out } = await transcribeFails("parakeet");
        expect(exitCode).toBe(1);
        expect(out.error).toMatch(
          /^Parakeet needs glibc 2\.32 or newer; this system has glibc 2\.31\.$/,
        );
      },
    );
  });

  it("imports an SRT and exports an SRT sidecar from transcript.json", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-test-"));
    dirs.push(dir);
    const input = join(dir, "sample.srt");
    const sample = `1
00:00:01,000 --> 00:00:03,500
Write HTML.

2
00:00:03,500 --> 00:00:06,000
Render video. Built for agents.
`;
    writeFileSync(input, sample);

    await transcribeCmd.run!({ args: { input, dir, json: true } } as never);
    const transcriptPath = join(dir, "transcript.json");

    await transcribeCmd.run!({ args: { input: transcriptPath, to: "srt", json: true } } as never);
    const outputPath = join(dir, "transcript.srt");

    expect(readFileSync(outputPath, "utf-8")).toBe(sample);
    const log = vi.mocked(console.log).mock.calls.at(-1)?.[0];
    expect(typeof log).toBe("string");
    if (typeof log !== "string") throw new Error("Expected JSON log output");
    expect(JSON.parse(log)).toEqual({
      ok: true,
      format: "srt",
      wordCount: 2,
      outputPath,
    });
  });

  it("transcribes a media file straight to a VTT sidecar in one run", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const words = [
      { id: "w0", text: "Write", start: 0, end: 0.5 },
      { id: "w1", text: "HTML.", start: 0.5, end: 1 },
    ];
    transcribeMock.mockImplementation(async (_input, outputDir) => {
      const result = fakeTranscript(outputDir, "whisper");
      writeFileSync(result.transcriptPath, JSON.stringify(words));
      return { ...result, wordCount: 2 };
    });

    await runCommand(transcribeCmd, {
      rawArgs: [input, "--dir", dir, "--engine", "whisper", "--to", "vtt", "--json"],
    });

    const outputPath = join(dir, "transcript.vtt");
    expect(readFileSync(outputPath, "utf-8")).toBe(formatVtt(words));
    expect(JSON.parse(readFileSync(join(dir, "transcript.json"), "utf8"))).toEqual(words);
    expect(console.log).toHaveBeenCalledTimes(1);
    expect(lastJson()).toMatchObject({ ok: true, wordCount: 2, format: "vtt", outputPath });
  });

  it("fails on a missing --output folder before transcribing", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const output = join(dir, "missing", "captions.srt");

    await expect(
      transcribeCmd.run!({
        args: { input, json: true, engine: "whisper", to: "srt", output },
      } as never),
    ).rejects.toThrow(CliRuntimeError);

    expect(transcribeMock).not.toHaveBeenCalled();
    expect(lastJson()).toEqual({
      ok: false,
      error: `Output folder not found: ${join(dir, "missing")}`,
    });
  });

  it.each([
    ["an existing folder", (dir: string) => dir, "--output is a folder"],
    [
      "a path ending in a slash",
      (dir: string) => join(dir, "captions") + "/",
      "--output is a folder",
    ],
    [
      "a path under a file",
      (dir: string) => join(dir, "narration.wav", "out.srt"),
      "Output folder not found",
    ],
    ["the input media", (dir: string) => join(dir, "narration.wav"), "would overwrite"],
    ["the transcript it writes", (dir: string) => join(dir, "transcript.json"), "would overwrite"],
    [
      "a link to the input media",
      (dir: string) => {
        symlinkSync(join(dir, "narration.wav"), join(dir, "link.wav"));
        return join(dir, "link.wav");
      },
      "would overwrite",
    ],
    [
      "the transcript through a linked folder",
      (dir: string) => {
        symlinkSync(dir, join(dir, "alias"), "dir");
        return join(dir, "alias", "transcript.json");
      },
      "would overwrite",
    ],
    [
      "the input media by its real path",
      (dir: string) => join(realpathSync(dir), "narration.wav"),
      "would overwrite",
    ],
    [
      "the transcript by its real path",
      (dir: string) => join(realpathSync(dir), "transcript.json"),
      "would overwrite",
    ],
    [
      "the transcript in other letter case",
      (dir: string) => join(dir, "Transcript.json"),
      "would overwrite",
    ],
  ])("fails --output naming %s before transcribing", async (_name, output, error) => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);

    await expect(
      transcribeCmd.run!({
        args: { input, json: true, engine: "whisper", to: "srt", output: output(dir) },
      } as never),
    ).rejects.toThrow(CliRuntimeError);

    expect(transcribeMock).not.toHaveBeenCalled();
    expect(lastJson()).toMatchObject({ ok: false, error: expect.stringContaining(error) });
  });

  it("refuses --output naming the input media in other letter case on any disk", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const output = join(dir, "NARRATION.WAV");
    // Case-insensitive disks alias the name to the media (same inode); case-sensitive ones do not.
    if (existsSync(output)) expect(statSync(output).ino).toBe(statSync(input).ino);

    await expect(
      transcribeCmd.run!({
        args: { input, json: true, engine: "whisper", to: "srt", output },
      } as never),
    ).rejects.toThrow(CliRuntimeError);

    expect(transcribeMock).not.toHaveBeenCalled();
    expect(lastJson()).toMatchObject({
      ok: false,
      error: expect.stringContaining("would overwrite"),
    });
    expect(readFileSync(input, "utf8")).toBe("not-real-audio");
  });

  it("refuses the transcript under an upper-cased folder spelling on a first run", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const upper = join(dirname(dir), basename(dir).toUpperCase());
    const caseInsensitive = existsSync(upper);

    await expect(
      transcribeCmd.run!({
        args: {
          input,
          json: true,
          engine: "whisper",
          to: "srt",
          output: join(upper, "transcript.json"),
        },
      } as never),
    ).rejects.toThrow(CliRuntimeError);

    expect(transcribeMock).not.toHaveBeenCalled();
    // Only a case-insensitive disk has the upper-cased folder; elsewhere it is simply missing.
    const error = caseInsensitive ? "would overwrite" : "Output folder not found";
    expect(lastJson()).toMatchObject({ ok: false, error: expect.stringContaining(error) });
  });

  it("refuses an export whose default caption path is its own input", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-test-"));
    dirs.push(dir);
    const input = join(dir, "transcript.srt");
    const srt = "1\n00:00:00,000 --> 00:00:01,000\n<i>Hello</i>\n";
    writeFileSync(input, srt);

    await expect(
      transcribeCmd.run!({ args: { input, json: true, to: "srt" } } as never),
    ).rejects.toThrow(CliRuntimeError);

    expect(lastJson()).toMatchObject({
      ok: false,
      error: expect.stringContaining("would overwrite"),
    });
    expect(readFileSync(input, "utf8")).toBe(srt);
  });

  it("says why an export's caption file could not be written", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-test-"));
    dirs.push(dir);
    const input = join(dir, "subtitles.srt");
    writeFileSync(input, "1\n00:00:00,000 --> 00:00:01,000\nHello\n");
    const output = join(dir, "through-file.vtt");
    symlinkSync(join(input, "x.vtt"), output);

    await expect(
      transcribeCmd.run!({ args: { input, json: true, to: "vtt", output } } as never),
    ).rejects.toThrow(CliRuntimeError);

    expect(lastJson()).toMatchObject({
      ok: false,
      error: expect.stringContaining(`The caption file ${output} could not be written: `),
    });
    // Windows and Unix report a path through a file with different error codes.
    expect(lastJson().error).toMatch(/ENOTDIR|ENOENT/);
  });

  async function runWithInodeZero(zero: (path: string) => boolean, args: object): Promise<void> {
    const realStatSync = fs.statSync;
    vi.spyOn(fs, "statSync").mockImplementation(((path: string, options?: object) => {
      const stats = realStatSync(path, options);
      return zero(String(path)) ? Object.assign(stats, { ino: 0n }) : stats;
    }) as unknown as typeof statSync);
    syncBuiltinESMExports();
    transcribeMock.mockImplementation(async (_input, outputDir) =>
      fakeTranscript(outputDir, "whisper"),
    );
    try {
      await transcribeCmd.run!({ args } as never);
    } catch (err) {
      if (!(err instanceof CliRuntimeError)) throw err;
    } finally {
      vi.mocked(fs.statSync).mockRestore();
      syncBuiltinESMExports();
    }
  }

  it("does not call two different files the same when the disk reports inode 0", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const output = join(dir, "captions.srt");
    writeFileSync(output, "old captions");

    await runWithInodeZero(() => true, { input, json: true, engine: "whisper", to: "srt", output });

    expect(lastJson()).toMatchObject({ ok: true, outputPath: output });
    expect(readFileSync(output, "utf8")).toContain("-->");
  });

  it.each([
    ["the media", "every path", "would overwrite"],
    ["the media", "the caption path only", "would overwrite"],
    ["the media", "the media only", "would overwrite"],
    ["the transcript", "every path", "it is the same file as"],
    ["the transcript", "the caption path only", "it is the same file as"],
    ["the transcript", "the transcript only", "it is the same file as"],
  ])("refuses a link to %s when %s reports inode 0", async (target, zeroed, error) => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const kept = target === "the media" ? input : join(dir, "transcript.json");
    const output = join(dir, "link.srt");
    symlinkSync(kept, output);
    const zeroPath = zeroed === "the caption path only" ? output : kept;

    await runWithInodeZero((path) => zeroed === "every path" || path === zeroPath, {
      input,
      json: true,
      engine: "whisper",
      to: "srt",
      output,
    });

    expect(lastJson()).toMatchObject({ ok: false, error: expect.stringContaining(error) });
    expect(readFileSync(kept, "utf8")).not.toContain("-->");
  });

  it("fails a trailing -o with no path before transcribing", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);

    await expect(
      runCommand(transcribeCmd, { rawArgs: [input, "--to", "srt", "--json", "-o"] }),
    ).rejects.toThrow(CliRuntimeError);

    expect(transcribeMock).not.toHaveBeenCalled();
    expect(lastJson()).toEqual({ ok: false, error: "--output needs a file path" });
  });

  it.each([
    [
      "a link to the transcript it is about to write",
      (dir: string) => {
        symlinkSync(join(dir, "transcript.json"), join(dir, "dangling.srt"));
        return join(dir, "dangling.srt");
      },
      "it is the same file as",
    ],
    [
      "a relative link to it inside a linked folder",
      (dir: string) => {
        mkdirSync(join(dir, "sub"));
        symlinkSync("../transcript.json", join(dir, "sub", "cap.srt"));
        symlinkSync(join(dir, "sub"), join(dir, "lnk"), "dir");
        return join(dir, "lnk", "cap.srt");
      },
      "it is the same file as",
    ],
    [
      "a link that runs through a file",
      (dir: string) => {
        symlinkSync(join(dir, "narration.wav", "x.srt"), join(dir, "through-file.srt"));
        return join(dir, "through-file.srt");
      },
      /ENOTDIR|ENOENT/,
    ],
  ])("keeps the transcript when --output is %s", async (_name, output, reason) => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const transcript = join(dir, "transcript.json");
    const caption = output(dir);
    transcribeMock.mockImplementation(async (_input, outputDir) =>
      fakeTranscript(outputDir, "whisper"),
    );

    await transcribeCmd.run!({
      args: { input, json: true, engine: "whisper", to: "srt", output: caption },
    } as never);

    expect(consumeCommandResult().exitCode).toBe(1);
    expect(lastJson()).toMatchObject({
      ok: false,
      error: expect.stringContaining(
        `Transcript saved to ${transcript}, but the caption file ${caption} could not be written: `,
      ),
    });
    expect(lastJson().error).toMatch(reason);
    expect(JSON.parse(readFileSync(transcript, "utf8"))).toMatchObject([{ text: "whisper" }]);
  });

  it("says the transcript was saved when the caption file cannot be written", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const output = join(dir, "captions.srt");
    transcribeMock.mockImplementation(async (_input, outputDir) => {
      // A folder at the caption path makes the write fail on any OS, even as root.
      mkdirSync(output);
      return fakeTranscript(outputDir, "whisper");
    });

    await transcribeCmd.run!({
      args: { input, json: true, engine: "whisper", to: "srt", output },
    } as never);

    expect(consumeCommandResult().exitCode).toBe(1);
    expect(lastJson()).toMatchObject({
      ok: false,
      error: expect.stringContaining(
        `Transcript saved to ${join(dir, "transcript.json")}, but the caption file ${output} could not be written: `,
      ),
    });
    expect(existsSync(join(dir, "transcript.json"))).toBe(true);
  });

  it("groups transcribed CJK words into captions instead of one cue per word", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    transcribeMock.mockImplementation(async (_input, outputDir) => {
      const result = fakeTranscript(outputDir, "whisper");
      writeFileSync(
        result.transcriptPath,
        JSON.stringify([
          { text: "今日はいい", start: 0, end: 0.8 },
          { text: "天気ですね", start: 0.8, end: 1.6 },
        ]),
      );
      return { ...result, wordCount: 2 };
    });

    await transcribeCmd.run!({
      args: { input, dir, json: true, engine: "whisper", to: "srt" },
    } as never);

    const { words: cues } = loadTranscript(join(dir, "transcript.srt"));
    expect(cues.map((cue) => cue.text)).toEqual(["今日はいい天気ですね"]);
  });

  it("rejects a below-minimum --timeout with a discoverable error", async () => {
    const { dir, input } = dummyAudio();
    dirs.push(dir);
    const consoleLog = vi.mocked(console.log);

    // 100 is well below the 5000ms minimum — must fail loud instead of silently
    // reverting to the auto-scaled default (the whole point of the flag is
    // that the user explicitly asked for a specific value).
    await expect(
      transcribeCmd.run!({ args: { input, json: true, timeout: "100" } } as never),
    ).rejects.toThrow(CliRuntimeError);

    const log = consoleLog.mock.calls.at(-1)?.[0];
    expect(typeof log).toBe("string");
    if (typeof log !== "string") throw new Error("Expected JSON log output");
    const parsed = JSON.parse(log);
    expect(parsed.ok).toBe(false);
    expect(parsed.error).toContain("--timeout");
    expect(parsed.error).toContain("5000");
  });

  it("--preserve-cues keeps single-word cues separate when exporting from JSON", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-test-"));
    dirs.push(dir);
    // Single-word cues have no internal whitespace, so the whitespace heuristic
    // can't tell them from word-level whisper output. --preserve-cues forces 1:1.
    const transcriptPath = join(dir, "transcript.json");
    writeFileSync(
      transcriptPath,
      JSON.stringify([
        { text: "Yes", start: 0, end: 1 },
        { text: "No", start: 1, end: 2 },
      ]),
    );

    await transcribeCmd.run!({
      args: { input: transcriptPath, to: "srt", "preserve-cues": true, json: true },
    } as never);

    const output = readFileSync(join(dir, "transcript.srt"), "utf-8");
    expect(output).toBe(
      "1\n00:00:00,000 --> 00:00:01,000\nYes\n\n2\n00:00:01,000 --> 00:00:02,000\nNo\n",
    );
  });
});