README.md

metadata

title: Ijwi — English to Kinyarwanda Speech Translator
emoji: 🎙️
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
license: mit
app_port: 7860

Ijwi — English → Kinyarwanda Real-time Speech Translator

Real-time Speech-to-Speech translation from English to Kinyarwanda using:

• 🎤 Whisper small — Speech-to-Text
• 🔁 NLLB-200 distilled 600M — Neural translation (Meta)
• 🔊 Coqui VITS — Kinyarwanda Text-to-Speech

---

Deploying to Hugging Face Spaces

Step 1 — Create a new Space

1. Go to huggingface.co/new-space
2. Choose a name e.g. ijwi-translator
3. Set SDK to Docker
4. Set visibility to Public (free tier)
5. Click Create Space

Step 2 — Push this code

git clone https://huggingface.co/spaces/YOUR_USERNAME/ijwi-translator
cd ijwi-translator
# copy all files from this project into the folder
git add .
git commit -m "Initial deploy"
git push

Step 3 — Add Persistent Storage (strongly recommended — $5/month)

Without persistent storage, models (~2.6 GB) re-download on every restart.

1. In your Space → Settings → Persistent Storage
2. Choose Small (20 GB) — $5/month
3. HF will mount it at /data
4. The Dockerfile already points all caches to /data via env vars

Step 4 — Enable HTTPS

HF Spaces provides HTTPS automatically on https://YOUR_USERNAME-ijwi-translator.hf.space. The browser microphone API requires HTTPS — this is already handled for you.

---

Storage breakdown

Item	Disk	RAM
Whisper small	~244 MB	~500 MB
NLLB-200 distilled 600M	~2.4 GB	~2.5 GB
Coqui VITS (Kinyarwanda)	~80 MB	~200 MB
Python deps + OS	~3 GB	—
Total	~6 GB	~3.5 GB

Free tier provides 50 GB disk and 16 GB RAM — plenty of headroom.

---

Cold start warning

On the free CPU tier, the Space sleeps after inactivity. First request after wake-up loads all models (~30–60 seconds). Subsequent requests are fast (models stay in memory).

To avoid cold starts entirely, upgrade to a paid hardware tier in Space Settings.

---

Troubleshooting

Problem	Fix
Space won't start	Check Logs tab — likely an OOM or missing ffmpeg
Models re-downloading every restart	Add persistent storage and set HF_HOME=/data/.huggingface
"Microphone access denied"	You must be on HTTPS — HF Spaces provides this automatically
TTS audio missing	Coqui Kinyarwanda model may not load; translation still works
502 on first load	Models still loading — wait ~60s and refresh