fix(cli): classify missing whisper-cpp as a setup gap, not a command error (#1628)

transcribe hard-failed with cli_error whenever whisper-cpp was absent. On
Linux/Docker/CI (no Homebrew, no compiler toolchain) that is unavoidable, so it
drove ~30k cli_error/day that are really "install the prerequisite" rather than
bugs — and buried genuine transcription failures in the command-error budget.

ensureWhisper now throws a typed WhisperUnavailableError when no binary exists
and none can be built. The transcribe command reports that on a dedicated
transcribe_unavailable metric instead of cli_error, and a new --optional flag
lets pipelines skip captions and exit 0. Real transcription crashes still fail
as cli_error. init and the skill pipelines already continue without captions.

Also removes a stale doc reference to a `transcribe --provider groq` flag that
does not exist.
This commit is contained in:
Miguel Ángel
2026-06-21 20:39:19 -04:00
committed by GitHub
parent a843b2acb7
commit f12754f5ad
6 changed files with 156 additions and 5 deletions
@@ -144,7 +144,7 @@ Generate the full script as `narration.wav` (or `.mp3`) in the project directory
1. **Try again** — kill the process, run the same command again (transient failures are common)
2. **Try different flags** — smaller model (`--model tiny.en`), different voice, shorter test sentence first
3. **Try a different tool for the same task** — if `hyperframes transcribe` hangs, try `whisper-cli` directly, or Groq API (`npx hyperframes transcribe --provider groq`), or OpenAI API
3. **Try a different tool for the same task** — if `hyperframes transcribe` hangs, run `whisper-cli` directly on the audio
4. **Switch provider entirely** — if ElevenLabs is down, try HeyGen or Kokoro. If Kokoro hangs, try ElevenLabs.
Never sit idle for 10 minutes hoping a stuck process will finish.