whisper-cli

name

whisper-cli

description

Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. MANDATORY: Execute whisper.cpp transcription operations using the `whisper` CLI tool. CLI interface for whisper.cpp (whisper-cli) local, offline speech-to-text; output mirrors the openai-whisper CLI. Triggers: whisper, whisper cli, whisper.cpp, whisper-cli, transcribe audio, local transcription, speech to text, ggml transcript

Execute whisper.cpp transcription operations using the `whisper` CLI. All whisper.cpp interactions should use this CLI. It runs entirely offline against a local ggml model and emits transcripts whose shape matches the `openai-whisper` CLI, so the two are drop-in swappable.

<quick_start> The whisper CLI follows this pattern:

whisper <command-group> <action> [arguments] [options]

Task	Command
Transcribe a file (JSON)	whisper transcripts create audio.wav
Word-level timestamps	whisper transcripts create audio.wav --word-timestamps
Pick a language	whisper transcripts create audio.wav --language es
Use a specific model	whisper transcripts create audio.wav --model /path/to/ggml-small.en.bin
Table view of segments	whisper transcripts create audio.wav --table
List local ggml models	whisper transcripts models
</quick_start>

<essential_principles> MANDATORY: Verify the live command shape before executing ANY whisper command. Consult usage.json when the repo or installed package ships it. If usage.json is absent, use whisper --help, the relevant subcommand --help, and README.md instead. Never guess at command syntax.

whisper.cpp is a local, offline tool. There is no auth, no cache, and no network calls. The wrapper resolves the `whisper-cli` binary and a local ggml model, normalizes input to 16 kHz mono WAV via `ffmpeg`, runs whisper.cpp, and returns JSON. - **transcripts create** -- Transcribe an audio/video file into a JSON transcript with timestamped segments (seconds). With `--word-timestamps`, the output also includes a word-level `words` array. - **transcripts models** -- List local ggml model files found in the models directory. - Model: `--model` > env `WHISPER_CPP_MODEL` > default `~/.local/share/cli-tools/whisper/models/ggml-base.en.bin` - Binary: env `WHISPER_CLI_PATH` > env `WHISPER_CLI_COMMAND` > default `whisper-cli` A missing binary or missing model fails fast with a clear error (no fallback).

<reference_index> usage.json -- Complete command tree with arguments, options, defaults, and usage instructions when present. whisper --help and subcommand --help -- Live installed command tree and option list. README.md -- Supplemental examples and workflow notes. </reference_index>

<success_criteria>

• Command executes without error
• Output is displayed in requested format (JSON by default, table with --table)
• Correct command and flags used, verified against the live help output or usage.json when present </success_criteria>