README.md

---
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.

```json
{
  "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.