### Install WhisperX from GitHub

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Installs WhisperX directly from its GitHub repository using uvx. This is useful for installing the latest development version.

```bash
uvx git+https://github.com/m-bain/whisperX.git
```

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

### Install WhisperX using pip

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Installs the WhisperX package using pip, the standard Python package installer. This is the recommended method for most users.

```bash
pip install whisperx
```

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

### Developer Installation of WhisperX

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Installs WhisperX from its GitHub repository for development purposes. This involves cloning the repository and installing dependencies with extra features.

```bash
git clone https://github.com/m-bain/whisperX.git
cd WhisperX
uv sync --all-extras --dev
```

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

### WhisperX Module Logging Examples

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Shows examples of how logging is used within WhisperX modules for informational messages and warnings.

```python
# From whisperx/asr.py
logger.info(f"Loading model: {model_name}")
logger.warning(f"Failed to align: {error_msg}")
```

```python
# From whisperx/alignment.py
logger.warning(f'Failed to align segment ("{segment["text"]}"): {reason}')
```

```python
# From whisperx/diarize.py
logger.info("Performing voice activity detection using Pyannote...")
logger.warning("No active speech found in audio")
```

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

### Lazy Import Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Demonstrates how WhisperX uses lazy imports to defer loading of heavy dependencies until they are actually needed.

```python
def load_model(*args, **kwargs):
    asr = _lazy_import("asr")
    return asr.load_model(*args, **kwargs)
```

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

### Install WhisperX using uvx

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Installs the WhisperX package using uvx, a tool for managing Python environments and packages. This is an alternative to pip.

```bash
uvx whisperx
```

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

### CLI Entry Point Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Execute WhisperX transcription via the command-line interface. Requires specifying audio file path, model, and optionally diarization and Hugging Face token.

```bash
whisperx path/to/audio.wav --model large-v2 --diarize --hf_token hf_xxx
```

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

### Example: Using Pyannote VAD for Audio Segmentation

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Demonstrates how to load audio, initialize the Pyannote VAD module with a device and token, preprocess the audio, apply VAD, and merge the resulting segments into chunks for transcription.

```python
import whisperx
from whisperx.vads import Pyannote

# Load audio
audio = whisperx.load_audio("audio.mp3")

# Initialize Pyannote VAD
vad = Pyannote(
    device="cuda",
    token="hf_xxxxxxxxx",
    vad_onset=0.500
)

# Preprocess
waveform = vad.preprocess_audio(audio)
audio_dict = {"waveform": waveform, "sample_rate": 16000}

# Apply VAD
vad_output = vad(audio_dict)

# Merge chunks
merged = vad.merge_chunks(
    vad_output,
    chunk_size=30,
    onset=0.500,
    offset=0.363
)
```

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

### JSON Subtitle Format Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Example of subtitle data in JSON format, including segments and language.

```json
{
  "segments": [
    {
      "start": 5.234,
      "end": 8.567,
      "text": "This is the first segment",
      "words": [
        {"word": "This", "start": 5.234, "end": 5.456, "score": 0.99}
      ]
    }
  ],
  "language": "en"
}
```

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

### Custom VAD Configuration and Chunk Merging

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Example of configuring Pyannote VAD with custom sensitivity parameters and merging output with longer chunks.

```python
from whisperx.vads import Pyannote

# More aggressive detection (lower onset = detect quieter speech)
vad = Pyannote(
    device="cuda",
    token="hf_token",
    vad_onset=0.400,      # More sensitive
    vad_offset=0.300      # More sensitive offset
)

# Merge with longer chunks
merged = vad.merge_chunks(
    vad_output,
    chunk_size=45,        # Longer chunks
    onset=0.400,
    offset=0.300
)
```

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

### VTT Subtitle Format Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Example of a subtitle file in Web Video Text Tracks (VTT) format.

```plaintext
WEBVTT

00:00:05.234 --> 00:00:08.567
This is the first subtitle.

00:00:08.567 --> 00:00:12.345
This is the second subtitle.
```

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

### TranscriptionResult Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

An example of the data returned by TranscriptionResult. It includes a list of transcribed segments with start and end times, and the detected language.

```python
{
    "segments": [
        {"start": 0.0, "end": 3.5, "text": "Hello world", "avg_logprob": -0.35},
        {"start": 3.5, "end": 7.2, "text": "This is WhisperX", "avg_logprob": -0.42},
    ],
    "language": "en"
}
```

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

### SRT Subtitle Format Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Example of a subtitle file in SubRip Text (SRT) format.

```plaintext
1
00:00:05,234 --> 00:00:08,567
This is the first subtitle.

2
00:00:08,567 --> 00:00:12,345
This is the second subtitle.
```

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

### Setup WhisperX Logging

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Configure logging for WhisperX, supporting different levels and optional file output. Clears existing handlers and sets a specific log format. Use this to control log verbosity and output destination.

```python
import whisperx

# Setup console logging
whisperx.setup_logging(level="info")

# Setup with file output
whisperx.setup_logging(level="debug", log_file="/tmp/whisperx.log")

# Only warnings to console
whisperx.setup_logging(level="warning")
```

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

### Example SingleAlignedSegment Output

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

Illustrates the structure of a SingleAlignedSegment object as returned after alignment. Shows segment start/end times, text, optional log probability, and word-level details.

```python
{
    "start": 5.2,
    "end": 8.7,
    "text": "This is an example sentence.",
    "avg_logprob": -0.42,
    "words": [
        {"word": "This", "start": 5.2, "end": 5.4, "score": 0.98},
        {"word": "is", "start": 5.4, "end": 5.6, "score": 0.95},
        # ...
    ],
    "chars": None  # or list of character alignments
}
```

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

### Load Audio File

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-audio.md

Loads an audio file and resamples it to a specified sample rate. Requires ffmpeg to be installed and available in PATH. Automatically converts stereo to mono and normalizes audio to the [-1.0, 1.0] range.

```python
import whisperx

# Load audio at default 16kHz
audio = whisperx.load_audio("path/to/audio.mp3")

# Load audio at custom sample rate
audio = whisperx.load_audio("path/to/audio.wav", sr=22050)
```

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

### Long-Form Podcast Transcription with Diarization

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Optimize for long-form podcasts with diarization. This example uses a large model, specifies batch size, diarization parameters (min/max speakers), chunk size, VAD onset, and output formats/directory.

```bash
whisperx --model large-v2 --device cuda --batch_size 8 \
  --diarize --min_speakers 1 --max_speakers 4 \
  --chunk_size 30 --vad_onset 0.500 \
  --output_format all --output_dir ./transcriptions/ \
  podcast.wav
```

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

### Multi-Language Transcription with Custom Models

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Configure for multi-language transcription using custom alignment models. This example specifies the language, alignment model, diarization, Hugging Face token, and desired output formats.

```bash
whisperx --model large-v2 --device cuda \
  --language de --align_model german-wav2vec2 \
  --diarize --hf_token hf_xxxx \
  --output_format srt,json audio.wav
```

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

### WhisperX Log Message Format Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Illustrates the structure of log messages, including timestamp, module, log level, and the message content.

```text
2024-01-15 14:32:45,123 - whisperx.asr - INFO - Loading model: large-v2
2024-01-15 14:32:46,456 - whisperx.alignment - WARNING - Failed to align segment: no valid characters
```

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

### WhisperX Command Line Usage (German)

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Example of using WhisperX to transcribe an audio file in German. It specifies the language code and uses a large model.

```bash
whisperx --model large-v2 --language de path/to/audio.wav
```

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

### AlignedTranscriptionResult Example

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

An example of the data returned by AlignedTranscriptionResult. It includes segments with nested word details and a separate flat list of all words with their timings.

```python
{
    "segments": [
        {
            "start": 0.0,
            "end": 3.5,
            "text": "Hello world",
            "words": [
                {"word": "Hello", "start": 0.0, "end": 1.2, "score": 0.99},
                {"word": "world", "start": 1.2, "end": 3.5, "score": 0.98},
            ]
        }
    ],
    "word_segments": [
        {"word": "Hello", "start": 0.0, "end": 1.2, "score": 0.99},
        {"word": "world", "start": 1.2, "end": 3.5, "score": 0.98},
    ]
}
```

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

### Assign Speakers to Words and Segments

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-diarization.md

This example demonstrates the complete workflow of transcribing, aligning, diarizing, and finally assigning speaker labels to words and segments using WhisperX. Ensure you have the necessary models and audio file.

```python
import whisperx

# Transcribe
model = whisperx.load_model("base", device="cuda")
audio = whisperx.load_audio("audio.mp3")
result = model.transcribe(audio)

# Align
align_model, metadata = whisperx.load_align_model(
    result["language"], device="cuda"
)
result = whisperx.align(result["segments"], align_model, metadata, audio, "cuda")

# Diarize
diarizer = whisperx.DiarizationPipeline(device="cuda")
diarize_df = diarizer(audio)

# Assign speakers to words
result = whisperx.assign_word_speakers(diarize_df, result)

# Results now have speaker labels
for seg in result["segments"]:
    print(f"{seg.get('speaker', 'UNKNOWN')}: {seg['text']}")
    for word in seg["words"]:
        print(f
```

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

### Get Comma and Conjunction Lists for Language

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-subtitles.md

Load per-language lists for intelligent breakpoint selection. Requires specifying the language code.

```python
from whisperx.conjunctions import get_conjunctions, get_comma

commas = get_comma(lang)
conjunctions = get_conjunctions(lang)
```

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

### Configure Device and Compute Type for GPU Inference

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Use 'cuda' for GPU inference and 'float16' for a balance of speed and accuracy. Ensure you have an NVIDIA GPU with CUDA installed.

```bash
whisperx --device cuda --compute_type float16 audio.wav
```

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

### setup_logging

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Configures the logging system for WhisperX, allowing for custom log levels and optional file output. It clears existing handlers and sets a standard format.

```APIDOC
## setup_logging

### Description
Configure logging for WhisperX.

### Method Signature
```python
def setup_logging(
    level: str = "info",
    log_file: Optional[str] = None,
) -> None
```

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| level | str | No | "info" | Log level: debug, info, warning, error, critical |
| log_file | str, None | No | None | Optional file path for log file output |

### Request Example
```python
import whisperx

# Setup console logging
whisperx.setup_logging(level="info")

# Setup with file output
whisperx.setup_logging(level="debug", log_file="/tmp/whisperx.log")

# Only warnings to console
whisperx.setup_logging(level="warning")
```

### Behavior

- Clears existing handlers before setup
- Adds console handler to stdout
- Optionally adds file handler if log_file provided
- Sets format: `%(asctime)s - %(name)s - %(levelname)s - %(message)s`
- Disables propagation to root logger
```

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

### Python API Entry Point

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Load model, audio, transcribe, align, and diarize using the Python API. Ensure CUDA is available if 'cuda' is specified as the device.

```python
import whisperx

model = whisperx.load_model("large-v2", device="cuda")
audio = whisperx.load_audio("audio.mp3")
result = model.transcribe(audio, batch_size=16)

align_model, metadata = whisperx.load_align_model(result["language"], device="cuda")
result = whisperx.align(result["segments"], align_model, metadata, audio, "cuda")

diarizer = whisperx.DiarizationPipeline(device="cuda", token="hf_xxx")
diarize_df = diarizer(audio)
result = whisperx.assign_word_speakers(diarize_df, result)
```

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

### Get a Named Logger Instance

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Retrieve a configured logger instance for a specific module. This logger is a child of the main 'whisperx' logger and is automatically initialized if logging is not already set up. Use `__name__` to get a logger for the current module.

```python
from whisperx import get_logger

logger = get_logger(__name__)

# Use in code
logger.info("Starting transcription")
logger.debug("Loading model from cache")
logger.warning("GPU memory low")
logger.error("Failed to load model")
```

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

### Configuration Options

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/GENERATION_REPORT.txt

Details on available configuration parameters for CLI and API usage.

```APIDOC
## Configuration Options

WhisperX offers extensive configuration options accessible via the command-line interface (CLI) and the Python API. Over 150 arguments are documented, covering various aspects of the transcription and processing pipeline.

### Model Selection

- **ASR Models**: Specify which Whisper model to use for automatic speech recognition.
- **Alignment Models**: Choose models for word-level timing and alignment.
- **Diarization Models**: Select models for speaker identification and segmentation.

### Compute Configuration

- **Device**: Specify the compute device (e.g., 'cpu', 'cuda', 'mps').
- **Compute Type**: Configure precision (e.g., 'float32', 'float16', 'int8').

### Transcription Parameters

- **Language**: Set the language of the audio for improved accuracy.
- **Task**: Specify whether to 'transcribe' or 'translate'.
- **Beam Size**: Control the beam search algorithm's width.
- **Temperature**: Adjust the temperature for sampling.

### Alignment Options

- **Word Timestamps**: Enable or disable word-level timestamp generation.
- **Character Timestamps**: Enable or disable character-level timestamp generation.

### VAD Configuration

- **Threshold**: Set the voice activity detection threshold.
- **Min Speech Duration**: Minimum duration for a speech segment.
- **Min Silence Duration**: Minimum duration for a silence segment.

### Diarization Settings

- **Max Speakers**: Maximum number of speakers to detect.
- **Min Speaker Age**: Minimum duration for a speaker's segment.

### Output Formatting

- **Output Format**: Specify desired output formats (e.g., 'txt', 'srt', 'vtt').
- **Output Directory**: Set the directory for saving output files.

### Logging Control

- **Log Level**: Configure the verbosity of logging output (e.g., 'INFO', 'DEBUG').
- **Log File**: Specify a file to write logs to.


```

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

### Get Module Logger

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Obtain a logger instance for a specific module to log messages at different levels.

```python
from whisperx import get_logger

logger = get_logger(__name__)
logger.info("Starting transcription")
logger.debug("Debug details")
logger.warning("Warning message")
```

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

### Initialize DiarizationPipeline

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-diarization.md

Instantiate the DiarizationPipeline with optional model name, HuggingFace token, device, and cache directory. Requires a HuggingFace token for gated models.

```python
import whisperx

# Load diarization model
diarizer = whisperx.DiarizationPipeline(
    device="cuda",
    token="hf_xxxxxxxxxxxxxxxxx"  # HuggingFace token
)

# Perform diarization
diarize_segments = diarizer(
    audio,
    min_speakers=2,
    max_speakers=2
)
```

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

### WhisperX Command-Line Options for Memory Reduction

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Demonstrates command-line arguments for reducing GPU memory usage in WhisperX. Options include adjusting batch size, using a smaller ASR model, and employing lighter compute types. Note that options 2 and 3 may impact transcription quality.

```bash
--batch_size 4
--model base
--compute_type int8
```

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

### Format Timestamp to Seconds (Float)

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Extract start and end times directly from WhisperX segment output as floating-point numbers.

```python
# Direct from WhisperX output
start = seg['start']  # 5.234
end = seg['end']      # 8.567
```

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

### Silero VAD Constructor

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Initializes the Silero VAD model. Use this for lighter-weight VAD with lower GPU memory requirements, suitable for real-time or resource-constrained applications. The onset threshold determines voice activity detection sensitivity.

```python
class Silero(Vad):
    def __init__(
        self,
        vad_onset: float,
        device: str = "cpu"
    )
```

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

### Access Alignment Results with Word Timing

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Process alignment results to get segments with precise word timing information and a flat list of all words.

```python
result = whisperx.align(...)

# Segments with word timing
for seg in result["segments"]:
    for word in seg["words"]:
        print(f"{word['word']} @ {word['start']:.3f}s")

# Flat word list
for word in result["word_segments"]:
    print(f"{word['word']}: {word['start']:.3f} - {word['end']:.3f}")
```

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

### Define SingleCharSegment Type

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-alignment.md

Defines the structure for a single character within a transcription, including the character itself, its start and end times, and an alignment confidence score.

```python
class SingleCharSegment(TypedDict):
    char: str      # The character
    start: float   # Start time in seconds
    end: float     # End time in seconds
    score: float   # Alignment confidence score (0-1)
```

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

### Setting Log Level Programmatically

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Demonstrates how to set the log level for the whisperx logger using the standard logging module or the setup_logging utility.

```python
import logging

# Get whisperx logger and set level
whisperx_logger = logging.getLogger("whisperx")
whisperx_logger.setLevel(logging.DEBUG)

# Or use setup_logging
from whisperx import setup_logging
setup_logging(level="debug")
```

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

### Define SingleWordSegment Type

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-alignment.md

Defines the structure for a single word within a transcription, including the word itself, its start and end times, and an alignment confidence score.

```python
class SingleWordSegment(TypedDict):
    word: str      # The word text
    start: float   # Start time in seconds
    end: float     # End time in seconds
    score: float   # Alignment confidence score (0-1)
```

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

### Segment Class for Diarization

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

A simple container class representing a speaker segment identified during diarization. It holds start and end times, and an optional speaker identifier.

```python
class Segment:
    def __init__(self, start: float, end: float, speaker: Optional[str] = None)

    start: float
    end: float
    speaker: Optional[str]
```

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

### Basic CLI Transcription

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Run a minimal transcription using the WhisperX CLI.

```bash
whisperx audio.mp3
```

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

### Define SingleWordSegment TypedDict

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

Defines a TypedDict for a single word segment. It includes the word text, start and end times in seconds, and an alignment confidence score.

```python
class SingleWordSegment(TypedDict):
    word: str      # The word text
    start: float   # Start time in seconds
    end: float     # End time in seconds
    score: float   # Alignment confidence score (0.0-1.0)
```

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

### Configure Device for Model Loading

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Specify the device (GPU or CPU) for loading the WhisperX model. Auto-detection for CUDA is used if 'cuda' is specified.

```python
# GPU (auto-detected)
model = whisperx.load_model("base", device="cuda")

# Specific GPU
model = whisperx.load_model("base", device="cuda:0")

# CPU
model = whisperx.load_model("base", device="cpu", compute_type="float32")
```

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

### Configure Device and Compute Type for Low Memory GPU Inference

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Utilize 'int8' compute type on a GPU for the fastest inference and lowest memory footprint, at the cost of reduced accuracy.

```bash
whisperx --device cuda --compute_type int8 audio.wav
```

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

### Define SingleSegment Type

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-alignment.md

Defines the structure for a single transcription segment, including start and end times, and the transcribed text. Optionally includes average log probability.

```python
class SingleSegment(TypedDict):
    start: float          # Segment start time in seconds
    end: float            # Segment end time in seconds
    text: str             # Segment text
    avg_logprob: float    # (Optional) Average log probability
```

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

### Progress Callback

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Illustrates how to implement and use a callback function for tracking the progress of transcription tasks in WhisperX.

```python
def progress(pct):
    print(f"Progress: {pct:.1f}%")

model.transcribe(audio, progress_callback=progress)
```

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

### Define SingleCharSegment TypedDict

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

Defines a TypedDict for a single character segment. It includes the character, start and end times in seconds, and an alignment confidence score. This is only present if return_char_alignments=True is set.

```python
class SingleCharSegment(TypedDict):
    char: str      # The character
    start: float   # Start time in seconds
    end: float     # End time in seconds
    score: float   # Alignment confidence score (0.0-1.0)
```

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

### Configure Device and Compute Type for CPU Inference

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Use 'cpu' for inference when no GPU is available and 'float32' for higher accuracy. This option is slower than GPU inference.

```bash
whisperx --device cpu --compute_type float32 audio.wav
```

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

### Initialize SubtitlesProcessor

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-subtitles.md

Initializes the SubtitlesProcessor with aligned segments, language, and formatting options. Use this to prepare transcription data for subtitle generation.

```python
class SubtitlesProcessor:
    def __init__(
        self,
        segments: List[SingleAlignedSegment],
        lang: str,
        max_line_length: int = 45,
        min_char_length_splitter: int = 30,
        is_vtt: bool = False
    )
```

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

### Segment Class Definition

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-diarization.md

Defines the Segment class for representing a time segment with start and end times, and an optional speaker ID. This is a simple helper class for managing diarization segments.

```python
class Segment:
    def __init__(self, start: float, end: float, speaker: Optional[str] = None)
```

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

### Define SingleSegment TypedDict

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/types.md

Defines a TypedDict for a single segment of transcribed text. It includes start and end times in seconds, the transcribed text, and an optional average log probability indicating confidence.

```python
class SingleSegment(TypedDict):
    start: float                    # Segment start time in seconds
    end: float                      # Segment end time in seconds
    text: str                       # Transcribed text
    avg_logprob: NotRequired[float] # Average log probability (optional)
```

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

### Audio Loading and Preprocessing

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/INDEX.md

Functions for loading audio files and computing mel spectrograms.

```APIDOC
## load_audio

### Description
Load audio file.

### Parameters
- **file** (str) - Path to the audio file.
- **sr** (int, optional) - Target sampling rate. If None, uses the audio file's native sampling rate.

### Returns
- tuple[np.ndarray, int] - A tuple containing the audio time series and the sampling rate.
```

```APIDOC
## log_mel_spectrogram

### Description
Compute mel spectrograms from audio.

### Parameters
- **audio** (np.ndarray) - Audio time series.
- **n_mels** (int) - Number of mel filterbanks.
- **padding** (int) - Number of samples to pad.
- **device** (str) - Device to perform computation on (e.g., 'cpu', 'cuda').

### Returns
- torch.Tensor - Mel spectrogram.
```

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

### Utilities Module

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Contains utility functions and language mappings.

```APIDOC
## Utilities Module (`utils.py`)

### Description
This module provides various utility functions and data structures, including extensive language mappings and output format writers.

### Key Exports
- `LANGUAGES`: A dictionary containing mappings for over 90 language codes.
- `TO_LANGUAGE_CODE`: A reverse mapping for language codes.
- `PUNKT_LANGUAGES`: A list of languages supported by NLTK Punkt tokenizer.
- `get_writer()`: A function that returns appropriate writers for different output formats.
```

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

### Load WhisperX Model and Transcribe Audio

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/INDEX.md

Loads a WhisperX model and transcribes an audio file. Specify the model size and device for inference.

```python
import whisperx

model = whisperx.load_model("base", device="cuda")
audio = whisperx.load_audio("audio.mp3")
result = model.transcribe(audio, batch_size=16)
```

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

### Estimate Timestamp for Word

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-subtitles.md

Estimates the start and end timestamps for a specific word when automatic alignment has failed. It uses context from surrounding words or segments, falling back to a default duration estimation if no timing information is available.

```python
def estimate_timestamp_for_word(
    self,
    words: List[Dict],
    i: int,
    next_segment_start_time: Optional[float] = None
)
```

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

### WhisperX Command Line Usage (English)

Source: https://github.com/m-bain/whisperx/blob/main/README.md

Basic command-line usage of WhisperX for transcribing an audio file in English. It uses default parameters and can optionally highlight words in the SRT file.

```bash
whisperx path/to/audio.wav
whisperx path/to/audio.wav --highlight_words True
```

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

### Define SingleAlignedSegment Type

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-alignment.md

Defines the structure for a single aligned transcription segment, extending SingleSegment with word-level and optional character-level alignments. Includes start and end times, text, log probability, and detailed word/character data.

```python
class SingleAlignedSegment(TypedDict):
    start: float                         # Segment start time
    end: float                           # Segment end time
    text: str                            # Full segment text
    avg_logprob: float                   # (Optional) Log probability
    words: List[SingleWordSegment]       # Word-level alignments
    chars: Optional[List[SingleCharSegment]]  # (Optional) Character-level alignments
```

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

### VoiceActivitySegmentation Constructor

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Initializes the VoiceActivitySegmentation class, which wraps pyannote's segmentation pipeline. This is useful for applying binarization to voice activity detection results and supports caching and hooks for progress reporting. Specify the segmentation model and optionally provide an authentication token.

```python
class VoiceActivitySegmentation(VoiceActivityDetection):
    def __init__(
        self,
        segmentation: PipelineModel = "pyannote/segmentation",
        fscore: bool = False,
        token: Optional[str] = None,
        **inference_kwargs
    )
```

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

### Silero VAD __call__ Method

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Performs voice activity detection on audio data using the Silero model. It accepts either a file path or a NumPy array representing the audio. Returns a list of detected speech segments with their start and end times, and confidence scores.

```python
def __call__(self, audio: Union[str, np.ndarray], **kwargs) -> List[Dict]
```

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

### Pyannote VAD Constructor

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Initializes the Pyannote VAD implementation. Requires a device and optionally accepts a HuggingFace token or a path to a custom model file. VAD onset and offset thresholds can be passed via kwargs.

```python
class Pyannote(Vad):
    def __init__(
        self,
        device: str,
        token: Optional[str] = None,
        model_fp: Optional[str] = None,
        **kwargs
    )
```

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

### Exported Classes

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/GENERATION_REPORT.txt

Key classes available for instantiation and use by developers.

```APIDOC
## Exported Classes

The following classes are exported and can be used to build complex transcription and diarization pipelines.

### `WhisperModel`

**Description**: Represents the core Whisper transcription model.

### `FasterWhisperPipeline`

**Description**: A pipeline for faster transcription using optimized Whisper models.

### `DiarizationPipeline`

**Description**: A pipeline for speaker diarization.

### `IntervalTree`

**Description**: A data structure for managing time intervals, often used in alignment and diarization.

### `SubtitlesProcessor`

**Description**: Handles the processing and generation of subtitle files.

### `Vad`

**Description**: Voice Activity Detection module for identifying speech segments.

### `Pyannote`

**Description**: Interface for integrating with Pyannote.audio for diarization.

### `Silero`

**Description**: Interface for using Silero VAD models.

### `VoiceActivitySegmentation`

**Description**: A class for performing voice activity segmentation.

### `Binarize`

**Description**: Utility for binarizing audio signals, often used in VAD.


```

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

### Add cuDNN to LD_LIBRARY_PATH in Python

Source: https://github.com/m-bain/whisperx/blob/main/CUDNN_TROUBLESHOOTING.md

This Python code snippet dynamically adds the path to cuDNN libraries to the LD_LIBRARY_PATH environment variable. This is useful when WhisperX cannot find the installed cuDNN libraries. Ensure the Python version in the path matches your environment.

```python
import os

# Get current LD_LIBRARY_PATH
original = os.environ.get("LD_LIBRARY_PATH", "")

cudnn_path = "/usr/local/lib/python3.12/dist-packages/nvidia/cudnn/lib/"
os.environ['LD_LIBRARY_PATH'] = original + ":" + cudnn_path
```

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

### Configure Low-Memory Usage

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Load WhisperX models with configurations optimized for low memory usage, such as using smaller models, quantization, or CPU inference. This is useful for systems with limited VRAM.

```python
# Smallest model + quantization
model = whisperx.load_model(
    "tiny",
    device="cuda",
    compute_type="int8"
)

# Minimal batch size
result = model.transcribe(audio, batch_size=1)

# CPU inference
model = whisperx.load_model(
    "base",
    device="cpu",
    compute_type="float32"
)
```

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

### ASR Module

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Handles Whisper model loading and batched audio transcription.

```APIDOC
## ASR Module (`asr.py`)

### Description
This module facilitates the loading of Whisper ASR models and performs batched transcription of audio data. It leverages the faster-whisper implementation for efficiency.

### Functions
- `load_model(model_name, device, compute_type, download_root)`: Loads a specified Whisper model. Returns a `FasterWhisperPipeline` object.

### Classes
- `WhisperModel`: An extension of faster-whisper that includes methods for batched inference.
- `FasterWhisperPipeline`: The main transcription pipeline class.

### Key Methods
- `FasterWhisperPipeline.transcribe(audio, batch_size, language, task, ...)`: Transcribes the provided audio using the loaded model. Accepts parameters like `batch_size`, `language`, and `task`.
- `WhisperModel.generate_segment_batched(features, tokenizer, options)`: Generates batched segments from audio features.
- `WhisperModel.encode(features)`: Encodes audio features for the ASR model.
```

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

### Logging Utilities

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/INDEX.md

Functions for configuring and accessing the logger.

```APIDOC
## setup_logging

### Description
Configure the logging system.

### Parameters
- **level** (str) - Logging level (e.g., 'INFO', 'DEBUG').
- **log_file** (str, optional) - Path to a file to log messages to.

### Returns
None
```

```APIDOC
## get_logger

### Description
Get a logger instance by name.

### Parameters
- **name** (str) - The name of the logger.

### Returns
- logging.Logger - A logger instance.
```

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

### Select ASR Model

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Use the `--model` parameter to specify the Automatic Speech Recognition model. Larger models offer higher accuracy but are slower.

```bash
whisperx --model large-v2 audio.wav
```

```bash
whisperx --model base audio.wav
```

```bash
whisperx --model large-v3 audio.wav
```

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

### VAD Static Method: preprocess_audio

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-vad.md

Static method to preprocess audio data into a format suitable for VAD model input.

```python
@staticmethod
def preprocess_audio(audio: np.ndarray) -> torch.Tensor
```

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

### Logging Module

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Provides centralized logging configuration and utilities.

```APIDOC
## Logging Module (`log_utils.py`)

### Description
This module offers centralized configuration for logging within the application, ensuring consistent log output.

### Functions
- `setup_logging(level, log_file)`: Configures the logging system. Accepts a logging `level` and an optional `log_file` path.
- `get_logger(name)`: Retrieves a logger instance for a given name. Returns a standard Python `logging.Logger` object.
```

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

### Select Alignment Model

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Use the `--align_model` parameter to specify the alignment model. This can be a Torchaudio default or a HuggingFace model ID.

```bash
whisperx --language de --align_model deresr/wav2vec2-german audio.wav
```

```bash
whisperx --language ja --align_model jonatasgrosman/wav2vec2-large-xlsr-53-japanese audio.wav
```

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

### Set Output Format

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/configuration.md

Control the output file format using `--output_format` or `-f`. Multiple formats can be specified, separated by commas. Defaults to 'all'.

```bash
whisperx --output_format srt audio.wav          # Only SRT
```

```bash
whisperx --output_format json audio.wav         # Only JSON
```

```bash
whisperx --output_format srt,vtt audio.wav      # SRT and VTT
```

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

### WhisperX CLI Logging Control

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/logging-utils.md

Demonstrates how to control the logging verbosity and set custom log levels using CLI arguments.

```bash
whisperx --verbose True audio.wav
```

```bash
whisperx --verbose False audio.wav
```

```bash
whisperx --log-level debug audio.wav
```

```bash
whisperx --log-level error audio.wav
```

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

### Podcast Transcription with WhisperX

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Transcribe an audio file and align the segments for precise timing. This is useful for generating transcripts of podcasts or lectures.

```python
import whisperx

model = whisperx.load_model("large-v2", device="cuda", compute_type="float16")
audio = whisperx.load_audio("podcast.mp3")

# Transcribe + align
result = model.transcribe(audio, batch_size=16)
align_model, metadata = whisperx.load_align_model(result["language"], device="cuda")
result = whisperx.align(result["segments"], align_model, metadata, audio, "cuda")

# Get subtitles
for seg in result["segments"]:
    print(f"[{seg['start']:.2f}] {seg['text']}")
```

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

### Implement Progress Callback

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

Provide a custom callback function to track transcription progress. The callback receives the percentage completion.

```python
def progress(pct):
    print(f"{pct:.0f}%", end="\r")

result = model.transcribe(audio, progress_callback=progress)
```

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

### Explicit Model Cleanup

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/module-overview.md

Shows the recommended way to explicitly clean up models and free GPU memory when using PyTorch with WhisperX.

```python
import gc, torch
del model
gc.collect()
torch.cuda.empty_cache()
```

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

### FasterWhisperPipeline.transcribe

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/api-reference-asr.md

Transcribes audio using batched inference with VAD preprocessing. Supports specifying language, task, and progress callbacks.

```APIDOC
## FasterWhisperPipeline.transcribe

### Description
Transcribe audio using batched inference with VAD preprocessing.

### Parameters
#### Path Parameters
- **audio** (str, np.ndarray) - Required - Audio file path or loaded audio array
#### Query Parameters
- **batch_size** (int, None) - Optional - Default: None - Batch size for inference (None uses model default)
- **num_workers** (int) - Optional - Default: 0 - Number of data loading workers
- **language** (str, None) - Optional - Default: None - Language code (auto-detect if None)
- **task** (str, None) - Optional - Default: "transcribe" - Task: "transcribe" or "translate"
- **chunk_size** (int) - Optional - Default: 30 - Max chunk duration in seconds for VAD merging
- **print_progress** (bool) - Optional - Default: False - Print progress percentages to stdout
- **combined_progress** (bool) - Optional - Default: False - Combine with other progress indicators
- **verbose** (bool) - Optional - Default: False - Print transcription per segment
- **progress_callback** (Callable, None) - Optional - Default: None - Callback receiving progress 0-100 as float

### Returns
`TranscriptionResult` — Dictionary with keys:
- `segments`: List of `SingleSegment` with `start`, `end`, `text`, `avg_logprob`
- `language`: Detected language code

### Example
```python
import whisperx

model = whisperx.load_model("base", device="cuda")
audio = whisperx.load_audio("audio.mp3")

# Basic transcription
result = model.transcribe(audio, batch_size=16)

# With progress tracking
def progress(pct):
    print(f"Progress: {pct:.1f}%")

result = model.transcribe(
    audio,
    batch_size=16,
    language="en",
    task="transcribe",
    progress_callback=progress
)

print(result["language"])
for seg in result["segments"]:
    print(f"[{seg['start']:.2f} - {seg['end']:.2f}] {seg['text']}")
```
```

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

### Use Smaller Model for GPU Memory

Source: https://github.com/m-bain/whisperx/blob/main/_autodocs/quick-reference.md

If GPU memory is insufficient, consider using a smaller pre-trained model.

```python
# Use smaller model
model = whisperx.load_model("small", device="cuda")
```