Upload README.md with huggingface_hub

README.md

@@ -2,6 +2,8 @@
 license: cc-by-nc-4.0
 language:
 - tl
+- ceb
+- en
 base_model:
 - openai/whisper-small
 pipeline_tag: automatic-speech-recognition
@@ -12,4 +14,108 @@ tags:
 - cebuano-asr
 - bisaya
 - bisaya-asr
----
+- code-switching
+---
+
+# phcodeswitch-ceb-dvo
+
+Whisper `small` fine-tuned for automatic speech recognition (ASR) of **Davao Cebuano**, including English–Cebuano code-switching.
+
+- **Base model:** [openai/whisper-small](https://huggingface.co/openai/whisper-small)
+- **Fine-tuned language:** Cebuano (`ceb`), BCP-47 `ceb`
+- **Task:** Automatic speech recognition (`transcribe`)
+- **Best WER:** 20.86% (test split, step 1200)
+- **License:** CC BY-NC 4.0 — non-commercial research / educational use only
+
+## How to use
+
+Install dependencies:
+
+```bash
+pip install --upgrade transformers torch librosa
+```
+
+### Option 1 – `pipeline` (quickstart)
+
+```python
+from transformers import pipeline
+import librosa
+
+pipe = pipeline(
+    "automatic-speech-recognition",
+    model="eemberda/phcodeswitch-ceb-dvo",
+    device=0,  # use -1 for CPU
+)
+
+audio, sr = librosa.load("sample.wav", sr=16_000, mono=True)
+result = pipe(
+    audio,
+    generate_kwargs={
+        "language": "tl",   # Cebuano is not native to Whisper; Tagalog prompt works best
+        "task": "transcribe",
+        "num_beams": 5,
+    },
+)
+print(result["text"])
+```
+
+### Option 2 – manual inference with processor + model
+
+```python
+from transformers import WhisperForConditionalGeneration, WhisperProcessor
+import librosa
+import torch
+
+model_id = "eemberda/phcodeswitch-ceb-dvo"
+
+processor = WhisperProcessor.from_pretrained(model_id)
+model = WhisperForConditionalGeneration.from_pretrained(model_id)
+device = "cuda" if torch.cuda.is_available() else "cpu"
+model.to(device).eval()
+
+audio, sr = librosa.load("sample.wav", sr=16_000, mono=True)
+inputs = processor.feature_extractor(
+    audio, sampling_rate=16_000, return_tensors="pt"
+).input_features.to(device)
+
+forced_decoder_ids = processor.get_decoder_prompt_ids(
+    language="tl", task="transcribe"
+)
+
+with torch.no_grad():
+    predicted_ids = model.generate(
+        inputs,
+        forced_decoder_ids=forced_decoder_ids,
+        num_beams=5,
+    )
+
+transcription = processor.batch_decode(
+    predicted_ids, skip_special_tokens=True
+)[0].strip()
+print(transcription)
+```
+
+## Language notes
+
+- Whisper has **no native Cebuano language token**. The model is fine-tuned on
+  Cebuano audio but uses the **Tagalog (`tl`)** decoder prompt, which Whisper
+  treats as the closest supported related language.
+- The model also handles English and English–Cebuano code-switched speech.
+- Audio is expected at **16 kHz mono** (resampled automatically by `librosa`
+  in the examples above).
+
+## Training details
+
+- Base model: `openai/whisper-small`
+- Optimizer: AdamW, learning rate `1e-5`, warmup 100 steps
+- Batch size 4 with gradient accumulation 4 (effective batch 16)
+- Max steps 1800 (best checkpoint at step 1200), early stopping patience 3
+- Mixed precision (fp16), gradient checkpointing, beam search (5) decoding
+
+## Limitations
+
+- Trained on a small, community-contributed dataset; coverage of accents and
+  vocabulary is limited.
+- For non-commercial research and educational use only (CC BY-NC 4.0).
+- Contributed speaker data must not be used for voice cloning, impersonation,
+  or voice synthesis. See the project repository's compliance documents.