Metadata-Version: 2.5
Name: google-asr-africa
Version: 0.1.1
Summary: Transcribe African-language speech with Google's free web ASR endpoint. Ships a verified catalog of ~20 languages, a resumable batched transcriber, and a probe that checks whether any new language really works.
Author: AfriSpeech
License: MIT
License-File: LICENSE
Keywords: african-languages,asr,google-asr,speech,transcription,tts
Requires-Python: >=3.9
Requires-Dist: soundfile>=0.12
Requires-Dist: speechrecognition>=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: probe
Requires-Dist: fasttext>=0.9.2; extra == 'probe'
Requires-Dist: huggingface-hub>=0.23; extra == 'probe'
Description-Content-Type: text/markdown

# google-asr-africa

Transcribe African-language speech with Google's free web ASR endpoint —
only for the languages where it actually works.

Google's free endpoint silently falls back to English for unsupported
languages, so you can get English "transcripts" of your African audio.
This package only ships languages we've **verified** transcribe in their own
orthography — with a resumable batch transcriber and a probe to test new ones.

## Install

```bash
pip install google-asr-africa
```

## Quick start

```bash
# list the verified languages
google-asr-africa list-languages

# transcribe a folder of audio (resumable, rate-limited)
google-asr-africa transcribe data/amharic_clips --language amharic
```

```python
from google_asr_africa import transcribe_folder

tr = transcribe_folder('data/kirundi_clips', language='rn', rpm=50)
print(tr.stats)                        # {'ok': 120, 'unknown': 3, ...}
text = tr.transcripts['clip_00042.flac']
```

Batches are crash-safe: a rerun continues where a stopped run left off and
retries only transient failures.

## Verify a new language

```bash
google-asr-africa probe rg --audio my_kiraundi.wav
# SUPPORTED / UNSUPPORTED / REVIEW(<actual-language>)
```

## REST API + test UI

```bash
google-asr-africa serve          # http://localhost:8000
```

- `GET /` — browser UI (pick language, upload a clip, see the transcript)
- `GET /health` — liveness check
- `GET /languages` — the verified catalog as JSON
- `POST /transcribe?language=<code>` — send raw audio bytes, get JSON back

```bash
curl -X POST --data-binary @clip.flac -H 'Content-Type: audio/flac' \
     'localhost:8000/transcribe?language=amharic'
```

Run it in Docker (no external deps beyond Python):

```bash
docker build -t google-asr-africa .
docker run -p 8000:8000 google-asr-africa
```

## Verified languages

Amharic, Chichewa, Hausa, Igbo, Kinyarwanda, Kirundi, Ndebele, Oromo,
Sepedi, Sesotho, Setswana, Shona, Swahili, Swati, Tigrinya, Tsonga, Twi,
Venda, Xhosa, Yoruba, Zulu. Run `list-languages` for the full table.

## License

MIT — covers this code only. Google's ASR service and its outputs are subject
to [Google's Terms of Service](https://policies.google.com/terms).

Part of [AfriSpeech](https://github.com/AfriSpeech) — open-source tools for
African language technology.