---
title: Sauti TTS — Lightweight Swahili Text-to-Speech
emoji: 🌍
colorFrom: indigo
colorTo: green
sdk: docker
pinned: false
---

# Sauti TTS — Lightweight Swahili TTS

Swahili text-to-speech built on `msingiai/sauti-tts` (F5-TTS base), optimized to run on **Hugging Face Free CPU Spaces** and connect to **LiveKit**.

## What's included

| File | Purpose |
|------|---------|
| `lightweight_infer.py` | Optimized inference: pruned checkpoint, bf16 weights, optional INT8 dynamic quant, 10-step EPSS sampling |
| `app.py` | FastAPI server for HF Space, `/tts` and `/health` endpoints |
| `Dockerfile` | Reproducible HF Space image (Python 3.11, CPU torch) |
| `livekit_agent.py` | LiveKit agent that calls the HF Space TTS API |

## Key optimizations for free CPU

1. **Checkpoint pruning** — strips optimizer/scheduler; full 5GB+ → ~1.3GB
2. **BF16 weights** — halves weight memory with minimal quality loss on modern CPUs
3. **10-step EPSS** — instead of default 32, cuts compute by ~3×
4. **CFG 1.5** — lower guidance, fewer double-passes
5. **Dynamic INT8** (optional) — ~4× weight reduction
6. **Cached text encoder** — text embeddings computed once, reused across ODE steps

## Deploy to Hugging Face Spaces

1. Create a new **Space** → **Docker** → Free CPU.
2. Upload these four files (`app.py`, `lightweight_infer.py`, `Dockerfile`, `requirements.txt`).
3. Set **HF_TOKEN** in Space secrets (your HF write token).
4. Set **HF_MODEL_ID** (default: `msingiai/sauti-tts`).
5. Build completes in ~5 minutes. The first request will be slow (model download + pruning), but subsequent requests are fast.

### Space secrets

| Name | Required | Value |
|------|----------|-------|
| `HF_TOKEN` | Yes | Your HF token with read access to `msingiai/sauti-tts` |
| `DEFAULT_REF_AUDIO` | No | Absolute path to a reference wav for voice cloning |
| `TTS_URL` | No | Override if you changed the app port |

## LiveKit Integration

```bash
export LIVEKIT_URL=wss://your-project.livekit.cloud
export LIVEKIT_API_KEY=...
export LIVEKIT_API_SECRET=...
export TTS_URL=https://<your-space>.hf.space
export DEFAULT_REF_AUDIO=/app/reference.wav

python livekit_agent.py
```

## Local test

```bash
python lightweight_infer.py \
  --checkpoint msingiai/sauti-tts \
  --ref_audio path/to/reference.wav \
  --ref_text "Habari, karibu" \
  --text "Hujambo, ninasema na wewe leo." \
  --output out.wav
```

## Notes

- Free HF CPU Spaces have limited RAM. The pruned+bf16 model fits in ~1.2GB with the vocoder.
- First inference will take ~30-60s on free CPU; later requests drop to ~5-10s for short sentences.
- If you hit OOM, set `--no-quantize` and reduce `--steps 5`.