Faster Whisper

https://github.com/systran/faster-whisper
Admin
Faster Whisper is a reimplementation of OpenAI's Whisper model using CTranslate2, offering up to 4x...
Tokens:67,188
Snippets:375
Trust Score:6.8
License:MIT
Update:13 hours ago
Show doc for...
Tokens:
Raw
### Install faster-whisper from PyPI, master branch, or a specific commit

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Install the faster-whisper module from PyPI (recommended), the master branch, or a specific commit using a direct URL.

```bash
pip install faster-whisper

```

```bash
pip install --force-reinstall "faster-whisper @ https://github.com/SYSTRAN/faster-whisper/archive/refs/heads/master.tar.gz"

```

```bash
pip install --force-reinstall "faster-whisper @ https://github.com/SYSTRAN/faster-whisper/archive/a4f1cc8f11433e454c3934442b5e1a4ed5e865c3.tar.gz"

```

--------------------------------

### Install NVIDIA cuBLAS and cuDNN 9 with pip (Linux)

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Installs the required NVIDIA libraries (cuBLAS and cuDNN 9) using pip, which is only supported on Linux. After installation, the LD_LIBRARY_PATH environment variable must be set to the library paths as shown.

```bash
pip install nvidia-cublas-cu12 nvidia-cudnn-cu12==9.*

export LD_LIBRARY_PATH=$(python3 -c 'import os, nvidia.cublas, nvidia.cudnn; print(os.path.dirname(nvidia.cublas.__path__[0]) + "/cublas/lib:" + os.path.dirname(nvidia.cudnn.__path__[0]) + "/cudnn/lib")')
```

--------------------------------

### Install faster-whisper in editable mode with dev dependencies

Source: https://github.com/systran/faster-whisper/blob/master/CONTRIBUTING.md

Clones the repository, changes into the directory, and installs the package in editable mode with the 'dev' extra requirements. Use this to set up a development environment for faster-whisper.

```bash
git clone https://github.com/SYSTRAN/faster-whisper.git
cd faster-whisper/
pip install -e .[dev]
```

--------------------------------

### get_prompt usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Example call to get_prompt with no previous tokens and without_timestamps=True, producing a prompt like [<|startoftranscript|>, <|en|>, <|transcribe|>, <|notimestamps|>].

```python
prompt = model.get_prompt(tokenizer, previous_tokens=[], without_timestamps=True)
# e.g. [<|startoftranscript|>, <|en|>, <|transcribe|>, <|notimestamps|>]
```

--------------------------------

### SileroVADModel usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Shows how to load the VAD model and get speech probabilities per 512-sample window.

```python
from faster_whisper.vad import get_vad_model

model = get_vad_model()
probs = model(audio)   # one probability per 512-sample window
print(probs.shape)
```

--------------------------------

### download_model usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/utils.md

Downloads the 'small' model into './models' and prints the resulting path.

```python
from faster_whisper import download_model

path = download_model("small", output_dir="./models")
print(path)
```

--------------------------------

### Example usage of generate_with_fallback

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Shows how to call generate_with_fallback and print the result sequences, average log probability, temperature, and compression ratio.

```python
result, avg_logprob, temperature, compression_ratio = model.generate_with_fallback(
    encoder_output, prompt, tokenizer, options
)
print(result.sequences_ids[0], avg_logprob, temperature, compression_ratio)
```

--------------------------------

### Tokenizer instantiation example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/tokenizer.md

Shows how to create a Tokenizer from a WhisperModel's tokenizer and multilingual flag, specifying task and language. Requires importing from faster_whisper.tokenizer and faster_whisper.

```python
from faster_whisper.tokenizer import Tokenizer
from faster_whisper import WhisperModel

model = WhisperModel("small", device="cpu")
tokenizer = Tokenizer(model.hf_tokenizer, model.model.is_multilingual, task="transcribe", language="en")
```

--------------------------------

### available_models usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/utils.md

Iterates over the model names returned by available_models() and prints each one.

```python
from faster_whisper import available_models

for name in available_models():
    print(name)
```

--------------------------------

### Batched transcription with BatchedInferencePipeline (turbo model)

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Runs batched transcription using BatchedInferencePipeline.transcribe, a drop-in replacement for WhisperModel.transcribe, on an example audio file with batch_size=16 and printing segment timestamps and text.

```python
from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model=model)
segments, info = batched_model.transcribe("audio.mp3", batch_size=16)

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

```

--------------------------------

### Basic transcription example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model.md

Loads a small model on CPU with int8 quantization and transcribes an audio file with beam size 5, printing segment timestamps and text.

```python
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("audio.mp3", beam_size=5)
for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))
```

--------------------------------

### Example: get_speech_timestamps usage

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Example usage of get_speech_timestamps with VadOptions. Decodes audio from a file, runs VAD with custom min_silence_duration_ms and speech_pad_ms, and prints start/end sample indices for each speech chunk.

```python
import numpy as np
from faster_whisper.audio import decode_audio
from faster_whisper.vad import VadOptions, get_speech_timestamps

audio = decode_audio("speech.mp3")
chunks = get_speech_timestamps(
    audio,
    vad_options=VadOptions(min_silence_duration_ms=500, speech_pad_ms=200),
)
for chunk in chunks:
    print(chunk["start"], chunk["end"])
```

--------------------------------

### generate_segments usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Example of calling generate_segments directly with features, tokenizer, options, and log_progress=False, then iterating over the returned segments to print their text.

```python
segments = model.generate_segments(features, tokenizer, options, log_progress=False)
for segment in segments:
    print(segment.text)
```

--------------------------------

### Example: encode/decode round trip

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/tokenizer.md

Shows encoding and decoding a string, including timestamp decoding.

```python
ids = tokenizer.encode("Hello world")
print(ids)
print(tokenizer.decode(ids))                       # "Hello world"
print(tokenizer.decode_with_timestamps([50362]))   # "<|0.22|>" style output
```

--------------------------------

### format_timestamp usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/utils.md

Example usage of format_timestamp from faster_whisper. Shows default output, hours included with always_include_hours=True, and custom decimal_marker=",".

```python
from faster_whisper import format_timestamp

print(format_timestamp(65.4321))                    # 01:05.432
print(format_timestamp(65.4321, always_include_hours=True))   # 00:01:05.432
print(format_timestamp(0.5, decimal_marker=","))     # 00:00.500

```

--------------------------------

### Basic transcription with WhisperModel (large-v3) and generator handling

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Basic Faster-Whisper usage: loads a model on GPU or CPU with different compute types)Skip, transcribes an audio file with beam_size=5, and prints language and segment timestamps. The segments object is a generator, so transcription only starts when iterating (e.g., by converting to a list).

```python
from faster_whisper import WhisperModel

model_size = "large-v3"

# Run on GPU with FP16
model = WhisperModel(model_size, device="cuda", compute_type="float16")

# or run on GPU with INT8
# model = WhisperModel(model_size, device="cuda", compute_type="int8_float16")
# or run on CPU with INT8
# model = WhisperModel(model_size, device="cpu", compute_type="int8")

segments, info = model.transcribe("audio.mp3", beam_size=5)

print("Detected language '%s' with probability %f" % (info.language, info.language_probability))

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

```

```python
segments, _ = model.transcribe("audio.mp3")
segments = list(segments)  # The transcription will actually run here.

```

--------------------------------

### pad_or_trim example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/audio.md

Pads a feature array to 3000 frames along the last axis, or trims to a custom length. The default length matches the Whisper encoder's expected input size.

```python
import numpy as np
from faster_whisper.audio import pad_or_trim

features = np.zeros((80, 1000), dtype="float32")
padded = pad_or_trim(features)         # shape (80, 3000)
trimmed = pad_or_trim(features, length=500)
```

--------------------------------

### download_model error handling example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/utils.md

Catches the ValueError raised for an invalid model size and prints the error message.

```python
from faster_whisper.utils import download_model

try:
    download_model("not-a-model")
except ValueError as e:
    print(e)  # Invalid model size 'not-a-model', expected one of: ...
```

--------------------------------

### detect_language usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model.md

Loads a small model, decodes an audio file, and calls detect_language with VAD filtering enabled. Prints the detected language, probability, and all language probabilities.

```python
import numpy as np
from faster_whisper import WhisperModel
from faster_whisper.audio import decode_audio

model = WhisperModel("small", device="cpu")
waveform = decode_audio("speech.wav")
language, prob, all_probs = model.detect_language(audio=waveform, vad_filter=True)
print(language, prob, all_probs)
```

--------------------------------

### Configure faster_whisper logger level

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/configuration.md

Configure the package's single module logger named "faster_whisper" externally. The logger is obtained via `get_logger` in `utils.py:44`. This example sets the log level to DEBUG after basic configuration.

```python
import logging

logging.basicConfig()
logging.getLogger("faster_whisper").setLevel(logging.DEBUG)

```

--------------------------------

### decode_audio stereo split and error handling example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/audio.md

Decodes a stereo audio file into separate left and right channels. Catches FileNotFoundError for invalid paths.

```python
from faster_whisper.audio import decode_audio

try:
    left, right = decode_audio("two_speakers.mp4", sampling_rate=16000, split_stereo=True)
    print(left.shape, right.shape)
except FileNotFoundError:
    print("audio file not found")
```

--------------------------------

### Convert original Whisper large-v3 model to CTranslate2 with FP16 quantization

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Converts the original OpenAI Whisper large-v3 model and saves weights in FP16. Requires installing transformers[torch]>=4.23 first. The --model option accepts a Hub model name or a local directory path; omitting --copy_files tokenizer.json means the tokenizer configuration is downloaded automatically when the model is loaded later.

```bash
pip install transformers[torch]>=4.23

ct2-transformers-converter --model openai/whisper-large-v3 --output_dir whisper-large-v3-ct2
--copy_files tokenizer.json preprocessor_config.json --quantization float16
```

--------------------------------

### SileroVADModel constructor

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Initializes the VAD model by importing onnxruntime and configuring a CPU InferenceSession with specific thread and memory settings. Raises RuntimeError if onnxruntime is not installed.

```python
class SileroVADModel:
    def __init__(self, path):
```

--------------------------------

### decode_audio basic example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/audio.md

Decodes a mono audio file to a float32 NumPy array at 16000 Hz. The returned array has shape (N,) and dtype float32.

```python
from faster_whisper.audio import decode_audio

mono = decode_audio("speech.webm", sampling_rate=16000)
print(mono.dtype, mono.shape)  # float32 (N,)
```

--------------------------------

### encode usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model.md

Creates a tiny model, extracts features from a zero-filled 16 kHz waveform, and encodes them. Prints the type of the encoder output, which is a ctranslate2.StorageView.

```python
import numpy as np
model = WhisperModel("tiny")
features = model.feature_extractor(np.zeros(16000, dtype=np.float32))
encoder_output = model.encode(features)
print(type(encoder_output))  # <class 'ctranslate2.StorageView'>
```

--------------------------------

### Instantiate BatchedInferencePipeline with WhisperModel

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/batched-inference-pipeline.md

Example of creating a WhisperModel and wrapping it in a BatchedInferencePipeline. Uses the 'turbo' model on CUDA with float16 compute type.

```python
from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model)
```

--------------------------------

### FeatureExtractor usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/feature-extractor.md

Creates a default FeatureExtractor (80 mels, 16 kHz, 30 s chunks), generates a 3-second random waveform, and computes its log-Mel spectrogram. Output shape is (80, 3001).

```python
import numpy as np
from faster_whisper.feature_extractor import FeatureExtractor

extractor = FeatureExtractor()                       # 80 mels, 16 kHz, 30 s chunks
waveform = np.random.rand(16000 * 3).astype("float32")  # 3 seconds
mel = extractor(waveform)
print(mel.shape)  # (80, 3001)
```

--------------------------------

### STFT with error handling example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/feature-extractor.md

Calls FeatureExtractor.stft on a random 16000-sample float32 array with n_fft=400, hop_length=160, and return_complex=True. Prints the output shape or catches ValueError and prints the error message.

```python
import numpy as np
from faster_whisper.feature_extractor import FeatureExtractor

try:
    spec = FeatureExtractor.stft(
        np.random.rand(16000).astype("float32"), n_fft=400, hop_length=160, return_complex=True
    )
    print(spec.shape)
except ValueError as e:
    print("stft failed:", e)
```

--------------------------------

### Core public workflow: WhisperModel.transcribe

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/index.md

Loads a WhisperModel and transcribes an audio file with beam search. The returned `segments` is a generator, so transcription only starts when the iterable is consumed (e.g., via `list(segments)` or a `for` loop).

```python
from faster_whisper import WhisperModel

model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("audio.mp3", beam_size=5)

print(info.language, info.language_probability)   # e.g. "en" 0.98
for segment in segments:                          # transcription runs here (generator)
    print(segment.start, segment.end, segment.text)
```

--------------------------------

### forward method signature

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/batched-inference-pipeline.md

Runs one batch: calls generate_segment_batched, then splits output tokens per chunk using WhisperModel._split_segments_by_timestamps with segment_size = ceil(duration) * model.frames_per_second. Produces per-subsegment dicts with text, avg_logprob, no_speech_prob, tokens, start, end, compression_ratio, seek. When options.word_timestamps is set, calls model.add_word_timestamps over all chunk outputs with the shared last_speech_timestamp. Returns a list (per chunk) of lists of segment dicts.

```python
def forward(self, features, tokenizer, chunks_metadata, options):
```

--------------------------------

### SpeechTimestampsMap usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Example of using SpeechTimestampsMap to convert a VAD-relative time to original audio time. Requires chunks and sampling_rate=16000.

```python
from faster_whisper.vad import SpeechTimestampsMap

ts_map = SpeechTimestampsMap(chunks, sampling_rate=16000)
original = ts_map.get_original_time(1.25, is_end=False)
print(original)
```

--------------------------------

### faster-whisper package entry point (__init__.py)

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/index.md

Re-exports the public API of the faster-whisper library. Use this to import the main classes and functions.

```python
from faster_whisper.audio import decode_audio
from faster_whisper.transcribe import BatchedInferencePipeline, WhisperModel
from faster_whisper.utils import available_models, download_model, format_timestamp
from faster_whisper.version import __version__

__all__ = [
    "available_models",
    "decode_audio",
    "WhisperModel",
    "BatchedInferencePipeline",
    "download_model",
    "format_timestamp",
    "__version__",
]
```

--------------------------------

### Format and lint code with black, isort, and flake8

Source: https://github.com/systran/faster-whisper/blob/master/CONTRIBUTING.md

Runs the code formatter (black), import sorter (isort), and linter (flake8) on the codebase. These tools help maintain consistent style and catch potential issues before submitting a pull request.

```bash
black .
```

```bash
isort .
```

```bash
flake8 .
```

--------------------------------

### Word-level timestamps with word_timestamps=True

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Enables word-level timestamps by setting word_timestamps=True; each segment now has a words attribute containing per-word start, end, and text.

```python
segments, _ = model.transcribe("audio.mp3", word_timestamps=True)

for segment in segments:
    for word in segment.words:
        print("[%.2fs -> %.2fs] %s" % (word.start, word.end, word.word))

```

--------------------------------

### Run the test suite with pytest

Source: https://github.com/systran/faster-whisper/blob/master/CONTRIBUTING.md

Executes the existing test suite located in the 'tests/' directory. Run this to verify that changes do not break existing functionality.

```bash
pytest tests/
```

--------------------------------

### _split_segments_by_timestamps signature

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Private method that splits a decoded token sequence into segments at timestamp tokens. Parameters: tokenizer, tokens, time_offset (window start in seconds), segment_size (window size in feature frames), segment_duration (window duration in seconds), seek (current feature-frame position). Returns (current_segments, seek, single_timestamp_ending) where current_segments is a list of dicts with keys seek, start, end, tokens. Called by both pipelines.

```python
def _split_segments_by_timestamps(
    self,
    tokenizer: Tokenizer,
    tokens: List[int],
    time_offset: float,
    segment_size: int,
    segment_duration: float,
    seek: int,
) -> List[List[int]]:
```

--------------------------------

### WhisperModel constructor

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/configuration.md

Initializes a WhisperModel instance with configurable options for model size, device, compute type, and more. This is the primary entry point for loading a Whisper model.

```APIDOC
## WhisperModel constructor

### Description
Initializes a WhisperModel instance with configurable options for model size, device, compute type, and more.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **model_size_or_path** (str) - Required - Size name, model directory path, or HF repo ID.
- **device** (str) - Optional - `"cpu"`, `"cuda"`, `"auto"`. Default: `"auto"`.
- **device_index** (Union[int, List[int]]) - Optional - Device ID(s); a list enables multi-GPU parallel transcription. Default: `0`.
- **compute_type** (str) - Optional - CTranslate2 precision/quantization: `"float16"`, `"int8_float16"`, `"int8"`, `"float32"`, etc. See https://opennmt.net/CTranslate2/quantization.html. Default: `"default"`.
- **cpu_threads** (int) - Optional - CPU threads (CTranslate2 `intra_threads`). Default: `0`.
- **num_workers** (int) - Optional - CTranslate2 `inter_threads` (parallel decodes across threads). Default: `1`.
- **download_root** (Optional[str]) - Optional - HF cache dir for downloads. Default: `None`.
- **local_files_only** (bool) - Optional - Never download; local cache only. Default: `False`.
- **files** (dict) - Optional - In-memory model files (`config.json`, `model.bin`, `tokenizer.json`, `preprocessor_config.json`). Default: `None`.
- **revision** (Optional[str]) - Optional - HF Git revision. Default: `None`.
- **use_auth_token** (Optional[Union[str, bool]]) - Optional - HF auth token / `True`. Default: `None`.
- **model_kwargs** (dict) - Optional - Forwarded to `ctranslate2.models.Whisper(...)`.

### Notes
Derived constants set at construction: `input_stride = 2`, `time_precision = 0.02` s, `max_length = 448` tokens.
```

--------------------------------

### collect_chunks usage example

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Shows how to call collect_chunks with a max_duration of 30 seconds and iterate over the returned metadata to print offset, duration, and segments.

```python
from faster_whisper.vad import collect_chunks

audio_chunks, chunks_metadata = collect_chunks(audio, chunks, max_duration=30)
for meta in chunks_metadata:
    print(meta["offset"], meta["duration"], meta["segments"])
```

--------------------------------

### SileroVADModel.__init__(path)

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Constructor for the SileroVADModel class. It imports onnxruntime and configures a CPU InferenceSession with specific session options and provider.

```APIDOC
## SileroVADModel.__init__(path)

### Description
Constructor for the SileroVADModel class. It imports onnxruntime and configures a CPU InferenceSession with specific session options and provider.

### Method
Constructor

### Signature
```python
def __init__(self, path):
```

### Parameters
- **path** - Path to the VAD model file.

### Errors
- **RuntimeError** - Raised if onnxruntime is not installed: "Applying the VAD filter requires the onnxruntime package".
```

--------------------------------

### WhisperModel.__init__

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model.md

Constructor for the WhisperModel class. Initializes the model with the given size or path, device, compute type, and other options.

```APIDOC
## WhisperModel.__init__

### Description
Constructor for the WhisperModel class. Initializes the model with the given size or path, device, compute type, and other options.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    model_size_or_path: str,
    device: str = "auto",
    device_index: Union[int, List[int]] = 0,
    compute_type: str = "default",
    cpu_threads: int = 0,
    num_workers: int = 1,
    download_root: Optional[str] = None,
    local_files_only: bool = False,
    files: dict = None,
    revision: Optional[str] = None,
    use_auth_token: Optional[Union[str, bool]] = None,
    **model_kwargs,
):
```

### Parameters
- **model_size_or_path** (str) - Required - Model size (`tiny`, `tiny.en`, `base`, `base.en`, `small`, `small.en`, `distil-small.en`, `medium`, `medium.en`, `distil-medium.en`, `large-v1`, `large-v2`, `large-v3`, `large`, `distil-large-v2`, `distil-large-v3`, `large-v3-turbo`, `turbo`), a path to a converted model directory, or a CTranslate2-converted Whisper model ID on the Hugging Face Hub. Sizes/IDs are downloaded from the HF Hub.
- **device** (str) - Optional - `"cpu"`, `"cuda"` or `"auto"`. Default: `"auto"`.
- **device_index** (Union[int, List[int]]) - Optional - Device ID(s). A list spreads the model over multiple GPUs; concurrent `transcribe()` calls from multiple Python threads then run in parallel (see `num_workers`). Default: `0`.
- **compute_type** (str) - Optional - Quantization/precision, e.g. `"float16"`, `"int8"`, `"int8_float16"`, `"float32"`. See https://opennmt.net/CTranslate2/quantization.html. Default: `"default"`.
- **cpu_threads** (int) - Optional - CPU threads (CTranslate2 `intra_threads`; 4 by default per CTranslate2). A non-zero value overrides the `OMP_NUM_THREADS` environment variable. Default: `0`.
- **num_workers** (int) - Optional - CTranslate2 `inter_threads`. With multiple workers, concurrent `self.model.generate()` calls from multiple Python threads run in parallel (higher throughput, more memory). Default: `1`.
- **download_root** (Optional[str]) - Optional - Directory where models are saved (`cache_dir`); defaults to the standard Hugging Face cache. Default: `None`.
- **local_files_only** (bool) - Optional - If `True`, never download; return the local cached file path if it exists. Default: `False`.
- **files** (dict) - Optional - Map of file names to file-like/bytes objects to load the model from memory (`config.json`, `model.bin`, `tokenizer.json`, `preprocessor_config.json`). `model_size_or_path` then acts as an identifier. Default: `None`.
- **revision** (Optional[str]) - Optional - HF Git revision (branch, tag, or commit hash) for model downloads. Default: `None`.
- **use_auth_token** (Optional[Union[str, bool]]) - Optional - HF auth token, or `True` to use the token stored in the HF config folder. Default: `None`.
- **model_kwargs** (dict) - Optional - Forwarded to `ctranslate2.models.Whisper(...)`.

### Raises
- **ValueError** - Invalid model size name (from `download_model`).
- **ValueError** - `files` provided but `config.json` missing; or on-disk model without `config.json`.
- **ValueError** - `config.json` missing any of the required keys `lang_ids`, `suppress_ids`, `suppress_ids_begin`.

### Example: basic
```python
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("audio.mp3", beam_size=5)
for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))
```

### Example: multiple GPUs / error handling
```python
import faster_whisper

try:
    model = WhisperModel("large-v3", device="cuda", device_index=[0, 1], compute_type="float16")
except ValueError as e:
    print("model could not be loaded:", e)
```
```

--------------------------------

### transcribe

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model.md

Transcribes audio from a file path, file-like object, or raw waveform. Returns a lazy generator of segments and transcription info; processing starts only when the generator is consumed.

```APIDOC
## transcribe

### Description
Transcribes audio from a file path, file-like object, or raw waveform. Returns a lazy generator of segments and transcription info; processing starts only when the generator is consumed.

### Method
N/A (Python method)

### Endpoint
N/A (Python method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `audio` (Union[str, BinaryIO, np.ndarray]) - Required - Path to the input file (or a file-like object), or the audio waveform (1-D float32, 16 kHz).
- `language` (Optional[str]) - Optional - Language code ("en", "fr", …). If unset, detected in the first 30 s of audio.
- `task` (str) - Optional - Task to execute: "transcribe" or "translate". Default: "transcribe".
- `log_progress` (bool) - Optional - Show a tqdm progress bar. Default: False.
- `beam_size` (int) - Optional - Beam size for decoding (used at temperature 0). Default: 5.
- `best_of` (int) - Optional - Number of candidates when sampling with non-zero temperature. Default: 5.
- `patience` (float) - Optional - Beam search patience factor. Default: 1.
- `length_penalty` (float) - Optional - Exponential length penalty constant. Default: 1.
- `repetition_penalty` (float) - Optional - Penalty applied to scores of previously generated tokens (>1 to penalize). Default: 1.
- `no_repeat_ngram_size` (int) - Optional - Prevent repetitions of n-grams of this size (0 disables). Default: 0.
- `temperature` (Union[float, List[float], Tuple[float, ...]]) - Optional - Sampling temperature(s); successive values are tried on failure according to compression_ratio_threshold or log_prob_threshold. Default: [0.0, 0.2, 0.4, 0.6, 0.8, 1.0].
- `compression_ratio_threshold` (Optional[float]) - Optional - If the gzip compression ratio is above this value, treat the decode as failed and retry with a higher temperature. Default: 2.4.
- `log_prob_threshold` (Optional[float]) - Optional - If the average log probability over sampled tokens is below this value, treat the decode as failed. Default: -1.0.
- `no_speech_threshold` (Optional[float]) - Optional - If no_speech probability is above this AND avg_logprob < log_prob_threshold, treat the segment as silent and skip it. Default: 0.6.
- `condition_on_previous_text` (bool) - Optional - Provide previous window output as prompt for the next window; disabling reduces repetition loops at the cost of cross-window consistency. Default: True.
- `prompt_reset_on_temperature` (float) - Optional - Resets the prompt if temperature is above this value (only when condition_on_previous_text=True). Default: 0.5.
- `initial_prompt` (Optional[Union[str, Iterable[int]]]) - Optional - Text string or iterable of token ids used as a prompt for the first window. Default: None.
- `prefix` (Optional[str]) - Optional - Text provided as a prefix for the first window. Default: None.
- `suppress_blank` (bool) - Optional - Suppress blank outputs at the beginning of sampling. Default: True.
- `suppress_tokens` (Optional[List[int]]) - Optional - Token IDs to suppress; -1 suppresses the default set from tokenizer.non_speech_tokens plus control tokens (see get_suppressed_tokens). Default: [-1].
- `without_timestamps` (bool) - Optional - Only sample text tokens. Default: False.
- `max_initial_timestamp` (float) - Optional - The initial timestamp cannot be later than this (seconds). Default: 1.0.
- `word_timestamps` (bool) - Optional - Extract word-level timestamps via cross-attention + DTW; each Segment.words is populated. Default: False.
- `prepend_punctuations` (str) - Optional - If word_timestamps=True, merge these punctuation symbols with the next word. Default: "\"'“¿([{-".
- `append_punctuations` (str) - Optional - If word_timestamps=True, merge these punctuation symbols with the previous word. Default: "\"'.。,，!！?？:：”)]}、".
- `multilingual` (bool) - Optional - Perform language detection on every segment. Default: False.
- `vad_filter` (bool) - Optional - Enable Silero VAD to filter out non-speech audio. Default: False.
- `vad_parameters` (Optional[Union[dict, VadOptions]]) - Optional - VAD options (see VadOptions); dict keys are the same field names. Default: None.
- `max_new_tokens` (Optional[int]) - Optional - Maximum new tokens per window; defaults to max_length (448) minus prompt. Default: None.
- `chunk_length` (Optional[int]) - Optional - Audio window length in seconds; overrides the FeatureExtractor's chunk_length. Intended for models that specify a chunk length (e.g. Distil models). Default: None.
- `clip_timestamps` (Union[str, List[float]]) - Optional - Comma-separated start,end,start,end,... seconds (or list of floats) of clips to process; last end defaults to end of file. vad_filter is ignored when a non-default value is used. Default: "0".
- `hallucination_silence_threshold` (Optional[float]) - Optional - When word_timestamps=True, skip silent periods longer than this (seconds) when a possible hallucination is detected. Default: None.
- `hotwords` (Optional[str]) - Optional - Hotwords/hint phrases for the model; no effect if prefix is not None. Default: None.
- `language_detection_threshold` (float) - Optional - If the max language-token probability is above this, accept the detection. Default: 0.5.
- `language_detection_segments` (int) - Optional - Number of 30 s segments to consider for language detection. Default: 1.

### Request Example
N/A (Python method)

### Response
#### Success Response (200)
- Returns Tuple[Iterable[Segment], TranscriptionInfo] - a lazy generator of Segment objects and a TranscriptionInfo value object. Transcription runs only when the generator is consumed.

#### Response Example
N/A (Python method)
```

--------------------------------

### Load a converted model from a local directory

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Loads a converted CTranslate2 Whisper model directly from a local directory using faster-whisper. The model path points to the output directory created by the conversion script.

```python
model = faster_whisper.WhisperModel("whisper-large-v3-ct2")
```

--------------------------------

### Transcription with distil-large-v3 (English, condition_on_previous_text=False)

Source: https://github.com/systran/faster-whisper/blob/master/README.md

Runs inference with the distil-large-v3 checkpoint, which is compatible with Faster-Whisper and designed for its transcription algorithm. Uses English language and disables conditioning on previous text.

```python
from faster_whisper import WhisperModel

model_size = "distil-large-v3"

model = WhisperModel(model_size, device="cuda", compute_type="float16")
segments, info = model.transcribe("audio.mp3", beam_size=5, language="en", condition_on_previous_text=False)

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

```

--------------------------------

### Tokenizer.__init__

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/tokenizer.md

Constructs a Tokenizer instance wrapping a Hugging Face tokenizer, exposing Whisper-specific special-token IDs, encode/decode, and word splitting. Validates task and language for multilingual models.

```APIDOC
## Tokenizer.__init__

### Description
Constructs a Tokenizer instance wrapping a Hugging Face tokenizer, exposing Whisper-specific special-token IDs, encode/decode, and word splitting. Validates task and language for multilingual models.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    tokenizer: tokenizers.Tokenizer,
    multilingual: bool,
    task: Optional[str] = None,
    language: Optional[str] = None,
):
```

### Parameters
- **tokenizer** (tokenizers.Tokenizer) - Required - The underlying tokenizer (from `WhisperModel.hf_tokenizer`).
- **multilingual** (bool) - Required - Whether the model is multilingual.
- **task** (Optional[str]) - Optional - Task name for the task token: `"transcribe"` or `"translate"` (only validated when `multilingual=True`).
- **language** (Optional[str]) - Optional - Language code (only validated when `multilingual=True`).

### Behavior
For multilingual models, sets `self.task` and `self.language` to the token ids of `<|task|>` / `<|language|>` and `self.language_code` to the code. For English-only models, sets `task = None`, `language = None`, `language_code = "en"`.

### Errors
- **ValueError** - Invalid `task` - `"'%s' is not a valid task (accepted tasks: transcribe, translate)"`
- **ValueError** - Invalid `language` code - `"'%s' is not a valid language code (accepted language codes: ...)"`
- **ValueError** - Language not supported by this model's vocabulary - `"Language '%s' is not supported by this model"` (when `token_to_id("<|lang|>")` is `None`)

### Example
```python
from faster_whisper.tokenizer import Tokenizer
from faster_whisper import WhisperModel

model = WhisperModel("small", device="cpu")
tokenizer = Tokenizer(model.hf_tokenizer, model.model.is_multilingual, task="transcribe", language="en")
```
```

--------------------------------

### download_model(size_or_id, output_dir=None, local_files_only=False, cache_dir=None, revision=None, use_auth_token=None)

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/utils.md

Downloads a model from the Hugging Face Hub or uses a local cached copy. Returns the path to the downloaded model directory.

```APIDOC
## download_model(size_or_id, output_dir=None, local_files_only=False, cache_dir=None, revision=None, use_auth_token=None)

### Description
Downloads a model from the Hugging Face Hub or uses a local cached copy. Returns the path to the downloaded model directory.

### Method
Function call

### Endpoint
`faster_whisper.utils.download_model`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **size_or_id** (str) - Required - Model size (e.g. `"large-v3"`) or a CTranslate2-converted model ID on the Hugging Face Hub (e.g. `"Systran/faster-whisper-large-v3"`). A string containing `/` is treated as a repo ID.
- **output_dir** (Optional[str]) - Optional - Directory where the model is saved (`local_dir`); defaults to the HF cache.
- **local_files_only** (bool) - Optional - If `True`, never download; use the local cached copy if it exists.
- **cache_dir** (Optional[str]) - Optional - Folder where cached files are stored.
- **revision** (Optional[str]) - Optional - Git revision (branch, tag, commit hash).
- **use_auth_token** (Optional[Union[str, bool]]) - Optional - HF auth token or `True` for the stored token.

### Returns
- **str** - Path to the downloaded model directory

### Raises
- **ValueError** - If the model size is invalid.

### Example
```python
from faster_whisper import download_model

path = download_model("small", output_dir="./models")
print(path)
```

### Example: error handling
```python
from faster_whisper.utils import download_model

try:
    download_model("not-a-model")
except ValueError as e:
    print(e)  # Invalid model size 'not-a-model', expected one of: ...
```
```

--------------------------------

### Word dataclass definition

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/types.md

Defines the Word value-object type with start, end, word, and probability fields. The _asdict() method is deprecated and emits a DeprecationWarning; use dataclasses.asdict(word) instead.

```python
@dataclass
class Word:
    start: float
    end: float
    word: str
    probability: float

    def _asdict(self):
        warn(
            "Word._asdict() method is deprecated, use dataclasses.asdict(Word) instead",
            DeprecationWarning,
            2,
        )
        return asdict(self)
```

--------------------------------

### add_word_timestamps method signature

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Defines the add_word_timestamps method that mutates segments in place, filling each subsegment's words with word, start, end, and probability dicts. Returns None when segments is empty.

```python
def add_word_timestamps(
    self,
    segments: List[dict],
    tokenizer: Tokenizer,
    encoder_output: ctranslate2.StorageView,
    num_frames: int,
    prepend_punctuations: str,
    append_punctuations: str,
    last_speech_timestamp: float,
) -> float:
```

--------------------------------

### Basic call: BatchedInferencePipeline.transcribe

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/batched-inference-pipeline.md

Initialize a WhisperModel and BatchedInferencePipeline, then transcribe an audio file with batching. Prints language, duration, duration after VAD, and each segment's timestamps and text.

```python
from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("small", device="cpu", compute_type="int8")
pipeline = BatchedInferencePipeline(model)

segments, info = pipeline.transcribe("long_podcast.mp3", batch_size=8)
print("language:", info.language, "| duration:", info.duration, "| after VAD:", info.duration_after_vad)

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))
```

--------------------------------

### generate_with_fallback method signature

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Defines the generate_with_fallback method that runs model.generate once per temperature in options.temperatures. It handles sampling mode for temperature > 0 and beam search for temperature == 0, with fallback logic based on compression ratio and average log probability. Raises ValueError when prompt length plus max_new_tokens exceeds self.max_length.

```python
def generate_with_fallback(
    self,
    encoder_output: ctranslate2.StorageView,
    prompt: List[int],
    tokenizer: Tokenizer,
    options: TranscriptionOptions,
) -> Tuple[ctranslate2.models.WhisperGenerationResult, float, float, float]:
```

--------------------------------

### Handle RuntimeError when VAD filter is unavailable

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/errors.md

Use this pattern to catch the RuntimeError raised when onnxruntime is not installed and VAD filtering is attempted. The error is chained from an ImportError and occurs the first time VAD filtering is used.

```python
try:
    segments, info = model.transcribe("audio.wav", vad_filter=True)
    for segment in segments:
        ...
except RuntimeError as e:
    print("VAD unavailable:", e)
```

--------------------------------

### get_speech_timestamps(audio, vad_options=None, sampling_rate=16000, **kwargs)

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Detects speech segments in an audio waveform using Silero VAD. Returns a list of dictionaries with integer sample indices 'start' and 'end' for each speech chunk.

```APIDOC
## get_speech_timestamps(audio, vad_options=None, sampling_rate=16000, **kwargs)

### Description
Detects speech segments in an audio waveform using Silero VAD. Returns a list of dictionaries with integer sample indices 'start' and 'end' for each speech chunk.

### Method
Function call

### Endpoint
`faster_whisper.vad.get_speech_timestamps`

### Parameters
#### Positional Parameters
- **audio** (np.ndarray) - Required - One-dimensional float array (waveform).

#### Keyword Parameters
- **vad_options** (Optional[VadOptions]) - Optional - VAD processing options. Default: `None`.
- **sampling_rate** (int) - Optional - Sampling rate of the audio. Default: `16000`.
- **\*\*kwargs** (dict) - Optional - VAD options as keyword arguments, accepted for backward compatibility; used to build `VadOptions` when `vad_options` is `None`.

### Request Example
```python
import numpy as np
from faster_whisper.audio import decode_audio
from faster_whisper.vad import VadOptions, get_speech_timestamps

audio = decode_audio("speech.mp3")
chunks = get_speech_timestamps(
    audio,
    vad_options=VadOptions(min_silence_duration_ms=500, speech_pad_ms=200),
)
```

### Response
#### Success Response
Returns a list of dicts, each with integer sample indices `"start"` and `"end"` for one speech chunk.

#### Response Example
```python
[{"start": 0, "end": 16000}, {"start": 32000, "end": 48000}]
```
```

--------------------------------

### BatchedInferencePipeline.__init__

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/batched-inference-pipeline.md

Constructs a BatchedInferencePipeline instance wrapping an existing WhisperModel. The pipeline runs transcription in batches over VAD-separated audio chunks.

```APIDOC
## BatchedInferencePipeline.__init__

### Description
Constructs a BatchedInferencePipeline instance wrapping an existing WhisperModel. The pipeline runs transcription in batches over VAD-separated audio chunks.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    model,
)
```

### Parameters
- **model** (WhisperModel) - Required - An already-constructed WhisperModel instance.

### Example
```python
from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model)
```
```

--------------------------------

### get_speech_timestamps function signature

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/vad.md

Signature of the get_speech_timestamps function in faster_whisper.vad. Accepts a 1D float audio array, optional VadOptions, and sampling rate (default 16000). Returns a list of dicts with integer sample indices 'start' and 'end' for each speech chunk.

```python
def get_speech_timestamps(
    audio: np.ndarray,
    vad_options: Optional[VadOptions] = None,
    sampling_rate: int = 16000,
    **kwargs,
) -> List[dict]:
```

--------------------------------

### Import WhisperModel

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model.md

Import the WhisperModel class from the faster_whisper package.

```python
from faster_whisper import WhisperModel
```

--------------------------------

### get_prompt method signature

Source: https://github.com/systran/faster-whisper/blob/master/_autodocs/api-reference/whisper-model-generation.md

Defines the get_prompt method that builds the decoder prompt token list. It takes the tokenizer, previous tokens, and optional flags for timestamps, prefix, and hotwords.

```python
def get_prompt(
    self,
    tokenizer: Tokenizer,
    previous_tokens: List[int],
    without_timestamps: bool = False,
    prefix: Optional[str] = None,
    hotwords: Optional[str] = None,
) -> List[int]:
```
Tokens:
Raw