# 한국어 보이스 클로닝 TTS

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

## 빠른 시작 (NVIDIA GPU Linux)

```bash
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 업로드 |

### 예시

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

## 내 목소리 녹음

[samples/README.md](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)의 원저작권·라이선스를 따릅니다.