README.md

metadata

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

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.