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:

uv add mas-asr

Or using standard pip:

pip install mas-asr

To install fine-tuning dependencies:

pip install "mas-asr[finetune]"

---

Quickstart (Python API)

Basic Transcription

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:

# 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

# 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

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

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

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)

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

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 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.