Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,87 @@
+---
+language:
+- ig
+license: cc-by-nc-sa-4.0
+library_name: transformers
+pipeline_tag: automatic-speech-recognition
+tags:
+- automatic-speech-recognition
+- whisper
+- igbo
+- asr
+- on-device
+- olu-igbo
+datasets:
+- google/fleurs
+- naijavoices/naijavoices-dataset
+- benjaminogbonna/nigerian_common_voice_dataset
+metrics:
+- wer
+base_model: openai/whisper-small
+model-index:
+- name: whisper-small-igbo-25k
+  results:
+  - task:
+      type: automatic-speech-recognition
+      name: Automatic Speech Recognition
+    dataset:
+      name: FLEURS (Igbo, ig_ng)
+      type: google/fleurs
+      config: ig_ng
+      split: test
+    metrics:
+    - type: wer
+      value: 41.95
+      name: Test WER
+---
+
+# Whisper Small — Igbo (Olu Igbo)
+
+A full fine-tune of [openai/whisper-small](https://huggingface.co/openai/whisper-small) for **Igbo** automatic speech recognition, built to run **fully on-device** on mid-range Android phones (developed and tested on a Redmi Note 10 / Snapdragon 678, CPU-only).
+
+- **WER: 41.95%** on the FLEURS Igbo test set (969 samples, normalized), down from a 68.95% zero-shot baseline.
+- Part of the **Olu Igbo** project: <https://github.com/Elvaceishim/olu-igbo>
+- INT8 ONNX exports of this model power the on-device Android app in that repo.
+
+## Language token
+
+Igbo is not one of Whisper's 99 languages, so this model uses the **Yoruba token `<|yo|>` (id 50325)** as a language-token proxy, at both training and inference. Supply the forced decoder prefix shown below.
+
+## Usage
+
+```python
+import numpy as np, torch
+from transformers import WhisperProcessor, WhisperForConditionalGeneration
+
+processor = WhisperProcessor.from_pretrained("openai/whisper-small")
+model = WhisperForConditionalGeneration.from_pretrained("theelvace/whisper-small-igbo-25k").eval()
+model.config.forced_decoder_ids = None
+
+# audio: 16 kHz mono float32 numpy array
+feats = processor.feature_extractor(audio, sampling_rate=16000, return_tensors="pt").input_features
+ids = model.generate(
+    feats,
+    forced_decoder_ids=[[1, 50325], [2, 50359], [3, 50363]],  # <|yo|>, transcribe, no-timestamps
+    num_beams=5,
+    max_new_tokens=100,
+)
+print(processor.tokenizer.decode(ids[0], skip_special_tokens=True))
+```
+
+## Training
+
+- **Base:** `openai/whisper-small`, warm-started from a LoRA adapter (q/v, r=32) that reached 62.45% WER, then **full fine-tuned** (all parameters — same on-device size as the base).
+- **Data:** FLEURS Igbo + Nigerian Common Voice (Igbo) + ~25k streamed utterances of [NaijaVoices](https://huggingface.co/datasets/naijavoices/naijavoices-dataset) (a ~600-hour Igbo read-speech corpus).
+- **SpecAugment** enabled; checkpoints selected on the FLEURS **validation** split, WER reported on the held-out **test** split.
+- **WER journey:** 68.95% (zero-shot) → 62.45% (LoRA) → 48.58% (full fine-tune) → **41.95%** (+ NaijaVoices).
+- Full training, export, and on-device inference code: <https://github.com/Elvaceishim/olu-igbo>
+
+## Limitations
+
+- Short, clear utterances transcribe well; long or complex sentences show the model's real error rate.
+- **Live-mic audio is harder than clean test audio** — on long/complex live speech the model may fail to emit an end-of-sentence token and ramble.
+- Borrowed words, proper nouns, and numbers are the weakest spots.
+
+## License
+
+**CC-BY-NC-SA-4.0** (non-commercial, share-alike) — inherited from the NaijaVoices training data. (Base Whisper is MIT; FLEURS is CC-BY-4.0; Common Voice is CC0.) If you need a permissively-licensed variant, the FLEURS + Common Voice–only model [`theelvace/whisper-small-igbo`](https://huggingface.co/theelvace/whisper-small-igbo) (62.45% WER) is not subject to the non-commercial restriction.