Abstract
NeuTTS FastAPI wraps a local NeuTTS voice-cloning model behind a FastAPI service, giving other pipelines a stable HTTP interface for keyword-addressed reference voices and offline speech synthesis. The part worth reporting on is the persistent voice registry: save a reference once, reference it by keyword across many generations, and let the container stay stateless.
1. What This Is
A Dockerized FastAPI service that exposes offline NeuTTS inference as REST endpoints. Callers save a reference WAV plus its transcript under a chosen keyword, then request speech generation by passing text and that keyword. All voice assets and generated audio live on bind-mounted volumes so they survive container restarts. The deployment is CPU-only and fully offline—no external model downloads or cloud calls at runtime.
2. How It Works
The service follows a simple request flow: register a voice, then synthesize against it. The table below maps each stage.
| # | Stage | Input | Tool | Output |
|---|---|---|---|---|
| 01 | Service startup | Docker image | FastAPI + NeuTTS runtime | Ready service on local port |
| 02 | Voice registration | Reference WAV + transcript + keyword | POST /voices | Stored reference pair on volume |
| 03 | Voice discovery | None | GET /voices | List of saved keywords |
| 04 | Speech synthesis | Text + voice keyword | NeuTTS local inference | Generated WAV on output volume |
| 05 | Health check | None | GET /health | Readiness status |
3. Implementation Notes
3.1 Keyword-based voice registry
A flat mapping from a string keyword to a (reference WAV, transcript) pair stored on a mounted volume. No database layer—just files. This keeps the service dependency-light but means there is no concurrent-write safety, no versioning, and no documented deletion path.
3.2 Persistent volumes
Reference audio and generated outputs are written to bind-mounted directories. The container itself is stateless; all durable state lives outside it. This is what makes the voice store reusable across restarts and across multiple pipeline runs.
3.3 CPU-oriented deployment
The Docker Compose configuration and deployment notes target CPU-only hosts. NeuTTS runs without a GPU, trading generation latency for portability. This is a deliberate choice for local/offline setups where a dedicated GPU is not available.
4. Constraints
-
Single-process, no concurrency
The service handles one synthesis request at a time. A second caller will block until the first generation finishes. Fine for a single pipeline; not for shared infrastructure.
-
File-based registry, no validation
Keywords are plain strings with no schema, no uniqueness enforcement beyond the filesystem, and no documented delete endpoint. A typo in a keyword silently creates a new entry or 404s.
-
CPU inference latency
Without a GPU, longer texts take noticeably longer to synthesize. There is no streaming or chunked response—callers wait for the full WAV before the HTTP response returns.
-
No authentication or rate limiting
Endpoints are open on the local network. Acceptable for a single-host offline setup, but the service is not safe to expose beyond a trusted LAN without an auth layer.
5. Next
- a. Add a voice deletion endpoint and basic keyword validation (length, character set) to the registration route.
- b. Introduce a lightweight background job queue so multiple synthesis requests can be enqueued rather than serialized on a single thread.
- c. Ship a GPU Docker Compose override profile for hosts that have a CUDA device, reducing per-request latency without changing the API contract.
— end of report —