| --- |
| title: CPU OpenAI-Compatible TTS |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # CPU OpenAI-Compatible TTS for Hugging Face Spaces |
|
|
| This directory is a Hugging Face Docker Space variant of the project. |
|
|
| ## What changed |
|
|
| - Runs as a Docker Space on port `7860` |
| - Uses `/tmp/tts-server` for temporary job state and SQLite metadata |
| - Stages merged MP3s under `/tmp/tts-server` first, then moves them to `/store` only if that mount is writable |
| - Deletes temporary source, normalized, and chunk files after a successful merge |
| - Keeps auth disabled by default so the public Space UI works immediately |
| - Includes Kitten TTS alongside Supertonic and Kokoro, all running CPU-only |
|
|
| ## Persistent storage behavior |
|
|
| - `/store` is used for final MP3 outputs when writable |
| - if the mounted `/store` volume is not writable at runtime, final MP3s fall back to `/tmp/tts-server/final-outputs` |
| - Temporary files are written outside `/store` |
| - Deleting a job also deletes the persisted MP3 |
|
|
| ## Optional environment variables |
|
|
| See `.env.example`. |
|
|
| Most important overrides: |
|
|
| - `REQUIRE_AUTH=true` to re-enable bearer auth |
| - `API_KEY=...` when auth is enabled |
| - `PERSISTENT_OUTPUT_DIR=/store` |
| - `WORKSPACE_DIR=/tmp/tts-server` |
| - `KITTEN_MODEL_NAME=KittenML/kitten-tts-micro-0.8` |
| - `KITTEN_CACHE_DIR=/app/models/hf-cache` |
| - `ENABLE_MELO_TTS=true` (MeloTTS is installed and enabled in the image by default) |
|
|
| ## Local run |
|
|
| ```bash |
| docker build -t tts-hf-space . |
| docker run --rm -p 7860:7860 -v $(pwd)/.local-store:/store tts-hf-space |
| ``` |
|
|
| Then open `http://localhost:7860`. |
|
|
| ## API |
|
|
| - `POST /v1/audio/speech` |
| - `GET /v1/models` |
| - `GET /v1/voices` |
| - `POST /jobs` |
| - `GET /jobs/{job_id}` |
| - `GET /jobs/{job_id}/download` |
|
|
| ## Notes |
|
|
| - Build-time model downloads stay inside the image under `/app/models` |
| - Kitten TTS caches Hugging Face assets under `/app/models/hf-cache` |
| - Runtime final MP3s are staged in the workspace first, then promoted to `/store` when possible |
| - ffmpeg is required for MP3 encoding and merging |
|
|
| ## MeloTTS EN-only scaffold |
|
|
| - The repo includes a `melo-en` engine scaffold. |
| - MeloTTS is installed in the default Space image from the official GitHub repo at build time. |
| - The model is enabled by default in the Space image via `ENABLE_MELO_TTS=true`. |
|
|
