Skip to content

caption only ever spawns whisper, but doctor probes three names, so doctor can be green while caption fails #146

Open

Description

@Phelim2023315

Summary

doctor and caption resolve the Whisper binary differently:

  • src/doctor.ts — onPath("whisper") ?? onPath("whisper-cli") ?? onPath("faster-whisper")
  • src/caption.ts — const cmd = opts.whisperCmd ?? "whisper"; and, with no
    explicit --whisper-engine, detectEngine() assumes the openai dialect

So on a host whose only Whisper is whisper.cpp — a whisper-cli binary and no
whisper — doctor reports the check as ok, and the first caption run fails
with ENOENT while the error text points at --whisper-engine, not at the command
name that could not be found. whisper-cli is the name whisper.cpp has shipped
since v1.7.4 (previously main), and what Homebrew's whisper-cpp installs, so
this is the common case, not an exotic one.

Reproduction

Any host with whisper-cli on PATH and no whisper:

$ capcut doctor -H
[✓] whisper            found: /opt/homebrew/bin/whisper-cli

$ capcut caption ./my-draft --audio ./voice.wav --language zh
# → whisper CLI failed: spawnSync whisper ENOENT
#   Tried: whisper ./voice.wav --model base --language zh ...
#   Select the matching dialect with --whisper-engine openai|whisper-cpp|faster-whisper

Note the hint: the user is told to pick a dialect, but the actual problem is that
whisper was never the installed command name. The same mismatch hides a second
bug — even when the command is found by some other route, dialect detection
still reads the unresolved default, so a whisper.cpp binary would be driven with
openai's argument shape.

Measured on Windows 10.0.19045 with whisper.cpp's whisper-cli.exe; the same
resolution order is what a caller has to work around with
--whisper-cmd <path> --whisper-engine whisper-cpp today.

Expected

One resolver used by both, so doctor's answer is the answer caption obeys:
--whisper-cmd wins, then the first of whisper / whisper-cli /
faster-whisper actually on PATH, then the historical default — and dialect
detection reads whatever that resolved to.

Proposed fix

src/whisper.ts owns the PATH lookup and the preference list; doctor and
caption both call resolveWhisperCommand(). Explicit flags keep priority. The
resolver accepts an injectable probe so the order is tested without a real
Whisper install.

Patch: submitted as a PR from the same batch.

Activity

  1. renezander030 commented on Oct 14, 2026

    @renezander030
    Owner

    Thanks for the clear repro! The shared resolver in #149 looks like the right fix, with explicit command and engine flags keeping priority. Keeping this open until the PR passes CI and lands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions