whisper-algerian-darja-small

Whisper Algerian Arabic (Darja / الدارجة الجزائرية) — Small & Medium ASR Suite

<p align="center"> <img src="https://raw.githubusercontent.com/huggingface/transformers/main/docs/source/en/imgs/whisper_architecture.png" alt="Whisper Architecture" width="700"/> </p> <p align="center"> <a href="https://huggingface.co/touati-kamel/whisper-algerian-darja-medium"><img src="https://img.shields.io/badge/HF%20Model-Whisper%20Medium-orange?style=flat-square&logo=huggingface" alt="Whisper Medium Model"></a> <a href="https://huggingface.co/touati-kamel/whisper-algerian-darja-small"><img src="https://img.shields.io/badge/HF%20Model-Whisper%20Small-orange?style=flat-square&logo=huggingface" alt="Whisper Small Model"></a> <a href="https://github.com/huggingface/peft"><img src="https://img.shields.io/badge/PEFT-LoRA%204--bit%20(QLoRA)-purple?style=flat-square" alt="PEFT LoRA"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License"></a> <a href="https://wandb.ai/k_touati-estin/whisper-algerian-darja"><img src="https://img.shields.io/badge/W%26B-Training%20Logs-gold?style=flat-square&logo=weightsandbiases" alt="Weights and Biases"></a> </p>

---

Overview

This repository contains the evaluation benchmarks, inference code, and interactive Streamlit comparison application for fine-tuned Automatic Speech Recognition (ASR) models for Algerian Arabic (Darja / الدارجة الجزائرية):

1. touati-kamel/whisper-algerian-darja-medium (SOTA — 833M Parameters, 69.2M LoRA)
2. touati-kamel/whisper-algerian-darja-small (Lightweight — 267M Parameters, 25.9M LoRA)

Both models were adapted from OpenAI Whisper via 4-bit quantized Low-Rank Adaptation (QLoRA) across a 3-phase sequential streaming curriculum covering conversational podcasts, spontaneous expressive storytelling, and cultural narratives from the OddAdmix Algerian speech collection.

---

Comprehensive Benchmark & Performance Matrix

The models were evaluated iteratively across three distinct Algerian dialect audio domains using Word Error Rate (WER %) and Cross-Entropy Loss with standardized Arabic text normalization:

Model Architecture Specifications

---

Sequential Curriculum Learning Methodology

┌────────────────────────────────────────────────────────┐
│               OpenAI Whisper (Small / Medium)          │
│                (4-bit NF4 Quantization Base)           │
└──────────────────────────┬─────────────────────────────┘
                           │
             ┌─────────────┴─────────────┐
             │    LoRA Adapters (r=64)   │
             │   Target: q, k, v, out,   │
             │           fc1, fc2        │
             └─────────────┬─────────────┘
                           │
       ┌────────────────────┴────────────────────┐
       │     Sequential Curriculum Learning      │
       ├─────────────────────────────────────────┤
       │ Phase 1: Kahwa Podcast (Conversational) │
       │  • Small: 4,942 steps | Med: 9,886 steps│
       │                    ▼                    │
       │ Phase 2: Loubna Stories (Expressive)    │
       │  • Small: 10,324 steps| Med: 20,650 step│
       │                    ▼                    │
       │ Phase 3: Rawi Narratives (Storytelling) │
       │  • Small: 562 steps   | Med: 1,125 steps│
       └─────────────────────────────────────────┘

---

Interactive Streamlit Comparison Application

The repository includes a web application (app.py) that allows users to record or upload a single audio input and compare the transcription outputs of both models side-by-side.

Features:

• Live Microphone Recording & Audio File Upload (WAV, MP3, OGG, M4A, FLAC, WebM).
• Side-by-Side Model Comparison: Real-time evaluation of Whisper Medium vs. Whisper Small on the identical audio stream.
• Output Diff & Similarity Score: Computes textual alignment and shows vocabulary/phonetic nuances between models.
• Darja Text Normalization Toggle: Diacritics (harakat), tatweel (kashida), punctuation, and Alef/Yaa normalization.
• Copy to Clipboard & Latency / Duration Metrics.

Running the App Locally:

# 1. Clone the repository
git clone https://github.com/KamelTouati/whisper-darja-demo.git
cd whisper-darja-demo

# 2. Install dependencies
pip install -r requirements.txt

# 3. Launch Streamlit app
streamlit run app.py

---

Python Quickstart & Inference

1. Installation

pip install --upgrade transformers peft torch torchaudio soundfile librosa jiwer bitsandbytes accelerate

2. High-Level Usage with transformers.pipeline

import torch
from transformers import pipeline

# Choose model: "whisper-algerian-darja-medium" (recommended) or "whisper-algerian-darja-small"
model_id = "touati-kamel/whisper-algerian-darja-medium"

pipe = pipeline(
    task="automatic-speech-recognition",
    model=model_id,
    torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
    device=0 if torch.cuda.is_available() else "cpu",
    chunk_length_s=30,
)

# Transcribe an audio file (16kHz WAV or MP3)
result = pipe(
    "path/to/algerian_audio.mp3",
    generate_kwargs={"language": "arabic", "task": "transcribe"}
)

print("Transcription (Algerian Darja):", result["text"])

3. Native PyTorch + PeftModel

import torch
import librosa
from transformers import WhisperProcessor, WhisperForConditionalGeneration
from peft import PeftModel

device = "cuda" if torch.cuda.is_available() else "cpu"
base_model_id = "openai/whisper-medium"  # or "openai/whisper-small"
adapter_id = "touati-kamel/whisper-algerian-darja-medium"  # or "touati-kamel/whisper-algerian-darja-small"

# 1. Load Processor
processor = WhisperProcessor.from_pretrained(base_model_id, language="arabic", task="transcribe")

# 2. Load Base Model and Apply LoRA Adapter
base_model = WhisperForConditionalGeneration.from_pretrained(
    base_model_id,
    torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
    device_map="auto" if torch.cuda.is_available() else None,
)
model = PeftModel.from_pretrained(base_model, adapter_id)
model.eval()

# 3. Preprocess Audio
audio, sr = librosa.load("path/to/audio.mp3", sr=16000)
input_features = processor(audio, sampling_rate=16000, return_tensors="pt").input_features
if torch.cuda.is_available():
    input_features = input_features.to("cuda", dtype=torch.float16)

# 4. Generate
forced_decoder_ids = processor.get_decoder_prompt_ids(language="arabic", task="transcribe")
with torch.no_grad():
    predicted_ids = model.generate(
        input_features,
        forced_decoder_ids=forced_decoder_ids,
        max_new_tokens=225
    )

# 5. Decode
transcription = processor.batch_decode(predicted_ids, skip_special_tokens=True)[0]
print("Algerian Darja Output:", transcription)

---

Complete Arabic Normalization Function

import re
import string

_ARABIC_DIACRITICS = "\u064B\u064C\u064D\u064E\u064F\u0650\u0651\u0652\u0670"
_TATWEEL = "\u0640"
_PUNCT_MAP = {ord(c): None for c in string.punctuation + "\u060C\u061B\u061F\u00AB\u00BB"}

def normalize_darja_text(text: str) -> str:
    if not text:
        return ""
    # Strip diacritics & tatweel
    text = text.translate({ord(c): None for c in _ARABIC_DIACRITICS})
    text = text.replace(_TATWEEL, "")
    # Normalize Alef and Yaa
    text = text.replace("\u0625", "\u0627").replace("\u0623", "\u0627").replace("\u0622", "\u0627")
    text = text.replace("\u0649", "\u064A")
    # Remove punctuation
    text = text.translate(_PUNCT_MAP)
    # Collapse whitespace
    return " ".join(text.split()).strip()

---

Evaluation Benchmarks

1. Casablanca Algerian Benchmark

Evaluates Zero-Shot foundation Whisper vs. Fine-Tuned models on UBC-NLP/Casablanca (Algeria test split):

# Local or remote GPU
python eval_casablanca.py

# Kaggle Background GPU (saves results to /kaggle/working)
python eval_casablanca_kaggle.py

Benchmark Results (843 Authentic Dialectal Utterances)

2. YODAS v3 Algerian Dialect Split (dz)

Evaluates Zero-Shot foundation Whisper vs. Fine-Tuned models on the Algerian partition of oddadmix/yodas-v3-ar-labeled-split (split dz):

# Standalone CLI execution
python eval_yodas_dz.py --num_samples 3000 --batch_size 16

# Kaggle Background GPU (self-contained, caches audio to /kaggle/tmp, exports JSON/CSV/TeX to /kaggle/working)
python eval_yodas_dz_kaggle.py

Benchmark Results (3,000 Utterances / 14.31 Hours / 1,552 Distinct Video Sources)

---

Datasets & Citations

Training Datasets

• oddadmix/arabic-audio-collection-algerian-kahwa-postcast
• oddadmix/arabic-audio-collection-algerian-loubna-stories
• oddadmix/arabic-audio-collection-algerian-rawi

BibTeX Citations

@misc{touati2026whisper_darja_medium,
  author = {Kamel Touati},
  title = {Whisper Medium Fine-Tuned for Algerian Arabic (Darja)},
  year = {2026},
  publisher = {Hugging Face},
  journal = {Hugging Face Hub},
  howpublished = {\url{https://huggingface.co/touati-kamel/whisper-algerian-darja-medium}}
}

@misc{touati2026whisper_darja_small,
  author = {Kamel Touati},
  title = {Whisper Small Fine-Tuned for Algerian Arabic (Darja)},
  year = {2026},
  publisher = {Hugging Face},
  journal = {Hugging Face Hub},
  howpublished = {\url{https://huggingface.co/touati-kamel/whisper-algerian-darja-small}}
}

@article{radford2022whisper,
  title={Robust Speech Recognition via Large-Scale Weak Supervision},
  author={Radford, Alec and Kim, Jong Wook and Xu, Tao and Brockman, Greg and McLeavey, Christine and Sutskever, Ilya},
  journal={arXiv preprint arXiv:2212.04356},
  year={2022}
}