Bournemouth Forced Aligner

https://github.com/tabahi/bournemouth-forced-aligner
Admin
Bournemouth Forced Aligner (BFA) is a lightning-fast, high-precision Python library for...
Tokens:42,518
Snippets:407
Trust Score:7.9
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Verify installation

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

Run a Python command to verify that the library is correctly installed and importable.

```python
python -c "from bournemouth_aligner import PhonemeTimestampAligner; print('Installation successful')"
```

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

### Complete Mel-spectrum Alignment Example

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

A full workflow example demonstrating audio loading, timestamp processing, mel-spectrogram extraction, and frame compression.

```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='auto')

# 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
```

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

### Language Preset Examples

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Demonstrates usage of different language presets for phoneme alignment.

```bash
balign speech.wav "hello world" --preset=en-us     # English (US)
balign speech.wav "hallo welt" --preset=de          # German
balign speech.wav "bonjour monde" --preset=fr       # French
balign speech.wav "नमस्ते" --preset=hi              # Hindi
balign speech.wav "مرحبا بالعالم" --preset=ar      # Arabic
```

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

### Load audio for alignment

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Examples of loading audio from a file path or an existing tensor.

```python
audio_wav = aligner.load_audio("butterfly.wav")
# Returns tensor of shape (1, N) at 16 kHz
```

```python
import torchaudio
wav, sr = torchaudio.load("speech.wav")
audio_wav = aligner.load_audio(wav, sr=sr)
```

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

### Install System Dependencies on macOS

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

Install required system-level dependencies using Homebrew.

```bash
brew install espeak-ng ffmpeg
```

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

### Vocoder Configuration Examples

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

Common configuration instances for HiFi-GAN and BigVGAN vocoders.

```python
{
    'num_mels': 80,
    'num_freq': 1025,
    'n_fft': 1024,
    'hop_size': 256,
    'win_size': 1024,
    'sampling_rate': 22050,
    'fmin': 0,
    'fmax': 8000,
    'model': 'hifigan_22khz_80band_fmax8k_256x'
}
```

```python
{
    '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'
}
```

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

### Install System Dependencies on Linux

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

Install required system-level dependencies for Ubuntu or Debian distributions.

```bash
sudo apt-get install espeak-ng ffmpeg
```

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

### Configure Aligner via Presets and Explicit Parameters

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

Examples showing how to initialize the aligner using recommended presets, explicit model names, or direct checkpoint paths.

```python
aligner = PhonemeTimestampAligner(
    preset="hi",           # Selects Universal model + hi language
    duration_max=15,       # Your customizations
    silence_anchors=5
)
```

```python
aligner = PhonemeTimestampAligner(
    model_name="large_multi_mswc38_ua02g_e03_val_GER=0.5133.ckpt",
    lang="hi",
    duration_max=15,
    device="cuda"
)
```

```python
aligner = PhonemeTimestampAligner(
    cupe_ckpt_path="/workspace/finetuned_model.ckpt",
    lang="en-us"
)
```

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

### Install Bournemouth Forced Aligner

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

Use pip to install the library in your Python environment.

```bash
pip install bournemouth-forced-aligner
```

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

### Check Version

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Use the --version flag to display the current installed version of the BFA tool.

```bash
balign --version
# Output: 1.1.4
```

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

### Export TextGrid Examples

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Demonstrates saving alignment results to a file or retrieving them as a string for custom pipelines.

```python
result = aligner.process_sentence("hello world", audio)
aligner.convert_to_textgrid(result, output_file="hello.TextGrid")
# Open in Praat: File → Open → Read from file
```

```python
textgrid_str = aligner.convert_to_textgrid(result, output_file=None)
# Embed in web interface, send over network, etc.
```

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

### Phoneme Frame Selection Example

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

Example mapping of phoneme IDs to frame sequences.

```python
phoneme_frames = [29, 29, 29, 10, 10, 10, 58, ...]
# Frame 0–2: phoneme 29 (b)
# Frame 3–5: phoneme 10 (ʌ)
# Frame 6+: phoneme 58 (ɾ)
```

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

### Group Frame Selection Example

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

Example mapping of group IDs to frame sequences.

```python
group_frames = [7, 7, 7, 2, 2, 2, 14, ...]
# Frame 0–2: group 7 (voiced_stops)
# Frame 3–5: group 2 (central_vowels)
# Frame 6+: group 14 (rhotics)
```

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

### Install dependencies via Conda

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

Create and configure a conda environment with required dependencies.

```bash
conda create -n bfa
conda activate bfa
conda install pip
conda install "ffmpeg"
# or
conda install "ffmpeg" -c conda-forge
```

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

### Align SRT File Example

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Demonstrates how to align an SRT file and perform basic quality checks on the output segments.

```python
result = aligner.process_srt_file(
    "interview.srt.json",
    "interview.wav",
    ts_out_path="interview_aligned.json",
    do_groups=True,
    debug=True
)

# Check quality
print(f"Total segments: {len(result['segments'])}")
for seg in result['segments']:
    if seg['coverage_analysis']['bad_confidence']:
        print(f"WARNING: Low confidence in '{seg['text']}'")
```

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

### Example Output Structure

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

A sample JSON structure showing the phoneme array format used by the aligner.

```json
{
                        "ɚ",
                        "f",
                        "l",
                        "aɪ"
                    ]
                }
            ]
        }
    ]
}
```

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

### Install espeak-ng dependency

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Required system dependency for text-to-speech processing.

```bash
apt-get install espeak-ng
```

```bash
brew install espeak-ng
```

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

### Sample JSON output structure

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

Example of the JSON structure returned by the alignment process.

```json
{
    "segments": [
        {
            "start": 0.0,
            "end": 1.2588125,
            "text": "butterfly",
            "ph66": [
                29,
                10,
                58,
                9,
                43,
                56,
                23
            ],
            "pg16": [
                7,
                2,
                14,
                2,
                8,
                13,
                5
            ],
            "coverage_analysis": {
                "target_count": 7,
                "aligned_count": 7,
                "missing_count": 0,
                "extra_count": 0,
                "coverage_ratio": 1.0,
                "missing_phonemes": [],
                "extra_phonemes": []
            },
            "ipa": [
                "b",
                "ʌ",
                "ɾ",
                "ɚ",
                "f",
                "l",
                "aɪ"
            ],
            "word_num": [
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ],
            "words": [
                "butterfly"
            ],
            "phoneme_ts": [
                {
                    "phoneme_id": 29,
                    "phoneme_label": "b",
                    "ipa_label": "b",
                    "start_ms": 33.56833267211914,
                    "end_ms": 50.35249710083008,
                    "confidence": 0.9970603585243225,
                    "is_estimated": false,
                    "target_seq_idx": 0,
                    "index": 0
                },
                {
                    "phoneme_id": 10,
                    "phoneme_label": "ʌ",
                    "ipa_label": "ʌ",
                    "start_ms": 100.70499420166016,
                    "end_ms": 117.48916625976562,
                    "confidence": 0.8809734582901001,
                    "is_estimated": false,
                    "target_seq_idx": 1,
                    "index": 1
                },
                {
                    "phoneme_id": 58,
                    "phoneme_label": "ɾ",
                    "ipa_label": "ɾ",
                    "start_ms": 134.27333068847656,
                    "end_ms": 151.0574951171875,
                    "confidence": 0.07298105955123901,
                    "is_estimated": false,
                    "target_seq_idx": 2,
                    "index": 2
                },
                {
                    "phoneme_id": 9,
                    "phoneme_label": "ɚ",
                    "ipa_label": "ɚ",
```

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

### CLI Usage Examples

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

Common command-line operations for alignment, including language presets, embedding extraction, and batch processing.

```bash
# Align a single word — text mode (simplest)
balign butterfly.wav "butterfly" --preset=en-us

# Save a mel-spectrogram image at the same time
balign butterfly.wav "butterfly" --preset=en-us --mel-path=mel_spectrum.png

# Align a full sentence, save TextGrid for Praat
balign speech.wav "hello world" result.json --preset=en-us --textgrid=result.TextGrid

# Align from a Whisper transcript file (SRT mode)
balign interview.wav transcript.srt.json aligned.json --preset=en-us

# German
balign speech.wav "hallo welt" --preset=de

# Hindi with GPU
balign speech.wav "नमस्ते" out.json --preset=hi --device=cuda

# Save phoneme embeddings
balign speech.wav "hello world" out.json --preset=en-us --embeddings=emb.pt

# Batch-align all wav files in a folder (SRT mode)
for f in *.wav; do balign "$f" "${f%.wav}.srt.json" "${f%.wav}.vs.json" --preset=en-us; done
```

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

### Perform basic single-sentence alignment

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Example of aligning a simple transcript and iterating through phoneme timestamps.

```python
result = aligner.process_sentence("butterfly", audio_wav)
for phoneme in result["segments"][0]["phoneme_ts"]:
    print(f"{phoneme['ipa_label']:>5} {phoneme['start_ms']:.1f}–{phoneme['end_ms']:.1f} ms (conf: {phoneme['confidence']:.2f})")
```

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

### Compress and Decompress Frames

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

Example of defining a compressed frame list and using the aligner to decompress it back into a full frame sequence.

```python
compressed = [(29, 3), (10, 3), (58, 1), (9, 1), (43, 1), (56, 1), (23, 1)]
# 3 frames of phoneme 29
# 3 frames of phoneme 10
# 1 frame each of 58, 9, 43, 56, 23
```

```python
frames = aligner.decompress_frames(compressed)
# frames = [29, 29, 29, 10, 10, 10, 58, 9, 43, 56, 23]
```

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

### Compound phoneme JSON structure

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

Example of how compound phonemes like /ɑːɹ/ are represented in the output JSON.

```json
{
    "phoneme_id": 19,
    "phoneme_label": "a:",
    "ipa_label": "ɑːɹ",
    "start_ms": 2478.1,
    "end_ms": 2606.8,
    "confidence": 0.937,
    "is_estimated": false
},
{
    "phoneme_id": 59,
    "phoneme_label": "ɹ",
    "ipa_label": "-",
    "start_ms": 2606.8,
    "end_ms": 2639.0,
    "confidence": 0.665,
    "is_estimated": false
}
```

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

### Initialize with Language Presets

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

Use presets to automatically select the appropriate model and espeak-ng language, or defer loading by setting the preset to None.

```python
# English
PhonemeTimestampAligner(preset="en-us")

# German
PhonemeTimestampAligner(preset="de")

# Hindi
PhonemeTimestampAligner(preset="hi")

# Deferred loading (load model later)
aligner = PhonemeTimestampAligner(preset=None)
aligner.load_model(preset="fr")  # Load later
```

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

### List Available Presets

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Displays all supported language presets.

```bash
balign --list-presets
```

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

### Initialize with Local Checkpoint Paths

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

Provide a direct filesystem path to a .ckpt file to override all other model selection parameters.

```python
# Local model file
aligner = PhonemeTimestampAligner(
    cupe_ckpt_path="/home/models/my_custom_model.ckpt",
    lang="en-us"
)

# Trained fine-tuned model
aligner = PhonemeTimestampAligner(
    cupe_ckpt_path="/workspace/finetuned_english_v2.ckpt",
    lang="en-us"
)
```

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

### Define segment dictionary structure

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Example structure of the dictionary returned by the alignment process.

```json
{
    "start": 0.0,               # Segment start in seconds
    "end": 1.259,               # Segment end in seconds
    "text": "butterfly",        # Transcript
    "ph66": [29, 10, 58, ...],  # Phoneme IDs (66-class set)
    "pg16": [7, 2, 14, ...],    # Phoneme group IDs (16-class set)
    "ipa": ["b", "ʌ", "ɾ", ...], # IPA labels (original espeak-ng)
    "words": ["butterfly"],      # Word list
    "word_num": [0, 0, ...],    # Word index per phoneme
    "coverage_analysis": {       # Quality metrics
        "target_count": 7,
        "aligned_count": 7,
        "missing_count": 0,
        "extra_count": 0,
        "coverage_ratio": 1.0,
        "missing_phonemes": [],
        "extra_phonemes": [],
        "bad_confidence": False
    },
    "phoneme_ts": [
        {
            "phoneme_id": 29,
            "phoneme_label": "b",
            "ipa_label": "b",
            "start_ms": 33.57,
            "end_ms": 50.35,
            "confidence": 0.99,
            "is_estimated": False,
            "target_seq_idx": 0,
            "index": 0
        },
        # ... one per phoneme
    ],
    "group_ts": [  # Only if do_groups=True
        {
            "group_id": 7,
            "group_label": "voiced_stops",
            "start_ms": 33.57,
            "end_ms": 50.35,
            "confidence": 0.998,
            "is_estimated": False,
            "target_seq_idx": 0,
            "index": 0
        },
        # ... one per group
    ],
    "words_ts": [
        {
            "word": "butterfly",
            "start_ms": 33.57,
            "end_ms": 621.01,
            "confidence": 0.655,
            "ph66": [29, 10, 58, ...],
            "ipa": ["b", "ʌ", "ɾ", ...]
        }
    ]
}
```

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

### Initialize PhonemeTimestampAligner

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

Configure the aligner with language presets, hardware device selection, and alignment constraints.

```python
aligner = PhonemeTimestampAligner(
    preset="en-us",              # Language preset
    model_name=None,             # Explicit model name
    cupe_ckpt_path=None,        # Direct checkpoint path
    lang="en-us",               # Phonemization language
    duration_max=30,            # Max segment duration (seconds)
    device="auto",              # "cpu" | "cuda" | "mps" | "auto"
    silence_anchors=10,         # Silence-based segmentation
    boost_targets=True,         # Boost target phoneme probabilities
    enforce_minimum=True,       # Minimum probability floor
    enforce_all_targets=True,   # Force path through all targets
    ensure_completeness=False,  # Post-alignment recovery
    ignore_noise=True,          # Skip noise frames
    extend_soft_boundaries=True,# Extend into adjacent frames
    boundary_softness=3,        # Extension leniency (0-7)
    bad_confidence_threshold=0.6 # Quality flagging threshold
)
```

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

### Initialize and Run Phoneme Alignment

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Demonstrates basic usage of the aligner with an English preset to process a sentence and retrieve phoneme timestamps.

```python
from bournemouth_aligner import PhonemeTimestampAligner

aligner = PhonemeTimestampAligner(preset="en-us")
audio = aligner.load_audio("speech.wav")
result = aligner.process_sentence("hello world", audio)
print(result["segments"][0]["phoneme_ts"])
```

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

### Implement Production Alignment Service in Python

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/usage-patterns.md

This pattern demonstrates a production-ready service class with integrated logging, error handling, and batch directory processing.

```python
import logging
import json
import traceback
from pathlib import Path
from datetime import datetime
from bournemouth_aligner import PhonemeTimestampAligner

# Setup logging
logging.basicConfig(
    filename="bfa_production.log",
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)

class BFAAlignmentService:
    """Production alignment service with monitoring."""
    
    def __init__(self, preset="en-us", device="auto"):
        self.aligner = PhonemeTimestampAligner(preset=preset, device=device)
        logger.info(f"BFA initialized (preset={preset}, device={device})")
    
    def align_file(self, audio_path, transcript_path, output_path):
        """Align audio file and save results."""
        try:
            logger.info(f"Processing: {audio_path}")
            
            # Load inputs
            audio = self.aligner.load_audio(audio_path)
            with open(transcript_path) as f:
                transcript = json.load(f)
            
            # Align
            result = self.aligner.process_srt_file(
                transcript_path,
                audio_path,
                ts_out_path=output_path,
                debug=False
            )
            
            # Validate output
            for seg in result["segments"]:
                if seg["coverage_analysis"]["coverage_ratio"] < 0.9:
                    logger.warning(f"Low coverage in segment: {seg['text'][:50]}")
            
            logger.info(f"✓ Completed: {output_path}")
            return True
        
        except Exception as e:
            logger.error(f"✗ Failed to align {audio_path}: {e}\n{traceback.format_exc()}")
            return False
    
    def process_directory(self, input_dir, output_dir):
        """Process all audio files in directory."""
        input_dir = Path(input_dir)
        output_dir = Path(output_dir)
        output_dir.mkdir(exist_ok=True)
        
        audio_files = list(input_dir.glob("*.wav"))
        results = {"total": len(audio_files), "succeeded": 0, "failed": 0}
        
        for audio_file in audio_files:
            srt_file = audio_file.with_suffix(".srt.json")
            if not srt_file.exists():
                logger.warning(f"No transcript for {audio_file}")
                continue
            
            output_file = output_dir / f"{audio_file.stem}_aligned.json"
            success = self.align_file(str(audio_file), str(srt_file), str(output_file))
            
            if success:
                results["succeeded"] += 1
            else:
                results["failed"] += 1
        
        logger.info(f"Batch complete: {results['succeeded']}/{results['total']} succeeded")
        return results

# Usage
if __name__ == "__main__":
    service = BFAAlignmentService(preset="en-us", device="cuda")
    results = service.process_directory("./audio_files", "./aligned_output")
    print(f"Results: {results}")
```

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

### Align a single audio file with Python

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/usage-patterns.md

Initializes the aligner with a preset, processes a single sentence, and exports the results to JSON.

```python
from bournemouth_aligner import PhonemeTimestampAligner
import json

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

# Load audio
audio = aligner.load_audio("speech.wav")

# Align
result = aligner.process_sentence("hello world", audio)

# Access results
seg = result["segments"][0]
print(f"Aligned {len(seg['phoneme_ts'])} phonemes")
for p in seg["phoneme_ts"]:
    print(f"  {p['ipa_label']:>5} {p['start_ms']:>7.1f}–{p['end_ms']:<7.1f} ms")

# Save to JSON
with open("output.json", "w") as f:
    json.dump(result, f, indent=2)
```

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

### Perform alignment with embeddings for TTS training

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Example of extracting phoneme and group embeddings alongside alignment data.

```python
result, phoneme_emb, group_emb = aligner.process_sentence(
    "hello world",
    audio_wav,
    extract_embeddings=True,
    do_groups=True,
    debug=True
)
print(f"Phoneme embeddings shape: {phoneme_emb.shape}")  # (num_phonemes, 512)
```

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

### Initialize PhonemeTimestampAligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Configure the aligner using language presets or a direct path to a custom checkpoint file.

```python
aligner = PhonemeTimestampAligner(
    preset="de",
    duration_max=15,
    device="cuda",
    silence_anchors=5
)
```

```python
aligner = PhonemeTimestampAligner(
    cupe_ckpt_path="/home/models/custom_model.ckpt",
    lang="ja",
    device="auto"
)
```

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

### Initialize and use PhonemeTimestampAligner

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

Basic usage pattern for initializing the aligner, loading audio, and processing a text string.

```python
aligner = PhonemeTimestampAligner(preset="en-us")
audio = aligner.load_audio("speech.wav")
result = aligner.process_sentence("hello", audio)
```

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

### Check Version and Device Capabilities in Python

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/usage-patterns.md

Use this pattern to verify library versions, check for CUDA availability, and implement a fallback mechanism for the aligner device.

```python
from bournemouth_aligner import __version__
from bournemouth_aligner import PhonemeTimestampAligner
import sys

print(f"BFA Version: {__version__}")
print(f"Python: {sys.version}")

# Check device support
import torch
print(f"PyTorch: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"CUDA device: {torch.cuda.get_device_name(0)}")

# Initialize and check loaded capabilities
try:
    aligner = PhonemeTimestampAligner(preset="en-us", device="cuda")
    print(f"✓ GPU inference available")
except RuntimeError:
    print(f"✗ GPU inference failed, falling back to CPU")
    aligner = PhonemeTimestampAligner(preset="en-us", device="cpu")

# Check supported features
print(f"Supported presets: 80+")
print(f"Max languages: Supports all esp speak-ng languages")
```

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

### Extend phoneme boundaries

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/advanced-methods.md

Adjusts phoneme start and end indices by extending them into adjacent frames based on acoustic confidence and a softness parameter.

```python
def extend_soft_boundaries_func(
    self,
    log_probs,
    framestamps,
    boundary_softness=3,
    debug=False
) -> list
```

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

### Compound Phoneme IPA Representation

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

Example showing how compound phonemes are represented with a full IPA label followed by continuation frames marked with a hyphen.

```python
{
    "phoneme_id": 19,
    "phoneme_label": "a:",
    "ipa_label": "ɑːɹ",      # Full IPA label
    "start_ms": 2478.1,
    "end_ms": 2606.8
},
{
    "phoneme_id": 59,
    "phoneme_label": "ɹ",
    "ipa_label": "-",         # Continuation marker
    "start_ms": 2606.8,
    "end_ms": 2639.0
}
```

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

### Align audio using Python

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

Load audio and perform alignment using the PhonemeTimestampAligner class. The model is downloaded automatically on the first run.

```python
from bournemouth_aligner import PhonemeTimestampAligner

# 1. Create the aligner — it will automatically download the right model
#    Change "en-us" to your language code, e.g. "de", "fr", "es", "hi"
aligner = PhonemeTimestampAligner(preset="en-us")

# 2. Load your audio file (WAV, MP3, FLAC, etc.)
audio = aligner.load_audio("butterfly.wav")

# 3. Run alignment
#    Provide the transcript exactly as spoken in the audio
result = aligner.process_sentence("butterfly", audio)

# 4. Print the phoneme timestamps
for phoneme in result["segments"][0]["phoneme_ts"]:
    print(f"{phoneme['ipa_label']:>5}  {phoneme['start_ms']:.0f} ms – {phoneme['end_ms']:.0f} ms  (confidence: {phoneme['confidence']:.2f})")
```

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

### Whisper JSON Transcript Format

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

The input transcript file must follow this JSON structure, containing an array of segments with start, end, and text fields.

```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"
    },
    {
      "start": 7.2,
      "end": 12.0,
      "text": "final segment here"
    }
  ]
}
```

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

### Initialize PhonemeTimestampAligner with Language Presets

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

Instantiate the aligner by providing a specific language preset code to automatically select the appropriate model.

```python
aligner = PhonemeTimestampAligner(preset="de")   # German
aligner = PhonemeTimestampAligner(preset="hi")   # Hindi
aligner = PhonemeTimestampAligner(preset="fr")   # French
aligner = PhonemeTimestampAligner(preset="ar")   # Arabic
aligner = PhonemeTimestampAligner(preset="ru")   # Russian
```

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

### Basic CLI Syntax

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

General structure for executing the alignment command.

```bash
balign AUDIO_PATH TEXT_OR_SRT [OUTPUT_PATH] [OPTIONS]
```

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

### Project File Structure

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

Visual representation of the BFA repository directory layout.

```text
bournemouth_aligner/
├── __init__.py              # Package entry point
├── core.py                  # PhonemeTimestampAligner class
├── cli.py                   # Command-line interface
├── forced_alignment.py       # Viterbi decoder
├── presets.py               # Language presets
├── utils.py                 # Utilities (TextGrid, visualization, etc.)
├── ipamappers/
│   ├── ph66_mapper.py       # Phoneme mapping logic
│   └── ph66_phonemeizer.py  # Phonemizer wrapper (espeak-ng)
├── cupe2i/
│   ├── model2i.py          # CUPE-2i neural model
│   ├── model_utils.py       # Model utilities
│   └── windowing.py         # Audio windowing
├── helpers/
│   └── mel_spec.py          # Mel-spectrogram extraction
└── cpp_onnx/                # ONNX export (in progress)
```

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

### Switching Languages at Runtime with PhonemeTimestampAligner

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/usage-patterns.md

Demonstrates how to reuse a single aligner instance for multiple languages by updating the phonemizer backend.

```python
from bournemouth_aligner import PhonemeTimestampAligner

# Initialize once
aligner = PhonemeTimestampAligner(
    model_name="large_multi_mswc38_ua02g_e03_val_GER=0.5133.ckpt",
    lang="en-us",
    device="cuda"
)

# English
audio_en = aligner.load_audio("english.wav")
result_en = aligner.process_sentence("hello world", audio_en)
print(f"English: {len(result_en['segments'][0]['phoneme_ts'])} phonemes")

# Switch to German
aligner.phonemizer.set_backend(language="de")
audio_de = aligner.load_audio("german.wav")
result_de = aligner.process_sentence("Hallo Welt", audio_de)
print(f"German: {len(result_de['segments'][0]['phoneme_ts'])} phonemes")

# Switch to Hindi
aligner.phonemizer.set_backend(language="hi")
audio_hi = aligner.load_audio("hindi.wav")
result_hi = aligner.process_sentence("नमस्ते", audio_hi)
print(f"Hindi: {len(result_hi['segments'][0]['phoneme_ts'])} phonemes")
```

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

### Full Sentence Alignment with Visualization

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Generate alignment output, a TextGrid file, and a mel-spectrogram visualization simultaneously.

```bash
balign speech.wav "hello world this is a test" output.json \
  --preset=en-us \
  --mel-path=mel.png \
  --textgrid=output.TextGrid \
  --debug
```

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

### Batch Process Audio Files

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Use a shell loop to iterate through all .wav files in a directory and align them individually.

```bash
for wav in *.wav; do
  srt="${wav%.wav}.srt.json"
  json="${wav%.wav}.vs.json"
  balign "$wav" "$srt" "$json" --preset=en-us
  echo "Aligned $wav"
done
```

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

### Batch process audio files with Bash

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/usage-patterns.md

Iterate through a directory of WAV files to align them against corresponding JSON transcripts using the balign CLI tool.

```bash
#!/bin/bash

# Align all WAV files with corresponding SRT transcripts

for audio_file in *.wav; do
    srt_file="${audio_file%.wav}.srt.json"
    output_file="${audio_file%.wav}.vs.json"
    
    if [ ! -f "$srt_file" ]; then
        echo "Skipping $audio_file (no transcript)"
        continue
    fi
    
    echo "Aligning $audio_file..."
    balign "$audio_file" "$srt_file" "$output_file" \
        --preset=en-us \
        --device=cuda \
        --silence-anchors=5 \
        --debug
    
    if [ $? -eq 0 ]; then
        echo "✓ $output_file"
    else
        echo "✗ Failed to align $audio_file"
    fi
done

echo "Done!"
```

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

### Phonemization Inspection and Language Configuration

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Shows how to inspect phoneme indices and change the backend language for phonemization.

```python
result = aligner.phonemize_sentence("butterfly")
print(result["eipa"])      # ['b', 'ʌ', 'ɾ', 'ɚ', 'f', 'l', 'aɪ']
print(result["ph66"])      # [29, 10, 58, 9, 43, 56, 23]
print(result["pg16"])      # [7, 2, 14, 2, 8, 13, 5]
print(result["words"])     # ['butterfly']
```

```python
aligner.phonemizer.set_backend(language='de')
result = aligner.phonemize_sentence("Schmetteling")
```

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

### List Supported Language Presets

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

The --list-presets flag displays all available language configurations and terminates the process without performing alignment.

```bash
balign --list-presets
# Output:
# Supported language presets:
#
# English Variants:
#   en-us, en, en-gb, en-029, en-gb-x-gbclan, en-gb-x-rp, ...
#
# European (MLS8):
#   de, fr, fr-be, fr-ch, es, es-419, it, pt, pt-br, pl, nl, ...
# ...
```

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

### load_audio

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Loads and preprocesses audio for alignment.

```APIDOC
## load_audio

### Description
Load and preprocess audio from file path or tensor, applying RMS normalization and resampling to 16 kHz.

### Parameters
- **audio** (str or torch.Tensor) - Required - Path to audio file or pre-loaded tensor.
- **sr** (int) - Optional - Sample rate of the input tensor (required if audio is a tensor).
```

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

### Initialize aligner for different languages

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

Configure the aligner for specific languages by setting the preset parameter.

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

# French
aligner_fr = PhonemeTimestampAligner(preset="fr")

# Hindi
aligner_hi = PhonemeTimestampAligner(preset="hi")

# Spanish
aligner_es = PhonemeTimestampAligner(preset="es")
```

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

### balign AUDIO_PATH TEXT_OR_SRT [OUTPUT_PATH] [OPTIONS]

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

The primary command for aligning audio with text or transcript files.

```APIDOC
## balign AUDIO_PATH TEXT_OR_SRT [OUTPUT_PATH] [OPTIONS]

### Description
Aligns an audio file with provided text or a transcript file. The tool automatically detects whether the input is a sentence or a JSON transcript file.

### Parameters
#### Positional Arguments
- **AUDIO_PATH** (string) - Required - Path to the audio file (WAV, MP3, FLAC, OGG, M4A, etc.).
- **TEXT_OR_SRT** (string) - Required - A quoted sentence or path to a JSON transcript file.
- **OUTPUT_PATH** (string) - Optional - Path to save the alignment results as JSON. Defaults to <AUDIO_NAME>.vs.json.

#### Options
- **--preset** (string) - Optional - Language preset code (default: "en-us").
- **--model** (string) - Optional - Override the CUPE model name.
- **--lang** (string) - Optional - espeak-ng language code for phonemization.
```

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

### Align audio via command line

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

Execute phoneme alignment directly from the terminal without requiring Python code.

```bash
balign butterfly.wav "butterfly" --preset=en-us --mel-path=mel_spectrum.png
```

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

### GPU Inference with Custom Model

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/cli-reference.md

Run alignment on a GPU device using a specific custom model checkpoint.

```bash
balign speech.wav "hello world" output.json \
  --device=cuda \
  --model=large_multi_mswc38_ua02g_e03_val_GER=0.5133.ckpt \
  --lang=en-us
```

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

### Configure boost_targets for PhonemeTimestampAligner

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

Toggle acoustic probability boosting for target phonemes to improve alignment in noisy or cross-lingual audio.

```python
# Enable boosting (default)
aligner = PhonemeTimestampAligner(preset="en-us", boost_targets=True)

# Disable boosting (probabilistically strict)
aligner = PhonemeTimestampAligner(preset="en-us", boost_targets=False)
```

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

### PhonemeTimestampAligner.__init__

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

Initializes the aligner with specific language presets, model paths, and alignment constraints.

```APIDOC
## PhonemeTimestampAligner.__init__

### Description
Initializes the alignment engine with configuration parameters for language, device, and alignment behavior.

### Parameters
- **preset** (str) - Optional - Language preset (e.g., "en-us").
- **model_name** (str) - Optional - Explicit model name.
- **cupe_ckpt_path** (str) - Optional - Path to checkpoint.
- **lang** (str) - Optional - Phonemization language.
- **duration_max** (int) - Optional - Max segment duration in seconds.
- **device** (str) - Optional - Computation device ("cpu", "cuda", "mps", "auto").
- **silence_anchors** (int) - Optional - Silence-based segmentation threshold.
- **boost_targets** (bool) - Optional - Boost target phoneme probabilities.
- **enforce_minimum** (bool) - Optional - Minimum probability floor.
- **enforce_all_targets** (bool) - Optional - Force path through all targets.
- **ensure_completeness** (bool) - Optional - Post-alignment recovery.
- **ignore_noise** (bool) - Optional - Skip noise frames.
- **extend_soft_boundaries** (bool) - Optional - Extend into adjacent frames.
- **boundary_softness** (int) - Optional - Extension leniency (0-7).
- **bad_confidence_threshold** (float) - Optional - Quality flagging threshold.
```

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

### PhonemeTimestampAligner.__init__

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/phoneme-timestamp-aligner.md

Initializes the aligner with specific model presets or custom checkpoint paths.

```APIDOC
## PhonemeTimestampAligner.__init__

### Description
Initializes the aligner instance. You can either use a predefined preset or provide a direct path to a custom checkpoint.

### Parameters
- **preset** (str) - Optional - Preset configuration (e.g., "de").
- **cupe_ckpt_path** (str) - Optional - Path to a custom model checkpoint.
- **lang** (str) - Optional - Language code (e.g., "ja").
- **duration_max** (int) - Optional - Maximum duration for alignment.
- **device** (str) - Optional - Device to run on (e.g., "cuda", "auto").
- **silence_anchors** (int) - Optional - Number of silence anchors.
```

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

### Perform Batch Phoneme Alignment

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/advanced-methods.md

Demonstrates how to prepare audio and phoneme tensors for batch processing and extract timestamps with optional embeddings.

```python
import torch

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

# Prepare batch
audio1 = aligner.load_audio("speech1.wav")
audio2 = aligner.load_audio("speech2.wav")

# Pad to same length
max_len = max(audio1.shape[1], audio2.shape[1])
audio1_padded = torch.nn.functional.pad(audio1, (0, max_len - audio1.shape[1]))
audio2_padded = torch.nn.functional.pad(audio2, (0, max_len - audio2.shape[1]))
wavs = torch.cat([audio1_padded, audio2_padded], dim=0)  # (2, 1, T)
wav_lens = torch.tensor([audio1.shape[1], audio2.shape[1]])

# Phonemize texts
text1_phon = aligner.phonemize_sentence("hello")["ph66"]
text2_phon = aligner.phonemize_sentence("world")["ph66"]

# Pad phoneme sequences
max_phon = max(len(text1_phon), len(text2_phon))
text1_phon_padded = text1_phon + [-100] * (max_phon - len(text1_phon))
text2_phon_padded = text2_phon + [-100] * (max_phon - len(text2_phon))
phoneme_sequences = torch.tensor([text1_phon_padded, text2_phon_padded])

# Batch alignment
results, embeddings = aligner.extract_timestamps_from_segment_batch(
    wavs,
    wav_lens,
    phoneme_sequences,
    extract_embeddings=True,
    debug=True
)
# results[0] = {"aligned_ts": [phoneme timestamps]}
# embeddings[0] = tensor of shape (num_phonemes, 512)
```

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

### Configure Aligner for Specific Use Cases

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

Pre-defined configurations optimized for different audio quality levels and research requirements.

```python
PhonemeTimestampAligner(
    preset="en-us",
    duration_max=30,
    boost_targets=True,
    enforce_all_targets=True,
    boundary_softness=3,
    bad_confidence_threshold=0.6,
    device="auto"
)
```

```python
PhonemeTimestampAligner(
    preset="en-us",
    duration_max=15,
    silence_anchors=5,
    boost_targets=True,
    enforce_all_targets=True,
    ensure_completeness=True,
    device="cuda"  # GPU recommended
)
```

```python
PhonemeTimestampAligner(
    model_name="large_multi_mswc38_ua02g_e03_val_GER=0.5133.ckpt",
    lang="ja",  # Not trained on this language
    boost_targets=True,
    enforce_minimum=True
)
```

```python
PhonemeTimestampAligner(
    preset="en-us",
    boost_targets=False,
    enforce_all_targets=False,
    ensure_completeness=False,
    boundary_softness=1
)
```

```python
PhonemeTimestampAligner(
    preset="en-us",
    enforce_all_targets=True,
    extend_soft_boundaries=True,
    boundary_softness=3,
    bad_confidence_threshold=0.7  # Filter low-quality
)
```

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

### Manual Alignment Pipeline

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

Load audio and perform alignment directly using the PhonemeTimestampAligner class.

```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")
```

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

### Implement alignment error recovery with Python

Source: https://github.com/tabahi/bournemouth-forced-aligner/blob/main/_autodocs/usage-patterns.md

Use a multi-strategy fallback approach to handle alignment failures by adjusting device settings, silence anchors, and model selection.

```python
from bournemouth_aligner import PhonemeTimestampAligner
import json

def align_with_fallback(text, audio_path):
    """
    Align with progressive fallback strategies if alignment fails or is poor.
    """
    
    # Strategy 1: Standard
    try:
        aligner = PhonemeTimestampAligner(preset="en-us", device="cuda")
        audio = aligner.load_audio(audio_path)
        result = aligner.process_sentence(text, audio)
        
        coverage = result["segments"][0]["coverage_analysis"]["coverage_ratio"]
        if coverage == 1.0 and not result["segments"][0]["coverage_analysis"]["bad_confidence"]:
            return result, "strategy_1_success"
    except Exception as e:
        print(f"Strategy 1 failed: {e}")
    
    # Strategy 2: CPU + silence anchoring
    try:
        aligner = PhonemeTimestampAligner(
            preset="en-us",
            device="cpu",
            silence_anchors=10,
            boost_targets=True
        )
        audio = aligner.load_audio(audio_path)
        result = aligner.process_sentence(text, audio)
        
        coverage = result["segments"][0]["coverage_analysis"]["coverage_ratio"]
        if coverage > 0.8:
            return result, "strategy_2_partial"
    except Exception as e:
        print(f"Strategy 2 failed: {e}")
    
    # Strategy 3: Universal model with aggressive forcing
    try:
        aligner = PhonemeTimestampAligner(
            model_name="large_multi_mswc38_ua02g_e03_val_GER=0.5133.ckpt",
            lang="en-us",
            device="cpu",
            enforce_all_targets=True,
            ensure_completeness=True
        )
        audio = aligner.load_audio(audio_path)
        result = aligner.process_sentence(text, audio, debug=True)
        
        return result, "strategy_3_forced"
    except Exception as e:
        print(f"Strategy 3 failed: {e}")
    
    # All strategies failed
    return None, "all_strategies_failed"

# Usage
result, strategy = align_with_fallback("hello world", "speech.wav")
if result:
    print(f"✓ Aligned using {strategy}")
    print(f"Coverage: {result['segments'][0]['coverage_analysis']['coverage_ratio']:.0%}")
else:
    print("✗ All alignment strategies failed")
```
Tokens:
Raw