boazsew/Ethio-ASR-medical-api

Ethio-ASR Medical API

Long-form, multi-speaker transcription for Ethiopian languages, packaged for Hugging Face Inference Endpoints.

Pipeline: silero-VAD (chunking) → pyannote/speaker-diarization-3.1 (speaker labels) → boazsew/Ethio-ASR-w2v-bert-2.0-uf (ASR for 5 Ethiopian languages: Amharic, Tigrinya, Oromo, Sidaama, Wolaytta).

Built for a mobile app that records doctor↔patient consultations and returns speaker-labelled transcripts.

---

Two deployment paths

Path A — Python handler (simpler, sync only)

Use the Inference Endpoint UI:

1. Go to https://ui.endpoints.huggingface.co
2. Click New Endpoint → pick this repo (boazsew/Ethio-ASR-medical-api).
3. Container type: Default.
4. Task: Custom.
5. Hardware: GPU · NVIDIA L4 · ~$0.80/hr (good starting point).
6. Environment variables:
   • HF_TOKEN = a read token from https://huggingface.co/settings/tokens (needed to download the gated diarizer).
7. Click Create Endpoint. First boot takes ~5 min (model downloads).

Request format:

curl https://<your-id>.endpoints.huggingface.cloud \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: audio/wav" \
  --data-binary @visit.wav

Returns the full transcript JSON when done. Suitable for clips up to ~15 minutes (longer than that, HF's request timeout may fire).

Path B — Custom Docker (full FastAPI, supports SSE streaming)

Use this when you want /transcribe/stream (live transcript turns arriving as they're produced) or multiple endpoints.

1. Build & push the image (one-time, from your laptop):

   docker build -f Dockerfile -t boazsew/ethio-asr-api:0.1 .
   docker push boazsew/ethio-asr-api:0.1
   

2. Inference Endpoints UI → New Endpoint → Container type: Custom.
3. Container URL: docker.io/boazsew/ethio-asr-api:0.1
4. Container port: 80
5. Health check path: /health
6. Environment variables:
   • HF_TOKEN (for the diarizer download)
   • API_TOKEN (bearer token your mobile app must present — generate with openssl rand -hex 24)
7. Hardware: GPU · NVIDIA L4 (or A10G for faster long-form).

Request format:

# Sync
curl https://<your-id>.endpoints.huggingface.cloud/transcribe \
  -H "Authorization: Bearer $API_TOKEN" \
  -F audio=@visit.wav

# Streaming (Server-Sent Events)
curl -N https://<your-id>.endpoints.huggingface.cloud/transcribe/stream \
  -H "Authorization: Bearer $API_TOKEN" \
  -F audio=@visit.wav

---

Response shape

{
  "duration_s": 480.3,
  "languages": ["amh", "tir"],
  "num_speakers": 2,
  "turns": [
    {"speaker": "SPEAKER_00", "start_s": 0.0, "end_s": 4.2,
     "text": "ሰላም ለዓለም", "language": "amh"},
    {"speaker": "SPEAKER_01", "start_s": 4.5, "end_s": 9.1,
     "text": "selam le alem", "language": "amh"}
  ],
  "processing_time_s": 42.3
}

For streaming (Path B /transcribe/stream):

event: meta
data: {"duration_s": 480.3, "num_chunks": 32, "num_speakers_initial": 2}

event: turn
data: {"speaker": "SPEAKER_00", "start_s": 0.0, "end_s": 4.2, ...}

event: done
data: {"languages": ["amh", "tir"], "num_speakers": 2, "num_turns_final": 18}

Notes

• First request after deploy / scale-up takes ~30 s extra for model load. Set min_replicas=1 if you want always-on (costs more).
• Audio limits: 50 MB upload, ~45 min duration. Longer audio should be chunked client-side.
• Server does not retain audio — files are deleted from the temp dir immediately after the response is returned.
• No medical-vocabulary patch. Drug names and Latin terms transcribe phonetically. Fine for v1; future work could add an LM rescorer.