Implementation:Openai Whisper DecodingOptions

Overview

DecodingOptions is a frozen dataclass that encapsulates all configuration parameters for Whisper's autoregressive decoding process. It is defined in whisper/decoding.py at lines 80-115. Being a frozen dataclass means that once instantiated, its fields cannot be modified, ensuring immutability throughout the decoding pipeline.

All fields have default values, so a bare DecodingOptions() call produces a valid configuration for greedy English transcription.

Source

• File: whisper/decoding.py:L80-115
• Import: from whisper.decoding import DecodingOptions or from whisper import DecodingOptions
• Repository: https://github.com/openai/whisper

Signature

@dataclass(frozen=True)
class DecodingOptions:
    task: str = "transcribe"
    language: Optional[str] = None
    temperature: float = 0.0
    sample_len: Optional[int] = None
    best_of: Optional[int] = None
    beam_size: Optional[int] = None
    patience: Optional[float] = None
    length_penalty: Optional[float] = None
    prompt: Optional[Union[str, List[int]]] = None
    prefix: Optional[Union[str, List[int]]] = None
    suppress_tokens: Optional[Union[str, Iterable[int]]] = "-1"
    suppress_blank: bool = True
    without_timestamps: bool = False
    max_initial_timestamp: Optional[float] = 1.0
    fp16: bool = True

Parameters

Parameter	Type	Default	Description
task	str	"transcribe"	"transcribe" for same-language transcription (X to X) or "translate" for translation to English (X to English)
language	Optional[str]	None	Language code (e.g., "en", "ja"). None triggers automatic language detection.
temperature	float	0.0	0.0 for greedy decoding, >0 enables sampling with temperature scaling.
sample_len	Optional[int]	None	Maximum number of tokens to generate.
best_of	Optional[int]	None	Number of independent samples for n-best sampling. Mutually exclusive with beam_size.
beam_size	Optional[int]	None	Beam width for beam search decoding. Mutually exclusive with best_of.
patience	Optional[float]	None	Beam search patience factor. Controls how long beams are allowed to continue.
length_penalty	Optional[float]	None	Penalty applied to sequence scores based on length during beam search.
prompt	Optional[Union[str, List[int]]]	None	Previous context or user-provided text, placed before the start-of-transcript token.
prefix	Optional[Union[str, List[int]]]	None	Text forced at the start of decoding, placed after the start-of-transcript token.
suppress_tokens	Optional[Union[str, Iterable[int]]]	"-1"	Token IDs to suppress. -1 maps to a default list of non-speech symbol tokens.
suppress_blank	bool	True	Suppress blank and end-of-text tokens at the start of sampling.
without_timestamps	bool	False	Disable timestamp token generation.
max_initial_timestamp	Optional[float]	1.0	Maximum allowed time (in seconds) for the first timestamp token.
fp16	bool	True	Use half-precision (float16) inference. Set to False for CPU.

Inputs and Outputs

• Inputs: User configuration choices (keyword arguments to the dataclass constructor)
• Outputs: A frozen DecodingOptions dataclass instance used by DecodingTask and decode()

Usage Examples

from whisper import DecodingOptions

# Greedy decoding (default)
options = DecodingOptions()

# Beam search decoding
options = DecodingOptions(beam_size=5, language="en")

# Translation mode with sampling
options = DecodingOptions(task="translate", temperature=0.2, best_of=5)

# Without timestamps
options = DecodingOptions(without_timestamps=True, language="ja")

Key Constraints

• beam_size and best_of are mutually exclusive. Setting both will raise an error in DecodingTask.
• fp16=True requires a CUDA-capable GPU. For CPU inference, set fp16=False.
• The dataclass is frozen: attempting to modify a field after creation raises FrozenInstanceError.
• suppress_tokens="-1" is a string that gets resolved to a predefined list of non-speech token IDs during decoding setup.

See Also

• Principle:Openai_Whisper_Decoding_Configuration