# 한국어 TTS 엔진 분석 및 통합 계획

6개 리포를 심층 분석하여 한국어 TTS를 스튜디오에 다중 엔진으로 통합하기 위한 기록.
목표: 무제한·무료 자가호스팅, 가능하면 GPU(Blackwell sm_120, torch cu128) 사용.

## 분석 결과 (feasibility matrix)

| # | 리포 | 아키텍처 | 한국어 | 사전학습 모델 | 라이선스 | 런타임 | GPU(Blackwell) | 판정 |
|---|------|----------|--------|----------------|----------|--------|----------------|------|
| 1 | FunAudioLLM/CosyVoice (=QwenAudio/CosyVoice) | LLM+flow+HiFiGAN | 예(zero-shot) | CosyVoice2-0.5B, ~1–2GB, HF/ModelScope, 비게이트 | Apache-2.0 (무제한/상업 OK) | PyTorch (torch 2.3.1 pin) | cu128로 올리면 가능 | 통합(주의) |
| 2 | TensorSpeech/TensorFlowTTS | Tacotron2/FS2 + MB-MelGAN | 예(KSS) | tts-*-kss-ko, HF, 비게이트 | 코드 Apache-2.0 / **가중치 CC BY-NC-SA(비상업)** | TensorFlow2 | ❌ CPU만 | 옵션(주의) |
| 3 | hccho2/Tacotron2-Wavenet-Korean-TTS | Tacotron2+WaveNet | 예 | ❌ 없음(직접 학습) | MIT | TF1 | ❌ | 제외 |
| 4 | ttop32/coqui_tts_korea | GlowTTS + MB-MelGAN | 예(KSS) | GlowTTS+MBMelGAN ckpt, Google Drive, 비게이트 | **MPL-2.0(무제한/상업 OK)** | PyTorch (coqui-tts idiap fork) | ✅ 동작 확인 | **1순위 통합** |
| 5 | esoyeon/KoreanTTS | Tacotron/Tacotron2 | 예 | ❌ 없음(직접 학습) | MIT | TF1 | ❌ | 제외 |
| 6 | AzamRabiee/Emotional-TTS | Tacotron(emotional) | 의도상 예 | ❌ 없음, 코드도 없음 | **없음(권리 유보)** | TF1 | ❌ | 제외 |

핵심 결론
- 실제로 최신 스택에서 돌릴 수 있는 "무료·무제한·한국어" 엔진: **Coqui GlowTTS-KSS(4번)**, 그리고 **CosyVoice2(1번, Apache)**.
- 3·5·6번은 사전학습 가중치가 없고 TF1 전용이라 최신 Python3.11/CUDA12.8/Blackwell에서 실행 불가 → 제외.
- 2번은 비상업 라이선스 + CPU 전용 + 레거시 TF 사이드카 필요 → 개인 테스트용으로만 옵션.

## 통합 아키텍처

기존 스튜디오는 단일 MeloTTS 인프로세스였음. 문제: Coqui/CosyVoice는 각자 다른 torch/librosa/numpy 핀을 요구 → 한 venv에 섞으면 충돌(예: MeloTTS는 librosa==0.9.1, Coqui는 최신 요구).

해결: **단일 컨테이너 + 엔진별 격리 venv + 서브프로세스 호출**.
- 메인 FastAPI(기본 venv, MeloTTS 인프로세스)가 `/api/engines`, `/api/tts?engine=...` 제공.
- Coqui 등은 `/opt/<engine>-venv` 전용 venv의 합성 스크립트를 subprocess로 실행해 WAV 반환.
- 배포 포트는 그대로 8788 유지.

엔진 레지스트리 인터페이스: `list_models()`, `synth(text, model, speed, pitch) -> wav bytes`.
프론트엔드: 엔진 선택 → 모델(목소리) 선택 → 속도/피치.

## 진행 단계 (단계마다 Gitea 커밋/푸시)

- A. 백엔드를 엔진 레지스트리로 리팩터링(MeloTTS 유지, 동작 불변) + 프론트 엔진 선택 UI. ✅ 커밋
- B. Coqui GlowTTS-KSS 엔진 추가(전용 venv + Google Drive 체크포인트 베이킹 + subprocess). 테스트 후 커밋.
- C. CosyVoice2 한국어 엔진 추가(Apache, torch cu128 재빌드). 가능 시 커밋.
- D. (옵션) TensorFlowTTS KSS CPU 엔진. 비상업 라이선스 명시.

무료·무제한 보장: 통합 대상은 Apache-2.0(CosyVoice) / MPL-2.0(Coqui)만 GPU 기본 경로로 사용. 비상업(CC BY-NC-SA)인 TF-TTS는 개인용 옵션으로만, UI에 라이선스 표기.

## 진행 로그 / 실측 결과

### Coqui GlowTTS-KSS (repo #4) — 통합 불가로 확정
- 라이브러리(coqui-tts idiap fork)는 torch 2.11+cu128에서 정상 동작(Synthesizer import OK, torchcodec 필요).
- 그러나 **사전학습 체크포인트 구글드라이브 폴더 4개가 전부 삭제(404)**: GlowTTS/MB-MelGAN/HalfLife 2종 모두. 가중치가 없어 직접 학습(수일) 외 방법이 없어 제외.

### CosyVoice (repo #1) — GPU 실측 성공 ✅ (채택)
- 모델: `iic/CosyVoice-300M-SFT` (ModelScope, ~5.4GB), Apache-2.0.
- 프리셋 화자에 `韩语女`(한국어) 포함 → 참조음성 없이 `inference_sft(text, '韩语女')` 로 한국어 합성.
- 실측(RTX 5050, torch 2.11+cu128): 로드 15.3s, 합성 3.2s(4.8s 음성, RTF 0.66), device=cuda.
- 의존성 조정(핵심):
  - torch/torchaudio를 2.11.0+cu128로 고정(원 requirements의 2.3.1/cu121 제거).
  - deepspeed / tensorrt / onnxruntime-gpu 제거(추론 불필요), onnxruntime(CPU)로 대체.
  - pyworld 제거(학습 파이프라인에서만 사용). numpy 1.26과 빌드 비호환.
  - openai-whisper는 CosyVoice 토크나이저(`whisper.tokenizer.get_tokenizer`)에 필요 → `--no-deps`로 설치(토치 덮어쓰기 방지) + tiktoken/more-itertools.
  - `cosyvoice/cli/frontend.py`, `cosyvoice/dataset/processor.py`의 `import whisper`/`import pyworld`를 optional 처리.
  - WAV 저장은 torchaudio(2.11 torchcodec 경로 깨짐) 대신 soundfile 사용.
- 통합 방식: 전용 venv(`/opt/cosyvoice`, base torch 공유) + subprocess 호출. 모델은 이미지에 베이킹(또는 호스트 볼륨 마운트).