GPT-SoVITS Administrator & Developer Guide

GPT-SoVITS is a few-shot voice cloning and text-to-speech system that combines a GPT-based autoregressive model for semantic token prediction with a SoVITS (Singing Voice Intelligent TTS) model for waveform synthesis. This guide covers the full technical surface: architecture, configuration, deployment, operations, security posture, and developer internals across all model versions (v1, v2, v3, v4, v2Pro, v2ProPlus).

1. Architecture Overview

1.1 Two-Stage Inference Pipeline

GPT-SoVITS splits text-to-speech into two distinct stages, each handled by a separate neural network.

Stage 1 — GPT (Text-to-Semantic)

Text passes through language-specific phonemizers, then through BERT feature extraction, and finally into an autoregressive transformer that predicts semantic tokens one at a time.

Raw Text
  → Language Detection (LangSegmenter)
  → Text Normalization (zh_normalization for Chinese)
  → Phonemization (language-specific G2P)
  → BERT Embedding (chinese-roberta-wwm-ext-large)
  → Text2SemanticDecoder (12-24 layer transformer)
  → Semantic Token Sequence

The Text2SemanticDecoder (GPT_SoVITS/AR/models/t2s_model.py:260) is a causal transformer with these core dimensions:

Sampling parameters control generation quality: top_k (default 5 in training config, 15 at API level), top_p (default 1.0), temperature (default 1.0), and repetition_penalty (default 1.35). The EOS token (1024) terminates generation.

Note

Chinese text receives real BERT embeddings from chinese-roberta-wwm-ext-large. All other languages receive a zero tensor of matching dimensions. This asymmetry means Chinese TTS has richer prosodic information available to the GPT stage.

Stage 2 — SoVITS (Semantic-to-Audio)

Semantic tokens from Stage 1 are decoded into audio waveforms. The decoder architecture varies by model version:

The CFM (Conditional Flow Matching) module (GPT_SoVITS/module/models.py:1100) uses a DiT (Diffusion Transformer) backbone with configurable sample_steps (default 32). Higher step counts improve quality at the cost of latency.

1.2 Feature Extraction Stack

Three pretrained models provide input features:

CNHuBERT (GPT_SoVITS/feature_extractor/cnhubert.py:22)

• Chinese HuBERT model for self-supervised audio features
• Extracts SSL representations from reference audio
• Pretrained weights: GPT_SoVITS/pretrained_models/chinese-hubert-base
• Class: CNHubert — wraps HubertModel from transformers

BERT (chinese-roberta-wwm-ext-large)

• Extracts 1024-dim text embeddings for Chinese text
• Non-Chinese languages bypass BERT entirely (zero tensor substitution)
• Path: GPT_SoVITS/pretrained_models/chinese-roberta-wwm-ext-large

ERes2NetV2 (GPT_SoVITS/eres2net/ERes2NetV2.py:152)

• Speaker verification embedding network for v2Pro and v2ProPlus
• Provides speaker identity conditioning to improve multi-speaker fidelity
• Path configured via sv_path environment variable

1.3 Vocoder Details

BigVGAN (GPT_SoVITS/BigVGAN/bigvgan.py:226) — v3 only

• NVIDIA's BigVGAN v2 architecture
• Snake activation functions with anti-aliased multi-periodicity composition (AMP)
• Pretrained: models--nvidia--bigvgan_v2_24khz_100band_256x
• use_cuda_kernel=False by default — pure PyTorch fallback; set True for CUDA-optimized kernels if compiled
• Outputs 24 kHz audio, upsampled to 48 kHz via AP-BWE (tools/AP_BWE_main/)

HiFi-GAN (GPT_SoVITS/module/models.py:Generator) — v1/v2 internal + v4 vocoder

• initial_channel=100, upsample_rates=[10, 6, 2, 2, 2]
• Produces 32 kHz (v1/v2 internal) or 48 kHz (v4) output

1.4 Text Processing Pipeline

Input Text
  → LangSegmenter (GPT_SoVITS/text/LangSegmenter/)
      Auto-detects: zh, en, ja, ko, yue + mixed
  → Language Router (GPT_SoVITS/text/cleaner.py)
      Routes to: chinese.py | chinese2.py | english.py |
                 japanese.py | korean.py | cantonese.py
  → G2P (Grapheme-to-Phoneme)
      Chinese: pypinyin + G2PW polyphone disambiguation
      English: g2p_en
      Japanese: pyopenjtalk
      Korean: g2pk
  → Symbol Mapping
      v1: symbols.py (322 symbols)
      v2+: symbols2.py (732 symbols)
  → Phoneme Sequence

Chinese text normalization (GPT_SoVITS/text/zh_normalization/) handles numbers, dates, currency, percentages, telephone numbers, and other special forms before phonemization.

1.5 Component Dependency Graph

                    ┌─────────────────────┐
                    │   WebUI / API       │
                    │ (webui.py/api_v2.py)│
                    └─────────┬───────────┘
                              │
                    ┌─────────▼───────────┐
                    │     TTS Class        │
                    │ (TTS_infer_pack/     │
                    │  TTS.py:421)         │
                    └──┬──────┬────────┬──┘
                       │      │        │
            ┌──────────▼┐  ┌──▼────┐  ┌▼──────────┐
            │TextPreproc│  │  GPT  │  │  SoVITS   │
            │(TextPre-  │  │(t2s_  │  │(models.py)│
            │processor) │  │model) │  │           │
            └──────┬────┘  └───┬───┘  └─────┬─────┘
                   │           │            │
            ┌──────▼────┐  ┌───▼───┐  ┌─────▼─────┐
            │  BERT     │  │CNHuBERT│ │  Vocoder  │
            │(roberta)  │  │        │  │(BigVGAN/  │
            └───────────┘  └────────┘  │ HiFi-GAN) │
                                       └───────────┘

1.6 Audio Processing Subsystems

UVR5 — Vocal Separation (tools/uvr5/)

Three backend architectures for separating vocals from accompaniment:

Configuration YAML files live in tools/uvr5/uvr5_weights/. Model weights are loaded on demand.

ASR — Automatic Speech Recognition (tools/asr/)

Models auto-download from HuggingFace or ModelScope (Chinese mirror fallback).

Audio Slicer (tools/slicer2.py)

• VAD-based audio segmentation for preprocessing training data
• Configurable threshold, minimum length, minimum interval, hop size

AP-BWE (tools/AP_BWE_main/)

• Audio super-resolution: 24 kHz → 48 kHz
• Required for v3 output (BigVGAN produces 24 kHz natively)

2. System Requirements

2.1 Hardware

Important

GPU compute capability must match the installed PyTorch CUDA build. Common failures include FATAL error sm80 (#2766) when running sm_80 kernels on incompatible hardware, and sm370 errors (#2388) from Blackwell architecture mismatches. Verify with python -c "import torch; print(torch.cuda.get_device_capability())".

2.2 Software

2.3 Pretrained Model Downloads

All pretrained models must exist before first inference. The system does not auto-download core models.

2.4 VRAM Consumption by Version

Setting is_half=False (fp32) roughly doubles VRAM consumption. Half precision is automatically disabled on CPU.

3. Configuration Reference

3.1 Inference Configuration: GPT_SoVITS/configs/tts_infer.yaml

This is the primary runtime configuration file. It contains a custom section (active settings) and per-version defaults (v1, v2, v3, v4, v2Pro, v2ProPlus).

custom:
  device: cuda
  is_half: true
  version: v2
  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

Important

The custom section is what the runtime actually loads. Changing version-specific defaults under v1, v2, etc. has no effect unless copied into custom. The TTS_Config class (GPT_SoVITS/TTS_infer_pack/TTS.py:217) reads custom first, then falls back to the version-keyed defaults.

Complete key reference:

Default model paths per version:

3.2 GPT Training Configuration: GPT_SoVITS/configs/s1longer.yaml

train:
  seed: 1234
  epochs: 20
  batch_size: 8
  precision: "16-mixed"
  save_every_n_epoch: 1
  num_workers: 4
  accumulate_grad_batches: 1
optimizer:
  lr: 0.01
  warmup_steps: 2000
data:
  max_sec: 54
  max_ps_ratio: 15.0
  min_ps_ratio: 3.0
  pad_val: 1024     # EOS token used as padding
model:
  embedding_dim: 512
  hidden_dim: 512
  head: 16
  linear_units: 2048
  n_layer: 24
  EOS: 1024
  vocab_size: 1025
  phoneme_vocab_size: 732
inference:
  top_k: 5

Training uses PyTorch Lightning with a custom checkpoint callback (my_model_ckpt) in GPT_SoVITS/s1_train.py.

3.3 SoVITS Training Configuration: GPT_SoVITS/configs/s2.json

{
  "train": {
    "learning_rate": 0.0001,
    "batch_size": 32,
    "epochs": 100,
    "segment_size": 20480,
    "fp16_run": true,
    "log_interval": 200,
    "eval_interval": 1000,
    "seed": 1234
  },
  "data": {
    "sampling_rate": 32000,
    "filter_length": 2048,
    "hop_length": 640,
    "win_length": 2048,
    "n_speakers": 300,
    "training_files": "",
    "validation_files": ""
  },
  "model": {
    "inter_channels": 192,
    "hidden_channels": 192,
    "filter_channels": 768,
    "n_heads": 2,
    "n_layers": 6,
    "kernel_size": 3,
    "p_dropout": 0.1,
    "gin_channels": 512,
    "semantic_frame_rate": "25hz",
    "freeze_quantizer": true
  }
}

Additional configs exist for v2Pro (s2v2Pro.json) and v2ProPlus (s2v2ProPlus.json) with speaker verification integration.

3.4 Environment Variables

These are read by config.py and the data preparation scripts. They serve as the primary mechanism for configuring training runs and inference sessions.

Runtime / Inference:

Training / Data Preparation:

3.5 Port Assignments

All ports are configured in config.py via the infer_ttswebui variable (default 9872) and hardcoded defaults for other services.

3.6 Internationalization

The I18nAuto class (tools/i18n/i18n.py) loads translations from JSON files in tools/i18n/locale/:

en_US.json  es_ES.json  fr_FR.json  it_IT.json  ja_JP.json
ko_KR.json  pt_BR.json  ru_RU.json  tr_TR.json  zh_CN.json
zh_HK.json  zh_SG.json  zh_TW.json

Language auto-detection uses system locale. Override with the language environment variable.

4. Deployment & Scaling

4.1 Docker Deployment

The repository provides a Docker-based deployment path with CUDA support.

Build:

# Standard build with CUDA 12.6
bash docker_build.sh --cuda 12.6

# CUDA 12.8
bash docker_build.sh --cuda 12.8

# Lite build (smaller image, fewer optional deps)
bash docker_build.sh --cuda 12.6 --lite

The Dockerfile at the repository root uses Miniforge (conda) with Python 3.12. Flash Attention is installed from a custom PIP index for CUDA compatibility. Pretrained models are symlinked from /workspace/models/ inside the container.

Supporting scripts:

• Docker/miniforge_install.sh — Conda environment setup
• Docker/install_wrapper.sh — Dependency installation wrapper

docker-compose.yaml is available for orchestration. Mount model directories and output volumes as needed.

Note

The Docker build installs Flash Attention from a custom PIP index URL. If building behind a corporate proxy or air-gapped environment, pre-download the wheel and adjust the Dockerfile accordingly.

4.2 Bare Metal Deployment

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

# 2. Create conda environment
conda create -n gpt-sovits python=3.12
conda activate gpt-sovits

# 3. Install PyTorch with CUDA
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

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

# 5. Download pretrained models to GPT_SoVITS/pretrained_models/

# 6. Launch
python webui.py          # Full WebUI on port 9874
python api_v2.py         # API server on port 9880

Warning

Windows users: the install.ps1 script has known issues (#2757). Manual installation via pip is more reliable. ROCm GPU detection (#2743) also requires manual configuration on AMD hardware.

4.3 Scaling Considerations

Horizontal scaling is limited. The system is designed as a single-GPU inference server. For multi-request throughput:

1. Run multiple instances behind a load balancer, each on a separate GPU
2. Each instance loads its own copy of all models into VRAM
3. No shared state between instances — each is fully independent

Vertical scaling options:

• Increase batch_size in API requests (default 1, controls how many text segments are processed in parallel)
• Enable parallel_infer (default true) for parallel batch processing
• Use split_bucket=true (default) to group similar-length segments for efficient batching
• Reduce sample_steps for v3/v4 (default 32; lower = faster but lower quality)

DDP (Distributed Data Parallel) Training:

Training supports multi-GPU via PyTorch DDP. The LOCAL_RANK environment variable controls GPU assignment. Data preparation scripts support partitioning via i_part and all_parts for parallel feature extraction across GPUs.

# Multi-GPU training example
torchrun --nproc_per_node=4 GPT_SoVITS/s2_train.py

4.4 Model Hot-Swapping

The API supports runtime model switching without restart:

# API v2 — switch GPT weights
curl "http://localhost:9880/set_gpt_weights?weights_path=/path/to/model.ckpt"

# API v2 — switch SoVITS weights
curl "http://localhost:9880/set_sovits_weights?weights_path=/path/to/model.pth"

# API v1 — switch both
curl -X POST http://localhost:9880/set_model \
  -d '{"gpt_model_path": "/path/to/gpt.ckpt", "sovits_model_path": "/path/to/sovits.pth"}'

Model switching triggers full re-initialization of the respective pipeline stage. Expect 5-15 seconds of unavailability during the switch depending on model size and disk speed.

5. Operations

5.1 Data Preparation Pipeline

Training requires a four-step data preparation pipeline. Each step is a standalone script driven by environment variables.

Raw Audio + Annotations
    │
    ▼
Step 1: 1-get-text.py
    Phoneme extraction + BERT features
    Input: annotation file (wav_path|speaker|lang|text)
    Output: phoneme sequences, BERT embeddings (.pt files)
    │
    ▼
Step 2: 2-get-hubert-wav32k.py
    CNHuBERT SSL features + 32kHz resampling
    Output: HuBERT features, resampled audio
    │
    ▼
Step 2b: 2-get-sv.py (v2Pro/v2ProPlus only)
    Speaker verification embeddings
    Output: ERes2NetV2 speaker embeddings
    │
    ▼
Step 3: 3-get-semantic.py
    Semantic token extraction via VQ model
    Output: quantized semantic tokens

Annotation format (pipe-delimited):

/path/to/audio.wav|speaker_name|zh|你好世界
/path/to/audio2.wav|speaker_name|en|Hello world

Caution

All preparation scripts read configuration from environment variables, not command-line arguments. If variables like inp_text, inp_wav_dir, exp_name, and opt_dir are not set, scripts will fail silently or with cryptic errors. Always verify environment setup before launching.

Note

Data preparation supports partitioned parallel execution. Set i_part (0-indexed) and all_parts to distribute work across multiple processes or GPUs. Each partition processes a non-overlapping slice of the input data.

5.2 Training Operations

GPT (S1) Training:

python GPT_SoVITS/s1_train.py

Uses PyTorch Lightning. Checkpoints saved every epoch via custom my_model_ckpt callback. Training config loaded from GPT_SoVITS/configs/s1longer.yaml.

SoVITS (S2) Training:

# v1/v2
python GPT_SoVITS/s2_train.py

# v3/v4
python GPT_SoVITS/s2_train_v3.py

# v3/v4 LoRA fine-tuning
python GPT_SoVITS/s2_train_v3_lora.py

LoRA Fine-Tuning (v3/v4 only):

• Low-rank adaptation applied to CFM DiT layers
• Dramatically reduces VRAM requirements vs full fine-tuning
• Produces lightweight adapter weights that layer on top of pretrained models

5.3 Model Checkpoint Format

All checkpoints use Python dicts with standard keys:

GPT (S1) checkpoints (.ckpt):

{
    "weight": OrderedDict,  # model state_dict
    "config": dict,         # model configuration
    # PyTorch Lightning metadata (epoch, step, etc.)
}

SoVITS (S2) checkpoints (.pth):

{
    "weight": OrderedDict,  # model state_dict
    "config": dict,         # model configuration (JSON-compatible)
    "info": str,            # training info string
    "version": str,         # model version identifier
}

5.4 Model Export

TorchScript Export:

# v1/v2
python GPT_SoVITS/export_torch_script.py

# v3/v4
python GPT_SoVITS/export_torch_script_v3v4.py

ONNX Export:

python GPT_SoVITS/onnx_export.py

TorchScript and ONNX exports enable deployment without Python runtime dependencies, suitable for C++ inference servers or mobile deployment.

5.5 Monitoring and Health

The system has no built-in health check endpoint or monitoring. Operational visibility requires external tooling.

Key signals to monitor:

• GPU memory utilization (inference and training)
• API response latency (inference time scales with text length)
• Audio output quality (no automated quality metrics — manual spot-checking)
• Disk usage for model checkpoints and training outputs
• Process status (no automatic restart on crash)

Common failure modes:

Warning

The ASGI application exception (#2762) indicates unhandled errors in the API layer. The API server does not catch all exceptions at the top level — malformed requests or unexpected model states can crash the server process. Use a process manager (systemd, supervisor, or Docker restart policy) for automatic recovery.

5.6 Troubleshooting Reference

Tip

Reference audio must be between 3-10 seconds. Audio outside this range triggers: OSError: '参考音频在3~10秒范围外，请更换！' (Reference audio outside 3-10 second range, please change).

Tip

v3 and v4 models do not support streaming inference mode. Attempting streaming with these versions raises: RuntimeError: 'SoVits V3/4模型不支持流式推理模式'. Use v1/v2 or GPT_SoVITS/stream_v2pro.py for streaming use cases.

Complete error reference:

6. Performance

6.1 Inference Tuning Parameters

6.2 Text Splitting Methods

The text_split_method parameter controls how long texts are segmented:

6.3 Memory Optimization

• Half precision (is_half=True): Halves model memory footprint. Mandatory for 4GB GPUs.
• Model version selection: v1/v2 use significantly less VRAM than v3/v4 due to simpler decoder architecture.
• Reduce sample_steps (v3/v4): Steps below 32 trade quality for speed. 16 steps give ~2x speedup.
• LoRA training: For v3/v4 fine-tuning, LoRA (s2_train_v3_lora.py) trains only a fraction of parameters.

7. Security

7.1 API Authentication

Caution

The API server (api.py, api_v2.py) has no authentication mechanism. All endpoints are publicly accessible to any client that can reach the network port. In production, place the API behind a reverse proxy with authentication (e.g., nginx with basic auth, OAuth proxy, or API gateway).

7.2 Model Loading

All model loading uses torch.load() with weights_only=False (implicit default in older PyTorch) or pickle deserialization. This means:

• Arbitrary code execution is possible via crafted model checkpoint files
• Never load model files from untrusted sources
• The set_gpt_weights and set_sovits_weights API endpoints accept arbitrary file paths — an attacker with API access can load any .ckpt/.pth file accessible to the process

# Pattern found throughout codebase — no safety wrappers
dict_s1 = torch.load(gpt_path, map_location="cpu")
dict_s2 = torch.load(sovits_path, map_location="cpu")

Warning

Model weight files (.ckpt, .pth) are essentially pickle files. A malicious checkpoint can execute arbitrary Python code when loaded. Only use checkpoints from trusted sources. There is no integrity verification (no hash checking, no signature validation) on any model loading path.

7.3 Subprocess Execution

The system invokes ffmpeg via subprocess calls for audio I/O operations. Input filenames are passed through to shell commands. While most paths are constructed internally, API endpoints that accept file paths (ref_audio_path, model weight paths) could potentially be vectors for command injection if the underlying subprocess calls do not properly escape arguments.

7.4 File System Access

• The API accepts file paths as parameters (ref_audio_path, model paths) with no path traversal restrictions
• Training scripts write outputs to directories specified by environment variables without sandboxing
• UVR5 vocal separation writes to user-specified output directories
• No file access audit logging

7.5 Network Exposure

• Default Gradio WebUI binds to 0.0.0.0 when is_share=True
• API server binds to 0.0.0.0 by default
• No TLS — all communication is plaintext HTTP
• No rate limiting on any endpoint
• No request size limits beyond framework defaults

7.6 Security Recommendations

1. Network isolation: Run behind a reverse proxy with TLS termination and authentication
2. Model provenance: Only load checkpoints from the official repository or verified sources
3. File path restrictions: If exposing the API, sanitize all file path inputs to prevent directory traversal
4. Process isolation: Run with minimum required privileges; use a dedicated service account
5. Firewall: Restrict API port access to trusted networks only
6. Resource limits: Set VRAM and memory limits to prevent DoS via large inputs

8. Developer Internals

8.1 Core Class Hierarchy

Inference Pipeline:

GPT (Autoregressive) Stage:

SoVITS (Synthesis) Stage:

Feature Extraction:

VITS Sub-Modules:

Text Processing:

Audio Tools:

F5-TTS Backbone (GPT_SoVITS/f5_tts/):

Streaming:

8.2 Inference Call Flow

# Simplified inference flow through TTS class
tts = TTS(config)  # Loads all models into GPU memory

# 1. Text preprocessing
phones, bert_features, norm_text = tts.text_preprocessor.segment_and_extract(
    text, text_lang
)

# 2. Reference audio processing
ref_ssl = tts.cnhubert_model(ref_audio)  # SSL features
ref_semantic = tts.vq_model.extract_latent(ref_ssl)  # Semantic tokens

# 3. GPT stage — autoregressive semantic token generation
pred_semantic = tts.t2s_model.infer(
    phones, bert_features, ref_semantic,
    top_k=top_k, top_p=top_p, temperature=temperature,
    repetition_penalty=repetition_penalty
)

# 4. SoVITS stage — waveform synthesis
audio = tts.vits_model.decode(
    pred_semantic, phones, ref_audio,
    speed_factor=speed_factor
)

# 5. (v3 only) Super-resolution
if version == "v3" and super_sampling:
    audio = ap_bwe(audio)  # 24kHz → 48kHz

8.3 Adding a New Language

To add support for a new language:

1. Create GPT_SoVITS/text/{language}.py implementing:

   • g2p(text) → (phones, word2ph) — grapheme-to-phoneme conversion
   • Phone symbols added to symbols2.py

2. Register the language in GPT_SoVITS/text/cleaner.py:

   # Add to the language routing dict
   

3. Add language detection rules to GPT_SoVITS/text/LangSegmenter/

4. Create locale file tools/i18n/locale/{lang_CODE}.json for WebUI strings

5. Update phoneme_vocab_size in training configs if new symbols are added

8.4 Adding a New Model Version

Model versions are tightly integrated across the codebase. Adding a new version requires changes in:

1. GPT_SoVITS/module/models.py — New SynthesizerTrn* class
2. GPT_SoVITS/TTS_infer_pack/TTS.py — Version routing in TTS and TTS_Config
3. GPT_SoVITS/configs/tts_infer.yaml — Default weights and paths
4. GPT_SoVITS/configs/s2*.json — Training configuration
5. api_v2.py / api.py — Version-specific parameter validation
6. Data preparation scripts — If feature extraction changes
7. Export scripts — export_torch_script*.py, onnx_export.py

8.5 Code Patterns

Model Loading Pattern (universal):

dict_s2 = torch.load(sovits_path, map_location="cpu")
hps = dict_s2["config"]
weights = dict_s2["weight"]
vq_model = SynthesizerTrn(hps)
vq_model.load_state_dict(weights)
vq_model.eval().to(device)
if is_half:
    vq_model = vq_model.half()

Environment-driven script pattern (all data preparation scripts):

inp_text = os.environ.get("inp_text")
inp_wav_dir = os.environ.get("inp_wav_dir")
exp_name = os.environ.get("exp_name")
i_part = int(os.environ.get("i_part", 0))
all_parts = int(os.environ.get("all_parts", 1))
opt_dir = os.environ.get("opt_dir")

Device/precision management:

device = "cuda" if torch.cuda.is_available() else "cpu"
is_half = True
if device == "cpu":
    is_half = False  # Auto-disable half on CPU

8.6 Testing

Note

The codebase has minimal test coverage. Only BigVGAN has dedicated test files (3 test files under GPT_SoVITS/BigVGAN/). There is no test suite for the core TTS pipeline, text processing, or API endpoints. Testing is done manually via the WebUI and API.

No CONTRIBUTING.md or test documentation exists in the repository. For developers extending the system, manual integration testing through the WebUI or API is the practical validation path.

9. Integration Points

9.1 API v1 (api.py)

Four endpoint groups, each supporting both GET (query params) and POST (JSON/form body):

9.2 API v2 (api_v2.py)

Full /tts POST body schema:

{
    "text": "",
    "text_lang": "",
    "ref_audio_path": "",
    "aux_ref_audio_paths": [],
    "prompt_text": "",
    "prompt_lang": "",
    "top_k": 15,
    "top_p": 1,
    "temperature": 1,
    "text_split_method": "cut5",
    "batch_size": 1,
    "batch_threshold": 0.75,
    "split_bucket": true,
    "speed_factor": 1.0,
    "fragment_interval": 0.3,
    "seed": -1,
    "media_type": "wav",
    "streaming_mode": false,
    "parallel_infer": true,
    "repetition_penalty": 1.35,
    "sample_steps": 32,
    "super_sampling": false,
    "overlap_length": 2,
    "min_chunk_length": 16
}

Response: Audio stream in the requested media_type format. When streaming_mode=true (v1/v2 only), response is chunked transfer encoding.

9.3 WebUI Integration

The Gradio WebUI (webui.py, port 9874) provides a unified interface for:

• TTS inference with all parameter controls
• UVR5 vocal separation
• ASR transcription
• Data preparation pipeline
• GPT and SoVITS training
• Model management

9.4 Programmatic Integration

import requests

# Basic TTS request
response = requests.post("http://localhost:9880/tts", json={
    "text": "Hello, this is a test.",
    "text_lang": "en",
    "ref_audio_path": "/path/to/reference.wav",
    "prompt_text": "This is the reference text.",
    "prompt_lang": "en",
    "media_type": "wav"
})

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

# Model switching
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"})

9.5 Directory Structure Reference

GPT-SoVITS/
├── GPT_SoVITS/                    # Core TTS engine
│   ├── AR/                        # Autoregressive GPT model
│   │   └── models/
│   │       └── t2s_model.py       # Text2SemanticDecoder
│   ├── BigVGAN/                   # BigVGAN vocoder (v3)
│   │   └── bigvgan.py             # BigVGAN model
│   ├── configs/                   # Training + inference configs
│   │   ├── s1longer.yaml          # GPT training config
│   │   ├── s2.json                # SoVITS v1/v2 training config
│   │   ├── s2v2Pro.json           # SoVITS v2Pro training config
│   │   ├── s2v2ProPlus.json       # SoVITS v2ProPlus training config
│   │   └── tts_infer.yaml         # Inference config
│   ├── eres2net/                   # Speaker verification (v2Pro+)
│   │   └── ERes2NetV2.py          # ERes2NetV2 model
│   ├── f5_tts/                    # F5-TTS backbone (DiT/MMDiT/UNet-T)
│   ├── feature_extractor/         # CNHuBERT, Whisper extractors
│   │   └── cnhubert.py            # CNHubert class
│   ├── module/                    # VITS model components
│   │   ├── models.py              # SynthesizerTrn, CFM, Generator, etc.
│   │   └── quantize.py            # Vector quantization
│   ├── prepare_datasets/          # Data preparation scripts
│   │   ├── 1-get-text.py          # Phoneme + BERT extraction
│   │   ├── 2-get-hubert-wav32k.py # CNHuBERT features + resampling
│   │   ├── 2-get-sv.py            # Speaker verification (v2Pro+)
│   │   └── 3-get-semantic.py      # Semantic token extraction
│   ├── pretrained_models/         # Downloaded pretrained weights
│   ├── text/                      # Text processing per language
│   │   ├── LangSegmenter/         # Language detection
│   │   ├── g2pw/                  # G2PW polyphone disambiguation
│   │   ├── zh_normalization/      # Chinese text normalization
│   │   ├── chinese.py / chinese2.py / english.py / japanese.py
│   │   ├── korean.py / cantonese.py
│   │   ├── cleaner.py             # Language router
│   │   ├── symbols.py             # v1 phoneme set (322)
│   │   └── symbols2.py            # v2+ phoneme set (732)
│   ├── TTS_infer_pack/            # Inference pipeline
│   │   ├── TTS.py                 # TTS + TTS_Config classes
│   │   └── TextPreprocessor.py    # TextPreprocessor class
│   ├── export_torch_script.py     # TorchScript export (v1/v2)
│   ├── export_torch_script_v3v4.py # TorchScript export (v3/v4)
│   ├── inference_webui.py         # TTS inference WebUI
│   ├── inference_webui_fast.py    # Fast inference WebUI
│   ├── onnx_export.py            # ONNX export
│   ├── s1_train.py               # GPT training
│   ├── s2_train.py               # SoVITS v1/v2 training
│   ├── s2_train_v3.py            # SoVITS v3/v4 training
│   ├── s2_train_v3_lora.py       # SoVITS v3/v4 LoRA training
│   └── stream_v2pro.py           # Streaming inference (v2Pro)
├── tools/                         # Auxiliary tools
│   ├── asr/                       # ASR engines
│   │   ├── fasterwhisper_asr.py
│   │   └── funasr_asr.py
│   ├── i18n/                      # Internationalization
│   │   ├── i18n.py                # I18nAuto class
│   │   └── locale/                # 13 locale JSON files
│   ├── uvr5/                      # Vocal separation
│   │   ├── bsroformer.py
│   │   ├── mdxnet.py
│   │   ├── vr.py
│   │   └── uvr5_weights/          # Model configs
│   ├── AP_BWE_main/               # Audio super-resolution
│   └── slicer2.py                 # Audio slicer
├── Docker/                        # Docker build scripts
│   ├── miniforge_install.sh
│   └── install_wrapper.sh
├── Dockerfile                     # Container build file
├── docker-compose.yaml            # Container orchestration
├── docker_build.sh                # Build helper script
├── api.py                         # API v1 server
├── api_v2.py                      # API v2 server
├── webui.py                       # Main Gradio WebUI
├── config.py                      # Environment/port configuration
└── requirements.txt               # Python dependencies