Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,185 @@
+---
+license: mit
+language:
+  - ar
+  - en
+tags:
+  - speech
+  - asr
+  - automatic-speech-recognition
+  - ctc
+  - conformer
+  - egyptian-arabic
+  - code-switching
+  - arabic
+  - audio
+  - pytorch
+library_name: metro-asr
+pipeline_tag: automatic-speech-recognition
+datasets:
+  - AlaaSamir/custom-egy-tts
+  - OmarAhmedSobhy/egyption-with-emotion-dataset
+  - MightyStudent/Egyptian-ASR-MGB-3
+  - MAdel121/arabic-egy-cleaned
+  - MAdel121/Continuation-egy-for-ultravox-v1
+  - Raniahossam33/Egyptian_TTS3RS
+  - ahmedbasemdev/egyptain-tts-dataset
+  - MohamedRashad/arabic-english-code-switching
+  - librispeech_asr
+metrics:
+  - wer
+  - cer
+model-index:
+  - name: Metro-ASR Small
+    results:
+      - task:
+          type: automatic-speech-recognition
+          name: Speech Recognition
+        dataset:
+          type: custom
+          name: Egyptian Arabic + Code-Switching Test Set
+          config: all
+          split: test
+        metrics:
+          - type: wer
+            value: 46.85
+            name: WER (All)
+          - type: cer
+            value: 28.41
+            name: CER (All)
+          - type: wer
+            value: 37.24
+            name: WER (Arabic)
+          - type: cer
+            value: 17.45
+            name: CER (Arabic)
+          - type: wer
+            value: 36.32
+            name: WER (Code-Switching)
+          - type: cer
+            value: 17.44
+            name: CER (Code-Switching)
+---
+
+<h1 align="center">Metro-ASR Small (61M)</h1>
+
+<p align="center">
+  <strong>Non-Autoregressive CTC Speech Recognition for Egyptian Arabic + Code-Switching</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/mohammedaly22/Metro-ASR"><img src="https://img.shields.io/badge/GitHub-Repository-blue?style=for-the-badge&logo=github" alt="GitHub"></a>
+  <a href="https://pypi.org/project/metro-asr/"><img src="https://img.shields.io/pypi/v/metro-asr?style=for-the-badge&logo=pypi&logoColor=white&color=blue" alt="PyPI"></a>
+  <a href="https://huggingface.co/spaces/mohammedaly22/metro-asr"><img src="https://img.shields.io/badge/%F0%9F%A4%97_Space-Demo-orange?style=for-the-badge" alt="Space"></a>
+</p>
+
+## Model Description
+
+**Metro-ASR Small** is a 61M parameter non-autoregressive CTC-based ASR model built on a modern Conformer encoder. It is specifically designed for **Egyptian Arabic** (العامية المصرية) with native **Arabic-English code-switching** support.
+
+### Architecture
+
+| Component | Details |
+|-----------|---------|
+| Encoder | Conformer (12 layers, d_model=384, 6 heads) |
+| Position Encoding | RoPE (Rotary Position Embeddings) |
+| Feed-Forward | SwiGLU (Macaron-style dual FFN) |
+| Normalization | RMSNorm (Pre-norm) |
+| Convolution | SE-Gated Depthwise Separable (kernel=31) |
+| Regularization | Stochastic Depth (rate=0.05) |
+| Auxiliary Loss | Intermediate CTC at layer 6 |
+| Tokenizer | BPE (SentencePiece, vocab=5000) |
+| Decoding | CTC Greedy / Beam Search + KenLM |
+| Parameters | 61.6M |
+
+### Performance
+
+| Split | WER (%) | CER (%) |
+|-------|---------|---------|
+| All | 46.85 | 28.41 |
+| Arabic Only | 37.24 | 17.45 |
+| Code-Switching | 36.32 | 17.44 |
+
+**Speed:** RTF ~0.002 on CPU (500x faster than real-time)
+
+## Usage
+
+### Install
+
+```bash
+pip install metro-asr
+```
+
+### Quick Start
+
+```python
+from metro_asr import MetroASREngine
+
+engine = MetroASREngine.from_pretrained("small")  # Auto-downloads this model
+result = engine.transcribe("audio.wav")
+print(result.text)
+```
+
+### With Language Model (Beam Search)
+
+```python
+engine = MetroASREngine.from_pretrained(
+    "small",
+    lm_path="lm_5gram.bin",     # Download from this repo
+    beam_width=100,
+    lm_alpha=0.5,
+    lm_beta=5.0,
+)
+
+result = engine.transcribe("audio.wav", beam_search=True)
+print(result.text)
+```
+
+### Batch Transcription
+
+```python
+results = engine.transcribe_batch(["audio1.wav", "audio2.wav", "audio3.wav"])
+for r in results:
+    print(f"{r.text}  (RTF={r.rtf:.4f})")
+```
+
+## Files in this Repository
+
+| File | Description | Size |
+|------|-------------|------|
+| `model.pt` | Model checkpoint (weights + optimizer state) | ~706MB |
+| `config.yaml` | Model architecture configuration | <1KB |
+| `bpe.model` | SentencePiece BPE tokenizer model | ~200KB |
+| `bpe.vocab` | BPE vocabulary file | ~100KB |
+| `lm_5gram.bin` | KenLM 5-gram language model (optional) | ~6GB |
+
+## Training
+
+Trained on a combination of open-source Egyptian Arabic datasets and custom YouTube data:
+
+- **Audio data:** 130K+ samples from 8 datasets + YouTube Egyptian Arabic content
+- **Text data:** 1.9M Egyptian sentences for LM training
+- **Training:** 440K steps, batch size 32, 4x gradient accumulation, AdamW + Cosine LR
+- **Hardware:** Single GPU training
+
+## Limitations
+
+- Optimized for Egyptian Arabic dialect; MSA and other dialects may have higher error rates
+- Code-switching support is Arabic-English only
+- Best performance on audio 0.5s-30s in duration
+- The language model significantly improves accuracy but adds ~6GB to download
+
+## Citation
+
+```bibtex
+@software{metro-asr-2025,
+  title  = {Metro-ASR: Non-Autoregressive CTC-based ASR for Egyptian Arabic and Code-Switching},
+  author = {Mohammed Aly},
+  year   = {2025},
+  url    = {https://github.com/mohammedaly22/Metro-ASR}
+}
+```
+
+## License
+
+MIT