mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-10 22:20:14 +00:00
feat(cli): configurable transcribe timeout with duration-scaled default
Adds a `--timeout <ms>` CLI flag (and `HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS` env var) plus a model-slowdown factor in the auto-scaled default so `hyperframes transcribe` doesn't hard-fail with `spawnSync ETIMEDOUT` on slow CPUs running heavier whisper models. Field-signal ts=1784165471 (win32/arm64 emulating x64 on Snapdragon, CLI 0.7.59) reported the failure on a 63s wav with `-m medium` at ~13x realtime — the historical 10x-realtime scale (PR #2463) gave 10.5 min while the machine needed ~13.7 min. Splitting audio and merging offsets was the manual workaround. - Add `--timeout <ms>` and `HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS` (min 5000). Explicit override bypasses auto-scaling; still capped at 12h. - Add per-model slowdown factor (tiny 0.5, base 0.7, small 1, medium 2, large 4, large-v3-turbo 2). Multiplied into the 10s/audio-second baseline so medium/large get proportional headroom while `small.en` (the default) preserves the historical safety window. - Wrap whisper's spawn error with a discoverability hint naming `--timeout`, the env var, and the effective timeout when the child was killed by SIGTERM/ETIMEDOUT (mirrors PR #2504 protocol-timeout). - Docs: new `--timeout` row in `docs/packages/cli.mdx` Flags table. Regression coverage in `packages/cli/src/whisper/transcribe.test.ts` (56 tests) and `packages/cli/src/commands/transcribe.test.ts` (5 tests): - Model factor per known name + case-insensitive + safe unknown fallback. - 63s field-signal case on medium.en → 1_260_000ms (was 630_000ms). - Explicit override honored below the auto floor + capped at 12h. - Model factor ignored when overrideMs is set. - SIGTERM/ETIMEDOUT detection + augmented message contract. - CLI rejects below-minimum `--timeout` with error naming both the flag and the 5000ms floor. — Via Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Via
@@ -1,8 +1,11 @@
|
||||
import { describe, expect, it, test } from "vitest";
|
||||
import {
|
||||
dtwPresetForModel,
|
||||
isWhisperTimeoutError,
|
||||
resolveAudioPreparationTimeoutMs,
|
||||
resolveWhisperTimeoutMs,
|
||||
whisperModelSlowdownFactor,
|
||||
wrapWhisperTimeoutError,
|
||||
} from "./transcribe.js";
|
||||
|
||||
describe("dtwPresetForModel", () => {
|
||||
@@ -55,6 +58,179 @@ describe("resolveWhisperTimeoutMs", () => {
|
||||
});
|
||||
});
|
||||
|
||||
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 a Node SIGTERM child-timeout error", () => {
|
||||
const err = Object.assign(new Error("Command failed"), { signal: "SIGTERM" });
|
||||
expect(isWhisperTimeoutError(err)).toBe(true);
|
||||
});
|
||||
|
||||
it("returns true for an ETIMEDOUT-coded error", () => {
|
||||
const err = Object.assign(new Error("Command failed"), { code: "ETIMEDOUT" });
|
||||
expect(isWhisperTimeoutError(err)).toBe(true);
|
||||
});
|
||||
|
||||
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"), { 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],
|
||||
|
||||
@@ -46,19 +46,95 @@ const AUDIO_PREPARATION_TIMEOUT_PER_MEDIA_SECOND_MS = 500;
|
||||
const AUDIO_PREPARATION_TIMEOUT_CAP_MS = 21_600_000;
|
||||
|
||||
/**
|
||||
* Give long recordings enough time to transcribe while retaining a bounded
|
||||
* failure window. Short recordings keep the historical five-minute timeout.
|
||||
* 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.
|
||||
*/
|
||||
export function resolveWhisperTimeoutMs(durationSeconds: number | null): number {
|
||||
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) {
|
||||
return WHISPER_TIMEOUT_FLOOR_MS;
|
||||
// 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),
|
||||
Math.ceil(durationSeconds * WHISPER_TIMEOUT_PER_AUDIO_SECOND_MS * factor),
|
||||
),
|
||||
);
|
||||
}
|
||||
@@ -185,6 +261,12 @@ export interface TranscribeOptions {
|
||||
model?: string;
|
||||
language?: string;
|
||||
onProgress?: (message: string) => void;
|
||||
/**
|
||||
* 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 TranscribeResult {
|
||||
@@ -388,11 +470,26 @@ export async function transcribe(
|
||||
}
|
||||
whisperArgs.push(wavPath);
|
||||
|
||||
const whisperTimeoutMs = resolveWhisperTimeoutMs(getPreparedWavDurationSeconds(wavPath));
|
||||
execFileSync(whisper.executablePath, whisperArgs, {
|
||||
stdio: "ignore",
|
||||
timeout: whisperTimeoutMs,
|
||||
const whisperTimeoutMs = resolveWhisperTimeoutMs(getPreparedWavDurationSeconds(wavPath), {
|
||||
model: effectiveModel,
|
||||
overrideMs: options?.timeoutMs,
|
||||
});
|
||||
try {
|
||||
execFileSync(whisper.executablePath, whisperArgs, {
|
||||
stdio: "ignore",
|
||||
timeout: whisperTimeoutMs,
|
||||
});
|
||||
} 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. Non-timeout errors flow through unchanged so the
|
||||
// existing stderr-tail handling in `transcribeAudio` still applies.
|
||||
throw wrapWhisperTimeoutError(err, {
|
||||
effectiveTimeoutMs: whisperTimeoutMs,
|
||||
model: effectiveModel,
|
||||
wasOverride: options?.timeoutMs != null,
|
||||
});
|
||||
}
|
||||
|
||||
// 6. Read and validate output
|
||||
const transcriptPath = `${outputBase}.json`;
|
||||
@@ -433,3 +530,51 @@ export async function transcribe(
|
||||
speechOnsetSeconds,
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Timeout error discoverability
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
// Node's `execFileSync` kills the child with SIGTERM when its `timeout` option
|
||||
// fires, so the resulting Error carries `signal === "SIGTERM"`. On some platforms
|
||||
// / Node versions `code === "ETIMEDOUT"` is also set. Match either signal so we
|
||||
// don't miss a timeout on a platform we haven't validated.
|
||||
export function isWhisperTimeoutError(err: unknown): boolean {
|
||||
if (!(err instanceof Error)) return false;
|
||||
const record = err as { signal?: unknown; code?: unknown };
|
||||
return record.signal === "SIGTERM" || record.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;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user