easy-whisperx 0.0.1

A Python package for easy transcription using WhisperX.

easy-whisperx

A streamlined Python wrapper around the WhisperX project, providing enhanced type safety, automatic resource management, and simplified API for audio transcription with GPU acceleration, word-level alignment, and speaker diarization.

Acknowledgments

This project builds upon the outstanding work of the WhisperX team, particularly:

• Max Bain and contributors for creating WhisperX
• The original Whisper team at OpenAI
• The faster-whisper project for performance improvements

What easy-whisperx adds:

• Type Safety: Comprehensive type hints and mypy compatibility
• Resource Management: Automatic GPU memory cleanup using context managers
• Performance Tracking: Built-in metrics collection for all operations
• Simplified API: Cleaner interface with sensible defaults
• Error Handling: Robust error handling with detailed logging
• Bulk Processing: Efficient batch processing capabilities

All the core transcription, alignment, and diarization capabilities are provided by the underlying WhisperX library.

Python Version Requirements

This package requires Python 3.10, 3.11, or 3.12. Python 3.13+ is not supported due to dependency limitations with the WhisperX library.

Features

• Audio Transcription: WhisperX-powered speech-to-text conversion
• Word-level Alignment: Precise timestamp alignment for individual words
• Speaker Diarization: Automatic speaker identification and assignment
• GPU Acceleration: CUDA support for faster processing
• Performance Tracking: Built-in metrics collection for all operations
• Bulk Processing: Efficient batch processing with individual item tracking
• Type Safety: Comprehensive type hints throughout
• Context Management: Automatic resource cleanup and memory management

Installation

Standard Installation

git clone https://github.com/falahat/easy-whisperx.git
cd easy-whisperx
pip install -e .

Development Installation

git clone https://github.com/falahat/easy-whisperx.git
cd easy-whisperx
pip install -e .[dev]

Notebook Support

pip install -e .[notebook]

Prerequisites for GPU Transcription

1. NVIDIA GPU with CUDA support
2. Hugging Face Token (for speaker diarization models)
3. PyTorch with GPU support

# Install PyTorch with GPU support
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Setting up Transcription Environment

1. Get a Hugging Face Token:

   • Go to Hugging Face Settings
   • Create a token with "read" permissions
   • Accept user agreements for segmentation and diarization models

2. Set Environment Variable:

   # Windows PowerShell
   $env:HF_TOKEN="your_token_here"
   

   # Linux/macOS
   export HF_TOKEN="your_token_here"
   

Quick Start

Basic Transcription

from easy_whisperx import Transcriber

# Initialize transcriber
transcriber = Transcriber(
    model_size="base",
    device="cuda",  # or "cpu" 
    compute_type="float16",
    batch_size=16
)

# Transcribe audio file
with transcriber:
    result = transcriber("path/to/audio.mp3")
    print(result["text"])

Complete Pipeline with Alignment and Diarization

import os
from easy_whisperx import Transcriber, Aligner, Diarizer

audio_path = "path/to/audio.mp3"
hf_token = os.getenv("HF_TOKEN")

# Step 1: Transcribe
with Transcriber("base", "cuda", "float16", 16) as transcriber:
    transcript = transcriber(audio_path)

# Step 2: Align words
with Aligner("cuda", "en") as aligner:
    aligned_transcript = aligner(transcript["segments"], audio_path)

# Step 3: Diarize speakers (optional)
if hf_token:
    with Diarizer("cuda", hf_token) as diarizer:
        final_transcript = diarizer(aligned_transcript, audio_path)
else:
    final_transcript = aligned_transcript

print(final_transcript)

Bulk Processing

from easy_whisperx import BulkExecutor, Transcriber

audio_files = ["file1.mp3", "file2.mp3", "file3.mp3"]

with Transcriber("base", "cuda", "float16", 16) as transcriber:
    with BulkExecutor(transcriber) as executor:
        def transcribe_file(model, audio_path, tracker):
            result = model(audio_path)
            tracker["segments_count"] = len(result.get("segments", []))
            
        executor.for_each(audio_files, transcribe_file)
        metrics = executor.get_metrics()
        print(f"Bulk processing metrics: {metrics}")

WhisperX Integration

This package uses WhisperX as its core transcription engine. We maintain a fork at falahat/whisperx that may include specific optimizations or compatibility fixes, but all credit for the underlying transcription technology goes to the original WhisperX project.

The original WhisperX provides:

• Fast automatic speech recognition with word-level timestamps
• Speaker diarization capabilities
• Multiple language support
• GPU acceleration with optimized inference

Our wrapper adds the resource management and type safety layer on top of this excellent foundation.

Development

Setting up Development Environment

git clone https://github.com/falahat/easy-whisperx.git
cd easy-whisperx

# Create virtual environment (note the .venv name)
python -m venv .venv

# Activate virtual environment
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# Linux/macOS:
source .venv/bin/activate

# Install in development mode
pip install -e .[dev]

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=easy_whisperx --cov-report=html

# Run specific test file
pytest tests/test_transcriber.py -v

# Run integration tests
pytest -m integration

Code Quality Tools

The project uses:

• Black for code formatting
• mypy for type checking
• flake8 for linting
• pytest for testing

# Format code
black src/ tests/

# Type checking
mypy src/easy_whisperx/

# Linting
flake8 src/easy_whisperx/

Core Components

The package is built with a modular architecture:

• Transcriber - Main transcription using WhisperX models
• Aligner - Word-level timestamp alignment
• Diarizer - Speaker identification and assignment
• BulkExecutor - Bulk processing with performance tracking
• PerformanceTracker - Performance metrics collection
• BaseWhisperxModel - Abstract base for model management
• Utility functions - Audio loading and device configuration

Performance and Memory Management

The package includes automatic resource management:

• Context Managers: All models automatically clean up GPU memory
• Performance Tracking: Built-in metrics for all operations
• Memory Optimization: Automatic garbage collection and CUDA cache clearing
• Error Handling: Graceful failure handling with detailed logging

API Reference

Device Configuration

from easy_whisperx.utils import _determine_device_config

# Automatic device selection
device, compute_type = _determine_device_config("auto", "auto")
# Returns ("cuda", "float16") if GPU available, ("cpu", "int8") otherwise

Performance Tracking

from easy_whisperx import PerformanceTracker

with PerformanceTracker("my_operation") as tracker:
    # Your code here
    tracker["custom_metric"] = "value"

metrics = tracker.to_dict()
print(f"Operation took {metrics['my_operation']['duration_seconds']} seconds")

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Ensure all tests pass (pytest)
5. Check code quality (black src/ tests/ and mypy src/)
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.