Metadata-Version: 2.4
Name: asrx
Version: 0.3.2
Summary: Universal, ultra-fast Forced Alignment, VAD Segmentation, and Speaker Diarization engine.
Author: ASRX Team
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0.0
Requires-Dist: torchaudio>=2.0.0
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: nltk
Requires-Dist: librosa
Requires-Dist: soundfile
Provides-Extra: transformers
Requires-Dist: transformers; extra == "transformers"
Provides-Extra: pyannote
Requires-Dist: pyannote.audio; extra == "pyannote"
Provides-Extra: nemo
Requires-Dist: nemo_toolkit[asr]>=2.5.0; extra == "nemo"
Provides-Extra: ctc
Requires-Dist: ctc-segmentation; extra == "ctc"
Provides-Extra: flashvad
Requires-Dist: flashvad; extra == "flashvad"
Provides-Extra: all
Requires-Dist: asrx[ctc,flashvad,nemo,pyannote,transformers]; extra == "all"

<p align="center">
  <img src="asrx_logo.png" alt="ASRX Logo" width="600">
</p>

# ASRX: Universal Forced Alignment & Speech Segmentation

**`ASRX`** is a high-performance, model-agnostic **Forced Alignment**, **VAD Segmentation**, and **Speaker Diarization** engine.

It allows developers to take text generated by **ANY** external ASR model, LLM, or API (e.g. Cohere, Qwen, Whisper, vLLM, OpenAI, Deepgram, or custom local scripts) and immediately generate:

- ⏱️ **Exact millisecond-level word timestamps** (`start`, `end`)
- 🎯 **Word-level confidence scores**
- 🎙️ **VAD-guided natural speech segment grouping**
- 👥 **Speaker Diarization**
- ⚡ **Ultra-fast processing**

---

## 🚀 Quickstart

### 1. Installation

ASRX uses a **lazy-loaded backend architecture**. You only install the heavy ML dependencies for the specific models you want to use.

```bash
# Core installation (fast, no heavy dependencies)
pip install -e asrx

# 1. Install for Wav2Vec2/MMS alignment (Recommended)
pip install -e asrx[transformers]

# 2. Install for Pyannote VAD and Diarization
pip install -e asrx[pyannote]

# 3. Install for NVIDIA NeMo (Aligner, VAD, Sortformer)
pip install -e asrx[nemo]

# 4. Install for CTC-Segmentation (Confidence scores)
pip install -e asrx[ctc,transformers]
```

### 2. Standalone Alignment in 1 Line (`asrx.align`)

```python
import asrx

audio_file = "meeting.wav"
my_text = "I don't have a problem with where we go, the most important thing is that the place is quiet, has good coffee, and we can sit comfortably and talk."

# Generates word timestamps, confidence scores, and VAD-guided segments
result = asrx.align(
    audio=audio_file,
    text=my_text,
    language="en",
    aligner="wav2vec2", # "wav2vec2", "mms", "nemo", "ctc_segmentation"
    vad="silero"        # "silero", "pyannote", "nemo", "flashvad"
)

print("Total words aligned:", len(result["word_segments"]))
print("First word timestamp:", result["word_segments"][0])
```

---

## 🧰 Backend Registry

Because `ASRX` is entirely modular, you can mix and match the best tools for your specific use case.

### Alignment Backends (`aligner=...`)

| Key                  | Description                    | Pros                               | Install Required    |
| -------------------- | ------------------------------ | ---------------------------------- | ------------------- |
| `"wav2vec2"`         | HuggingFace Wav2Vec2 (Default) | Fast, built-in dicts for 40 langs  | `transformers`      |
| `"mms"`              | Meta MMS (1B params)           | Supports **1,107+ languages**      | `transformers`      |
| `"nemo"`             | NVIDIA NeMo Forced Aligner     | Viterbi CTC, highly optimized      | `nemo_toolkit[asr]` |
| `"ctc_segmentation"` | CTC-Segmentation Algorithm     | Provides per-word confidence flags | `ctc-segmentation`  |

### VAD Backends (`vad=...`)

| Key          | Description          | Pros                                   | Install Required    |
| ------------ | -------------------- | -------------------------------------- | ------------------- |
| `"silero"`   | Silero VAD (Default) | Fast, works out of the box (Torch Hub) | _None_              |
| `"pyannote"` | Pyannote VAD         | **Best accuracy in noise**             | `pyannote.audio`    |
| `"nemo"`     | NVIDIA MarbleNet     | Fast and accurate                      | `nemo_toolkit[asr]` |
| `"flashvad"` | FlashVAD             | Ultra-lightweight (~46K params)        | `flashvad`          |

### Diarization Backends (`diarize=...`)

| Key            | Description                    | Pros                            | Install Required    |
| -------------- | ------------------------------ | ------------------------------- | ------------------- |
| `"pyannote"`   | Pyannote Diarization (Default) | Industry standard, clustering   | `pyannote.audio`    |
| `"sortformer"` | NVIDIA NeMo Sortformer         | **SOTA for overlapping speech** | `nemo_toolkit[asr]` |

---

## 🛠️ Advanced Usage

### 1. Alignment with SOTA Diarization (NeMo Sortformer)

```python
import asrx

result = asrx.align(
    audio="panel_discussion.wav",
    text=transcript_text,
    language="en",
    vad="nemo",
    diarize="sortformer"
)

# Words and segments will have "SPEAKER_00", "SPEAKER_01", etc.
for seg in result["segments"]:
    print(f"[{seg['speaker']}] {seg['start']}s -> {seg['end']}s: {seg['text']}")
```

### 2. Custom Pyannote Models (e.g., Community-1)

```python
result = asrx.align(
    audio="audio.wav",
    text=my_text,
    language="ar",
    diarize="pyannote",
    model_name="pyannote/speaker-diarization-community-1",
    hf_token="your_hf_token"
)
```

### 3. Reusable Pipeline for High-Throughput Batching

```python
import asrx

# Load pipeline once into memory
pipeline = asrx.load_aligner(
    language="en",
    aligner="mms",
    vad="pyannote",
    diarize="sortformer",
    device="cuda",
    hf_token="your_hf_token"
)

# Process multiple audio files efficiently
for audio_path, text in dataset:
    result = pipeline.align(audio=audio_path, text=text)
```

---

## 📊 Standardized JSON Output

```json
{
  "segments": [
    {
      "start": 0.12,
      "end": 7.15,
      "text": "I don't have a problem with where we go, the most important thing is that the place is quiet.",
      "speaker": "SPEAKER_00",
      "words": [
        {
          "word": "I",
          "start": 0.12,
          "end": 0.34,
          "score": 0.769,
          "speaker": "SPEAKER_00"
        },
        {
          "word": "don't",
          "start": 0.381,
          "end": 0.461,
          "score": 0.976,
          "speaker": "SPEAKER_00"
        }
      ]
    }
  ],
  "word_segments": [
    {
      "word": "I",
      "start": 0.12,
      "end": 0.34,
      "score": 0.769,
      "speaker": "SPEAKER_00"
    },
    {
      "word": "don't",
      "start": 0.381,
      "end": 0.461,
      "score": 0.976,
      "speaker": "SPEAKER_00"
    }
  ],
  "language": "en"
}
```

---

## 🌍 Supported Alignment Languages

Supports **Arabic (`ar`)**, **English (`en`)**, **French (`fr`)**, **German (`de`)**, **Spanish (`es`)**, **Italian (`it`)**, **Japanese (`ja`)**, **Chinese (`zh`)**, **Portuguese (`pt`)**, **Russian (`ru`)**, **Turkish (`tr`)**, **Hindi (`hi`)**, **Korean (`ko`)**, and 1000+ other languages via MMS and Multilingual models.

---

## 📄 License

Apache-2.0
