README.md

metadata

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:

{
  "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

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.