Metadata-Version: 2.3
Name: mas-asr
Version: 0.1.1
Summary: Production-grade, modular multilingual ASR library with native script, mixed script, streaming, and fine-tuning support
Author: ArYan9908
Author-email: ArYan9908 <9908aryan@gmail.com>
Requires-Dist: huggingface-hub>=0.23.0
Requires-Dist: peft>=0.21.2
Requires-Dist: sentencepiece>=0.2.2
Requires-Dist: sounddevice>=0.5.6
Requires-Dist: soundfile>=0.14.0
Requires-Dist: torch>=2.14.1
Requires-Dist: torchaudio>=2.11.0
Requires-Dist: transformers>=5.19.0
Requires-Dist: triton-windows>=3.8.0.post29
Requires-Dist: peft>=0.10.0 ; extra == 'finetune'
Requires-Dist: accelerate>=0.30.0 ; extra == 'finetune'
Requires-Dist: datasets>=2.19.0 ; extra == 'finetune'
Requires-Python: >=3.10
Provides-Extra: finetune
Description-Content-Type: text/markdown

# mas-asr

**mas-asr** is a production-grade, modular Python speech recognition library inspired by `openai-whisper` and `faster-whisper`. Built with first-class support for Indic languages, offering transcription in **native scripts**, **mixed scripts (Hinglish/code-mixing)**, and **romanized transliteration**, powered by models like **`bodhan-ai/indic-transcribe-flex`** (1.2B FastConformer + Transformer decoder).

---

## Key Features

- **Whisper-like Intuitive API**: Load and transcribe with minimal code (`mas_asr.load_model(...)` & `model.transcribe(...)`).
- **3 Output Script Modes**:
  - `native`: Standard native script (Devanagari, Gurmukhi, Bengali, Tamil, etc.).
  - `mixed`: Code-mixing & loanwords in Latin script with Indic digits (e.g., modern conversational messaging).
  - `romanized`: Full phonetic transliteration in Latin script.
- **27+ Indian Languages**: Hindi, Tamil, Telugu, Bengali, Kannada, Marathi, Malayalam, Punjabi, Gujarati, Odia, Urdu, Assamese, and more + English.
- **Auto Long-Form Audio Segmentation**: Automatically splits audio exceeding 30 seconds at natural pauses using energy-based VAD to prevent context collapse.
- **Real-Time Streaming**: VAD-buffered sliding window streaming processor for microphone input and WebSockets.
- **Built-in CLI**: Transcribe directly from terminal with SRT, VTT, JSON, and TXT export.
- **LoRA & PEFT Fine-Tuning**: Out-of-the-box support for low-rank adapter fine-tuning on domain-specific datasets.

---

## Installation

Using `uv`:

```bash
uv add mas-asr
```

Or using standard `pip`:

```bash
pip install mas-asr
```

To install fine-tuning dependencies:

```bash
pip install "mas-asr[finetune]"
```

---

## Quickstart (Python API)

### Basic Transcription

```python
import mas_asr

# Load model (auto-downloads from Hugging Face or loads local checkpoint directory)
model = mas_asr.load_model("bodhan-ai/indic-transcribe-flex", device="cuda", compute_type="bfloat16")

# Transcribe an audio file
result = model.transcribe(
    "speech.mp3",
    language="hi",       # or None for automatic language detection
    mode="native",       # "native", "mixed", or "romanized"
    vad_filter=True,     # Auto-chunks long audio > 30s at natural pauses
)

print(result.text)
print(f"Language: {result.language} (Confidence: {result.language_probability:.2f})")

# Timestamped segments
for seg in result.segments:
    print(f"[{seg.start:.2f}s -> {seg.end:.2f}s] {seg.text}")
```

### High-Speed Inference with `torch.compile`

Compile the model encoder to reduce kernel overhead and achieve faster transcription:

```python
# Enable torch.compile for reduced kernel launch overhead
model = mas_asr.load_model(
    "bodhan-ai/indic-transcribe-flex",
    device="cuda",
    compute_type="bfloat16",
    compile=True,  # Compiles FastConformer encoder
)
```

### Loading Trained LoRA Adapters

```python
# Load base model with a custom domain adapter attached
model = mas_asr.load_model(
    "bodhan-ai/indic-transcribe-flex",
    adapter_path="./my_domain_adapters",
)
```

### Multi-Mode Transcription in One Go

```python
# Transcribe into Native, Mixed, and Romanized scripts simultaneously
outputs = model.all_modes("audio.wav", language="hi")
print("Native:   ", outputs["native"])
print("Mixed:    ", outputs["mixed"])
print("Romanized:", outputs["romanized"])
```

### Export Subtitles (SRT / VTT)

```python
# Save SubRip Subtitles
with open("subtitles.srt", "w", encoding="utf-8") as f:
    f.write(result.to_srt())

# Save WebVTT Subtitles
with open("subtitles.vtt", "w", encoding="utf-8") as f:
    f.write(result.to_vtt())
```

---

## Real-Time Audio Streaming

Use `AudioStreamer` for streaming microphone feeds, audio generator streams, or WebSockets:

```python
import mas_asr
from mas_asr import AudioStreamer

model = mas_asr.load_model("bodhan-ai/indic-transcribe-flex")
streamer = AudioStreamer(model, language="hi", mode="native")

# Feed 16kHz audio chunks (torch.Tensor, numpy array, or 16-bit PCM bytes)
for pcm_chunk in audio_stream:
    for event in streamer.feed(pcm_chunk):
        if event.is_final:
            print(f"\nFinal: {event.text}")
        else:
            print(f"Partial: {event.text}", end="\r")

# Flush remaining audio when stream ends
for event in streamer.flush():
    print(f"\nFinal: {event.text}")
```

---

## Command-Line Interface (CLI)

```bash
# Basic transcription
mas-asr audio.wav --lang hi --mode native

# Auto-detect language and show detection confidence
mas-asr interview.mp3 --show-lang

# Transcribe long audio and export to SRT subtitles
mas-asr podcast.mp3 --output-format srt --output-dir ./subtitles/

# Output all 3 modes (native, mixed, romanized)
mas-asr clip.wav --all-modes

# Batch process multiple audio files
mas-asr ./recordings/*.wav --output-format json -o ./transcripts/
```

---

## Fine-Tuning with LoRA / PEFT

Adapt the 1.2B FastConformer model on domain-specific Indian language datasets with consumer GPUs:

```python
import mas_asr
from mas_asr.finetune import get_canary_lora_model, ASREngineTrainer

# Load base model
base_model = mas_asr.load_model("bodhan-ai/indic-transcribe-flex")

# Wrap with LoRA adapters
lora_model = get_canary_lora_model(base_model.model, r=16, lora_alpha=32)

# Train using ASREngineTrainer
trainer = ASREngineTrainer(
    model=lora_model,
    fe=base_model.fe,
    tokenizer=base_model.tokenizer,
    train_dataset=my_hf_dataset,
    batch_size=4,
    learning_rate=1e-4,
)

trainer.train_epoch()
trainer.save_adapters("./indic_lora_adapters")
```

See [examples/finetune_indic.py](file:///c:/Users/admin/Desktop/Projects/ITF/examples/finetune_indic.py) for a complete, runnable script.

---

## Supported Languages

| Code | Language | Code | Language | Code | Language |
|------|----------|------|----------|------|----------|
| `as` | Assamese | `gu` | Gujarati | `mr` | Marathi  |
| `bn` | Bengali  | `hi` | Hindi    | `ne` | Nepali   |
| `bho`| Bhojpuri | `kn` | Kannada  | `or` | Odia     |
| `doi`| Dogri    | `kok`| Konkani  | `pa` | Punjabi  |
| `en` | English  | `ml` | Malayalam| `ta` | Tamil    |
| `ur` | Urdu     | `mai`| Maithili | `te` | Telugu   |

*(And additional scheduled regional languages: `bgc`, `bhb`, `brx`, `hne`, `ks`, `mni`, `sa`, `sat`, `sd`)*

---

## License

Apache License 2.0.
