# GPT-SoVITS User Guide

GPT-SoVITS is an open-source few-shot voice cloning and text-to-speech system. Hand it a 3--10 second audio clip of any voice along with its transcript, and it synthesizes new speech that sounds like that person. Fine-tune on about one minute of audio for even higher fidelity. The toolkit supports Chinese (Mandarin and Cantonese), English, Japanese, and Korean, with automatic language detection and cross-lingual synthesis.

Six model generations are available -- v1, v2, v3, v4, v2Pro, and v2ProPlus -- each improving audio quality, language coverage, or speaker similarity. Every generation ships with pretrained weights so you can start generating speech immediately, and every generation can be fine-tuned on your own voice data through the built-in training pipeline.

---

## 1. Quick Start

This section gets you from zero to synthesized speech in the shortest path possible. Detailed explanations follow in later sections.

**Prerequisites:** Python 3.11+, an NVIDIA GPU with CUDA 12.6 or 12.8, and `ffmpeg` installed on your PATH.

```bash
# 1. Clone the repository
git clone https://github.com/RVC-Boss/GPT-SoVITS.git
cd GPT-SoVITS

# 2. Install dependencies
pip install -r requirements.txt

# 3. Launch the main WebUI
python webui.py
```

The WebUI opens at **http://localhost:9874**. Navigate to the inference tab, load pretrained model weights, upload a 3--10 second reference clip, type the transcript of that clip, then type new text and click synthesize.

> [!TIP]
> For the fastest results without any training, use the v2 pretrained models (the default). Record yourself reading a single sentence clearly, upload it as the reference audio, and type that sentence as the reference text. Then type whatever you want synthesized in the target text box.

If you want to skip the WebUI entirely, the command-line interface works in one shot:

```bash
python GPT_SoVITS/inference_cli.py \
  --ref_audio "my_reference.wav" \
  --ref_text "Hello, this is my reference sentence." \
  --ref_language "en" \
  --target_text "This is the text I want spoken in my voice." \
  --target_language "en" \
  --output_path "output.wav"
```

---

## 2. Installation

### 2.1 System Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Python | 3.11+ | 3.11 or 3.12 |
| GPU | NVIDIA with 4 GB VRAM | NVIDIA with 8+ GB VRAM |
| CUDA | 12.6 or 12.8 | 12.8 |
| RAM | 8 GB | 16+ GB |
| Disk | 10 GB (models + code) | 20+ GB (with training data) |
| OS | Windows 10/11, Linux | Linux for production |
| Other | `ffmpeg`, `cmake` | -- |

> [!IMPORTANT]
> `ffmpeg` must be installed and available on your system PATH. On Ubuntu: `sudo apt install ffmpeg`. On Windows: download from ffmpeg.org and add the `bin` folder to PATH. Without it, audio loading and conversion will fail silently or throw errors.

> [!WARNING]
> AMD GPUs with ROCm have limited support. GPU detection issues have been reported with ROCm 7.2 on Windows (see GitHub issue #2743). If you need AMD support, Linux with ROCm 6.x is more reliable.

### 2.2 Windows Installation

The repository includes a PowerShell install script that handles dependencies and model downloads:

```powershell
# Standard CUDA 12.6 install, models from HuggingFace
.\install.ps1 -Device CU126 -Source HF

# CUDA 12.8, models from ModelScope (faster in China)
.\install.ps1 -Device CU128 -Source ModelScope

# CPU-only (no GPU acceleration)
.\install.ps1 -Device CPU -Source HF
```

| Parameter | Values | Default |
|-----------|--------|---------|
| `-Device` | `CU126`, `CU128`, `CPU` | -- |
| `-Source` | `HF`, `HF-Mirror`, `ModelScope` | -- |

> [!WARNING]
> If `install.ps1` fails to execute, check your PowerShell execution policy: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`. Some users have reported the script not working on certain Windows configurations (#2757) -- in that case, fall back to the manual pip install method below.

### 2.3 Linux Installation

```bash
git clone https://github.com/RVC-Boss/GPT-SoVITS.git
cd GPT-SoVITS
bash install.sh
```

Or install manually:

```bash
pip install -r requirements.txt
```

### 2.4 Docker Installation

```bash
# Build with CUDA 12.6
bash docker_build.sh --cuda 12.6

# Build with CUDA 12.8
bash docker_build.sh --cuda 12.8

# Lite build (smaller image, inference only)
bash docker_build.sh --cuda 12.6 --lite
```

A `docker-compose.yaml` is included for orchestrated deployment:

```bash
docker compose up -d
```

### 2.5 Manual Dependency Installation

If the automated scripts fail, install manually:

```bash
pip install -r requirements.txt
```

Ensure `cmake` is available (needed to build some native extensions):

```bash
# Ubuntu/Debian
sudo apt install cmake

# Windows (via winget)
winget install cmake
```

### 2.6 Pretrained Models

Pretrained models must be placed in `GPT_SoVITS/pretrained_models/`. The install scripts download them automatically. If you need to download manually:

| Version | GPT Weights | SoVITS Weights |
|---------|-------------|----------------|
| v1 | `s1bert25hz-2kh-longer-epoch=68e-step=50232.ckpt` | `s2G488k.pth` |
| v2 (default) | `gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt` | `gsv-v2final-pretrained/s2G2333k.pth` |
| v3 | `s1v3.ckpt` | `s2Gv3.pth` |
| v4 | `s1v3.ckpt` | `gsv-v4-pretrained/s2Gv4.pth` |
| v2Pro | `s1v3.ckpt` | `v2Pro/s2Gv2Pro.pth` |
| v2ProPlus | `s1v3.ckpt` | `v2Pro/s2Gv2ProPlus.pth` |

Download from HuggingFace or ModelScope and place them in the appropriate subdirectories under `GPT_SoVITS/pretrained_models/`.

Additionally, the G2PW phoneme model (used for Chinese G2P) belongs in `GPT_SoVITS/text/G2PWModel/`.

---

## 3. Configuration

### 3.1 Inference Configuration File

The primary configuration file for inference is:

```
GPT_SoVITS/configs/tts_infer.yaml
```

This YAML file controls which model weights to load, device placement, and precision. Each model version has its own section. Key settings:

```yaml
# Example structure (per version)
device: cuda        # "cuda" or "cpu"
is_half: true       # Half precision (FP16) — faster, less VRAM
version: v2         # v1, v2, v3, v4, v2Pro, v2ProPlus
t2s_weights_path: GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt
vits_weights_path: GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s2G2333k.pth
bert_base_path: GPT_SoVITS/pretrained_models/chinese-roberta-wwm-ext-large
cnhuhbert_base_path: GPT_SoVITS/pretrained_models/chinese-hubert-base
```

### 3.2 Environment Variables

These environment variables control global behavior (set them before launching):

| Variable | Default | Description |
|----------|---------|-------------|
| `is_half` | `True` | Use FP16 half precision. Set to `False` on CPUs or GPUs without FP16 support. |
| `is_share` | `False` | Create a public Gradio share link for the WebUI. |
| `language` | `Auto` | UI language. Auto-detects from locale. |

### 3.3 Port Configuration

All ports are configured in `GPT_SoVITS/config.py`:

| Service | Port | Purpose |
|---------|------|---------|
| Main WebUI | 9874 | Training + inference Gradio interface |
| UVR5 WebUI | 9873 | Vocal separation tool |
| Inference TTS WebUI | 9872 | Standalone inference tab |
| Subtitle Fix WebUI | 9871 | Subtitle correction tool |
| API (v1 and v2) | 9880 | HTTP API for programmatic TTS |

### 3.4 Precision and Device Settings

Half precision (FP16) is the default and runs faster with less VRAM. If you encounter NaN outputs or distorted audio on older GPUs, disable it:

```bash
# Via environment variable
export is_half=False
python webui.py
```

Or edit `tts_infer.yaml` and set `is_half: false`.

### 3.5 UI Language

The interface supports 13 locales: `en_US`, `zh_CN`, `zh_TW`, `ja_JP`, `ko_KR`, and more. The default is auto-detected from your system locale. To force a specific language, set the `language` environment variable:

```bash
export language=en_US
python webui.py
```

---

## 4. Core Usage

### 4.1 The Main WebUI

Launch with:

```bash
python webui.py
```

This opens the full Gradio interface at **http://localhost:9874** with tabs for both training and inference. The WebUI is the recommended way to interact with GPT-SoVITS for most users.

> [!NOTE]
> The WebUI is a Gradio application. It works in any modern browser. If you set `is_share=True`, Gradio generates a public URL you can share with others temporarily.

### 4.2 Inference GUI (Desktop)

For a dedicated inference-only experience, GPT-SoVITS includes a Qt-based desktop GUI:

```bash
python GPT_SoVITS/inference_gui.py
```

This is a standalone window application that focuses purely on text-to-speech synthesis without the training features.

### 4.3 Inference CLI

For scripting and automation, use the command-line interface:

```bash
python GPT_SoVITS/inference_cli.py \
  --gpt_model "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt" \
  --sovits_model "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s2G2333k.pth" \
  --ref_audio "reference.wav" \
  --ref_text "This is the reference transcript." \
  --ref_language "en" \
  --target_text "Generate this new sentence in the cloned voice." \
  --target_language "en" \
  --output_path "output.wav"
```

| Flag | Description |
|------|-------------|
| `--gpt_model` | Path to GPT weights file |
| `--sovits_model` | Path to SoVITS weights file |
| `--ref_audio` | Path to reference audio (3--10 seconds) |
| `--ref_text` | Transcript of the reference audio |
| `--ref_language` | Language of the reference text |
| `--target_text` | Text to synthesize |
| `--target_language` | Language of the target text |
| `--output_path` | Where to save the output WAV |

### 4.4 API v2 (Recommended)

API v2 is the recommended programmatic interface. It reads its initial configuration from `GPT_SoVITS/configs/tts_infer.yaml`, so you can pre-configure model paths rather than passing them on every request.

**Start the API server:**

```bash
python api_v2.py
# Default: binds to 127.0.0.1:9880
```

```bash
# Custom bind address and port
python api_v2.py -a 0.0.0.0 -p 8080

# Custom config file
python api_v2.py -c my_custom_config.yaml
```

| Flag | Default | Description |
|------|---------|-------------|
| `-c` | `GPT_SoVITS/configs/tts_infer.yaml` | Config file path |
| `-a` | `127.0.0.1` | Bind address |
| `-p` | `9880` | Port |

> [!TIP]
> API v2 binds to `127.0.0.1` by default (localhost only). To expose it on your network, use `-a 0.0.0.0`. API v1 binds to `0.0.0.0` by default -- be aware of this security difference.

**Endpoints:**

| Method | Path | Purpose |
|--------|------|---------|
| GET/POST | `/tts` | Synthesize speech |
| GET | `/set_refer_audio` | Change the default reference audio |
| GET | `/set_gpt_weights` | Switch GPT model weights |
| GET | `/set_sovits_weights` | Switch SoVITS model weights |
| GET | `/control` | Restart or exit the server |

**TTS request (POST):**

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test of voice cloning.",
    "text_lang": "en",
    "ref_audio_path": "/path/to/reference.wav",
    "prompt_text": "This is the reference transcript.",
    "prompt_lang": "en",
    "media_type": "wav"
  }' \
  --output output.wav
```

**TTS request (GET):**

```bash
curl "http://localhost:9880/tts?text=Hello+world&text_lang=en&ref_audio_path=/path/to/ref.wav&prompt_text=Reference+transcript&prompt_lang=en" \
  --output output.wav
```

**Full parameter reference:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | string | *required* | Text to synthesize |
| `text_lang` | string | *required* | Language of target text |
| `ref_audio_path` | string | *required* | Path to reference audio file |
| `prompt_text` | string | optional | Transcript of reference audio |
| `prompt_lang` | string | *required* | Language of reference text |
| `aux_ref_audio_paths` | list | optional | Additional reference audio paths for multi-ref |
| `top_k` | int | 15 | Top-k sampling |
| `top_p` | float | 1.0 | Nucleus sampling |
| `temperature` | float | 1.0 | Sampling temperature |
| `text_split_method` | string | `"cut5"` | How to split long text |
| `batch_size` | int | 1 | Inference batch size |
| `batch_threshold` | float | 0.75 | Batch packing threshold |
| `split_bucket` | bool | true | Bucket-sort by length for batching |
| `speed_factor` | float | 1.0 | Playback speed multiplier |
| `fragment_interval` | float | 0.3 | Silence gap between fragments (seconds) |
| `seed` | int | -1 | Random seed (-1 = random) |
| `media_type` | string | `"wav"` | Output format: `wav`, `ogg`, `aac` |
| `streaming_mode` | int/bool | false | `0`/`false`=disabled, `1`/`true`=best quality, `2`=medium, `3`=fast |
| `parallel_infer` | bool | true | Enable parallel inference |
| `repetition_penalty` | float | 1.35 | Repetition penalty for GPT |
| `sample_steps` | int | 32 (v3) / 8 (v4) | Diffusion/flow matching steps |
| `super_sampling` | bool | false | Audio super-resolution (v3: 24kHz to 48kHz) |
| `overlap_length` | int | 2 | Cross-fade overlap for chunks |
| `min_chunk_length` | int | 16 | Minimum chunk length |

> [!NOTE]
> The `prompt_text` parameter is **required** for v3 models. Omitting it triggers an error. For v1/v2/v4, it is optional but recommended for better quality.

**Switching models at runtime:**

```bash
# Switch GPT weights
curl "http://localhost:9880/set_gpt_weights?weights_path=/path/to/new_gpt.ckpt"

# Switch SoVITS weights
curl "http://localhost:9880/set_sovits_weights?weights_path=/path/to/new_sovits.pth"

# Set new reference audio
curl "http://localhost:9880/set_refer_audio?refer_audio_path=/path/to/new_ref.wav"
```

### 4.5 API v1 (Legacy)

API v1 is the older interface, still functional but API v2 is preferred for new projects.

```bash
python api.py \
  -g "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt" \
  -s "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s2G2333k.pth" \
  -dr "reference.wav" \
  -dt "This is the reference transcript." \
  -dl "en"
```

| Flag | Default | Description |
|------|---------|-------------|
| `-s` | -- | SoVITS model path |
| `-g` | -- | GPT model path |
| `-dr` | -- | Default reference audio path |
| `-dt` | -- | Default reference text |
| `-dl` | -- | Default reference language |
| `-d` | -- | Device (cuda/cpu) |
| `-a` | `0.0.0.0` | Bind address |
| `-p` | `9880` | Port |
| `-fp` | -- | Full precision (FP32) |
| `-hp` | -- | Half precision (FP16) |
| `-sm` | -- | Stream mode: `close`, `normal`, `keepalive` |
| `-mt` | -- | Media type: `wav`, `ogg`, `aac` |
| `-st` | -- | Sub type: `int16`, `int32` |
| `-cp` | -- | Cut punctuation |
| `-hb` | -- | HuBERT model path |
| `-b` | -- | BERT model path |

**Endpoints:**

| Method | Path | Purpose |
|--------|------|---------|
| POST/GET | `/` | Synthesize speech |
| POST/GET | `/set_model` | Change GPT + SoVITS models |
| POST/GET | `/change_refer` | Change default reference audio |
| POST/GET | `/control` | `restart` or `exit` the server |

**Example TTS request:**

```bash
curl -X POST "http://localhost:9880/" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is synthesized speech.",
    "text_language": "en"
  }' \
  --output output.wav
```

### 4.6 Language Codes

| Code | Language | Available In |
|------|----------|-------------|
| `auto` | Automatic detection | All versions |
| `auto_yue` | Auto-detect with Cantonese priority | v2+ |
| `en` | English | All versions |
| `zh` | Chinese (Mandarin) | All versions |
| `ja` | Japanese | All versions |
| `yue` | Cantonese | v2+ |
| `ko` | Korean | v2+ |
| `all_zh` | Force all-Chinese mode | All versions |
| `all_ja` | Force all-Japanese mode | All versions |
| `all_yue` | Force all-Cantonese mode | v2+ |
| `all_ko` | Force all-Korean mode | v2+ |

> [!TIP]
> Use `auto` for mixed-language text. The system detects language boundaries automatically and applies the appropriate G2P (grapheme-to-phoneme) processing per segment. Use `all_*` codes only when you know the entire input is a single language -- this disables detection and can produce cleaner phoneme sequences.

### 4.7 Streaming Modes

Streaming delivers audio chunks as they are generated rather than waiting for the full output. This reduces time-to-first-audio for long texts.

**API v2 streaming modes:**

| Value | Quality | Latency | Description |
|-------|---------|---------|-------------|
| `0` / `false` | Best | Highest | No streaming; returns complete audio |
| `1` / `true` | Best | Medium | Streaming with best audio quality |
| `2` | Good | Lower | Medium quality streaming |
| `3` | Acceptable | Lowest | Fastest streaming, lower quality |

**API v1 streaming modes (via `-sm` flag or request param):**

| Value | Description |
|-------|-------------|
| `close` / `c` | No streaming (returns full audio in one response) |
| `normal` / `n` | Standard streaming (chunks delivered as generated) |
| `keepalive` / `k` | Persistent connection streaming |

> [!CAUTION]
> SoVITS v3 and v4 models do **not** support streaming inference. Attempting to use streaming with v3/v4 raises a RuntimeError. Use v1, v2, v2Pro, or v2ProPlus if you need streaming.

---

## 5. Common Tasks

### 5.1 Zero-Shot Voice Cloning (No Training)

The simplest workflow: clone a voice using only a short reference clip.

1. Prepare a clean audio clip of the target voice, **3 to 10 seconds** long.
2. Transcribe the clip exactly.
3. Choose your interface (WebUI, CLI, or API) and synthesize.

**Via CLI:**

```bash
python GPT_SoVITS/inference_cli.py \
  --ref_audio "speaker_sample.wav" \
  --ref_text "Good morning, welcome to our presentation." \
  --ref_language "en" \
  --target_text "Thank you for joining us today. We have exciting news to share." \
  --target_language "en" \
  --output_path "cloned_output.wav"
```

**Via API v2:**

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thank you for joining us today.",
    "text_lang": "en",
    "ref_audio_path": "speaker_sample.wav",
    "prompt_text": "Good morning, welcome to our presentation.",
    "prompt_lang": "en"
  }' \
  --output cloned_output.wav
```

> [!TIP]
> For best zero-shot results: use a clean recording with no background noise, speak naturally at a moderate pace, and ensure the reference clip is between 5 and 10 seconds. Clips shorter than 3 seconds or longer than 10 seconds are rejected by the system.

### 5.2 Fine-Tuning a Voice (Few-Shot Training)

For higher-quality voice cloning, fine-tune on approximately one minute of target voice audio. The full training pipeline runs through the WebUI at **http://localhost:9874**.

**Step 1: Prepare Audio Data**

Collect clean recordings of the target speaker. For best results:
- Record in a quiet environment
- Use consistent microphone placement
- Aim for 1--5 minutes of clear speech

**Step 2: Slice Audio**

Use the built-in audio slicer to split long recordings into manageable segments:

```bash
python tools/slice_audio.py --input raw_audio/ --output sliced_audio/
```

Or use the slicer tab in the WebUI.

**Step 3: Vocal Separation (Optional)**

If your recordings have background music or noise, separate vocals using UVR5:

```bash
python tools/uvr5/webui.py
```

This launches the UVR5 interface at **http://localhost:9873**. It supports BS-RoFormer, MDXNet, and VR separation models.

**Step 4: ASR Annotation**

Generate transcripts automatically:

```bash
# Using Faster Whisper (multilingual)
python tools/asr/fasterwhisper_asr.py --input sliced_audio/ --output annotations/

# Using FunASR (Chinese/Cantonese)
python tools/asr/funasr_asr.py --input sliced_audio/ --output annotations/
```

**Step 5: Review and Fix Annotations**

Launch the subtitle fix tool to manually correct ASR errors:

```bash
python tools/subfix_webui.py
```

This opens at **http://localhost:9871**. Accurate transcripts directly improve synthesis quality.

**Step 6: Run Training Pipeline via WebUI**

In the WebUI training tab, the pipeline runs these stages in sequence:

1. **Text extraction** (`1-get-text.py`) -- extracts phoneme sequences
2. **HuBERT feature extraction** (`2-get-hubert-wav32k.py`) -- extracts acoustic features
3. **Speaker verification extraction** (`2-get-sv.py`) -- only for v2Pro/v2ProPlus models
4. **Semantic token extraction** (`3-get-semantic.py`) -- converts to semantic tokens
5. **GPT training** (`s1_train.py`) -- trains the autoregressive model
6. **SoVITS training** (`s2_train.py` for v1/v2, `s2_train_v3.py` for v3/v4, or `s2_train_v3_lora.py` for LoRA)

After training completes, your custom weights are saved and can be loaded for inference.

### 5.3 Cross-Lingual Synthesis

GPT-SoVITS supports synthesizing speech in a different language from the reference audio. For example, clone a Chinese speaker and have them speak English:

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This English text will be spoken in a Chinese voice.",
    "text_lang": "en",
    "ref_audio_path": "chinese_speaker.wav",
    "prompt_text": "这是中文参考文本。",
    "prompt_lang": "zh"
  }' \
  --output cross_lingual.wav
```

### 5.4 Batch Processing Long Text

For long documents, configure text splitting and batch processing:

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Very long text goes here... multiple paragraphs...",
    "text_lang": "en",
    "ref_audio_path": "reference.wav",
    "prompt_text": "Reference transcript.",
    "prompt_lang": "en",
    "text_split_method": "cut5",
    "batch_size": 4,
    "parallel_infer": true,
    "split_bucket": true
  }' \
  --output long_output.wav
```

The `text_split_method` parameter controls how text is chunked. `"cut5"` is the default and works well for most cases.

### 5.5 Adjusting Speech Speed

Control playback speed with the `speed_factor` parameter:

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This will be spoken at 1.2x speed.",
    "text_lang": "en",
    "ref_audio_path": "reference.wav",
    "prompt_text": "Reference.",
    "prompt_lang": "en",
    "speed_factor": 1.2
  }' \
  --output fast_speech.wav
```

Values above 1.0 speed up; below 1.0 slow down.

### 5.6 Using Multiple Reference Audios

For better voice capture, pass additional reference clips via `aux_ref_audio_paths`:

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Synthesized with multiple references.",
    "text_lang": "en",
    "ref_audio_path": "ref1.wav",
    "aux_ref_audio_paths": ["ref2.wav", "ref3.wav"],
    "prompt_text": "Primary reference transcript.",
    "prompt_lang": "en"
  }' \
  --output multi_ref.wav
```

### 5.7 Audio Super-Resolution (v3)

SoVITS v3 outputs at 24 kHz natively. Enable super-resolution to upsample to 48 kHz:

```bash
curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "High quality v3 output.",
    "text_lang": "en",
    "ref_audio_path": "reference.wav",
    "prompt_text": "Reference transcript.",
    "prompt_lang": "en",
    "super_sampling": true
  }' \
  --output hd_output.wav
```

The super-resolution uses the AP-BWE model (`tools/audio_sr.py`) internally. This is only relevant for v3 -- v4 outputs at 48 kHz natively, and v1/v2 output at 32 kHz.

### 5.8 Denoising Audio

Clean up noisy recordings before using them as training data or references:

```bash
python tools/cmd-denoise.py --input noisy.wav --output clean.wav
```

### 5.9 Controlling Randomness and Reproducibility

For reproducible outputs, set a fixed seed:

```json
{
  "text": "Reproducible output.",
  "text_lang": "en",
  "ref_audio_path": "reference.wav",
  "prompt_text": "Reference.",
  "prompt_lang": "en",
  "seed": 42,
  "temperature": 0.8,
  "top_k": 10,
  "top_p": 0.9
}
```

Lower `temperature` produces more deterministic (but potentially flatter) speech. Higher values add variation. The `repetition_penalty` (default 1.35) discourages the GPT model from repeating tokens.

### 5.10 Choosing the Right Model Version

| Version | Output Sample Rate | Best For | Streaming | Notes |
|---------|-------------------|----------|-----------|-------|
| v1 | 32 kHz | Legacy compatibility | Yes | Fewer languages, original model |
| v2 | 32 kHz | General use (default) | Yes | Best balance of quality and speed |
| v3 | 24 kHz (48 kHz with SR) | Highest fidelity | **No** | Uses BigVGAN vocoder + CFM |
| v4 | 48 kHz | High fidelity + speed | **No** | Uses HiFi-GAN vocoder |
| v2Pro | 32 kHz | Speaker similarity | Yes | Adds speaker verification embeddings |
| v2ProPlus | 32 kHz | Best speaker similarity | Yes | Enhanced v2Pro |

> [!IMPORTANT]
> v3 and v4 do not support streaming inference. If your application requires real-time audio delivery, use v2, v2Pro, or v2ProPlus.

### 5.11 Controlling v3/v4 Quality with Sample Steps

The `sample_steps` parameter controls generation quality vs. speed for v3 and v4:

**v3 options:** 4, 8, 16, 32, 64, 128 (default: 32)
**v4 options:** 4, 8, 16, 32 (default: 8)

Higher values produce better audio but take longer. Halving the steps roughly halves generation time.

```json
{
  "text": "Quick draft.",
  "text_lang": "en",
  "ref_audio_path": "ref.wav",
  "prompt_text": "Reference.",
  "prompt_lang": "en",
  "sample_steps": 8
}
```

### 5.12 Using the UVR5 Vocal Separator

The UVR5 tool removes instrumentals from music or separates vocals from background noise:

```bash
python tools/uvr5/webui.py
```

Opens at **http://localhost:9873**. Supported model architectures:

- **BS-RoFormer** -- state-of-the-art separation quality
- **MDXNet** -- good quality, faster
- **VR** -- legacy, widest model variety

Upload your audio, select the model, and download the separated vocal track to use as training data.

### 5.13 Python Integration

Use the API programmatically from Python:

```python
import requests

response = requests.post("http://localhost:9880/tts", json={
    "text": "Hello from Python!",
    "text_lang": "en",
    "ref_audio_path": "/absolute/path/to/reference.wav",
    "prompt_text": "This is the reference transcript.",
    "prompt_lang": "en",
    "media_type": "wav"
})

with open("output.wav", "wb") as f:
    f.write(response.content)

print(f"Generated {len(response.content)} bytes of audio")
```

### 5.14 Switching Models at Runtime

You can switch between different voice models without restarting the API server:

```python
import requests

# Switch to a custom fine-tuned model
requests.get("http://localhost:9880/set_gpt_weights", params={
    "weights_path": "/path/to/custom_gpt.ckpt"
})
requests.get("http://localhost:9880/set_sovits_weights", params={
    "weights_path": "/path/to/custom_sovits.pth"
})

# Now all TTS requests use the new model
response = requests.post("http://localhost:9880/tts", json={
    "text": "Speaking with the new voice model.",
    "text_lang": "en",
    "ref_audio_path": "new_ref.wav",
    "prompt_text": "New reference.",
    "prompt_lang": "en"
})
```

---

## 6. Troubleshooting

### 6.1 Reference Audio Rejected

**Error:** `参考音频在3~10秒范围外，请更换！` (Reference audio outside 3-10 second range)

The reference audio must be between 3 and 10 seconds long. Trim your clip:

```bash
ffmpeg -i long_reference.wav -ss 0 -t 8 trimmed_reference.wav
```

### 6.2 Empty Reference Audio Path

**Error:** `ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio()`

You must either:
- Pass `ref_audio_path` in every TTS request, **or**
- Set a default reference using the `/set_refer_audio` endpoint before making requests

### 6.3 Empty or Invalid Text

**Error:** `请输入有效文本` (Please enter valid text)

The `text` parameter cannot be empty or whitespace-only. Ensure you are sending actual text content.

### 6.4 Streaming with v3/v4 Models

**Error:** `SoVits V3/4模型不支持流式推理模式` (SoVITS V3/4 models do not support streaming inference)

v3 and v4 use different vocoders (BigVGAN and HiFi-GAN respectively) that are not compatible with streaming. Set `streaming_mode` to `0` or `false`, or switch to a v1/v2/v2Pro model.

### 6.5 `use_libuv` RuntimeError

**Error:** `RuntimeError: use_libuv was requested but PyTorch was build without libuv support`

Reported in issues #1982 and #1357. This is a PyTorch build configuration issue. Solutions:

1. Set the environment variable before launching:
   ```bash
   export USE_LIBUV=0
   python webui.py
   ```
2. Or reinstall PyTorch from a build that includes libuv support.

### 6.6 CUDA sm80/sm370 FATAL Errors

**Error:** FATAL error mentioning `sm80` and `sm370` during inference.

Reported in issues #2766 and #2388. This usually means a CUDA architecture mismatch between your GPU and the installed PyTorch build. Solutions:

1. Verify your GPU's compute capability matches the installed CUDA toolkit.
2. Reinstall PyTorch with the correct CUDA version for your GPU.
3. On older GPUs, try disabling half precision: `export is_half=False`.

### 6.7 ASGI Application Exception

**Error:** `Exception in ASGI application`

Reported in issue #2762. Common causes:

1. Model weights not found at the configured path -- verify paths in `tts_infer.yaml`.
2. Insufficient GPU memory -- reduce `batch_size` or switch to CPU.
3. Corrupted model files -- re-download pretrained weights.

> [!WARNING]
> If the ASGI error occurs immediately on startup, check that all model files referenced in your config actually exist. Missing weights files are the most common cause.

### 6.8 `install.ps1` Not Working

Reported in issue #2757. The PowerShell install script may fail due to:

1. Execution policy restrictions -- run `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` first.
2. Network issues downloading models -- try `-Source HF-Mirror` or `-Source ModelScope`.
3. Fall back to manual installation: `pip install -r requirements.txt` and download models manually.

### 6.9 GPU Not Detected (ROCm)

Reported in issue #2743. AMD GPU with ROCm 7.2 on Windows may not be detected. This is a known limitation. Workarounds:

1. Use Linux with ROCm 6.x instead.
2. Fall back to CPU mode: `export is_half=False` and set `device: cpu` in `tts_infer.yaml`.

### 6.10 PermissionError: Permission Denied

Reported in issue #2729. Common causes:

1. Model files are read-only or owned by a different user.
2. Output directory does not exist or is not writable.
3. On Windows, another process has the file open.

Fix: ensure write permissions on the output directory and that no other process is locking model files.

> [!CAUTION]
> On Windows, if the WebUI crashes mid-inference, it may leave lock files on temporary audio. Restart the application and ensure the `TEMP` directory is writable.

### 6.11 Out of GPU Memory (OOM)

If inference or training runs out of VRAM:

1. Reduce `batch_size` to 1.
2. Enable half precision (`is_half: true`).
3. Use a smaller model version (v1/v2 instead of v3/v4).
4. Close other GPU-consuming applications.
5. For training, reduce the training batch size in the WebUI.

### 6.12 Deprecated Dependencies

Reported in issue #2761. Some dependencies may emit deprecation warnings or fail outright. Keep your environment up to date:

```bash
pip install -r requirements.txt --upgrade
```

If specific packages conflict, create a fresh virtual environment:

```bash
python -m venv venv
source venv/bin/activate  # Linux
# or: .\venv\Scripts\activate  # Windows
pip install -r requirements.txt
```

---

## 7. FAQ

**Q: What is the minimum audio needed for voice cloning?**
A: For zero-shot cloning (no training), you need a single 3--10 second clip plus its transcript. For fine-tuning, approximately 1 minute of clean audio produces noticeably better results. More data (up to 5 minutes) continues to improve quality with diminishing returns.

**Q: Which model version should I use?**
A: Start with **v2** (the default). It offers the best balance of quality, speed, and feature support including streaming. Move to v3 or v4 if you need the highest audio fidelity and don't need streaming. Use v2Pro or v2ProPlus if speaker similarity is your top priority.

**Q: Can I mix languages in a single synthesis request?**
A: Yes. Set `text_lang` to `auto` and write mixed-language text. The system detects language boundaries and applies appropriate phoneme processing per segment. For example: `"Hello, 你好, こんにちは"` with `text_lang: "auto"`.

**Q: What audio formats are supported for reference clips?**
A: WAV is the most reliable. The system uses `ffmpeg` internally, so any format `ffmpeg` can decode will work (MP3, FLAC, OGG, etc.). The output format is controlled by the `media_type` parameter: `wav`, `ogg`, or `aac`.

**Q: Can I run GPT-SoVITS on CPU only?**
A: Yes, but it will be significantly slower. Set `device: cpu` in `tts_infer.yaml` and `is_half: false` (CPU does not support FP16). Use the `-Device CPU` flag with the Windows install script.

**Q: How do I use a fine-tuned model with the API?**
A: Either update the model paths in `GPT_SoVITS/configs/tts_infer.yaml` before starting the server, or switch models at runtime using the `/set_gpt_weights` and `/set_sovits_weights` endpoints.

**Q: Why does my output sound robotic or distorted?**
A: Common causes: (1) reference audio is too short or too noisy, (2) reference transcript is inaccurate, (3) half precision issues on older GPUs (try `is_half: false`), (4) mismatched model versions (e.g., loading v1 weights with v2 config).

**Q: What sample rate does the output use?**
A: v1 and v2/v2Pro/v2ProPlus output at 32 kHz. v3 outputs at 24 kHz (48 kHz with `super_sampling: true`). v4 outputs at 48 kHz natively.

**Q: How do I expose the API to other machines?**
A: API v2 binds to `127.0.0.1` by default (localhost only). Start with `-a 0.0.0.0` to listen on all interfaces. API v1 already binds to `0.0.0.0` by default. Remember to configure your firewall accordingly.

**Q: Can I run multiple model versions simultaneously?**
A: Not in a single server instance. Each API server process loads one GPT model and one SoVITS model at a time. To serve multiple versions, run multiple server instances on different ports.

**Q: What is the `prompt_text` parameter?**
A: It is the transcript of your reference audio clip. It helps the model understand what is being said in the reference, improving voice matching and prosody. It is optional for v1/v2 but **required** for v3.

**Q: How do I handle very long text?**
A: The system automatically splits long text into chunks based on `text_split_method`. Increase `batch_size` and enable `parallel_infer` for faster processing. The `split_bucket` option groups similar-length chunks for more efficient batching.

**Q: Is there a maximum text length?**
A: There is no hard-coded maximum, but extremely long texts will consume more memory and time. The text splitting mechanism handles arbitrarily long inputs by chunking them before inference.

**Q: Can I use GPT-SoVITS commercially?**
A: Check the repository's license file. Voice cloning technology carries ethical and legal considerations -- always ensure you have permission to clone a specific person's voice and comply with local regulations.

**Q: What is the difference between API v1 and API v2?**
A: API v2 is config-driven (reads from `tts_infer.yaml`), binds to localhost by default (safer), has a cleaner parameter interface, and is the actively maintained version. API v1 is CLI-driven (all options via flags), binds to `0.0.0.0` by default, and is considered legacy.

**Q: How do I improve speaker similarity?**
A: (1) Use v2Pro or v2ProPlus which include speaker verification embeddings. (2) Provide multiple reference audios via `aux_ref_audio_paths`. (3) Ensure reference audio is clean and representative of the target voice. (4) Fine-tune on more data from the target speaker.

For architecture details, deployment configuration, security considerations, and internal pipeline documentation, see the **Admin Guide**.

---

_Generated May 2026 from RVC-Boss/GPT-SoVITS at 02425ea. 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._