voice.sori.studio/README.md

한국어 보이스 클로닝 TTS

한국어 자연스러움과 내 목소리 유사도를 우선하는 로컬 TTS 프로토타입입니다.
기본 엔진은 CosyVoice3, 비교·대안으로 F5-TTS를 지원합니다.

빠른 시작 (NVIDIA GPU Linux)

cd /path/to/tts

# 1) 환경 점검
chmod +x scripts/*.sh
./scripts/check_env.sh

# 2) API + 모델 venv (모델별 격리)
./scripts/setup_api.sh
./scripts/setup_f5tts.sh      # 약 5~15분, GPU/CUDA 필요
./scripts/setup_cosyvoice.sh  # 레포 클론 + 모델 다운로드, 시간 소요

# 3) A/B 비교 (동일 텍스트·reference)
./scripts/run_ab_compare.py --ref-audio auto
# 본인 목소리:
# samples/my_voice_30s.wav 녹음 + my_voice_ref.txt 작성 후
./scripts/run_ab_compare.py --ref-audio samples/my_voice_30s.wav

# 4) API + 웹 UI
cp .env.example .env   # 필요 시 TTS_MODEL 수정
./scripts/run_server.sh
# 브라우저: http://localhost:8000

디렉터리

경로	설명
config/	설정, 테스트 문장, 모델 선택
samples/	reference WAV + 대본
outputs/	A/B 비교 및 API 생성 결과
models/	CosyVoice3 체크포인트
backend/	FastAPI
web/	간단한 웹 UI
.venvs/f5tts, .venvs/cosyvoice, .venvs/api	격리 Python 환경

모델 선택

config/model_choice.json — 품질 우선 시 cosyvoice 권장.
F5-TTS가 더 나으면 .env에서 TTS_MODEL=f5_tts로 변경.

API

Method	Path	설명
GET	/api/health	상태
POST	/api/tts	텍스트 → WAV
GET	/api/audio/{job_id}	결과 재생
GET	/api/voice-samples	샘플 목록
POST	/api/voice-sample	WAV 업로드

예시

curl -X POST http://localhost:8000/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"안녕하세요. 테스트입니다."}'

내 목소리 녹음

samples/README.md 참고.
30초 / 1분 / 3분 샘플을 각각 녹음해 A/B 비교하는 것을 권장합니다.

문제 해결

• nvidia-smi 없음 → NVIDIA 드라이버/CUDA 설치 후 재시도
• CosyVoice import/sox 오류 → sudo apt install sox libsox-dev
• F5-TTS ref_text 필수 → samples/my_voice_ref.txt 작성
• API 503 → 해당 모델 venv setup 스크립트 재실행

라이선스

각 모델(F5-TTS, CosyVoice)의 원저작권·라이선스를 따릅니다.