### Install Project Dependencies

Source: https://github.com/vadiml1024/whisper-speech-to-text/blob/main/CLAUDE.md

Installs the required Python packages for MLX-optimized Whisper and the pyannote speaker diarization toolkit.

```bash
pip install mlx_whisper pyannote.audio
```

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

### Install Dependencies for Audio Transcription

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

Install the necessary Python packages including MLX Whisper, pyannote.audio, and torch components required for local transcription and diarization.

```bash
pip install mlx-whisper pyannote.audio torch torchaudio
```

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

### Debug Pyannote Pipeline Loading

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

A diagnostic script to verify HuggingFace authentication, model access permissions, and pipeline initialization. It attempts to load the pyannote speaker diarization model using multiple configuration methods to identify potential setup issues.

```python
import logging
from pyannote.audio import Pipeline
from huggingface_hub import HfApi
import os

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

def test_pyannote_loading(hf_token):
    try:
        api = HfApi(token=hf_token)
        user_info = api.whoami()
        logger.info(f"HF Hub connection OK, user: {user_info['name']}")
    except Exception as e:
        logger.error(f"HF Hub connection failed: {e}")
        return None

    try:
        model_info = api.model_info("pyannote/speaker-diarization-3.1")
        logger.info(f"Model accessible: {model_info.id}")
    except Exception as e:
        logger.error("Model access failed - ensure you accepted the user agreement")
        return None

    methods = [
        {"use_auth_token": hf_token},
        {"token": hf_token},
        {"use_auth_token": hf_token, "cache_dir": os.path.expanduser("~/whisper_cache")},
    ]

    for i, params in enumerate(methods, 1):
        try:
            logger.info(f"Method {i}: Loading pipeline...")
            pipeline = Pipeline.from_pretrained("pyannote/speaker-diarization-3.1", **params)
            return pipeline
        except Exception as e:
            logger.error(f"Method {i} failed: {e}")
    return None
```

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

### CLI Transcription and Diarization Commands

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

Command-line usage examples for performing speech-to-text transcription with optional speaker diarization. Supports outputting results in TXT, SRT, or JSON formats.

```bash
# Basic usage - outputs TXT format
python speech-to-text-fixed.py audio_file.mp3 your_hf_token

# Generate SRT subtitles with speaker labels
python speech-to-text-fixed.py interview.mp3 hf_xxxxxxxxxxxxx srt

# Generate JSON output with full metadata
python speech-to-text-fixed.py podcast.wav hf_xxxxxxxxxxxxx json
```

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

### Run Speech-to-Text and Diarization Script

Source: https://github.com/vadiml1024/whisper-speech-to-text/blob/main/CLAUDE.md

Executes the main transcription script which processes an audio file using the provided HuggingFace token and optional output format.

```bash
python speech-to-text.py <audio_file> <hf_token> [output_format]
```

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

### Validate MLX Whisper API Functionality

Source: https://github.com/vadiml1024/whisper-speech-to-text/blob/main/CLAUDE.md

Runs the test script to verify that the MLX Whisper API is correctly configured and functional for the specified audio file.

```bash
python test-mlx.py <audio_file>
```

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

### Simple Transcription CLI

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

Command-line usage for performing basic transcription without speaker diarization. Supports TXT, SRT, and JSON output formats.

```bash
# Quick transcription to text
python transcribe_only.py lecture.mp3

# Generate SRT subtitles
python transcribe_only.py video.mp4 srt

# Generate JSON with segments
python transcribe_only.py meeting.wav json
```

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

### Transcribe Audio with MLX Whisper (Python)

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

A lightweight Python function for basic audio transcription without speaker diarization. It utilizes MLX Whisper for fast local processing and supports output formats like TXT, SRT, and JSON. Dependencies include mlx_whisper, json, and os.

```Python
import mlx_whisper
import json
import os

def transcribe_audio(audio_file, output_format="txt"):
    """
    Transcribe audio with MLX Whisper only (no speaker diarization)

    Args:
        audio_file: Path to audio file
        output_format: "txt", "srt", or "json"

    Returns:
        dict: MLX Whisper result with text and segments
    """
    result = mlx_whisper.transcribe(audio_file)
    base_name = os.path.splitext(audio_file)[0]

    if output_format == "txt":
        output_file = f"{base_name}_transcription.txt"
        with open(output_file, 'w') as f:
            f.write(result['text'])

    elif output_format == "json":
        output_file = f"{base_name}_transcription.json"
        with open(output_file, 'w') as f:
            json.dump(result, f, indent=2)

    elif output_format == "srt":
        output_file = f"{base_name}_transcription.srt"
        with open(output_file, 'w') as f:
            for i, segment in enumerate(result['segments'], 1):
                start = format_time(segment['start'])
                end = format_time(segment['end'])
                f.write(f"{i}\n{start} --> {end}\n{segment['text'].strip()}\n\n")

    return result

def format_time(seconds):
    """Convert seconds to SRT time format HH:MM:SS,mmm"""
    hours = int(seconds // 3600)
    minutes = int((seconds % 3600) // 60)
    secs = int(seconds % 60)
    millis = int((seconds % 1) * 1000)
    return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"

# Usage examples
# Plain text output
# result = transcribe_audio("lecture.mp3", "txt")
# print(result['text'])

# SRT subtitles for video
# result = transcribe_audio("video.mp4", "srt")
# Creates: video_transcription.srt

# JSON with full segment data
# result = transcribe_audio("meeting.wav", "json")
# print(f"Detected language: {result.get('language')}")
# print(f"Number of segments: {len(result['segments'])}")
```

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

### Transcribe Audio with Speaker Diarization in Python

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

This function performs full audio transcription using MLX Whisper and maps speaker labels to text segments using pyannote.audio. It includes automatic audio preprocessing to ensure compatibility with diarization requirements.

```python
import mlx_whisper
from pyannote.audio import Pipeline
import torchaudio
import torch

def transcribe_with_speakers(audio_file, hf_token):
    result = mlx_whisper.transcribe(audio_file)
    pipeline = Pipeline.from_pretrained("pyannote/speaker-diarization-3.1", use_auth_token=hf_token)
    try:
        diarization = pipeline(audio_file)
    except Exception as e:
        waveform, sample_rate = torchaudio.load(audio_file)
        if waveform.shape[0] > 1:
            waveform = torch.mean(waveform, dim=0, keepdim=True)
        if sample_rate != 16000:
            resampler = torchaudio.transforms.Resample(sample_rate, 16000)
            waveform = resampler(waveform)
            sample_rate = 16000
        audio_dict = {"waveform": waveform, "sample_rate": sample_rate}
        diarization = pipeline(audio_dict)
    segments_with_speakers = []
    for segment in result["segments"]:
        start_time = segment["start"]
        end_time = segment["end"]
        speaker_time = {}
        for turn, _, speaker in diarization.itertracks(yield_label=True):
            overlap_start = max(start_time, turn.start)
            overlap_end = min(end_time, turn.end)
            if overlap_start < overlap_end:
                overlap_duration = overlap_end - overlap_start
                speaker_time[speaker] = speaker_time.get(speaker, 0) + overlap_duration
        dominant_speaker = max(speaker_time, key=speaker_time.get) if speaker_time else "SPEAKER_UNKNOWN"
        segments_with_speakers.append({"start": start_time, "end": end_time, "text": segment["text"], "speaker": dominant_speaker})
    return {"text": result["text"], "segments": segments_with_speakers, "language": result.get("language", "unknown")}
```

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

### transcribe_audio - Simple Transcription Without Speaker Diarization

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

A lightweight function for basic audio transcription when speaker identification is not needed. Uses only MLX Whisper for fast local processing.

```APIDOC
## transcribe_audio - Simple Transcription Without Speaker Diarization

### Description
A lightweight function for basic audio transcription when speaker identification is not needed. Uses only MLX Whisper for fast local processing.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Plain text output
result = transcribe_audio("lecture.mp3", "txt")
print(result['text'])

# SRT subtitles for video
result = transcribe_audio("video.mp4", "srt")

# JSON with full segment data
result = transcribe_audio("meeting.wav", "json")
print(f"Detected language: {result.get('language')}")
print(f"Number of segments: {len(result['segments'])}")
```

### Response
#### Success Response (200)
- **result** (dict) - MLX Whisper result with text and segments

#### Response Example
```json
{
  "text": "The quick brown fox jumps over the lazy dog.",
  "language": "en",
  "segments": [
    {
      "text": "The quick brown fox.",
      "start": 0.5,
      "end": 2.0
    },
    {
      "text": "Jumps over the lazy dog.",
      "start": 2.5,
      "end": 4.0
    }
  ]
}
```
```

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

### Test MLX Whisper API Methods (Python)

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

A diagnostic Python function to test various MLX Whisper API methods for transcription. It helps identify the most suitable method for a given environment and troubleshoot potential issues. Dependencies include mlx_whisper and sys.

```Python
import mlx_whisper
import sys

def test_transcribe(audio_file):
    """
    Test MLX Whisper transcription with different API calls

    Args:
        audio_file: Path to test audio file

    Returns:
        dict or None: Transcription result if successful
    """
    # Method 1: Simple transcribe (recommended)
    try:
        print("Method 1: Simple transcribe...")
        result = mlx_whisper.transcribe(audio_file)
        print("Method 1 worked!")
        return result
    except Exception as e:
        print(f"Method 1 failed: {e}")

    # Method 2: With explicit model path
    try:
        print("Method 2: With model path...")
        result = mlx_whisper.transcribe(
            audio_file,
            path_or_hf_repo="mlx-community/whisper-large-v3-mlx"
        )
        print("Method 2 worked!")
        return result
    except Exception as e:
        print(f"Method 2 failed: {e}")

    # Method 3: Load model first
    try:
        print("Method 3: Load model first...")
        model = mlx_whisper.load_model("mlx-community/whisper-large-v3-mlx")
        result = mlx_whisper.transcribe(audio_file, model=model)
        print("Method 3 worked!")
        return result
    except Exception as e:
        print(f"Method 3 failed: {e}")

    return None

# Usage
# result = test_transcribe("test_audio.mp3")
# if result:
#     print(f"Result keys: {list(result.keys())}")
#     print(f"Number of segments: {len(result['segments'])}")
#     for i, segment in enumerate(result['segments'][:3]):
#         print(f"{i+1}. [{segment['start']:.1f}s - {segment['end']:.1f}s]: {segment['text']}")
```

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

### test_transcribe - MLX Whisper API Testing

Source: https://context7.com/vadiml1024/whisper-speech-to-text/llms.txt

A diagnostic function that tests different MLX Whisper API methods to identify the working approach for your environment. Useful for troubleshooting transcription issues.

```APIDOC
## test_transcribe - MLX Whisper API Testing

### Description
A diagnostic function that tests different MLX Whisper API methods to identify the working approach for your environment. Useful for troubleshooting transcription issues.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
result = test_transcribe("test_audio.mp3")
if result:
    print(f"Result keys: {list(result.keys())}")
    print(f"Number of segments: {len(result['segments'])}")
    for i, segment in enumerate(result['segments'][:3]):
        print(f"{i+1}. [{segment['start']:.1f}s - {segment['end']:.1f}s]: {segment['text']}")
```

### Response
#### Success Response (200)
- **result** (dict or None) - Transcription result if successful, otherwise None.

#### Response Example
```json
{
  "text": "This is a test transcription.",
  "language": "en",
  "segments": [
    {
      "text": "This is a test.",
      "start": 0.0,
      "end": 1.5
    },
    {
      "text": "Transcription.",
      "start": 2.0,
      "end": 3.0
    }
  ]
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.