README.md

---
title: VoiceCraft CPU Clone Server
emoji: 🎙️
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
startup_duration_timeout: 1h
---

# VoiceCraft FastAPI Worker 3.1.2

Deploy the contents of this `HF` directory at the root of a Docker Hugging Face Space.

The worker provides:

- Edge, Piper, and Silero text-to-speech where available
- Optional Pocket TTS CPU voice cloning
- Firebase license, device, credit, version, and worker-assignment enforcement
- FastAPI health/status endpoints for the admin tools
- Capacity protection and per-license/device rate limits

## Required protected settings

- `VOICECRAFT_AUTH_MODE=license`
- `FIREBASE_SERVICE_ACCOUNT_JSON` containing the complete Firebase service-account JSON
- `VOICECRAFT_SPACE_ID=auto` so Hugging Face's `SPACE_ID` identifies each worker uniquely

For a TTS-only worker:

- `ENABLE_CLONE_ENGINES=0`

For a clone worker:

- `ENABLE_CLONE_ENGINES=1`
- `HF_TOKEN` with read access after accepting the Pocket TTS model terms

A single protected `VOICECRAFT_SPACE_CONFIG_JSON` may be used instead:

```json
{
  "space_id": "auto",
  "auth_mode": "license",
  "max_concurrent_jobs": 1,
  "service_version": "3.1.2",
  "minimum_version": "3.0.0",
  "enable_clone_engines": false,
  "firebase_service_account": {
    "type": "service_account",
    "project_id": "YOUR_PROJECT_ID",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "client_email": "firebase-adminsdk@YOUR_PROJECT_ID.iam.gserviceaccount.com",
    "token_uri": "https://oauth2.googleapis.com/token"
  }
}
```

Keep `space_id` set to `auto` when reusing the same configuration across workers. A fixed ID would make multiple workers write health and usage under the same Firestore document.

## Optional settings

- `VOICECRAFT_MAX_CONCURRENT_JOBS` — 1 to 20; default 1
- `VOICECRAFT_SERVICE_VERSION` — reported service version
- `MIN_CLIENT_VERSION` — fallback minimum desktop version
- `TTS_REQUESTS_PER_MINUTE` — default 60
- `CLONE_REQUESTS_PER_MINUTE` — default 8
- `VOICECRAFT_SPACE_URL` — explicit public worker URL when auto-detection is unavailable
- `VOICECRAFT_DISABLE_WARMUP=1` — testing only; prevents startup model warm-up

`VOICECRAFT_AUTH_MODE=layered` requires both Firebase licensing and `VOICECRAFT_API_SECRET`. `api_secret` mode exists for legacy private integrations and is not recommended for distributed desktop software.

## Firebase worker document

Create or update the worker in the admin Spaces page. Important fields include:

- canonical Space ID matching the worker's reported `space_id`
- HTTPS `.hf.space` URL
- enabled status
- `clone_enabled`
- `visibility`: `public` or `private`
- priority and maximum concurrent jobs

Private workers are excluded from the public runtime pool. The worker also rejects direct requests from accounts that are not assigned to it.

## Endpoints

- `GET/HEAD /health` — health and availability
- `GET /status` — service status and policy summary
- `GET /all_voices` — available voices
- `POST /register_user` — Firebase user/device registration
- `POST /activate_license` — license activation
- `GET /license_status` — current license state
- `POST /tts` — authenticated TTS or voice-clone generation

## Local Docker test

```bash
docker build -t voicecraft-worker .
docker run --rm -p 7860:7860 \
  -e VOICECRAFT_DISABLE_WARMUP=1 \
  -e ENABLE_CLONE_ENGINES=0 \
  voicecraft-worker
```

For an authenticated `/tts` test, supply a real test Firebase project, license, device ID, worker document, and client headers. Never test with production customer credentials in shared logs.

## Pocket TTS access

1. Accept the model terms on the Pocket TTS model page while signed in.
2. Create a Hugging Face read token.
3. Store it as the protected `HF_TOKEN` secret.
4. Restart the Space.

First startup can be slow while model files download. Keep cloning requests within the application's documented character limits and test representative reference audio before enabling the worker for customers.