Skip to content

Write HTML. Render video. Built for agents.

14.0 KB
Raw Blame
import { chmodSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, test } from "vitest";
import {
  getPreparedWavDurationSeconds,
  initialModelForLanguage,
  isPcm16kMono,
  isWhisperTimeoutError,
  prepareWav,
  resolveAudioPreparationTimeoutMs,
  resolveWhisperTimeoutMs,
  whisperModelSlowdownFactor,
  withoutPaths,
  wrapWhisperTimeoutError,
} from "./transcribe.js";

describe("withoutPaths", () => {
  it("leaves only file names of absolute paths, and leaves other slashes alone", () => {
    expect(
      withoutPaths(
        `loading '${join(homedir(), ".cache", "m", "ggml-tiny.bin")}' from /opt/x/lib/libwhisper.1.dylib (C:\\Users\\me\\w.exe), file:/srv/a/talk.wav [/srv/b/c.wav] 1/2 done`,
      ),
    ).toBe(
      "loading 'ggml-tiny.bin' from libwhisper.1.dylib (w.exe), file:talk.wav [c.wav] 1/2 done",
    );
  });
});

describe("resolveWhisperTimeoutMs", () => {
  it("keeps the existing five-minute floor for short recordings", () => {
    expect(resolveWhisperTimeoutMs(10)).toBe(300_000);
  });

  it("scales the timeout for long recordings", () => {
    expect(resolveWhisperTimeoutMs(41 * 60)).toBe(24_600_000);
  });

  it("caps the safety window at twelve hours", () => {
    expect(resolveWhisperTimeoutMs(24 * 60 * 60)).toBe(43_200_000);
  });

  it("falls back to five minutes when duration is unavailable", () => {
    expect(resolveWhisperTimeoutMs(null)).toBe(300_000);
    expect(resolveWhisperTimeoutMs(Number.NaN)).toBe(300_000);
  });

  it.each([
    [30, 300_000],
    [30.1, 301_000],
    [4319, 43_190_000],
    [4320, 43_200_000],
  ])("clamps duration %ss to %sms", (duration, expected) => {
    expect(resolveWhisperTimeoutMs(duration)).toBe(expected);
  });
});

describe("whisperModelSlowdownFactor", () => {
  it.each([
    ["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],
  ])("returns factor %s for known model %s", (model, expected) => {
    expect(whisperModelSlowdownFactor(model)).toBe(expected);
  });

  it("is case-insensitive", () => {
    expect(whisperModelSlowdownFactor("MEDIUM.EN")).toBe(2);
    expect(whisperModelSlowdownFactor("Large-V3")).toBe(4);
  });

  it("falls back to the small.en baseline (1) for unknown model names", () => {
    // Unknown model names must never shorten the safety window, so the default
    // is the baseline factor rather than a smaller (tiny/base) value.
    expect(whisperModelSlowdownFactor("my-custom-finetune")).toBe(1);
  });
});

describe("resolveWhisperTimeoutMs with model factor", () => {
  it("keeps small.en (default) at the historical baseline for 63s clips", () => {
    // Regression guard: `small.en` (the CLI default model) must not lose
    // headroom when the caller passes a model. 63s * 10s/s * 1 = 630_000ms.
    expect(resolveWhisperTimeoutMs(63, { model: "small.en" })).toBe(630_000);
  });

  it("doubles the auto-scaled window for medium.en (field-signal ts=1784165471)", () => {
    // 63s clip on medium.en: emulated arm64/x64 saw ~13x realtime — 63*13 =
    // 819s needed. The 10x baseline (630_000ms = 10.5min) was insufficient;
    // the 2x medium factor lifts it to 1_260_000ms (21min), covering the
    // reported case with margin.
    expect(resolveWhisperTimeoutMs(63, { model: "medium.en" })).toBe(1_260_000);
  });

  it("quadruples the auto-scaled window for the large family", () => {
    expect(resolveWhisperTimeoutMs(60, { model: "large-v3" })).toBe(2_400_000);
  });

  it("still enforces the five-minute floor on tiny/base short clips", () => {
    // 10s * 10 * 0.5 = 50_000ms — below the floor, so the floor wins.
    expect(resolveWhisperTimeoutMs(10, { model: "tiny.en" })).toBe(300_000);
  });

  it("still enforces the twelve-hour cap on large-model marathon clips", () => {
    // 4320s * 10 * 4 = 172_800_000ms — the cap wins.
    expect(resolveWhisperTimeoutMs(4320, { model: "large-v3" })).toBe(43_200_000);
  });

  it("scales the null-duration fallback by the model factor", () => {
    // When ffprobe can't read the WAV, we lose duration signal but still know
    // the model. Scaling the floor keeps heavy models proportionally covered.
    expect(resolveWhisperTimeoutMs(null, { model: "medium.en" })).toBe(600_000);
    expect(resolveWhisperTimeoutMs(null, { model: "large-v3" })).toBe(1_200_000);
    expect(resolveWhisperTimeoutMs(null, { model: "small.en" })).toBe(300_000);
  });
});

describe("resolveWhisperTimeoutMs with overrideMs", () => {
  it("respects the explicit override even below the auto-scaled floor", () => {
    // A user who deliberately passed --timeout 30000 on a short clip meant 30s,
    // not five minutes. The auto-scaled floor must NOT stomp on the explicit
    // value — that would silently defeat the flag.
    expect(resolveWhisperTimeoutMs(60, { overrideMs: 30_000 })).toBe(30_000);
  });

  it("caps the override at the twelve-hour ceiling", () => {
    // A runaway value still can't hang the process forever.
    expect(resolveWhisperTimeoutMs(60, { overrideMs: 999_999_999 })).toBe(43_200_000);
  });

  it("ignores the model factor when overrideMs is set", () => {
    // Override wins outright — the model factor only affects the auto-scaled
    // path. Otherwise `--timeout 60000` on `medium.en` would silently become
    // 120_000ms and break the discoverability contract.
    expect(resolveWhisperTimeoutMs(60, { overrideMs: 60_000, model: "medium.en" })).toBe(60_000);
  });

  it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY])(
    "falls back to auto-scaling when overrideMs is invalid (%s)",
    (invalid) => {
      // Invalid override → auto-scaled default kicks in (10s * 10 = 100_000ms →
      // floor 300_000ms). Prevents callers from accidentally disabling the
      // timeout via a bad env var.
      expect(resolveWhisperTimeoutMs(10, { overrideMs: invalid })).toBe(300_000);
    },
  );
});

describe("isWhisperTimeoutError", () => {
  it("returns true for execFileSync's own timeout (ETIMEDOUT with SIGTERM)", () => {
    const err = Object.assign(new Error("Command failed"), {
      code: "ETIMEDOUT",
      signal: "SIGTERM",
    });
    expect(isWhisperTimeoutError(err)).toBe(true);
  });

  it("returns false for a SIGTERM someone else sent, so it reaches the cancel rule", () => {
    const err = Object.assign(new Error("Command failed"), { signal: "SIGTERM" });
    expect(isWhisperTimeoutError(err)).toBe(false);
  });

  it("returns false for a non-timeout child error", () => {
    const err = Object.assign(new Error("Exit code 1"), { status: 1, signal: null });
    expect(isWhisperTimeoutError(err)).toBe(false);
  });

  it("returns false for a plain string", () => {
    expect(isWhisperTimeoutError("boom")).toBe(false);
  });
});

describe("wrapWhisperTimeoutError", () => {
  it("passes non-timeout errors through unchanged", () => {
    const err = new Error("segfault");
    const result = wrapWhisperTimeoutError(err, {
      effectiveTimeoutMs: 600_000,
      model: "small.en",
      wasOverride: false,
    });
    expect(result).toBe(err);
  });

  it("wraps SIGTERM timeouts with a discoverable hint naming --timeout and the env var", () => {
    const original = Object.assign(new Error("Command failed"), {
      code: "ETIMEDOUT",
      signal: "SIGTERM",
    });
    const wrapped = wrapWhisperTimeoutError(original, {
      effectiveTimeoutMs: 1_260_000,
      model: "medium.en",
      wasOverride: false,
    });
    // Discoverability contract: message must name the flag, env var, effective
    // timeout, and cite the model so slow-CPU reporters see the knob.
    expect(wrapped).not.toBe(original);
    expect(wrapped.message).toContain("--timeout");
    expect(wrapped.message).toContain("HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS");
    expect(wrapped.message).toContain("1260s");
    expect(wrapped.message).toContain("medium.en");
    expect((wrapped as { cause?: unknown }).cause).toBe(original);
  });

  it("labels the source as explicit when wasOverride is true", () => {
    const original = Object.assign(new Error("Command failed"), { code: "ETIMEDOUT" });
    const wrapped = wrapWhisperTimeoutError(original, {
      effectiveTimeoutMs: 90_000,
      model: "medium.en",
      wasOverride: true,
    });
    expect(wrapped.message).toContain("explicit --timeout 90000ms");
  });

  it("coerces non-Error timeout-shaped values to Error without augmenting", () => {
    // A non-Error thrown value can't carry `.signal`, so it flows through
    // untouched but is still normalized to an Error instance for downstream
    // handlers that use instanceof checks.
    const wrapped = wrapWhisperTimeoutError("something bad", {
      effectiveTimeoutMs: 600_000,
      model: "small.en",
      wasOverride: false,
    });
    expect(wrapped).toBeInstanceOf(Error);
    expect(wrapped.message).toBe("something bad");
    expect(wrapped.message).not.toContain("--timeout");
  });
});

describe("resolveAudioPreparationTimeoutMs", () => {
  it.each([
    [10, 120_000],
    [6 * 60 * 60, 10_800_000],
    [24 * 60 * 60, 21_600_000],
  ])("scales duration %ss to %sms", (duration, expected) => {
    expect(resolveAudioPreparationTimeoutMs(duration)).toBe(expected);
  });

  it("falls back to two minutes when duration is unavailable", () => {
    expect(resolveAudioPreparationTimeoutMs(null)).toBe(120_000);
    expect(resolveAudioPreparationTimeoutMs(Number.NaN)).toBe(120_000);
  });
});

describe("initialModelForLanguage", () => {
  test("keeps the default English-only model when no language is specified", () => {
    expect(initialModelForLanguage("small.en", undefined)).toBe("small.en");
  });

  test("uses the multilingual model before downloading for explicit German", () => {
    expect(initialModelForLanguage("small.en", "de")).toBe("small");
  });

  test("keeps English-only models for English locale variants", () => {
    expect(initialModelForLanguage("small.en", "en-US")).toBe("small.en");
  });

  test("keeps an already multilingual model unchanged", () => {
    expect(initialModelForLanguage("large-v3", "de")).toBe("large-v3");
  });
});

describe("isPcm16kMono", () => {
  it("passes only 16-bit PCM through; 24-bit and float WAV go through ffmpeg", () => {
    const wav = (codec_name: string) => ({ codec_name, sample_rate: "16000", channels: 1 });
    expect(isPcm16kMono(wav("pcm_s16le"))).toBe(true);
    expect(isPcm16kMono(wav("pcm_s24le"))).toBe(false);
    expect(isPcm16kMono(wav("pcm_f32le"))).toBe(false);
    expect(isPcm16kMono({ ...wav("pcm_s16le"), sample_rate: "24000" })).toBe(false);
  });
});

describe("getPreparedWavDurationSeconds", () => {
  it("reads the length from the size alone, whatever comes before the samples", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-wav-duration-"));
    const wav = join(dir, "prepared.wav");
    writeFileSync(wav, Buffer.concat([Buffer.alloc(6000), Buffer.alloc(1.5 * 32_000)]));
    expect(getPreparedWavDurationSeconds(wav)).toBeCloseTo(1.69, 2);
    expect(getPreparedWavDurationSeconds(join(dir, "missing.wav"))).toBeNull();
    rmSync(dir, { recursive: true, force: true });
  });
});

describe.skipIf(process.platform === "win32")("prepareWav", () => {
  it("removes the partial WAV when ffmpeg fails or is stopped", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-prepare-wav-"));
    const ffmpeg = join(dir, "ffmpeg");
    writeFileSync(
      ffmpeg,
      `#!${process.execPath}\nrequire("fs").writeFileSync(process.argv.at(-1), "partial");\nprocess.exit(255);\n`,
    );
    chmodSync(ffmpeg, 0o755);
    const leftovers = () =>
      readdirSync(tmpdir()).filter((f) => f.startsWith(`hyperframes-audio-${process.pid}-`));
    const saved = process.env.HYPERFRAMES_FFMPEG_PATH;
    process.env.HYPERFRAMES_FFMPEG_PATH = ffmpeg;
    try {
      for (const input of ["talk.mp3", "talk.mp4"]) {
        await expect(prepareWav(join(dir, input))).rejects.toThrow(/Command failed/);
        expect(leftovers()).toEqual([]);
      }
    } finally {
      if (saved === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
      else process.env.HYPERFRAMES_FFMPEG_PATH = saved;
      rmSync(dir, { recursive: true, force: true });
    }
  });

  async function failWith(script: string): Promise<unknown> {
    const dir = mkdtempSync(join(tmpdir(), "hf-prepare-wav-"));
    const ffmpeg = join(dir, "ffmpeg");
    writeFileSync(ffmpeg, `#!${process.execPath}\n${script}\n`);
    chmodSync(ffmpeg, 0o755);
    const saved = process.env.HYPERFRAMES_FFMPEG_PATH;
    process.env.HYPERFRAMES_FFMPEG_PATH = ffmpeg;
    try {
      await prepareWav(join(dir, "talk.mp3"));
    } catch (err) {
      return err;
    } finally {
      if (saved === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
      else process.env.HYPERFRAMES_FFMPEG_PATH = saved;
      rmSync(dir, { recursive: true, force: true });
    }
    throw new Error("prepareWav did not fail");
  }

  it("keeps ffmpeg's stderr on the error, so the cause above its summary line is shown", async () => {
    const said =
      "Output file does not contain any stream\nError opening output files: Invalid argument";
    const err = await failWith(`process.stderr.write(${JSON.stringify(said)}); process.exit(234);`);
    expect(err).toMatchObject({ cancelled: false, stderr: said });
  });

  it("reads a cancel only from ffmpeg's own signal line, not a path that mentions one", async () => {
    const said = "/in/received signal.mp3: Invalid data found when processing input";
    const err = await failWith(`process.stderr.write(${JSON.stringify(said)}); process.exit(255);`);
    expect(err).toMatchObject({ cancelled: false });
  });

  it("rethrows Node's own failure (output overflow) as is, never as a cancel", async () => {
    const flood = `require("fs").writeSync(2, "Exiting normally, received signal 2.\\n" + "x".repeat(65 << 20));`;
    const err = (await failWith(`${flood} process.exit(255);`)) as {
      code?: string;
      cancelled?: boolean;
    };
    expect(err.code).toBe("ENOBUFS");
    expect(err.cancelled).toBeUndefined();
  });
});