Configuration

Complete reference for the whisper CLI and the whisper.transcribe() Python API. The CLI is defined in whisper/transcribe.py:cli; most flags map 1:1 to keyword arguments of transcribe() (or DecodingOptions).

Model and I/O

CLI flag	Python argument	Default	Notes
--model	model.load_model(name)	turbo	One of the names in whisper.available_models(), or a path to a .pt checkpoint.
--model_dir	download_root	~/.cache/whisper	Where to cache downloaded checkpoints.
--device	device	cuda if available, else cpu	device= to load_model.
--output_dir/-o	—	.	Where transcripts are written.
--output_format/-f	—	all	One of txt, vtt, srt, tsv, json, all.
--verbose	verbose	True	True prints decoded segments live; False shows a tqdm bar; None is silent.
--threads	torch.set_num_threads	0	CPU-only; supersedes MKL_NUM_THREADS / OMP_NUM_THREADS.

Task and language

CLI flag	Python argument	Default	Notes
--task	task	transcribe	Or translate (X→English; multilingual non-turbo models only).
--language	language	auto-detect	Either an ISO 639-1 code (en, ja, zh) or an English name (English, Japanese). See Tokenizer for the full set.

Sampling

CLI flag	Python argument	Default	Notes
--temperature	temperature	0	Combined with temperature_increment_on_fallback to build a schedule.
--temperature_increment_on_fallback	temperature (tuple)	0.2	Combined into (t, t+inc, …, 1.0).
--best_of	DecodingOptions.best_of	5	Sampling: number of independent samples per audio at t > 0.
--beam_size	DecodingOptions.beam_size	5	Beam search at t == 0.
--patience	DecodingOptions.patience	None (= 1.0)	Patience factor; max candidates is round(beam_size * patience).
--length_penalty	DecodingOptions.length_penalty	None	Google-NMT α (in [0,1]).
--suppress_tokens	DecodingOptions.suppress_tokens	-1	-1 → tokenizer.non_speech_tokens; or comma-separated ints.
--initial_prompt	initial_prompt	None	Bias the first window. The text is tokenized and prepended.
--carry_initial_prompt	carry_initial_prompt	False	Prepend initial_prompt to every internal decode call.
--condition_on_previous_text	condition_on_previous_text	True	Forward previous output as the next chunk's prompt.
--fp16	DecodingOptions.fp16	True	Forced to False on CPU.

Fallback thresholds

CLI flag	Python argument	Default	Effect
--compression_ratio_threshold	compression_ratio_threshold	2.4	Above this gzip ratio, treat output as too repetitive — fallback.
--logprob_threshold	logprob_threshold	-1.0	Below this avg log-prob, treat as too uncertain — fallback.
--no_speech_threshold	no_speech_threshold	0.6	Above this no-speech prob (with avg log-prob also low), skip chunk as silent.

Word timestamps

CLI flag	Python argument	Default	Notes
--word_timestamps	word_timestamps	False	Enable per-word timing.
--prepend_punctuations	prepend_punctuations	"\"'"¿([{-	Punctuation merged into the next word.
--append_punctuations	append_punctuations	"\"'.。,，!！?？:：")]}、	Punctuation merged into the previous word.
--highlight_words	(writer kwarg)	False	Underline active word in VTT/SRT.
--max_line_width	(writer kwarg)	None	Subtitle line wrap width.
--max_line_count	(writer kwarg)	None	Subtitle line count per cue (requires --max_line_width).
--max_words_per_line	(writer kwarg)	None	Words per subtitle cue (no effect with --max_line_width).
--hallucination_silence_threshold	hallucination_silence_threshold	None	Skip silence longer than this when an anomalous segment is detected.

Clip selection

CLI flag	Python argument	Default	Notes
--clip_timestamps	clip_timestamps	0	start,end,start,end,... seconds. The last end defaults to EOF.

CLI-only validations

cli() enforces:

• --max_line_count has no effect without --max_line_width (warning).
• --max_words_per_line has no effect with --max_line_width (warning).
• --highlight_words, --max_line_count, --max_line_width, --max_words_per_line all require --word_timestamps True (error).
• For an .en model with a non-English --language, the language is reset to en (warning).

Python API extras (no CLI)

A few DecodingOptions fields are not exposed via the CLI but can be passed to transcribe() as **decode_options:

• prefix — text or token IDs that should appear at the start of the decoded output (rather than as preceding context).
• prompt — text or token IDs of preceding context. The CLI sets this to initial_prompt indirectly.
• without_timestamps — emit <|notimestamps|> so the model does not output timestamp tokens. The CLI never enables this; transcribe() always wants timestamps.
• max_initial_timestamp — clamp the first emitted timestamp to be ≤ this many seconds (default 1.0).
• sample_len — cap on tokens to sample (default n_text_ctx // 2).

See also

• Decoding — how each DecodingOptions field maps to logit filters and decoders.
• Transcribe — how the CLI flags are consumed by transcribe().
• Models — model sizes and English-only variants.