### Install Bournemouth Forced Aligner and Dependencies

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Installs the BFA library from PyPI, along with necessary system dependencies like espeak-ng and ffmpeg. Includes a verification step to confirm successful installation.

```bash
# Install from PyPI
pip install bournemouth-forced-aligner

# Install system dependencies
apt-get install espeak-ng ffmpeg

# Verify installation
balign --version
python -c "from bournemouth_aligner import PhonemeTimestampAligner; print('Installation successful!')"
```

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

### Complete Mel-Spectrum Alignment Example (Python)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

An example demonstrating how to perform mel-spectrum alignment using the PhonemeTimestampAligner. This involves loading audio, processing sentences, extracting mel spectrograms, and aligning phonemes.

```python
# pip install librosa
import torch
from bournemouth_aligner import PhonemeTimestampAligner

# Initialize aligner
extractor = PhonemeTimestampAligner(model_name="en_libri1000_ua01c_e4_val_GER=0.2186.ckpt", 
                                  lang='en-us', duration_max=10, device='cpu')

# Process audio and get timestamps
audio_wav = extractor.load_audio("examples/samples/audio/109867__timkahn__butterfly.wav")
timestamps = extractor.process_sentence("butterfly", audio_wav)

# Extract mel spectrogram with vocoder compatibility
vocoder_config = {'num_mels': 80, 'hop_size': 256, 'sampling_rate': 22050}
segment_wav = audio_wav[:, :int(timestamps['segments'][0]['end'] * extractor.resampler_sample_rate)]
mel_spec = extractor.extract_mel_spectrum(segment_wav, extractor.resampler_sample_rate, vocoder_config)

# Create frame-wise phoneme alignment
total_frames = mel_spec.shape[0]
frames_per_second = total_frames / timestamps['segments'][0]['end']
frames_assorted = extractor.framewise_assortment(
    aligned_ts=timestamps['segments'][0]['phoneme_ts'], 
    total_frames=total_frames, 
    frames_per_second=frames_per_second
)

# Compress and visualize
compress_framesed = extractor.compress_frames(frames_assorted)
# Use provided plot_mel_phonemes() function to visualize
```

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

### Install Bournemouth Forced Aligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Installs the bournemouth-forced-aligner package from PyPI or directly from GitHub. It also installs necessary system dependencies like espeak-ng and ffmpeg.

```bash
pip install bournemouth-forced-aligner

# Alternatively, install the latest library directly from github:
# pip install git+https://github.com/tabahi/bournemouth-forced-aligner.git

# Install system dependencies
apt-get install espeak-ng ffmpeg
```

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

### BFA CLI Usage Examples

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Demonstrates basic and advanced usage of the BFA command-line interface tool 'balign'. This includes processing single audio files, utilizing various options like specifying models, languages, devices, and debugging, as well as performing batch processing using a shell loop.

```bash
# Basic usage
balign audio.wav transcription.srt.json output.json

# With options
balign audio.wav transcription.srt.json output.json \
    --model "en_libri1000_ua01c_e4_val_GER=0.2186.ckpt" \
    --lang en-us \
    --device cuda \
    --duration-max 10.0 \
    --embeddings embeddings.pt \
    --debug

# View help
balign --help

# Check version
balign --version

# Batch processing
for audio in *.wav; do
    balign "$audio" "${audio%.wav}.srt.json" "${audio%.wav}.json"
done
```

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

### Bournemouth Forced Aligner CLI Advanced Options (Bash)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Examples demonstrating advanced options for the Bournemouth Forced Aligner CLI, including specifying the model, language, device, and enabling target phoneme boosting.

```bash
# Basic usage
balign audio.wav transcription.srt.json output.json

# With GPU and embeddings  
balign audio.wav transcription.srt.json output.json --device cuda --embeddings embeddings.pt

# Multi-language (English + 8 european langauges model available)
balign audio.wav transcription.srt.json output.json --lang es
```

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

### Quick Start: Phoneme Timestamp Extraction in Python

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Demonstrates how to use the PhonemeTimestampAligner to extract phoneme timestamps from an audio file and its corresponding text. It shows configuration, loading audio, processing, and printing results.

```python
import torch
import time
import json
from bournemouth_aligner import PhonemeTimestampAligner

# Configuration
text_sentence = "butterfly"
audio_path = "examples/samples/audio/109867__timkahn__butterfly.wav"

# Initialize aligner using language preset (recommended)
extractor = PhonemeTimestampAligner(
    preset="en-us",  # Automatically selects best English model
    duration_max=10,
    device='cpu'
)

# Alternative: explicit model selection
# extractor = PhonemeTimestampAligner(
#     model_name="en_libri1000_ua01c_e4_val_GER=0.2186.ckpt",
#     lang='en-us',
#     duration_max=10,
#     device='cpu'
# )

# Load and process
audio_wav = extractor.load_audio(audio_path) # use RMS normalization for preloaded wav `audio_wav = extractor._rms_normalize(audio_wav)`

t0 = time.time()
timestamps = extractor.process_sentence(
    text_sentence,
    audio_wav,
    ts_out_path=None,
    extract_embeddings=False,
    vspt_path=None,
    do_groups=True,
    debug=True
)
t1 = time.time()

print("🎯 Timestamps:")
print(json.dumps(timestamps, indent=4, ensure_ascii=False))
print(f"⚡ Processing time: {t1 - t0:.2f} seconds")
```

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

### Phoneme Timestamp Aligner with Language Presets (Python)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Demonstrates initializing the PhonemeTimestampAligner using language presets for automatic model and language configuration. Presets simplify setup for supported languages, with German, Hindi, and French examples provided.

```python
from bfa.aligner import PhonemeTimestampAligner

# Using presets (recommended)
aligner = PhonemeTimestampAligner(preset="de")  # German with MLS8 model
aligner = PhonemeTimestampAligner(preset="hi")  # Hindi with Universal model
aligner = PhonemeTimestampAligner(preset="fr")  # French with MLS8 model
```

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

### Manual Processing Pipeline (Python)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

A Python example showing a manual processing pipeline for audio alignment. It initializes the aligner, loads audio, processes a sentence, and exports the results to a Praat TextGrid file.

```python
import torch
from bournemouth_aligner import PhonemeTimestampAligner

# Initialize and process
extractor = PhonemeTimestampAligner(model_name="en_libri1000_ua01c_e4_val_GER=0.2186.ckpt")
audio_wav = extractor.load_audio("audio.wav")  # Handles resampling and normalization
timestamps = extractor.process_sentence("your text here", audio_wav)

# Export to Praat
extractor.convert_to_textgrid(timestamps, "output.TextGrid")
```

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

### Bournemouth Forced Aligner CLI Usage (Bash)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Examples of using the Bournemouth Forced Aligner (balign) command-line interface. Covers basic alignment, enabling debug output, and extracting embeddings.

```bash
# Basic alignment
balign audio.wav transcription.srt.json output.json

# With debug output
balign audio.wav transcription.srt.json output.json --debug

# Extract embeddings
balign audio.wav transcription.srt.json output.json --embeddings embeddings.pt
```

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

### Verify Bournemouth Forced Aligner Installation

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Commands to verify the installation of the Bournemouth Forced Aligner by checking its help message, version, and running a simple Python test.

```bash
# Show help
balign --help

# Check version
balign --version

# Test installation
python -c "from bournemouth_aligner import PhonemeTimestampAligner; print('✅ Installation successful!')"
```

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

### Whisper Integration Example (Python)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Integrates the Bournemouth Forced Aligner with OpenAI's Whisper for transcription and alignment. It transcribes an audio file using Whisper and then processes the resulting SRT JSON with the aligner.

```python
# pip install git+https://github.com/openai/whisper.git 
import whisper, json
from bournemouth_aligner import PhonemeTimestampAligner

# Transcribe and align
model = whisper.load_model("turbo")
result = model.transcribe("audio.wav")
with open("whisper_output.srt.json", "w") as f:
    json.dump(result, f)

# Process with BFA
extractor = PhonemeTimestampAligner(model_name="en_libri1000_ua01c_e4_val_GER=0.2186.ckpt")
timestamps = extractor.process_srt_file("whisper_output.srt.json", "audio.wav", "timestamps.json")
```

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

### Sample SRT JSON Input Format

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

This JSON structure represents the input format for SRT files used by the Bournemouth Forced Aligner. It contains an array of segments, each with a start time, end time, and the corresponding text.

```json
{
  "segments": [
    {
      "start": 0.0,
      "end": 3.5,
      "text": "hello world this is a test"
    },
    {
      "start": 3.5,
      "end": 7.2,
      "text": "another segment of speech"
    }
  ]
}
```

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

### Initialize PhonemeTimestampAligner Class for Forced Alignment

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Demonstrates how to initialize the main `PhonemeTimestampAligner` class. It shows two methods: using a language preset for automatic model selection and explicitly specifying the model name. Key parameters include language preset, maximum segment duration, device (CPU/CUDA), and alignment enhancement options.

```python
import torch
import json
from bournemouth_aligner import PhonemeTimestampAligner

# Initialize with language preset (recommended)
aligner = PhonemeTimestampAligner(
    preset="en-us",          # Language preset (auto-selects best model)
    duration_max=10,         # Max segment duration in seconds
    device="cpu",            # "cpu" or "cuda"
    boost_targets=True,      # Enhance target phoneme probabilities
    enforce_all_targets=True # Guarantee all phonemes appear in alignment
)

# Alternative: explicit model selection
aligner = PhonemeTimestampAligner(
    model_name="en_libri1000_ua01c_e4_val_GER=0.2186.ckpt",
    lang="en-us",
    duration_max=10,
    device="cpu"
)

# Load audio file
audio_wav = aligner.load_audio("audio.wav")

# Process a sentence
timestamps = aligner.process_sentence(
    text="butterfly",
    audio_wav=audio_wav,
    ts_out_path="output.json",  # Optional: save to file
    extract_embeddings=False,
    do_groups=True,
    debug=True
)

print(json.dumps(timestamps, indent=2))
# Output includes:
# - segments[].phoneme_ts: list of {phoneme_idx, phoneme_label, start_ms, end_ms, confidence}
# - segments[].group_ts: list of {group_idx, group_label, start_ms, end_ms, confidence}
# - segments[].words_ts: list of {word, start_ms, end_ms, confidence, ph66, ipa}
```

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

### BFA Multi-Language Support Initialization

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Shows how to initialize the PhonemeTimestampAligner from the bournemouth_aligner library for various languages using presets. It covers English variants and several European, Indo-European, and related languages, noting the absence of support for tonal languages.

```python
from bournemouth_aligner import PhonemeTimestampAligner

# English variants
aligner_en = PhonemeTimestampAligner(preset="en-us")  # US English
aligner_gb = PhonemeTimestampAligner(preset="en-gb")  # British English

# European languages (MLS8 model)
aligner_de = PhonemeTimestampAligner(preset="de")     # German
aligner_fr = PhonemeTimestampAligner(preset="fr")     # French
aligner_es = PhonemeTimestampAligner(preset="es")     # Spanish
aligner_it = PhonemeTimestampAligner(preset="it")     # Italian
aligner_pt = PhonemeTimestampAligner(preset="pt")     # Portuguese
aligner_pl = PhonemeTimestampAligner(preset="pl")     # Polish
aligner_nl = PhonemeTimestampAligner(preset="nl")     # Dutch

# Indo-European & related (Universal model)
aligner_ru = PhonemeTimestampAligner(preset="ru")     # Russian
aligner_hi = PhonemeTimestampAligner(preset="hi")     # Hindi
aligner_ar = PhonemeTimestampAligner(preset="ar")     # Arabic
aligner_tr = PhonemeTimestampAligner(preset="tr")     # Turkish
aligner_el = PhonemeTimestampAligner(preset="el")     # Greek
aligner_fa = PhonemeTimestampAligner(preset="fa")     # Persian

# Note: Tonal languages (Chinese, Vietnamese, Thai) are NOT supported
```

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

### Multi-Language Initialization for PhonemeTimestampAligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Shows how to initialize the PhonemeTimestampAligner for different languages using presets. This allows for easy switching between language models for forced alignment.

```python
# German with MLS8 model
aligner_de = PhonemeTimestampAligner(preset="de")

# Hindi with Universal model
aligner_hi = PhonemeTimestampAligner(preset="hi")

# French with MLS8 model
aligner_fr = PhonemeTimestampAligner(preset="fr")
```

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

### Initialization

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Initializes the PhonemeTimestampAligner with specified parameters. You can choose language presets, override models, and configure alignment behavior.

```APIDOC
## Initialization

### Description
Initializes the PhonemeTimestampAligner with specified parameters. You can choose language presets, override models, and configure alignment behavior.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **preset** (string) - Required - Language preset for automatic model and language selection. Use language codes like "de", "fr", "hi", "ja", etc. Supports 127+ languages with intelligent model selection.
- **model_name** (string) - Optional - Name of the CUPE model. Overrides preset selection. Downloaded automatically if available.
- **cupe_ckpt_path** (string) - Optional - Local path to model checkpoint. Highest priority - overrides both preset and model_name.
- **lang** (string) - Required - Language code for phonemization. Only overridden by preset if using default.
- **duration_max** (integer) - Optional - Maximum segment duration (seconds, for batch padding). Best to keep <30 seconds. Default is 10.
- **output_frames_key** (string) - Optional - Output key for frame assortment (`phoneme_idx`, `phoneme_label`, `group_idx`, `group_label`). Default is `phoneme_idx`.
- **device** (string) - Optional - Inference device (`cpu` or `cuda`). Default is `cpu`.
- **silence_anchors** (integer) - Optional - Number of silent frames to anchor pauses. Set `0` to disable. Default is 10.
- **boost_targets** (boolean) - Optional - Boost target phoneme probabilities for better alignment. Default is True.
- **enforce_minimum** (boolean) - Optional - Enforce minimum probability for target phonemes. Default is True.
- **enforce_all_targets** (boolean) - Optional - Band-aid postprocessing patch. It will insert phonemes missed by viterbi decoding at their expected positions based on target positions. Default is True.
- **ignore_noise** (boolean) - Optional - Whether to ignore the predicted "noise" in the alignment. If set to True, noise will be skipped over. If False, long noisy/silent segments will be included as "noise" timestamps. Default is True.

### Request Example
```python
PhonemeTimestampAligner(
    preset="en-us",
    model_name=None,
    cupe_ckpt_path=None,
    lang="en-us",
    duration_max=10,
    output_frames_key="phoneme_idx",
    device="cpu",
    boost_targets=True,
    enforce_minimum=True,
    enforce_all_targets=True,
    ignore_noise=True
)
```

### Response
#### Success Response (200)
Returns an initialized `PhonemeTimestampAligner` object.

#### Response Example
None (Initialization does not return a value, it creates an object).
```

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

### Initialize PhonemeTimestampAligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Initializes the PhonemeTimestampAligner with specified parameters. Supports various language presets and model overrides for flexible audio alignment tasks. It handles device selection and output formatting.

```python
PhonemeTimestampAligner(
    preset="en-us",  # Language preset (recommended)
    model_name=None,  # Optional: explicit model override
    cupe_ckpt_path=None,  # Optional: direct checkpoint path
    lang="en-us",  # Language for phonemization
    duration_max=10,
    output_frames_key="phoneme_idx",
    device="cpu",
    boost_targets=True,
    enforce_minimum=True,
    enforce_all_targets=True,
    ignore_noise=True
)
```

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

### BFA and Whisper Integration for Transcription and Alignment

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Illustrates combining the BFA library with OpenAI Whisper for an end-to-end speech processing pipeline. This snippet covers transcribing an audio file using Whisper, saving the transcription, performing phoneme alignment with BFA, and exporting the results to a Praat TextGrid format for visualization.

```python
import whisper
import json
from bournemouth_aligner import PhonemeTimestampAligner

# Transcribe with Whisper
model = whisper.load_model("turbo")
result = model.transcribe("audio.wav")

# Save Whisper output
with open("whisper_output.srt.json", "w") as f:
    json.dump(result, f)

# Process with BFA
aligner = PhonemeTimestampAligner(preset="en-us", duration_max=10)
timestamps = aligner.process_srt_file(
    srt_path="whisper_output.srt.json",
    audio_path="audio.wav",
    ts_out_path="phoneme_timestamps.json",
    debug=True
)

# Export to Praat for visualization
aligner.convert_to_textgrid(timestamps, "alignment.TextGrid")
```

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

### Convert Text to Phoneme Sequences

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Converts input text into phoneme sequences using the espeak-ng backend. The output includes various representations such as ph66 indices, pg16 group indices, IPA symbols, and word-level mappings. It also demonstrates how to switch the backend language.

```python
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us")

result = aligner.phonemize_sentence("butterfly")

print(f"IPA: {result['ipa']}")        # ['b', 'ʌ', 'ɾ', 'ɚ', 'f', 'l', 'aɪ']
print(f"ph66: {result['ph66']}")      # [29, 10, 58, 9, 43, 56, 23]
print(f"pg16: {result['pg16']}")      # [7, 2, 14, 2, 8, 13, 5]
print(f"words: {result['words']}")    # ['butterfly']
print(f"word_num: {result['word_num']}")  # [0, 0, 0, 0, 0, 0, 0]

# Change language
aligner.phonemizer.set_backend(language='de')
german_result = aligner.phonemize_sentence("Schmetterling")
print(f"German IPA: {german_result['ipa']}")
```

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

### Enable Debug Mode for Bournemouth Forced Aligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

This command runs the 'balign' tool with the --debug flag enabled. This provides comprehensive output detailing the alignment process, including audio/SRT file paths, language, model information, and processing steps.

```bash
balign audio.wav transcription.srt.json output.json --debug
```

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

### Convert Text to Phonemes with Phonemizer

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Converts input text into phonemes using the phonemizer package with an espeak-ng backend. It returns a detailed mapping including IPA phonemes, phoneme class indices, group indices, and corresponding words and word numbers. Optional backend language setting is available.

```python
from bfa.aligner import PhonemeTimestampAligner

# Phonemize a sentence
result = PhonemeTimestampAligner.phonemize_sentence("butterfly")
print(result["ipa"])
print(result["ph66"])
print(result["pg16"])

# Optionally change the espeak language
PhonemeTimestampAligner.phonemizer.set_backend(language='en')
```

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

### Batch Process WAV Files with Bournemouth Forced Aligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

This script iterates through all WAV files in the current directory and processes each one using the 'balign' command. It generates an SRT subtitle file and a JSON output file for each audio file.

```bash
for audio in *.wav; do balign "$audio" "${audio%.wav}.srt" "${audio%.wav}.json"; done
```

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

### Extract Phoneme Timestamps and Embeddings from Audio Segments with Python

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Provides low-level access to the alignment engine for custom audio processing. It extracts phoneme timestamps from a given audio segment and text, with options to also extract pooled phoneme and group embeddings. This is useful for detailed analysis or integration into custom pipelines.

```python
import torch
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us", duration_max=10)
audio_wav = aligner.load_audio("audio.wav")

# Phonemize text manually
phoneme_info = aligner.phonemize_sentence("hello")
phoneme_sequence = phoneme_info['ph66']
group_sequence = phoneme_info['pg16']

# Prepare audio segment
wav, wav_len = aligner.chop_wav(
    audio_wav,
    start_frame=0,
    end_frame=int(1.5 * aligner.resampler_sample_rate)
)

# Extract timestamps
result, phoneme_embeddings, group_embeddings = aligner.extract_timestamps_from_segment(
    wav=wav,
    wav_len=wav_len,
    phoneme_sequence=phoneme_sequence,
    start_offset_time=0.0,
    group_sequence=group_sequence,
    extract_embeddings=True,
    do_groups=True,
    debug=True
)

# Access raw timestamp tuples: (idx, start_frame, end_frame, confidence, start_ms, end_ms)
for ts in result['phoneme_timestamps']:
    print(f"Phoneme {ts[0]}: {ts[4]:.1f}-{ts[5]:.1f}ms")

# Pooled embeddings shape: [num_phonemes, embedding_dim]
if phoneme_embeddings is not None:
    print(f"Embedding shape: {phoneme_embeddings.shape}")

```

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

### Extract Mel Spectrogram for Vocoder Compatibility with Python

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Extracts mel spectrograms from audio segments, compatible with HiFi-GAN/BigVGAN vocoders. This is crucial for audio synthesis workflows. The function requires audio data, its sample rate, and a vocoder configuration dictionary specifying parameters like number of mels, FFT details, and model name.

```python
import torch
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us")
audio_wav = aligner.load_audio("audio.wav")
timestamps = aligner.process_sentence("butterfly", audio_wav)

# Vocoder-compatible configuration
vocoder_config = {
    'num_mels': 80,
    'num_freq': 1025,
    'n_fft': 1024,
    'hop_size': 256,
    'win_size': 1024,
    'sampling_rate': 22050,
    'fmin': 0,
    'fmax': 8000,
    'model': 'nvidia/bigvgan_v2_22khz_80band_fmax8k_256x'
}

# Extract segment audio
segment = timestamps['segments'][0]
segment_start = int(segment['start'] * aligner.resampler_sample_rate)
segment_end = int(segment['end'] * aligner.resampler_sample_rate)
segment_wav = audio_wav[:, segment_start:segment_end]

# Extract mel spectrogram
mel_spec = aligner.extract_mel_spectrum(
    wav=segment_wav,
    wav_sample_rate=aligner.resampler_sample_rate,
    vocoder_config=vocoder_config
)

print(f"Mel shape: {mel_spec.shape}")  # (frames, 80)

```

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

### Convert to TextGrid

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Converts a timestamp dictionary, typically generated from alignment, into the Praat TextGrid file format.

```APIDOC
## POST /convert_to_textgrid

### Description
Converts a provided timestamp dictionary into the Praat TextGrid format.

### Method
POST

### Endpoint
/convert_to_textgrid

### Parameters
#### Request Body
- **timestamps_dict** (object) - Required - Timestamp dictionary, typically obtained from alignment results.
- **output_file** (string) - Optional - Path to save the generated TextGrid file. If not provided, the content is returned as a string.
- **include_confidence** (boolean) - Optional - Whether to include confidence values in the output. Defaults to false.

### Request Example
```json
{
  "timestamps_dict": {
    "phonemes": [
      {"start": 0.1, "end": 0.2, "text": "b", "phoneme_idx": 29},
      {"start": 0.2, "end": 0.3, "text": "ʌ", "phoneme_idx": 10}
    ]
  },
  "output_file": "/path/to/output.TextGrid",
  "include_confidence": false
}
```

### Response
#### Success Response (200)
- **textgrid_content** (string) - The content of the TextGrid file as a string, if `output_file` was not specified.

#### Response Example
```
File type = "ooTextFile"
Object class = "TextGrid"

xmin = 0.1 
xmax = 0.3 
tiers? <exists>
 1   name = "phonemes"
 entries? <exists>
  1   interval starts: 0.1 
  2   interval ends: 0.2 
  3   item: "b"
  2   interval starts: 0.2 
  3   interval ends: 0.3 
  4   item: "ʌ"
```
```

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

### Process SRT File

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Processes an SRT file along with its corresponding audio file to generate phoneme timestamps. Supports optional embedding extraction and group timestamp generation.

```APIDOC
## Process SRT File

### Description
Processes an SRT file along with its corresponding audio file to generate phoneme timestamps. Supports optional embedding extraction and group timestamp generation.

### Method
`process_srt_file`

### Endpoint
`/process_srt_file` (This is a method, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **srt_path** (string) - Required - Path to input SRT file (whisper JSON format).
- **audio_path** (string) - Required - Path to audio file.
- **ts_out_path** (string) - Optional - Output path for timestamps (vs2 format).
- **extract_embeddings** (boolean) - Optional - Extract embeddings. Default is False.
- **vspt_path** (string) - Optional - Path to save embeddings (`.pt` file).
- **do_groups** (boolean) - Optional - Extract group timestamps. Default is True.
- **debug** (boolean) - Optional - Enable debug output. Default is True.

### Request Example
```python
aligner.process_srt_file(
    srt_path="path/to/your/subtitle.srt",
    audio_path="path/to/your/audio.wav",
    ts_out_path="path/to/output/timestamps.vs2",
    extract_embeddings=False,
    vspt_path=None,
    do_groups=True,
    debug=True
)
```

### Response
#### Success Response (200)
- **timestamps_dict** (dict) - Dictionary with extracted timestamps.

#### Response Example
```json
{
    "timestamps_dict": {
        "segments": [
            {
                "start": 0.123,
                "end": 1.456,
                "text": "Hello world",
                "phonemes": [
                    {"start": 0.123, "end": 0.234, "text": "h"},
                    {"start": 0.234, "end": 0.345, "text": "ə"},
                    // ... more phonemes
                ]
            }
            // ... more segments
        ]
    }
}
```
```

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

### Generate Frame-Level Phoneme Labels for TTS with Python

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Converts time-aligned phoneme data into frame-wise labels that match mel spectrogram frames, essential for Text-to-Speech (TTS) systems. It requires the aligned phoneme timestamps, total number of frames, frames per second, and optional gap contraction parameters. The output can be compressed for storage.

```python
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us")
audio_wav = aligner.load_audio("audio.wav")
timestamps = aligner.process_sentence("butterfly", audio_wav)

segment = timestamps['segments'][0]
segment_duration = segment['end'] - segment['start']

# Calculate frame parameters
vocoder_hop_size = 256
vocoder_sample_rate = 22050
total_frames = int(segment_duration * vocoder_sample_rate / vocoder_hop_size)
frames_per_second = vocoder_sample_rate / vocoder_hop_size

# Get frame-wise phoneme labels
frame_labels = aligner.framewise_assortment(
    aligned_ts=segment['phoneme_ts'],
    total_frames=total_frames,
    frames_per_second=frames_per_second,
    gap_contraction=5,  # Frames to fill silent gaps
    select_key="phoneme_idx"  # Can also use "phoneme_label", "group_idx", "group_label"
)

# Convert to IPA labels
frame_labels_ipa = [aligner.phoneme_id_to_label[idx] for idx in frame_labels]

# Compress for storage efficiency
compressed = aligner.compress_frames(frame_labels_ipa)
print(compressed)  # [('b', 4), ('ʌ', 3), ('ɾ', 2), ...]

# Decompress back to full sequence
decompressed = aligner.decompress_frames(compressed)
assert decompressed == frame_labels_ipa

```

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

### Convert Text to Phonemes

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Phonemizes a given text sentence into IPA, ph66, and pg16 phoneme representations. It also provides word-to-phoneme mappings and allows for setting the phonemizer language.

```APIDOC
## POST /phonemize

### Description
Phonemizes a sentence and returns a detailed mapping including IPA, ph66, pg16 phoneme indices, and word correspondences.

### Method
POST

### Endpoint
/phonemize

### Parameters
#### Request Body
- **text** (string) - Required - The input sentence to phonemize.
- **language** (string) - Optional - The language code for the phonemizer (e.g., 'en'). Defaults to the initialized language.

### Request Example
```json
{
  "text": "butterfly",
  "language": "en"
}
```

### Response
#### Success Response (200)
- **text** (string) - The original input sentence.
- **ipa** (array[string]) - List of phonemes in IPA format.
- **ph66** (array[integer]) - List of phoneme class indices (mapped to 66-class set).
- **pg16** (array[integer]) - List of phoneme group indices (16 broad categories).
- **words** (array[string]) - List of words corresponding to phonemes.
- **word_num** (array[integer]) - Word indices for each phoneme.

#### Response Example
```json
{
  "text": "butterfly",
  "ipa": [
    "b",
    "ʌ",
    "ɾ",
    "ɚ",
    "f",
    "l",
    "aɪ"
  ],
  "ph66": [
    29,
    10,
    58,
    9,
    43,
    56,
    23
  ],
  "pg16": [
    7,
    2,
    14,
    2,
    8,
    13,
    5
  ],
  "words": [
    "butterfly"
  ],
  "word_num": [
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ]
}
```
```

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

### Process Text Sentences

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Processes raw text sentences and their corresponding audio waveforms to generate phoneme timestamps. Supports optional embedding extraction and group timestamp generation.

```APIDOC
## Process Text Sentences

### Description
Processes raw text sentences and their corresponding audio waveforms to generate phoneme timestamps. Supports optional embedding extraction and group timestamp generation.

### Method
`process_sentence`

### Endpoint
`/process_sentence` (This is a method, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (string) - Required - Sentence/text.
- **audio_wav** (torch.Tensor) - Required - Audio waveform tensor.
- **ts_out_path** (string) - Optional - Output path for timestamps (vs2 format).
- **extract_embeddings** (boolean) - Optional - Extract embeddings. Default is False.
- **vspt_path** (string) - Optional - Path to save embeddings (`.pt` file).
- **do_groups** (boolean) - Optional - Extract group timestamps. Default is True.
- **debug** (boolean) - Optional - Enable debug output. Default is False.

### Request Example
```python
import torch

# Assume aligner is an initialized PhonemeTimestampAligner object
aligner = PhonemeTimestampAligner(preset="en-us", lang="en-us")

text_to_process = "This is a sample sentence."
audio_data = torch.randn(16000) # Example audio tensor (1 second at 16kHz)

aligner.process_sentence(
    text=text_to_process,
    audio_wav=audio_data,
    ts_out_path="path/to/output/sentence_timestamps.vs2",
    extract_embeddings=False,
    vspt_path=None,
    do_groups=True,
    debug=False
)
```

### Response
#### Success Response (200)
- **timestamps_dict** (dict) - Dictionary with extracted timestamps.

#### Response Example
```json
{
    "timestamps_dict": {
        "segments": [
            {
                "start": 0.123,
                "end": 1.456,
                "text": "This is a sample sentence.",
                "phonemes": [
                    {"start": 0.123, "end": 0.234, "text": "ð"},
                    {"start": 0.234, "end": 0.345, "text": "ɪ"},
                    // ... more phonemes
                ]
            }
        ]
    }
}
```
```

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

### Process SRT File with Bournemouth Aligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Processes an SRT file along with its corresponding audio file to generate timestamps. Supports embedding extraction and group timestamp generation. Debugging output can be enabled.

```python
PhonemeTimestampAligner.process_srt_file(
    srt_path,
    audio_path,
    ts_out_path=None,
    extract_embeddings=False,
    vspt_path=None,
    do_groups=True,
    debug=True
)
```

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

### Process SRT Transcription Files with Audio

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Processes audio files using provided SRT transcription files in JSON format. This function is useful for aligning audio with external speech recognition outputs, such as those from Whisper. It outputs detailed timestamp information.

```python
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us", duration_max=10, device="cpu")

# SRT file format (JSON):
# {
#   "segments": [
#     {"start": 0.0, "end": 3.5, "text": "hello world"},
#     {"start": 3.5, "end": 7.2, "text": "another segment"}
#   ]
# }

result = aligner.process_srt_file(
    srt_path="transcription.srt.json",
    audio_path="audio.wav",
    ts_out_path="timestamps.json",
    extract_embeddings=False,
    vspt_path=None,  # Optional: save embeddings to .pt file
    do_groups=True,
    debug=True
)

# Process multiple segments from Whisper output
for segment in result["segments"]:
    print(f"Text: {segment['text']}")
    print(f"Phonemes: {len(segment['phoneme_ts'])}")
    for ph in segment["phoneme_ts"]:
        print(f"  {ph['phoneme_label']}: {ph['start_ms']:.1f}-{ph['end_ms']:.1f}ms (conf: {ph['confidence']:.2f})")
```

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

### Convert Timestamps to Praat TextGrid Format with Python

Source: https://context7.com/tabahi/bournemouth-forced-aligner/llms.txt

Converts timestamp dictionaries generated by the aligner into Praat TextGrid format. This format is useful for visualizing phonetic alignments. The function can save the output to a file or return it as a string. It supports including confidence scores in the labels.

```python
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us")
audio_wav = aligner.load_audio("audio.wav")
timestamps = aligner.process_sentence("hello world", audio_wav)

# Convert to TextGrid format
textgrid_content = aligner.convert_to_textgrid(
    timestamps_dict=timestamps,
    output_file="output.TextGrid",
    include_confidence=False  # Set True to include confidence in labels
)

# Or get as string without saving
textgrid_str = aligner.convert_to_textgrid(timestamps, output_file=None)
print(textgrid_str)
# Output:
# File type = "ooTextFile"
# Object class = "TextGrid"
# xmin = 0
# xmax = 1.2588125
# tiers? <exists>
# size = 3
# item []:
#     item [1]:
#         class = "IntervalTier"
#         name = "phonemes"
#         ...

```

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

### Compress Frames (Run-Length Encoding)

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Compresses a list of frame labels using run-length encoding, grouping consecutive identical values.

```APIDOC
## POST /compress_frames

### Description
Compresses a list of frame labels into a run-length encoded format, representing consecutive identical values as (value, count) tuples.

### Method
POST

### Endpoint
/compress_frames

### Parameters
#### Request Body
- **frames_list** (array) - Required - The list of frame labels to compress.

### Request Example
```json
{
  "frames_list": [
    0, 0, 0, 0, 1, 1, 1, 1, 3, 4, 5, 4, 5, 2, 2, 2
  ]
}
```

### Response
#### Success Response (200)
- **compressed_frames** (array[object]) - List of `(frame_value, count)` tuples representing the run-length encoded data.

#### Response Example
```json
[
  {"value": 0, "count": 4},
  {"value": 1, "count": 4},
  {"value": 3, "count": 1},
  {"value": 4, "count": 1},
  {"value": 5, "count": 1},
  {"value": 4, "count": 1},
  {"value": 5, "count": 1},
  {"value": 2, "count": 3}
]
```
```

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

### Convert Timestamps to Praat TextGrid Format

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/README.md

Converts alignment timestamp data into the Praat TextGrid file format. This is useful for visualizing alignments in acoustic analysis software. It can optionally save the output to a file and include confidence values.

```python
from bfa.aligner import PhonemeTimestampAligner

# Assuming timestamps_dict is available from extract_timestamps_from_segment
textgrid_content = PhonemeTimestampAligner.convert_to_textgrid(
    timestamps_dict,
    output_file="output.TextGrid",
    include_confidence=False
)
```