# 다음 작업자 인수인계 문서

이 문서는 한국어 보이스 클로닝 TTS 프로젝트를 다른 PC 또는 다음 AI가 이어받을 때 가장 먼저 읽어야 하는 문서입니다.

## 한 줄 요약

한국어 자연스러움과 본인 목소리 유사도를 우선하는 로컬 TTS 프로토타입입니다. 기본 모델은 `CosyVoice3`, 비교 모델은 `F5-TTS`이며, FastAPI 백엔드와 간단한 웹 UI까지 만들어져 있습니다.

## 현재 작업 상태

- 프로젝트 뼈대 생성 완료
- FastAPI 서버 구현 완료
- 웹 UI 구현 완료
- 한국어 텍스트 전처리 구현 완료
- 내 목소리 reference 녹음 가이드 작성 완료
- `CosyVoice3` / `F5-TTS` A/B 비교 스크립트 작성 완료
- 모델별 격리 venv 설치 스크립트 작성 완료
- 현재 Mac에서 API/UI smoke test 완료
- 실제 고품질 TTS 추론은 아직 NVIDIA GPU 환경에서 검증 필요

## 중요한 전제

현재 작업한 Mac은 Apple Silicon 환경이고 `nvidia-smi`가 없습니다. 따라서 여기서는 API/UI 구조 확인은 가능하지만, 계획한 고품질 보이스 클로닝 추론은 Windows 또는 Linux의 NVIDIA GPU PC에서 이어가는 것이 맞습니다.

메인 PC가 Windows + NVIDIA GPU라면 다음 순서로 진행하세요. 가능하면 WSL2 Ubuntu 환경을 권장합니다. Windows 네이티브도 가능할 수 있지만, `CosyVoice`는 Linux/WSL2 쪽이 문제 해결 자료가 많습니다.

## 깃에 올릴 때 주의

올리면 좋은 것:

- `README.md`
- `docs/HANDOFF.md`
- `backend/`
- `web/`
- `scripts/`
- `config/`
- `samples/README.md`
- `samples/my_voice_ref.txt`
- `.env.example`
- `.gitignore`
- `docker-compose.yml`
- `tests/`

올리지 말아야 할 것:

- `.venvs/`
- `models/`
- `outputs/`
- `external/CosyVoice/`
- 실제 내 목소리 WAV 파일
- `.env` 안에 개인 경로나 민감한 값이 들어간 경우

현재 `.gitignore`에는 `.venvs/`, `models/`, `outputs/`, `external/CosyVoice/`, `.env`, WAV 파일 등이 제외되도록 설정되어 있습니다.

## 메인 PC에서 처음 할 일

```bash
git clone <repo-url>
cd tts

chmod +x scripts/*.sh
./scripts/check_env.sh
```

Windows라면 WSL2 Ubuntu에서 실행하는 것을 권장합니다.

```bash
sudo apt update
sudo apt install -y git python3 python3-venv python3-pip ffmpeg sox libsox-dev
```

NVIDIA GPU가 제대로 잡히는지 확인하세요.

```bash
nvidia-smi
```

## 환경 설치 순서

API 서버용 venv:

```bash
./scripts/setup_api.sh
```

F5-TTS 비교용 venv:

```bash
./scripts/setup_f5tts.sh
```

CosyVoice3 기본 모델용 venv:

```bash
./scripts/setup_cosyvoice.sh
```

`setup_cosyvoice.sh`는 `external/CosyVoice` 레포를 클론하고 `models/Fun-CosyVoice3-0.5B` 모델을 다운로드합니다. 시간이 오래 걸릴 수 있습니다.

## 현재 기본 모델

기본값은 `cosyvoice`입니다.

관련 파일:

- `.env.example`
- `.env`
- `config/settings.yaml`
- `config/model_choice.json`

모델 변경:

```bash
./scripts/select_model.sh cosyvoice
./scripts/select_model.sh f5_tts
```

또는 `.env`에서 직접 변경:

```env
TTS_MODEL=cosyvoice
```

## 내 목소리 샘플 준비

자세한 가이드는 `samples/README.md`에 있습니다.

권장 파일:

```text
samples/my_voice_30s.wav
samples/my_voice_1m.wav
samples/my_voice_3m.wav
samples/my_voice_ref.txt
```

중요:

- WAV는 mono, 24kHz 또는 16kHz 권장
- 녹음 대본과 `my_voice_ref.txt` 내용은 일치해야 함
- 조용한 환경에서 마이크 거리 일정하게 유지
- 30초, 1분, 3분 샘플을 각각 비교

reference WAV 전처리:

```bash
./scripts/prepare_reference.sh samples/my_voice_30s.wav
```

## 모델 A/B 비교

설치 검증용:

```bash
./scripts/run_ab_compare.py --ref-audio auto
```

본인 목소리 비교:

```bash
./scripts/run_ab_compare.py --ref-audio samples/my_voice_30s.wav
```

길이별 reference 비교:

```bash
./scripts/compare_voice_lengths.sh
```

결과는 보통 아래에 생성됩니다.

```text
outputs/ab_compare/
outputs/voice_length_compare/
```

평가 기준:

- 한국어 발음 정확도
- 조사/어미 자연스러움
- 억양과 호흡
- 내 목소리 유사도
- 긴 문장 안정성
- 숫자, 영어, 기호 포함 문장 처리

## 서버 실행

```bash
cp .env.example .env
./scripts/run_server.sh
```

브라우저:

```text
http://localhost:8000
```

주요 API:

```text
GET  /api/health
POST /api/tts
GET  /api/audio/{job_id}
GET  /api/voice-samples
POST /api/voice-sample
```

간단 테스트:

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

## Mac에서 가능한 것과 불가능한 것

현재 Mac에서 가능한 것:

- FastAPI 서버 실행
- 웹 UI 확인
- `/api/health` 확인
- 샘플 업로드 UI 확인
- 텍스트 전처리 테스트

현재 Mac에서 어려운 것:

- `CosyVoice3` 고품질 추론
- `F5-TTS` CUDA 기반 추론
- 최종 품질 평가

즉, Mac은 개발/구조 확인용이고, 최종 모델 품질 검증은 NVIDIA GPU PC에서 해야 합니다.

## 다음 AI에게 요청할 때 권장 문장

다음 AI에게는 아래처럼 시작하면 됩니다.

```text
먼저 docs/HANDOFF.md를 읽고, 현재 한국어 보이스 클로닝 TTS 프로젝트 상태를 파악한 뒤 이어서 작업해줘.
목표는 Windows/NVIDIA GPU PC에서 CosyVoice3와 F5-TTS를 설치하고, 내 목소리 샘플로 A/B 비교 후 더 자연스러운 모델을 선택하는 거야.
```

## 다음 작업자가 우선 확인할 파일

1. `docs/HANDOFF.md`
2. `README.md`
3. `config/settings.yaml`
4. `config/model_choice.json`
5. `.env.example`
6. `samples/README.md`
7. `scripts/setup_cosyvoice.sh`
8. `scripts/setup_f5tts.sh`
9. `scripts/run_ab_compare.py`
10. `backend/app/main.py`

## 알려진 주의점

- `FastAPI TestClient`는 현재 API venv에서 `httpx` 계열 패키지가 없어 직접 테스트가 실패했습니다. 대신 실제 `uvicorn` 서버를 띄우고 `/api/health`와 웹 UI 200 응답은 확인했습니다.
- `scripts/setup_f5tts.sh`와 `scripts/setup_cosyvoice.sh`는 CUDA 12.4 PyTorch index를 사용합니다. 메인 PC CUDA 버전에 맞지 않으면 `cu124`를 `cu121`, `cu126`, `cu128` 등으로 조정해야 할 수 있습니다.
- `CosyVoice`는 `sox`, `libsox-dev`, `ffmpeg`가 필요할 수 있습니다.
- 실제 음성 파일은 개인정보성이 있으므로 깃에 올리지 않는 것을 권장합니다.
- `.env`도 깃에 올리지 말고 `.env.example`만 공유하세요.

## 완료 기준

이 프로젝트의 다음 큰 완료 기준은 다음과 같습니다.

- NVIDIA GPU PC에서 `./scripts/setup_cosyvoice.sh` 성공
- NVIDIA GPU PC에서 `./scripts/setup_f5tts.sh` 성공
- 본인 목소리 샘플로 `./scripts/run_ab_compare.py` 실행 성공
- `outputs/ab_compare/` 결과를 듣고 모델 선택
- 선택 모델로 `./scripts/run_server.sh` 실행
- 웹 UI에서 텍스트 입력 후 본인 목소리 WAV 재생 성공