---
name: openai-whisper
source: https://app.decimal.ai/s/openai-whisper@1/SKILL.md
source_sha256: ec141e14c88c
---

# OpenAI Whisper CLI idiom

## Contract

Enforces the real, current command-line interface of OpenAI's **local** Whisper tool (the `whisper`
binary from the `openai-whisper` package). Apply whenever the task is to write a shell command that
transcribes or translates an audio file with Whisper on the user's own machine — choosing a model,
an output format, an output folder, a language, timestamps, or precision. The base model knows
Whisper exists but reproduces the flags in wrong forms; this pins the exact tokens the CLI accepts.

## Rules

1. **Binary + positional audio.** The command is `whisper <audio> [<audio> ...] [options]`. The
   audio file paths are POSITIONAL arguments, not a `--file`/`--input` flag. Pass several files to
   one invocation to batch them. This is the local CLI — not the hosted OpenAI transcription API and
   not a Python snippet, unless the user asks for code.

2. **Long options are snake_case (underscores), NEVER hyphens.** argparse defines them with
   underscores and rejects the hyphenated form with "unrecognized arguments". Every multi-word flag:
   `--output_format`, `--output_dir`, `--model_dir`, `--word_timestamps`, `--initial_prompt`,
   `--max_line_width`, `--max_line_count`, `--max_words_per_line`, `--highlight_words`,
   `--condition_on_previous_text`, `--suppress_tokens`, `--best_of`, `--beam_size`,
   `--clip_timestamps`, `--length_penalty`, `--logprob_threshold`, `--no_speech_threshold`. Do NOT
   write `--output-format`, `--output-dir`, `--word-timestamps`, etc.

3. **`--model` takes a LOCAL model name.** The valid names are `tiny`, `base`, `small`, `medium`,
   `large` (and `large-v1`/`large-v2`/`large-v3`), and `turbo`, plus the English-only variants
   `tiny.en`, `base.en`, `small.en`, `medium.en`. The default is `turbo`. Do NOT use the hosted API
   model name `whisper-1`, the HuggingFace id `openai/whisper-*`, or a whisper.cpp `ggml-*.bin`
   filename — those are different products. Smaller = faster; `large`/`large-v3` = most accurate.

4. **English-only audio → an `.en` model.** For material that is entirely English, a `.en` variant
   (`base.en`, `small.en`, …) is faster and slightly more accurate than the multilingual model of the
   same size.

5. **Output format is `--output_format` (alias `-f`).** The value is exactly one of
   `txt`, `vtt`, `srt`, `tsv`, `json`, `all`; the default is `all`. Do NOT invent `--format`,
   `--srt`, `--json`, `--subtitle`, or `--output-format`. Meanings: `txt` plain text, `srt` SubRip
   subtitles, `vtt` WebVTT captions, `tsv` tab-separated start/end/text columns, `json` structured
   with timings, `all` writes every type.

6. **Output folder is `--output_dir` (alias `-o`), default `.`.** Not `--out`, `--output`, `--dir`.

7. **Translation is `--task translate`.** `--task` is `transcribe` (default) or `translate`, and
   `translate` ALWAYS produces English (Whisper only does X→English). Do NOT write `--translate`,
   `--to en`, `--target-language`, or `--english`.

8. **Language is `--language`.** The value is the language NAME (`Japanese`, `Spanish`) or its code
   (`ja`, `es`). Setting it skips auto-detection. Not `--lang`, `--source-language`, `--locale`.

9. **Boolean options take an explicit `True`/`False` value.** They are parsed with str2bool, so you
   MUST supply the value: `--word_timestamps True`, `--fp16 False`, `--verbose False`,
   `--highlight_words True`, `--condition_on_previous_text False`. Do NOT use a bare switch
   (`--word_timestamps`) or a `--no-...` negation (`--no-fp16`).

10. **Word timestamps + subtitle line control.** `--word_timestamps True` emits per-word timing.
    Line length in the SRT/VTT is then capped with `--max_line_width N` and `--max_line_count N`;
    `--highlight_words True` underlines each word as spoken (it depends on word timestamps).

11. **Vocabulary bias is `--initial_prompt "..."`.** Feed known names/jargon spellings as its string
    value to steer transcription. Not `--prompt`, `--vocab`, `--hint`.

12. **Device & precision.** `--device cuda` or `--device cpu`; force full precision on CPU with
    `--fp16 False`. Silence per-segment console output with `--verbose False`.

13. **Model cache.** Weights download to `~/.cache/whisper` on first run; relocate them with
    `--model_dir PATH`. Not `--cache-dir`, `--download-dir`.

## Worked examples

BEFORE = the base model's wrong default → AFTER = the conforming Whisper CLI form.

**Subtitles.**
```bash
# BEFORE
whisper interview.mp3 --format srt --output-dir ./out
# AFTER
whisper interview.mp3 --output_format srt --output_dir ./out
```

**Translate to English.**
```bash
# BEFORE
whisper japanese_lecture.wav --translate --to en
# AFTER
whisper japanese_lecture.wav --language Japanese --task translate
```

**Model name.**
```bash
# BEFORE
whisper podcast.m4a --model whisper-1
# AFTER
whisper podcast.m4a --model medium        # local names: tiny/base/small/medium/large/turbo (+ .en)
```

**Word timestamps + boolean value.**
```bash
# BEFORE
whisper seminar.wav --word-timestamps
# AFTER
whisper seminar.wav --word_timestamps True
```

**Full precision on CPU.**
```bash
# BEFORE
whisper clip.wav --device cpu --no-fp16
# AFTER
whisper clip.wav --device cpu --fp16 False
```

**Relocate the model cache.**
```bash
# BEFORE
whisper notes.ogg --download-dir /data/models
# AFTER
whisper notes.ogg --model_dir /data/models     # default cache is ~/.cache/whisper
```

## Edge cases & exceptions

- **`translate` only goes to English.** There is no target-language option; to get English from any
  language, use `--task translate`. For a same-language transcript use `--task transcribe` (default).
- **`.en` models exist only up to `medium`.** There is no `large.en`; for English at the largest
  size use the plain multilingual `large`/`large-v3` or `turbo`.
- **`--highlight_words True` and line caps require `--word_timestamps True`.** Word-level features are
  no-ops without it.
- **Line-length caps only affect SRT/VTT.** `--max_line_width`/`--max_line_count` shape subtitle
  files, not the `txt`/`json`/`tsv` outputs.
- **`--output_format all` is the default.** Only narrow it when the user wants a single type.
- **The positional path can be several files.** `whisper a.wav b.wav c.wav ...` processes each.

## Do / Don't

- DON'T hyphenate long options (`--output-format`, `--output-dir`, `--word-timestamps`). ALWAYS use
  underscores (`--output_format`, `--output_dir`, `--word_timestamps`).
- DON'T pass `--model whisper-1` or `openai/whisper-*`. ALWAYS use a local name
  (`tiny`/`base`/`small`/`medium`/`large`/`turbo`, or an `.en` variant).
- DON'T write `--format`, `--srt`, `--json`. ALWAYS use `--output_format <txt|vtt|srt|tsv|json|all>`.
- DON'T write `--translate` or `--to en`. ALWAYS use `--task translate` (output is English).
- DON'T write `--lang`. ALWAYS use `--language <name-or-code>`.
- DON'T write bare booleans or `--no-...`. ALWAYS give the explicit value (`--fp16 False`,
  `--word_timestamps True`).
- DON'T use `--out`/`--dir` for the folder. ALWAYS use `--output_dir` (or `-o`).

## Common mistakes (the base model's wrong defaults)

- Hyphenating the multi-word flags, which argparse rejects.
- Reaching for the hosted API model name `whisper-1` for the local CLI.
- Inventing `--format`/`--srt`/`--subtitle` instead of `--output_format srt`.
- Using `--translate`/`--to en`/`--target-language` instead of `--task translate`.
- Using `--lang` instead of `--language`.
- Writing bare boolean switches or `--no-fp16` instead of the `True`/`False` value form.
- Using `--out`/`--output` for the destination folder instead of `--output_dir`.
- Assuming `translate` can target a non-English language.

## Quick checklist

- [ ] `whisper <audio> ...` with the file as a positional argument (local CLI, not the API).
- [ ] Long options in snake_case (`--output_format`, `--output_dir`, `--word_timestamps`).
- [ ] `--model` = a local name (`tiny`/`base`/`small`/`medium`/`large`/`turbo`, `.en` for English).
- [ ] `--output_format` value ∈ {txt, vtt, srt, tsv, json, all}; `--output_dir` for the folder.
- [ ] `--task translate` for English output; `--language <name-or-code>` to set the language.
- [ ] Booleans with explicit values (`--fp16 False`, `--word_timestamps True`).
- [ ] `--initial_prompt "..."` to bias vocabulary; `--model_dir` to relocate the cache.