---
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](https://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

```bash
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 |