AdnanFoisal/pdf-watermark-remover

Resona TTS Backend

Job-based multi-engine TTS API behind a single FastAPI app, packaged for a Hugging Face Docker Space on the CPU Basic (2 vCPU) tier.

What this is

Four CPU-only TTS engines wrapped behind one job API:

Job creation returns immediately with an id; synthesis runs on a single background worker (one job at a time, to protect the 2-vCPU tier). The client polls for status and downloads a 128 kbps MP3 when done.

Phase 1 status: stub mode

The image ships with RESONA_STUB=1, so every model resolves to a sine-tone stub engine. This lets the entire job lifecycle (create → poll → download → cancel → delete) be verified before any heavy model is installed. Flip to real engines in Phase 2 by uncommenting the engine installs in the Dockerfile and setting RESONA_STUB=0.

API

GET    /health                        liveness (used by the app's cold-start UI)
GET    /v1/models                     models + curated voice catalog
GET    /v1/voices/{voice_id}/preview  preview mp3 (pre-gen for curated, on-demand rest)
POST   /v1/jobs                       create a job -> returns job id immediately
GET    /v1/jobs/{id}                  poll status
GET    /v1/jobs/{id}/audio            download finished mp3
POST   /v1/jobs/{id}/cancel           cooperative cancel
DELETE /v1/jobs/{id}                  delete job + cached audio
POST   /v1/clone                      upload a voice-clone sample (multipart)

Run locally (no Docker)

cd backend
python -m pip install -r requirements.txt
RESONA_STUB=1 RESONA_DATA=./_data uvicorn app.main:app --reload --port 7860
# then in another shell:
bash scripts/smoke_test.sh http://localhost:7860

On Windows PowerShell:

$env:RESONA_STUB=1; $env:RESONA_DATA="./_data"; uvicorn app.main:app --port 7860

Run with Docker

cd backend
docker build -t resona-backend .
docker run -p 7860:7860 resona-backend

Explicit limitations (free HF tier)

• —No persistent storage. Jobs + finished MP3s are written under RESONA_DATA and survive within the container's life, but a container restart/sleep loses any in-flight job. The Android app stores the full source text and can re-submit to regenerate — that is the intended recovery path.
• —One job at a time. A second concurrent create returns 429.
• —Cold start. A sleeping Space returns 503 at the proxy while waking; the client retries /health for ~40s.