vTTS - Universal TTS/STT Serving System

목표

지원 모델

TTS (Text-to-Speech)

Chatterbox 모델 종류 (Resemble AI)

KaniTTS 스피커 (NineNineSix)

Qwen3-TTS 모델 종류

STT (Speech-to-Text)

빠른 시작

로컬 설치 (uv 권장 - 빠르고 정확함!)

# uv 설치 (한 번만)
pip install uv
# 또는: curl -LsSf https://astral.sh/uv/install.sh | sh

옵션 1: Supertonic만 (가장 가볍고 빠름)

# GPU 자동 지원 (uv 사용!)
uv pip install "vtts[supertonic] @ git+https://github.com/bellkjtt/vTTS.git" --system
# 서버 실행
vtts serve Supertone/supertonic-2 --device cuda

옵션 2: Supertonic + GPT-SoVITS (호환 보장!)

# 1. 통합 설치 (uv 사용!)
uv pip install "vtts[supertonic-gptsovits] @ git+https://github.com/bellkjtt/vTTS.git" --system
# 2. GPT-SoVITS 저장소 자동 클론
vtts setup --engine gptsovits
# 3. 서버 실행 (각각 다른 포트)
vtts serve Supertone/supertonic-2 --port 8001 --device cuda
vtts serve kevinwang676/GPT-SoVITS-v3 --port 8002 --device cuda

옵션 3: CosyVoice만 (2줄!)

# 1. vTTS + CosyVoice 의존성 설치 (CosyVoice 코드 내장!)
pip install "vtts[cosyvoice] @ git+https://github.com/bellkjtt/vTTS.git"
# 2. 서버 실행 (모델 자동 다운로드!)
vtts serve FunAudioLLM/CosyVoice2-0.5B --device cuda --port 8001

옵션 4: Qwen3-TTS (고품질 TTS)

# 1. vTTS + Qwen3-TTS 설치
pip install "vtts[qwen3tts] @ git+https://github.com/bellkjtt/vTTS.git"
# 2. CustomVoice (프리셋 스피커, 참조 오디오 불필요)
vtts serve Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --device cuda --port 8001
# 3. Base (Voice Clone, 참조 오디오 필요)
vtts serve Qwen/Qwen3-TTS-12Hz-0.6B-Base --device cuda --port 8001

옵션 5: Chatterbox (23개 언어)

# 1. vTTS + Chatterbox 설치
pip install "vtts[chatterbox] @ git+https://github.com/bellkjtt/vTTS.git"
# 2. English
vtts serve ResembleAI/chatterbox --device cuda --port 8001
# 3. Multilingual (한국어 포함 23개 언어)
vtts serve ResembleAI/chatterbox-multilingual --device cuda --port 8001

옵션 6: KaniTTS (초고속, 6개 언어)

# 별도 Python 3.11 환경 필요!
conda create -n kanitts python=3.11 -y
conda activate kanitts
# KaniTTS 설치 (nemo-toolkit 포함)
pip install kani-tts torch>=2.6.0 --index-url https://pypi.org/simple/
# vTTS 설치
pip install "vtts[kanitts] @ git+https://github.com/bellkjtt/vTTS.git"
# 서버 실행
vtts serve nineninesix/kani-tts-370m --device cuda --port 8001

옵션 7: 모든 엔진 한번에

# 모든 TTS 엔진 설치 (의존성 충돌 가능!)
pip install "vtts[all] @ git+https://github.com/bellkjtt/vTTS.git"

Docker (여러 엔진 동시 사용)

# 개별 실행
docker-compose up -d supertonic # :8001
docker-compose up -d gptsovits # :8002 (reference_audio 폴더 필요)
docker-compose up -d cosyvoice # :8003
# 전체 + Nginx API Gateway
docker-compose --profile gateway up -d # :8000 (통합 엔드포인트)

CLI 자동 설치

# 기본 설치 (Supertonic만)
pip install "vtts[supertonic] @ git+https://github.com/bellkjtt/vTTS.git"
# CosyVoice (코드 내장!)
pip install "vtts[cosyvoice] @ git+https://github.com/bellkjtt/vTTS.git"
# GPT-SoVITS (저장소 클론 필요)
pip install "vtts[gptsovits] @ git+https://github.com/bellkjtt/vTTS.git"
vtts setup --engine gptsovits # GPT-SoVITS 저장소 자동 클론

환경 설정

환경 진단 및 자동 수정

# 환경 진단
vtts doctor
# 자동 수정 (numpy, onnxruntime 호환성 문제 해결)
vtts doctor --fix
# CUDA 지원 강제 설치
vtts doctor --fix --cuda

vTTS Environment Diagnosis
✓ Python: 3.10.12
✓ numpy: 1.26.4
✓ onnxruntime: 1.16.0 (CUDA 지원)
 Providers: CUDAExecutionProvider, CPUExecutionProvider
✓ PyTorch: 2.1.0 (CUDA 12.1)
 GPU: NVIDIA GeForce RTX 4090
✓ vTTS: 설치됨
모든 환경이 정상입니다!

Kaggle/Colab에서

# Supertonic (가장 간단!)
!pip install "vtts[supertonic] @ git+https://github.com/bellkjtt/vTTS.git"
!vtts serve Supertone/supertonic-2 --device cuda &
# CosyVoice (2줄!)
!pip install "vtts[cosyvoice] @ git+https://github.com/bellkjtt/vTTS.git"
!vtts serve FunAudioLLM/Fun-CosyVoice3-0.5B-2512 --device cuda &

서버 실행

Supertonic (빠른 TTS)

vtts serve Supertone/supertonic-2
vtts serve Supertone/supertonic-2 --device cuda --port 8000

CosyVoice (다국어 음성 클로닝)

# 1. vTTS + CosyVoice 의존성 설치 (한 줄!)
pip install "vtts[cosyvoice] @ git+https://github.com/bellkjtt/vTTS.git"
# 2. 서버 실행 (모델 자동 다운로드!)
vtts serve FunAudioLLM/Fun-CosyVoice3-0.5B-2512 --device cuda --port 8001

GPT-SoVITS (음성 클로닝)

# GPT-SoVITS 저장소 설치 (위의 "방법 2" 참고)
vtts setup --engine gptsovits
# 서버 실행 (pretrained 모델 자동 다운로드됨!)
vtts serve kevinwang676/GPT-SoVITS-v3 --device cuda --port 8002

Qwen3-TTS (고품질 다국어 TTS)

# CustomVoice: 프리셋 스피커 사용 (참조 오디오 불필요)
vtts serve Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --device cuda --port 8003
# Base: Voice Clone (참조 오디오 필요)
vtts serve Qwen/Qwen3-TTS-12Hz-0.6B-Base --device cuda --port 8003
# 고품질 1.7B 모델 (더 자연스러운 음성)
vtts serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --device cuda --port 8003

TTS + STT 동시

vtts serve Supertone/supertonic-2 --stt-model large-v3
vtts serve Supertone/supertonic-2 --stt-model base --device cuda

사용 가능한 옵션

Python 사용

기본 사용법

from vtts import VTTSClient
client = VTTSClient("http://localhost:8000")
# TTS
audio = client.tts(
 text="안녕하세요, vTTS입니다.",
 voice="F1",
 language="ko",
 speed=1.05
)
audio.save("output.wav")
# STT
text = client.stt("audio.wav")
print(text)

고급 옵션 (Supertonic)

audio = client.tts(
 text="안녕하세요",
 voice="F1", # M1-M4, F1-F4
 language="ko", # en, ko, es, pt, fr
 speed=1.05, # 속도 (기본: 1.05)
 total_steps=5, # 품질 (1-20, 기본: 5)
 silence_duration=0.3 # 청크 간 무음 (초)
)

음성 클로닝 (CosyVoice)

from vtts import VTTSClient
# CosyVoice 클라이언트 (9개 언어 지원!)
client = VTTSClient("http://localhost:8001")
audio = client.tts(
 text="안녕하세요, CosyVoice로 생성한 음성입니다.",
 model="FunAudioLLM/Fun-CosyVoice3-0.5B-2512",
 voice="reference",
 language="ko", # ko, en, zh, ja, yue, es, fr, de, pt
 reference_audio="./samples/reference.wav", # 참조 오디오 (제로샷 클로닝)
 reference_text="참조 오디오에서 말하는 내용"
)
audio.save("cosyvoice_output.wav")

음성 클로닝 (GPT-SoVITS)

from vtts import VTTSClient
# GPT-SoVITS 클라이언트 (참조 오디오 필수!)
client = VTTSClient("http://localhost:8002")
audio = client.tts(
 text="안녕하세요, 음성 클로닝 테스트입니다.",
 model="kevinwang676/GPT-SoVITS-v3",
 voice="reference",
 language="ko",
 reference_audio="./samples/reference.wav", # 참조 오디오 (필수!)
 reference_text="참조 오디오에서 말하는 내용", # 참조 텍스트 (필수!)
 # 품질 조절 파라미터 (선택)
 speed=1.0, # 속도 (0.5-2.0)
 top_k=15, # Top-K 샘플링 (1-100)
 top_p=1.0, # Top-P 샘플링 (0.0-1.0)
 temperature=1.0, # 다양성 (0.1-2.0, 낮을수록 안정적)
 sample_steps=32, # 샘플링 스텝 (1-100, 높을수록 품질↑)
 seed=-1, # 시드 (-1: 랜덤, 고정값: 재현 가능)
 repetition_penalty=1.35, # 반복 억제 (1.0-2.0, 높을수록 반복 감소)
 text_split_method="cut5", # 텍스트 분할 (cut5, four_sentences 등)
 batch_size=1, # 배치 크기 (1-10)
 fragment_interval=0.3, # 문장 조각 간 간격 초 (0.0-2.0)
 parallel_infer=True # 병렬 추론 활성화
)
audio.save("cloned_voice.wav")

Qwen3-TTS (CustomVoice - 프리셋 스피커)

from vtts import VTTSClient
# Qwen3-TTS CustomVoice 클라이언트
client = VTTSClient("http://localhost:8003")
audio = client.tts(
 text="안녕하세요, Qwen3 TTS로 생성한 음성입니다.",
 model="Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
 voice="Sohee", # 한국어 스피커
 language="ko"
)
audio.save("qwen3_customvoice.wav")

Qwen3-TTS (Base - Voice Clone)

from vtts import VTTSClient
# Qwen3-TTS Base 클라이언트 (Voice Clone)
client = VTTSClient("http://localhost:8003")
audio = client.tts(
 text="안녕하세요, Voice Clone으로 생성한 음성입니다.",
 model="Qwen/Qwen3-TTS-12Hz-0.6B-Base",
 voice="reference",
 language="ko",
 reference_audio="./samples/reference.wav", # 참조 오디오 (필수!)
 reference_text="참조 오디오에서 말하는 내용" # 참조 텍스트 (필수!)
)
audio.save("qwen3_voice_clone.wav")

OpenAI SDK 호환

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
response = client.audio.speech.create(
 model="Supertone/supertonic-2",
 voice="F1",
 input="안녕하세요, 반갑습니다."
)
response.stream_to_file("output.mp3")

cURL

Supertonic (가장 빠름)

curl -X POST http://localhost:8000/v1/audio/speech \
 -H "Content-Type: application/json" \
 -d '{"input": "Hello!", "voice": "F1", "model": "Supertone/supertonic-2", "language": "en"}' \
 --output supertonic.mp3

Qwen3-TTS CustomVoice (프리셋 스피커)

curl -X POST http://localhost:8000/v1/audio/speech \
 -H "Content-Type: application/json" \
 -d '{"input": "안녕하세요, Qwen3 TTS입니다.", "voice": "Sohee", "model": "Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice", "language": "ko"}' \
 --output qwen3_customvoice.wav

Qwen3-TTS Base (Voice Clone)

curl -X POST http://localhost:8000/v1/audio/speech \
 -H "Content-Type: application/json" \
 -d '{
 "input": "안녕하세요, Voice Clone입니다.",
 "voice": "reference",
 "model": "Qwen/Qwen3-TTS-12Hz-0.6B-Base",
 "language": "ko",
 "reference_audio": "/path/to/reference.wav",
 "reference_text": "참조 오디오의 텍스트"
 }' \
 --output qwen3_voice_clone.wav

GPT-SoVITS (Voice Clone)

curl -X POST http://localhost:8000/v1/audio/speech \
 -H "Content-Type: application/json" \
 -d '{
 "input": "안녕하세요, GPT-SoVITS입니다.",
 "voice": "reference",
 "model": "kevinwang676/GPT-SoVITS-v3",
 "language": "ko",
 "reference_audio": "/path/to/reference.wav",
 "reference_text": "참조 오디오의 텍스트"
 }' \
 --output gptsovits.wav

CosyVoice (Voice Clone)

curl -X POST http://localhost:8000/v1/audio/speech \
 -H "Content-Type: application/json" \
 -d '{
 "input": "안녕하세요, CosyVoice입니다.",
 "voice": "reference",
 "model": "FunAudioLLM/CosyVoice2-0.5B",
 "language": "ko",
 "reference_audio": "/path/to/reference.wav",
 "reference_text": "참조 오디오의 텍스트"
 }' \
 --output cosyvoice.wav

Docker

포트 구성

빠른 시작

# 이미지 빌드
docker-compose build
# 실행
docker-compose up -d supertonic # Supertonic만
docker-compose up -d # 전체
# 로그
docker-compose logs -f supertonic
# 종료
docker-compose down

CLI 명령어

아키텍처

vTTS/
├── vtts/
│ ├── __init__.py # 환경 자동 체크
│ ├── cli.py # CLI (serve, doctor, setup)
│ ├── client.py # Python 클라이언트
│ ├── server/
│ │ ├── app.py # FastAPI 앱
│ │ ├── routes.py # TTS API 라우트
│ │ ├── stt_routes.py # STT API 라우트
│ │ └── models.py # Pydantic 모델
│ ├── engines/
│ │ ├── base.py # 베이스 엔진 인터페이스
│ │ ├── registry.py # 엔진 자동 등록
│ │ ├── supertonic.py # Supertonic 엔진
│ │ ├── gptsovits.py # GPT-SoVITS 엔진
│ │ ├── cosyvoice.py # CosyVoice 엔진
│ │ └── _supertonic/ # 내장 ONNX 모듈
│ └── utils/
│ └── audio.py # 오디오 처리
├── docker/
│ ├── Dockerfile.supertonic
│ ├── Dockerfile.gptsovits
│ ├── Dockerfile.cosyvoice
│ └── nginx.conf # API Gateway
├── docker-compose.yml
├── setup.py
└── README.md

개발 로드맵

문서

시작하기

예제 및 테스트

개발자 문서

다국어 문서

문제 해결

numpy 호환성 에러

ValueError: numpy.dtype size changed, may indicate binary incompatibility

CUDA를 찾을 수 없음

WARNING: CUDA requested but CUDAExecutionProvider not available

의존성 충돌

docker-compose up -d supertonic

라이선스

후원

감사의 말