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