README.md

metadata

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

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

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.