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.

1. 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.

1. --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.

1. 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.

1. 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.

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

1. 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.

1. 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.

1. 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).

1. 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).

1. Vocabulary bias is --initial_prompt "...". Feed known names/jargon spellings as its string

value to steer transcription. Not --prompt, --vocab, --hint.

1. Device & precision. --device cuda or --device cpu; force full precision on CPU with

--fp16 False. Silence per-segment console output with --verbose False.

1. 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.