{"id":45914396,"url":"https://github.com/fakehec/coqui-tts-local-server","last_synced_at":"2026-04-04T08:01:19.198Z","repository":{"id":340915163,"uuid":"1168142013","full_name":"fakehec/coqui-tts-local-server","owner":"fakehec","description":"High-performance Coqui TTS API server with a hybrid \"Hot/Cold\" worker architecture","archived":false,"fork":false,"pushed_at":"2026-04-04T03:14:05.000Z","size":1658,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-04T03:25:53.087Z","etag":null,"topics":["concurrency","coqui-tts","fastapi","local-ai","open-webui","openai-api","openclaw","personality-tuning","privacy-focused","python","self-hosted","text-to-speech","tts","voice-cloning","xtts-v2"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fakehec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T03:53:14.000Z","updated_at":"2026-04-04T03:14:09.000Z","dependencies_parsed_at":"2026-04-04T08:00:36.254Z","dependency_job_id":null,"html_url":"https://github.com/fakehec/coqui-tts-local-server","commit_stats":null,"previous_names":["fakehec/coqui-tts-local-server"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/fakehec/coqui-tts-local-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fakehec%2Fcoqui-tts-local-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fakehec%2Fcoqui-tts-local-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fakehec%2Fcoqui-tts-local-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fakehec%2Fcoqui-tts-local-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fakehec","download_url":"https://codeload.github.com/fakehec/coqui-tts-local-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fakehec%2Fcoqui-tts-local-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concurrency","coqui-tts","fastapi","local-ai","open-webui","openai-api","openclaw","personality-tuning","privacy-focused","python","self-hosted","text-to-speech","tts","voice-cloning","xtts-v2"],"created_at":"2026-02-28T07:12:20.823Z","updated_at":"2026-04-04T08:01:19.192Z","avatar_url":"https://github.com/fakehec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# coqui-tts-local-server\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/social-preview.png\" alt=\"Coqui TTS Local Server\" width=\"800\"\u003e\n\u003c/p\u003e\n\nHigh-performance Coqui TTS API server with a hybrid \"Hot/Cold\" worker architecture. \n\n**Ideal for locally running installations of agents like OpenClaw or Open-WebUI, where the media should not leave the private local domain.**\n\n## ⚖️ License \u0026 Terms of Service (IMPORTANT)\n\nThis server uses **Coqui TTS**, which is released under various licenses depending on the model.\n- **XTTS v2** and several other models are released under the **Coqui Public Model License (CPML)**.\n- **NON-COMMERCIAL USE ONLY**: Usage is free for personal and non-commercial projects.\n- **COMMERCIAL USE**: If you intend to use this for commercial purposes, you **must** purchase a commercial license from Coqui (licensing@coqui.ai).\n- By running the installation scripts, you acknowledge and agree to these terms.\n\n## 🚀 Key Features\n\n- **Hybrid Concurrency:** \n  - **Hot Worker:** Primary model resident in VRAM for sub-second (XTTSv2 ~1.0s) inference.\n  - **Cold Workers:** Spawns on-demand subprocesses on GPU when the main lane is busy.\n- **GPU Accelerated:** Native support for NVIDIA CUDA via `torch`, ensuring ultra-fast inference and high-quality synthesis.\n- **OpenAI Compatible:** Native support for OpenAI parameters (`model`, `voice`, `speed`, `response_format`). Includes `GET /v1/models` for client autodiscovery.\n- **Streaming:** `POST /v1/audio/speech/stream` delivers chunked WAV audio in real time via XTTS-v2's `inference_stream()` (Hot Lane only).\n- **Personality Tuning:** Full control over synthesis expressiveness via parameters like `temperature`, `top_p/k`, and `penalties`.\n- **Multilingual Excellence:** Native support for 16 languages: `en, es, fr, de, it, pt, pl, tr, ru, nl, cs, ar, zh-cn, hu, ko, ja` (English by default).\n- **Intelligent Caching:** MD5-based caching for zero-latency repeated requests. Configurable TTL via `CACHE_TTL_MINUTES`.\n- **Health Endpoint:** `GET /health` exposes server version, model name, and hot worker status for proxies and Docker healthchecks.\n\n## 📦 Installation \u0026 Setup\n\n### 1. Prerequisites (Debian/Ubuntu)\nInstall the following system dependencies first:\n```bash\nsudo apt update \u0026\u0026 sudo apt install -y espeak-ng curl file ffmpeg python3.12 python3.12-venv\n```\n\n\u003e **Python version:** `setup.sh` requires **Python 3.12**. Python 3.13+ has no prebuilt wheels for `torch==2.9.0` or `torchcodec==0.8.1`. On systems where Python 3.12 is not the default (e.g. Ubuntu 24.10 with Python 3.14), the package above installs it alongside the system Python.\n\n### 2. Unified Installation\n```bash\ngit clone https://github.com/fakehec/coqui-tts-local-server.git\ncd coqui-tts-local-server\nchmod +x setup.sh\n./setup.sh\n```\n\n### 3. User Permissions \u0026 Hardware Acceleration\nTo run the server without `sudo` privileges and enable GPU acceleration, the user must belong to the `video` and `render` groups:\n```bash\nsudo usermod -aG video $USER\nsudo usermod -aG render $USER\n```\n*Note: Restart your session for changes to take effect.*\n\n### 3. Network Permissions\nThe server listens on port `5100` by default. Ensure the user has permissions to open sockets on this port (standard for ports \u003e1024).\n\n### 4. Vocal Provisioning\n- **Standard Voices**: The server automatically provisions the 6 standard OpenAI identities (Alloy, Echo, Fable, Onyx, Nova, Shimmer) during setup.\n- **Elite/Custom Voices**: Reference voice files (.wav) for custom cloning are **not provided** due to copyright. Place your samples in `assets/voices/elite/` within the project directory.\n- Refer to [CLONE_VOICES.md](./CLONE_VOICES.md) for instructions on creating high-quality reference files.\n\n## 🎭 Personality Tuning \u0026 Parameters\n\nThe server supports advanced personality parameters to tune the output voice. These can be sent via the **API (JSON or Form-data)** or set as system-wide defaults via **environment variables** (or the `.env` file).\n\n| Parameter | Default | Description | Env Variable |\n| :--- | :--- | :--- | :--- |\n| `temperature` | **0.75** | Higher values increase expressiveness/randomness. | `DEFAULT_TEMPERATURE` |\n| `length_penalty`| **1.0** | Controls the length of the generated sequence. | `DEFAULT_LENGTH_PENALTY` |\n| `repetition_penalty`| **5.0** | Prevents the model from repeating words/phrases. | `DEFAULT_REPETITION_PENALTY`|\n| `top_k` | **50** | Limits sampling to the top K most likely tokens. | `DEFAULT_TOP_K` |\n| `top_p` | **0.85** | Nucleus sampling to ensure token diversity. | `DEFAULT_TOP_P` |\n| `language` | **en** | Default language code. | `DEFAULT_LANGUAGE` |\n\n### 🌐 Supported Languages\nThe following language codes are supported: `en, es, fr, de, it, pt, pl, tr, ru, nl, cs, ar, zh-cn, hu, ko, ja`.\n\n## 📡 API Endpoints\n\n| Method | Path | Description |\n| :--- | :--- | :--- |\n| `GET` | `/health` | Server liveness, version, and hot worker status. |\n| `GET` | `/v1/models` | OpenAI-compatible model list (`tts-1`, `tts-1-hd`). |\n| `GET` | `/v1/voices` | List of available voice identifiers. |\n| `POST` | `/v1/audio/speech` | Standard TTS synthesis (Hot or Cold Lane, cached). |\n| `POST` | `/v1/audio/speech/stream` | Real-time streaming TTS (Hot Lane only, no cache). |\n\n## 🔧 Troubleshooting\n\n### Transformers Compatibility Error\nThe `isin_mps_friendly` compatibility fix is applied automatically as a Python monkey-patch in `main_tts.py` before any model import, and also by `setup.sh` as a fallback. No manual action is required.\n\n## 🛠 Execution\n\nThe server uses direct **Uvicorn** execution for maximum ASGI performance.\n\n### Manual Execution (Console)\n```bash\nsource venv/bin/activate\n\n# Localhost only (Default: 127.0.0.1:5100)\nuvicorn main_tts:app --host 127.0.0.1 --port 5100\n\n# Expose to Local Network (0.0.0.0)\nuvicorn main_tts:app --host 0.0.0.0 --port 5100\n```\n\n### ⚙️ Environment Variables \u0026 .env\n\nThe server includes a `.env.example` file. You can create a **`.env`** file in the root directory to override default behaviors without changing the code.\n\n| Variable | Default | Description |\n| :--- | :--- | :--- |\n| `TTS_MODEL` | `xtts_v2` | Model name to pre-load into the Hot Worker. |\n| `DEFAULT_LANGUAGE` | `en` | Default language if not specified in the request. |\n| `CACHE_TTL_MINUTES` | `10080` (7 days) | Cache file expiration. Set to `0` to disable. |\n| `COLD_LANE_TIMEOUT_SECONDS` | `120` | Max time to wait for a Cold Lane subprocess before killing it and returning HTTP 500. |\n| `DEBUG` | `false` | Set to `true` to enable worker routing traces. |\n| `VENV_PYTHON` | *(auto-detected)* | Absolute path to the venv Python executable. |\n\n*Note: All personality parameters listed in the section above can also be set via their respective `DEFAULT_*` environment variables.*\n\n### 3. User Service (systemd --user)\n1. Create directory if it doesn't exist: `mkdir -p ~/.config/systemd/user`\n2. Create: `~/.config/systemd/user/coqui-tts.service`\n3. Configuration (all environment variables are loaded from your `.env` file):\n\n```ini\n[Unit]\nDescription=Coqui TTS Local Server\nAfter=network.target\n\n[Service]\nType=simple\nWorkingDirectory=%h/coqui-tts-local-server\nExecStart=%h/coqui-tts-local-server/venv/bin/uvicorn main_tts:app --host 127.0.0.1 --port 5100\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=default.target\n```\n\n4. Enable and start:\n```bash\nsystemctl --user daemon-reload\nsystemctl --user enable --now coqui-tts.service\n```\n\n## 🐳 Docker\n\n### Host Prerequisites (one-time setup)\n\nBefore running `docker compose up` for the first time, the host machine requires two one-time configuration steps to enable GPU passthrough via the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) CDI mode.\n\n\u003e These steps are required because Docker's default legacy GPU mode relies on BPF cgroup device filters, which are not available in cgroup v2 environments (Ubuntu 22.04+). CDI solves this cleanly.\n\n**1. Add the NVIDIA package repository:**\n```bash\ncurl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \\\n  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg\n\ncurl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \\\n  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \\\n  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list\n```\n\n**2. Install the toolkit:**\n```bash\nsudo apt update \u0026\u0026 sudo apt install -y nvidia-container-toolkit\n```\n\n**3. Generate the CDI spec** (exposes the GPU to containers via a stable device descriptor):\n```bash\nsudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml\n```\n\n**4. Enable CDI in the Docker daemon:**\n```bash\nsudo tee /etc/docker/daemon.json \u003c\u003c'EOF'\n{\n  \"features\": {\n    \"cdi\": true\n  }\n}\nEOF\nsudo systemctl restart docker\n```\n\n**5. Verify it works:**\n```bash\ndocker run --rm --device nvidia.com/gpu=all nvidia/cuda:12.6.3-runtime-ubuntu24.04 nvidia-smi\n```\n\n\u003e **Note:** Step 3 must be re-run if the NVIDIA driver is updated (`sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml`).\n\n### Running with Docker Compose\n\n```bash\n# Build and start (downloads model and standard voices on first run)\ndocker compose up -d\n\n# Check server is ready\ncurl http://localhost:5100/health\n\n# View logs (including first-run provisioning progress)\ndocker compose logs -f\n\n# Stop\ndocker compose down\n```\n\nOn first run, `entrypoint.sh` automatically:\n- Downloads the `xtts_v2` model (~1.7GB) into `assets/models/`\n- Downloads the 6 standard voices (alloy, echo, fable, onyx, nova, shimmer) into `assets/voices/standard/`\n\nBoth are persisted in host volumes and skipped on subsequent starts.\n\n### Elite Voices in Docker\n\nElite/custom voices are not provisioned automatically. Mount them into the container by placing your `.wav` files in `assets/voices/elite/` on the host — the volume mapping `./assets/voices:/app/assets/voices` picks them up automatically without rebuilding the image.\n\n## 🔒 Security \u0026 Network Note\nBy default, the server binds to **`127.0.0.1`** on port **`5100`**. \n- To allow external network access, modify the `--host` parameter to `0.0.0.0` in the execution command or systemd unit.\n- **WARNING**: This API **does not have authentication**. Exposing it to the network via `0.0.0.0` represents a security risk. Ensure the server is protected by a firewall or operating within a secure VPN/Local Network.\n\n## 📊 Performance (NVIDIA RTX 5090)\n| Task | Latency (Hot Lane) | Latency (Cold Lane) |\n| :--- | :--- | :--- |\n| Short Response (XTTSv2) | **~1.0s** | ~19s (Cold load) |\n| Cached Response | **\u003c0.02s** | \u003c0.02s |\n\n## 🛡 License\nGNU GPL v3. Maintainers: Hugo L. Espuny \u0026 J.A.R.V.I.S. A.I.\n\n## ☕ Support\n\nIf this project is useful to you, consider supporting its development:\n\n- **Bitcoin (BTC):** `38jJyMomtUqhCjuNJ9VxKpgEyMyx37Zqix`\n- **Monero (XMR):** `82bbUZdkMXUPAma4ioTuZNcJgTh8YTv4XNUwPy6T28kYJWCfeGgV79AZb7amCszFXeBaa5u595cQBVjFS4PkBGim56ap7Ej`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffakehec%2Fcoqui-tts-local-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffakehec%2Fcoqui-tts-local-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffakehec%2Fcoqui-tts-local-server/lists"}