# 🐸 Coqui TTS User Guide

**Coqui TTS** (package name `TTS`) is a Python library for advanced **Text-to-Speech** generation. It bundles dozens of pretrained neural voices in 1100+ languages, a one-line command-line tool, a Python API, a local web server, and full training recipes — so you can turn text into natural-sounding speech, clone a voice from a few seconds of reference audio, or convert one speaker's voice into another.

This guide covers everything you need to **use** the released models: installing the package, choosing a voice, synthesizing speech from the command line and from Python, voice cloning, voice conversion, and running the local demo server. Training your own models, architecture internals, and security hardening live in the companion **Admin Guide**.

> [!NOTE]
> Coqui TTS is documented here at version **0.22.0** (commit `dbf1a08`). The original company behind Coqui has since shut down, so the project is effectively frozen at this release and community-maintained. The voices and code below work, but expect compatibility friction with very new versions of PyTorch and `transformers` — see [Troubleshooting](#11-troubleshooting).

---

## 1. Quick Start

Install the package, then make your computer talk in two lines.

> [!IMPORTANT]
> Coqui TTS requires **Python ≥ 3.9 and < 3.12**. Installation fails on Python 3.12+ with a `RuntimeError`. Use a 3.9–3.11 virtual environment.

=== "Command line"

    ```bash
    pip install TTS
    tts --text "Hello world, spoken by Coqui." --out_path hello.wav
    ```

    ```text
     > tts_models/en/ljspeech/tacotron2-DDC is downloaded.
     > Text: Hello world, spoken by Coqui.
     > Saving output to hello.wav
    ```

=== "Python"

    ```python
    from TTS.api import TTS

    tts = TTS("tts_models/en/ljspeech/tacotron2-DDC")
    tts.tts_to_file(text="Hello world, spoken by Coqui.", file_path="hello.wav")
    ```

The first run downloads the default English model (`tts_models/en/ljspeech/tacotron2-DDC`) and writes a `.wav` file you can play in any audio player.

> [!TIP]
> No model specified means Coqui uses its default LJSpeech English voice. To pick a different voice, see [Choosing a Voice](#4-choosing-a-voice-the-model-zoo).

To clone a voice instead, point the high-quality **XTTS v2** model at a reference clip:

```python
from TTS.api import TTS

tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2")
tts.tts_to_file(
    text="This sentence is spoken in a cloned voice.",
    speaker_wav="reference.wav",   # a few seconds of the voice to clone
    language="en",
    file_path="cloned.wav",
)
```

---

## 2. What You Can Do

| Capability | How | Best model to start with |
|---|---|---|
| **Synthesize speech** from text | `tts` CLI or Python `tts_to_file()` | `tts_models/en/ljspeech/tacotron2-DDC` |
| **Voice cloning** from a reference clip | `--speaker_wav` / `speaker_wav=` | `tts_models/multilingual/multi-dataset/xtts_v2` |
| **Multilingual** speech (17 languages, one model) | XTTS v2 with `language=` | `xtts_v2` |
| **Multi-speaker** voices (pick from a roster) | `--speaker_idx` / `speaker=` | `tts_models/en/vctk/vits` (109 speakers) |
| **Voice conversion** (recast one voice as another) | `voice_conversion_to_file()` | `voice_conversion_models/multilingual/vctk/freevc24` |
| **1100+ languages** via Meta's MMS/Fairseq voices | `tts_models/<iso>/fairseq/vits` | e.g. `tts_models/deu/fairseq/vits` |
| **Serve a web/HTTP TTS endpoint** | `tts-server` | any tts_models name |

> [!NOTE]
> Coqui ships several **model families** with different strengths: end-to-end models (**XTTS**, **VITS**, **YourTTS**, **Bark**, **Tortoise**) and classic two-stage spectrogram models (**Tacotron2**, **Glow-TTS**, **FastPitch**, **Speedy-Speech**, **Overflow**) that pair with a separate **vocoder**. XTTS v2 is the most capable all-rounder for cloning and multilingual work.

---

## 3. Installation

### 3.1 From PyPI (recommended for synthesis only)

If you only want to generate speech with the released models, install from PyPI:

```bash
pip install TTS
```

### 3.2 From source (for training or development)

```bash
git clone https://github.com/coqui-ai/TTS
cd TTS
pip install -e .[all,dev,notebooks]   # select the extras you need
```

Available extras: `all`, `dev`, `notebooks`, `ja` (Japanese support).

### 3.3 On Ubuntu / Debian

A `Makefile` provides convenience targets:

```bash
make system-deps   # installs OS-level audio/build dependencies (Ubuntu/Debian only)
make install       # installs TTS in editable mode
```

### 3.4 With Docker (no install)

Coqui publishes prebuilt images so you can run TTS without installing anything locally:

```bash
docker run --rm -it -p 5002:5002 --entrypoint /bin/bash ghcr.io/coqui-ai/tts-cpu
python3 TTS/server/server.py --list_models                       # see available models
python3 TTS/server/server.py --model_name tts_models/en/vctk/vits  # start the server
```

Then open `http://[::1]:5002/` in a browser. GPU image variants are also published.

> [!WARNING]
> The hard Python version gate lives in `setup.py`: installing on **Python 3.12 or newer** raises `RuntimeError: TTS requires python >= 3.9 and < 3.12`. Create your environment with a supported interpreter *before* installing — for example `python3.11 -m venv .venv`.

### 3.5 Verify the install

```bash
tts --list_models
```

```text
 Name format: type/language/dataset/model
 1: tts_models/multilingual/multi-dataset/xtts_v2
 2: tts_models/multilingual/multi-dataset/xtts_v1.1
 ...
```

If `tts --list_models` prints a numbered model list, you're ready.

---

## 4. Choosing a Voice (the Model Zoo)

Every Coqui voice has a **four-part name**:

```text
<model_type>/<language>/<dataset>/<model_name>
```

For example `tts_models/en/ljspeech/tacotron2-DDC` is a TTS model, English, trained on the LJSpeech dataset, using the Tacotron2-DDC architecture. The three model types are:

| Type prefix | What it produces |
|---|---|
| `tts_models/...` | Text → speech |
| `vocoder_models/...` | Mel-spectrogram → waveform (paired with two-stage TTS models) |
| `voice_conversion_models/...` | Recast a source voice as a target voice |

### 4.1 Browse and inspect models

```bash
# List every available model
tts --list_models

# Show details for a model by its full name
tts --model_info_by_name tts_models/en/ljspeech/tacotron2-DDC

# Show details for a model by its index in --list_models
tts --model_info_by_idx tts_models/3
```

### 4.2 Headline models

| Model name | Languages | Notes |
|---|---|---|
| `tts_models/multilingual/multi-dataset/xtts_v2` | 17 | Best quality; voice cloning; streaming-capable. **Requires accepting a license** (see note below). |
| `tts_models/multilingual/multi-dataset/your_tts` | EN/FR/PT + more | Cross-language voice cloning. |
| `tts_models/multilingual/multi-dataset/bark` | many | Suno's Bark; expressive, unconstrained cloning. |
| `tts_models/en/multi-dataset/tortoise-v2` | EN | High quality, slower (Tortoise). |
| `tts_models/en/ljspeech/tacotron2-DDC` | EN | Fast default single-speaker voice. |
| `tts_models/en/ljspeech/vits` | EN | End-to-end, no separate vocoder needed. |
| `tts_models/en/vctk/vits` | EN | **109 speakers** — multi-speaker. |
| `tts_models/de/thorsten/tacotron2-DDC` | DE | German single-speaker. |
| `tts_models/<iso>/fairseq/vits` | 1100+ | Meta MMS voices, e.g. `tts_models/deu/fairseq/vits`. |

> [!IMPORTANT]
> **XTTS v2 is not open source.** It ships under the **Coqui Public Model License (CPML)**, which restricts commercial use, and it is *gated*: the first time you load it you must accept the terms. To pre-accept non-interactively (for scripts/servers), set the environment variable `COQUI_TOS_AGREED=1`. Other voices carry their own licenses (Apache-2.0, MPL, CC-BY-SA, MIT, etc.) — check `--model_info_by_name` before any commercial use.

> [!TIP]
> **Fairseq / MMS voices** unlock 1100+ languages with one naming convention: `tts_models/<lang-iso_code>/fairseq/vits`. Look up ISO codes in Meta's MMS language table. These are single-speaker but cover the long tail of languages no dedicated Coqui voice exists for.

### 4.3 Where models are stored

Downloaded models are cached on disk so they download only once. The cache location is resolved in this order:

1. `$TTS_HOME/tts/` if `TTS_HOME` is set
2. `$XDG_DATA_HOME/tts/` if `XDG_DATA_HOME` is set
3. otherwise `~/.local/share/tts/`

See the [Reference](#13-reference) for these environment variables.

---

## 5. Synthesizing Speech from the Command Line

The `tts` command is installed as a console script. Its single most-used form is:

```bash
tts --text "Text to speak" --out_path speech.wav
```

### 5.1 Common recipes

```bash
# Default English voice
tts --text "Text for TTS" --out_path output/speech.wav

# Pick a specific model
tts --text "Text for TTS" \
    --model_name "tts_models/en/ljspeech/glow-tts" \
    --out_path output/speech.wav

# Pick a model AND a specific vocoder
tts --text "Text for TTS" \
    --model_name "tts_models/en/ljspeech/glow-tts" \
    --vocoder_name "vocoder_models/en/ljspeech/univnet" \
    --out_path output/speech.wav

# Run your own trained model (uses Griffin-Lim if no vocoder given)
tts --text "Text for TTS" \
    --model_path path/to/model.pth \
    --config_path path/to/config.json \
    --out_path output/speech.wav

# Pipe the wav straight to an audio player instead of a file
tts --text "Text for TTS" --pipe_out --out_path output/speech.wav | aplay
```

```text
 > Text: Text for TTS
 > Saving output to output/speech.wav
```

### 5.2 Multi-speaker models

Models like `tts_models/en/vctk/vits` contain many voices. List them, then pick one:

```bash
# 1. See the available speaker IDs
tts --model_name "tts_models/en/vctk/vits" --list_speaker_idxs

# 2. Synthesize with a chosen speaker
tts --text "Text for TTS." \
    --model_name "tts_models/en/vctk/vits" \
    --speaker_idx p225 \
    --out_path output/speech.wav
```

```text
 > Available speaker ids: (Set --speaker_idx flag to one of these values to use the multi-speaker model.
 {'p225': 0, 'p226': 1, 'p227': 2, ...}
```

### 5.3 Multilingual models

For XTTS and other multilingual models, list and select a language ID:

```bash
tts --model_name "tts_models/multilingual/multi-dataset/xtts_v2" --list_language_idxs
tts --text "Bonjour le monde." \
    --model_name "tts_models/multilingual/multi-dataset/xtts_v2" \
    --language_idx fr \
    --speaker_wav reference.wav \
    --out_path output/fr.wav
```

### 5.4 Voice cloning from the command line

Pass one or more reference clips with `--speaker_wav` (multiple files are averaged):

```bash
tts --text "This is a cloned voice." \
    --model_name "tts_models/multilingual/multi-dataset/xtts_v2" \
    --language_idx en \
    --speaker_wav my_voice_1.wav my_voice_2.wav \
    --out_path cloned.wav
```

### 5.5 Voice conversion from the command line

Convert the voice in `--source_wav` into the voice from `--target_wav`:

```bash
tts --model_name "voice_conversion_models/multilingual/vctk/freevc24" \
    --source_wav my_voice.wav \
    --target_wav target_voice.wav \
    --out_path converted.wav
```

### 5.6 Full CLI flag reference

> [!NOTE]
> Running `tts` with none of `--text`, `--list_models`, `--list_speaker_idxs`, `--list_language_idxs`, `--reference_wav`, `--model_info_by_idx`, `--model_info_by_name`, `--source_wav`, or `--target_wav` set simply prints the help screen.

| Flag | Type | Default | Purpose |
|---|---|---|---|
| `--text` | str | `None` | Text to synthesize. |
| `--out_path` | str | `tts_output.wav` | Output `.wav` file path. |
| `--model_name` | str | `tts_models/en/ljspeech/tacotron2-DDC` | Pretrained model to use. |
| `--vocoder_name` | str | `None` | Pretrained vocoder (defaults to the model's own). |
| `--model_path` | str | `None` | Path to your own model checkpoint. |
| `--config_path` | str | `None` | Path to your own model config. |
| `--vocoder_path` | str | `None` | Path to your own vocoder checkpoint. |
| `--vocoder_config_path` | str | `None` | Path to your own vocoder config. |
| `--encoder_path` | str | `None` | Path to a speaker encoder checkpoint. |
| `--encoder_config_path` | str | `None` | Path to a speaker encoder config. |
| `--speakers_file_path` | str | `None` | `speakers.json` for a custom multi-speaker model. |
| `--language_ids_file_path` | str | `None` | `language_ids.json` for a custom multilingual model. |
| `--speaker_idx` | str | `None` | Target speaker ID (multi-speaker models). |
| `--language_idx` | str | `None` | Target language ID (multilingual models). |
| `--speaker_wav` | str(s) | `None` | One or more reference clips for cloning (averaged). |
| `--reference_wav` | str | `None` | Reference wav to convert into the target voice. |
| `--reference_speaker_idx` | str | `None` | Speaker ID of the reference wav speaker. |
| `--gst_style` | str | `None` | Wav file for GST (global style token) style reference. |
| `--capacitron_style_wav` | str | `None` | Prosody reference wav for Capacitron models. |
| `--capacitron_style_text` | str | `None` | Transcription of the Capacitron prosody reference. |
| `--source_wav` | str | `None` | Source audio for voice conversion. |
| `--target_wav` | str | `None` | Target voice for voice conversion. |
| `--voice_dir` | str | `None` | Voice directory for the Tortoise model. |
| `--list_models` | bool | `False` | List all available models and exit. |
| `--model_info_by_name` | str | `None` | Print model info by full name. |
| `--model_info_by_idx` | str | `None` | Print model info by `<type>/<idx>`. |
| `--list_speaker_idxs` | bool | `False` | List speaker IDs for the chosen model. |
| `--list_language_idxs` | bool | `False` | List language IDs for the chosen model. |
| `--use_cuda` | bool | `False` | Run the model on CUDA (GPU). |
| `--device` | str | `cpu` | Device to run on (e.g. `cuda`, `cpu`). |
| `--pipe_out` | bool | `False` | Write the wav to stdout for shell piping. |
| `--save_spectogram` | bool | `False` | Also save the raw spectrogram to `out_path`. |
| `--progress_bar` | bool | `True` | Show a download progress bar. |

---

## 6. Synthesizing Speech from Python

The `TTS` class in `TTS.api` is the programmatic entry point. Construct it with a model name (or your own paths), then call `tts()` (returns waveform samples) or `tts_to_file()` (writes a `.wav`).

### 6.1 Single-speaker model

```python
import torch
from TTS.api import TTS

device = "cuda" if torch.cuda.is_available() else "cpu"

tts = TTS("tts_models/de/thorsten/tacotron2-DDC").to(device)
tts.tts_to_file(text="Ich bin eine Testnachricht.", file_path="de.wav")
```

> [!TIP]
> Use `tts.to("cuda")` to move the model to the GPU. The older `gpu=True` constructor argument still works but is **deprecated** — prefer `.to(device)`.

### 6.2 Multi-speaker, multilingual model (XTTS)

```python
from TTS.api import TTS

tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2").to("cuda")

# Voice cloning requires a reference clip + a language for XTTS
wav = tts.tts(text="Hello world!", speaker_wav="reference.wav", language="en")
tts.tts_to_file(text="Hello world!", speaker_wav="reference.wav", language="en", file_path="out.wav")
```

> [!NOTE]
> Coqui validates your arguments against the model. If a model is multi-speaker you **must** pass `speaker` or `speaker_wav`; if it is multilingual you **must** pass `language`. Passing `speaker`/`language` to a model that doesn't support them also raises a `ValueError`. See [Troubleshooting](#11-troubleshooting).

### 6.3 Inspect the loaded model

```python
tts.is_multi_speaker     # True/False
tts.is_multi_lingual     # True/False
tts.speakers             # list of speaker names, or None
tts.languages            # list of language codes, or None
print(TTS().list_models())  # browse the zoo
```

### 6.4 Fairseq / MMS voices (1100+ languages)

```python
from TTS.api import TTS

api = TTS("tts_models/deu/fairseq/vits")
api.tts_to_file("Wie geht es dir?", file_path="de_fairseq.wav")
```

### 6.5 The `tts()` and `tts_to_file()` parameters

| Parameter | Default | Meaning |
|---|---|---|
| `text` | — | Input text to synthesize. |
| `speaker` | `None` | Speaker name for multi-speaker models. |
| `language` | `None` | Language code for multilingual models (XTTS). |
| `speaker_wav` | `None` | Reference clip(s) for voice cloning. |
| `split_sentences` | `True` | Split text into sentences, synthesize each, then concatenate. |
| `file_path` (file variant) | `output.wav` | Output path. |
| `pipe_out` (file variant) | `None` | Stream the wav to a pipe. |

> [!TIP]
> Leave `split_sentences=True` (the default) for long passages — it keeps each chunk within a model's text-length and VRAM limits. Set it to `False` only for short single sentences where you want to avoid the small concatenation seams; it uses more VRAM.

> [!CAUTION]
> The `emotion` and `speed` parameters exist on `tts()`/`tts_to_file()` but only ever worked with the discontinued **Coqui Studio** cloud models. Passing both together raises `ValueError: Emotion and speed can only be used with Coqui Studio models. Which is discontinued.` Leave them unset with local models.

---

## 7. Voice Cloning

Voice cloning recreates a target voice from a short reference clip. Use a cloning-capable model (**XTTS v2**, **YourTTS**, **Bark**) and pass the reference with `speaker_wav`.

```python
from TTS.api import TTS

tts = TTS("tts_models/multilingual/multi-dataset/your_tts").to("cuda")

tts.tts_to_file("This is voice cloning.",
                speaker_wav="my/cloning/audio.wav", language="en", file_path="en.wav")
tts.tts_to_file("C'est le clonage de la voix.",
                speaker_wav="my/cloning/audio.wav", language="fr-fr", file_path="fr.wav")
tts.tts_to_file("Isso é clonagem de voz.",
                speaker_wav="my/cloning/audio.wav", language="pt-br", file_path="pt.wav")
```

> [!TIP]
> Use a **clean, mono reference clip** of a few seconds with minimal background noise. You can pass multiple clips (`speaker_wav=["a.wav","b.wav"]`); their speaker embeddings are averaged for a steadier voice. Coqui does not enforce a fixed clip length in code, but very short or noisy references degrade quality.

### 7.1 Clone any voice with two-stage conversion

Even models that can't clone directly can be combined with a voice-conversion model using `tts_with_vc_to_file()`. Coqui synthesizes the text in the base voice, then converts it to your reference speaker:

```python
from TTS.api import TTS

tts = TTS("tts_models/de/thorsten/tacotron2-DDC")
tts.tts_with_vc_to_file(
    "Wie sage ich auf Italienisch, dass ich dich liebe?",
    speaker_wav="target/speaker.wav",
    file_path="output.wav",
)
```

---

## 8. Voice Conversion

Voice conversion recasts the speaker identity of an existing recording without changing the words. Coqui ships **FreeVC** for this.

```python
from TTS.api import TTS

tts = TTS("voice_conversion_models/multilingual/vctk/freevc24").to("cuda")
tts.voice_conversion_to_file(
    source_wav="my/source.wav",     # the words / performance to keep
    target_wav="my/target.wav",     # the voice to adopt
    file_path="output.wav",
)
```

> [!NOTE]
> `source_wav` supplies the content and timing; `target_wav` supplies the voice. The output says what `source_wav` said, in the voice of `target_wav`.

---

## 9. The Local Demo Server

Coqui includes a Flask web server with a browser UI and an HTTP API, installed as the `tts-server` console script.

### 9.1 Start the server

```bash
# Start with a chosen model on the default port 5002
tts-server --model_name tts_models/en/vctk/vits

# Or list models first
tts-server --list_models
```

Open `http://localhost:5002/` for the web UI, or call the HTTP API directly.

### 9.2 HTTP API

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/` | Web UI (HTML page). |
| `GET` | `/details` | Model detail page (when `--show_details true`). |
| `GET` / `POST` | `/api/tts` | Synthesize speech; returns `audio/wav`. |
| `GET` | `/locales` | MaryTTS-compatible locale list. |
| `GET` | `/voices` | MaryTTS-compatible voice list. |
| `GET` / `POST` | `/process` | MaryTTS-compatible synthesis endpoint. |

```bash
# Synthesize via the HTTP API
curl "http://localhost:5002/api/tts?text=Hello%20from%20the%20server" --output speech.wav
```

For multi-speaker or multilingual models, add `speaker_id`, `language_id`, or `style_wav` query parameters.

### 9.3 Server flags

| Flag | Default | Purpose |
|---|---|---|
| `--model_name` | `tts_models/en/ljspeech/tacotron2-DDC` | Pretrained model to serve. |
| `--vocoder_name` | `None` | Pretrained vocoder. |
| `--model_path` / `--config_path` | `None` | Serve your own model. |
| `--vocoder_path` / `--vocoder_config_path` | `None` | Serve your own vocoder. |
| `--speakers_file_path` | `None` | `speakers.json` for a custom multi-speaker model. |
| `--port` | `5002` | Port to listen on. |
| `--use_cuda` | `False` | Run on GPU. |
| `--debug` | `False` | Enable Flask debug mode. |
| `--show_details` | `False` | Enable the `/details` page. |
| `--list_models` | `False` | List models and exit. |

> [!CAUTION]
> The demo server is built for **local experimentation only**. It binds to all network interfaces, has **no authentication**, and the MaryTTS-compatibility layer is minimal. Do not expose `tts-server` directly to the public internet — put it behind your own authenticated proxy if you need remote access. See the Admin Guide's security section.

---

## 10. Running on a GPU

Coqui uses PyTorch, so it runs on CPU by default and on NVIDIA GPUs when available.

=== "Python"

    ```python
    import torch
    from TTS.api import TTS

    device = "cuda" if torch.cuda.is_available() else "cpu"
    tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2").to(device)
    ```

=== "Command line"

    ```bash
    tts --text "On the GPU" --model_name tts_models/en/ljspeech/vits --device cuda --out_path out.wav
    # or the legacy flag:
    tts --text "On the GPU" --use_cuda true --out_path out.wav
    ```

> [!TIP]
> Large models like **XTTS v2**, **Bark**, and **Tortoise** are slow on CPU. Use a GPU for interactive work. Lightweight VITS and Tacotron2 models are usable on CPU for short text.

---

## 11. Troubleshooting

### Error: `RuntimeError: TTS requires python >= 3.9 and < 3.12 ...`

**Cause:** You're installing on Python 3.12 or newer (or older than 3.9). The version is gated in `setup.py`.
**Solution:** Create a 3.9–3.11 environment: `python3.11 -m venv .venv && source .venv/bin/activate`, then `pip install TTS`.
**Prevention:** Check `python --version` before installing.

### Error: `ImportError: cannot import name 'isin_mps_friendly' from 'transformers.pytorch_utils'`

**Cause:** Your installed `transformers` version is incompatible. Coqui pins `transformers>=4.33.0` and breaks against `transformers` 5.x.
**Solution:** Pin a compatible version, e.g. `pip install "transformers>=4.33,<5"`.
**Prevention:** Install Coqui in a clean environment so its pinned dependencies resolve correctly.

### Error: `AttributeError: 'GenerationConfig' object has no attribute 'do_stream'`

**Cause:** XTTS streaming code is incompatible with `transformers` 5.0.0.
**Solution:** Downgrade `transformers` below 5.0 (see above).
**Prevention:** Avoid upgrading `transformers` past the 4.x line while using this release of Coqui.

### Error: `ModuleNotFoundError: No module named 'pkg_resources'`

**Cause:** `setuptools` is missing or too new (it removed the legacy `pkg_resources` module) in your environment.
**Solution:** `pip install setuptools<81` (or install a `setuptools` version that still provides `pkg_resources`).
**Prevention:** Use the dependency set Coqui installs rather than a bare interpreter.

### Error: `Exception: [!] You must agree to the terms of service to use this model.`

**Cause:** You loaded a gated model (e.g. **XTTS v2**, license CPML) without accepting its terms.
**Solution:** Accept interactively when prompted, or set `COQUI_TOS_AGREED=1` in the environment for non-interactive scripts and servers.
**Prevention:** Set `COQUI_TOS_AGREED=1` in your service environment for gated models.

### Error: `ValueError: Model is multi-speaker but no 'speaker' is provided.`

**Cause:** The model has multiple voices and you didn't choose one.
**Solution:** Pass `speaker="<id>"` (or `speaker_wav=...` for cloning). List options with `tts.speakers` or `tts --list_speaker_idxs`.
**Prevention:** Check `tts.is_multi_speaker` before synthesizing.

### Error: `ValueError: Model is multi-lingual but no 'language' is provided.`

**Cause:** A multilingual model (XTTS) needs a target language.
**Solution:** Pass `language="en"` (or `--language_idx en`). List options with `tts.languages` / `--list_language_idxs`.
**Prevention:** Check `tts.is_multi_lingual`.

### Error: `ValueError: Model is not multi-speaker but 'speaker' is provided.`

**Cause:** You passed `speaker`/`language` to a single-voice model that doesn't accept it.
**Solution:** Remove the `speaker`/`language` argument for single-speaker, single-language models.

### Error: `RuntimeError: The hash of {file} does not match. Delete the file manually and retry.`

**Cause:** A model download was corrupted or interrupted; its checksum doesn't match.
**Solution:** Delete the cached file at the path shown and re-run to re-download.
**Prevention:** Ensure a stable connection during the first download of large models.

### Error: `NotImplementedError: [!] only supports tar.gz, tgz, and zip archives.`

**Cause:** A custom model URL points to an unsupported archive format.
**Solution:** Repackage the model as `.zip`, `.tar.gz`, or `.tgz`.

### Error: `NotImplementedError: XTTS has a dedicated trainer ...`

**Cause:** You tried to train/fine-tune XTTS through the generic training path.
**Solution:** Use the dedicated XTTS fine-tuning recipe (see the XTTS docs and `recipes/ljspeech`).

### Issue: A voice's first word is sometimes skipped

**Cause:** A known artifact in some attention-based models (community issue #4016).
**Solution:** Prepend a short pause or punctuation, or try a different model (VITS/XTTS) for the same text.

### Issue: `coqui.ai` links don't work / look wrong

**Cause:** The original Coqui company shut down and the `coqui.ai` domain is no longer controlled by the project (community issues #4418, #4392).
**Solution:** Rely on the GitHub repository, the cached models, and this guide. Treat any content now served from `coqui.ai` with caution.

> [!TIP]
> When something goes wrong, `tts/bin/collect_env_info.py` (run as `python -m TTS.bin.collect_env_info`) prints your environment details — useful when comparing against a known-good setup.

---

## 12. FAQ

**Q: Do I need a GPU?**
No. Coqui runs on CPU. Lightweight models (VITS, Tacotron2) are fine on CPU for short text; large models (XTTS, Bark, Tortoise) are much faster on a GPU.

**Q: Which model should I use for the best quality and voice cloning?**
`tts_models/multilingual/multi-dataset/xtts_v2`. It covers 17 languages and clones from a reference clip. Note its non-commercial CPML license.

**Q: Can I use Coqui voices commercially?**
It depends on the specific model's license. XTTS v2 is **CPML (non-commercial)**. Others range from Apache-2.0 and MIT to CC-BY-NC. Always run `tts --model_info_by_name <name>` and check the `license` field before commercial use.

**Q: How many languages are supported?**
The dedicated Coqui voices cover ~20 languages; via Meta's Fairseq/MMS voices (`tts_models/<iso>/fairseq/vits`) you reach **1100+** languages.

**Q: How do I clone a voice?**
Load a cloning-capable model (XTTS v2, YourTTS, Bark) and pass `speaker_wav="reference.wav"`. For models that can't clone directly, use `tts_with_vc_to_file()`.

**Q: Where are downloaded models stored?**
Under `$TTS_HOME/tts/`, else `$XDG_DATA_HOME/tts/`, else `~/.local/share/tts/`. Delete a model's folder there to force a re-download.

**Q: How do I avoid the license prompt on a server?**
Set `COQUI_TOS_AGREED=1` in the environment before loading a gated model.

**Q: Can I run a long document through it?**
Yes — keep `split_sentences=True` (default). Coqui splits the text into sentences, synthesizes each, and concatenates them.

**Q: Is the company still around?**
No. Coqui shut down, so this codebase is frozen at v0.22.0 and community-maintained. The models and code work, but new PyTorch/`transformers` releases may need version pinning.

**Q: What's the difference between a "tts_model" and a "vocoder_model"?**
Two-stage TTS models produce a spectrogram that a separate **vocoder** turns into audio. End-to-end models (VITS, XTTS) do both in one model and need no separate vocoder. Coqui auto-selects each model's default vocoder for you.

**Q: How do I serve TTS over HTTP?**
Run `tts-server --model_name <name>` and call `GET/POST /api/tts`. Keep it behind your own auth — it has none built in.

---

## 13. Reference

### 13.1 Model name format

```text
<model_type>/<language>/<dataset>/<model_name>
# examples:
tts_models/en/ljspeech/tacotron2-DDC
tts_models/multilingual/multi-dataset/xtts_v2
vocoder_models/en/ljspeech/hifigan_v2
voice_conversion_models/multilingual/vctk/freevc24
tts_models/deu/fairseq/vits
```

### 13.2 Environment variables

| Variable | Purpose |
|---|---|
| `TTS_HOME` | Base directory for the model cache (`$TTS_HOME/tts/`). Highest priority. |
| `XDG_DATA_HOME` | Fallback cache base (`$XDG_DATA_HOME/tts/`) if `TTS_HOME` is unset. |
| `COQUI_TOS_AGREED` | Set to `1` to pre-accept the terms of service for gated models (XTTS). |

### 13.3 Console scripts

| Command | Entry point | Purpose |
|---|---|---|
| `tts` | `TTS.bin.synthesize:main` | Command-line synthesis & model browsing. |
| `tts-server` | `TTS.server.server:main` | Local Flask demo server + HTTP API. |

### 13.4 Python API surface (`from TTS.api import TTS`)

| Method | Purpose |
|---|---|
| `TTS(model_name, ...)` | Construct and load a model. |
| `.to(device)` | Move the model to CPU/GPU. |
| `.tts(text, ...)` | Synthesize; return waveform samples. |
| `.tts_to_file(text, ..., file_path=...)` | Synthesize and write a `.wav`. |
| `.voice_conversion(source_wav, target_wav)` | Convert a voice; return samples. |
| `.voice_conversion_to_file(source_wav, target_wav, file_path=...)` | Convert and write a `.wav`. |
| `.tts_with_vc(text, speaker_wav=..., ...)` | Synthesize, then convert to a target voice. |
| `.tts_with_vc_to_file(...)` | Same, written to a file. |
| `.list_models()` / `.models` | Browse the model zoo. |
| `.is_multi_speaker`, `.is_multi_lingual`, `.speakers`, `.languages` | Inspect the loaded model. |

### 13.5 Key dependencies

PyTorch (`torch>=2.1`) and `torchaudio` for the models; `librosa`, `soundfile`, `scipy`, `numpy` for audio; `transformers>=4.33.0` for XTTS/Tortoise; `gruut`, `pysbd`, `jieba`/`pypinyin` (Chinese), `jamo`/`g2pkk` (Korean), `bangla`/`bnnumerizer` (Bangla) for text processing; `flask` for the demo server; `trainer` and `coqpit` for training/config. See the Admin Guide for the complete breakdown.

---

_Generated June 2026 from coqui-ai/TTS at dbf1a08. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._