README.md

metadata

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

VoiceCraft CPU Clone Server

Deploy the contents of this HF folder at the root of your Hugging Face Space.

This profile is CPU-first:

• Normal TTS: Edge cloud voices, curated Piper models, and Silero Russian voices
• Voice clone: Pocket TTS CPU backend
• GPU/ZeroGPU: not required

Required Space settings

Set these in Space settings:

• VOICECRAFT_AUTH_MODE=license - requires a live active license and registered device on every /tts request.
• LICENSE_VALIDATION_URL - the deployed Google Apps Script URL. The current production URL is the code default, but setting it explicitly is recommended.
• ENABLE_CLONE_ENGINES=1 - keeps voice clone enabled.
• HF_TOKEN - Hugging Face read token from an account that has accepted the Pocket TTS model terms.

API_SECRET is legacy compatibility only. Do not put a shared API secret in distributed desktop apps. After every supported desktop build sends X-License-Key and X-Device-ID, remove the sheet ApiSecret value and rotate/remove the old Space API_SECRET.

Instead of setting many Space secrets, you can set one protected secret named VOICECRAFT_SPACE_CONFIG_JSON. Individual secrets still work and override this combined config when both are present.

{
  "space_id": "auto",
  "auth_mode": "license",
  "max_concurrent_jobs": 1,
  "service_version": "3.1.0",
  "enable_clone_engines": true,
  "hf_token": "hf_xxxxxxxxxxxxxxxxx",
  "firebase_service_account": {
    "type": "service_account",
    "project_id": "voicecraft-1",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "client_email": "firebase-adminsdk-xxx@voicecraft-1.iam.gserviceaccount.com",
    "token_uri": "https://oauth2.googleapis.com/token"
  }
}

Keep "space_id": "auto" when this same secret is reused across several workers. A fixed value would make every Space report and write usage under the same server ID.

Optional modes:

• VOICECRAFT_AUTH_MODE=layered requires both the live license/device and API_SECRET.
• VOICECRAFT_AUTH_MODE=api_secret is legacy-only and is not recommended for public distribution.

Rate limits default to 60 TTS requests/minute and 8 clone requests/minute per license/device. Override with TTS_REQUESTS_PER_MINUTE and CLONE_REQUESTS_PER_MINUTE.

Voice clone access

Pocket TTS voice cloning uses gated weights. Before using custom reference audio:

1. Open https://huggingface.co/kyutai/pocket-tts while logged in.
2. Accept the model terms/access form.
3. Create a read token at https://huggingface.co/settings/tokens.
4. Add that token to this Space as the secret HF_TOKEN.
5. Restart or rebuild the Space.

Google Sheet row

For a clone-enabled Space:

• AppLink = this Space URL
• VoiceClone = active, enabled, on, or true
• DeviceID and MaxDevices should be enabled for device binding.

For a TTS-only Space:

• VoiceClone = inactive, disabled, off, or blank

Notes

The desktop app still sends the clone engine as f5tts for compatibility, but this backend runs Pocket TTS on CPU. The public voice list only shows Voice Clone, so the model name is not shown in the desktop GUI.

First startup can be slower while model files download and load. Repeated use with the same reference audio is faster because the backend caches the reference voice state.

Voice Clone accepts long scripts from the desktop app. For best speed, keep each generation under 10,000 characters; longer scripts are batched automatically and joined into one WAV.

Authorization decisions are enforced by the backend. Hiding or unlocking a desktop UI control is never treated as authorization.