# MeloTTS-Korean 테스트 환경

디스코드 봇에 붙이기 전에 MeloTTS-Korean 음질·지연을 브라우저에서 바로 확인하기 위한 최소 환경.

## 구성

- `server.py` — FastAPI 서버 (`POST /tts` → wav 반환, `/` → 정적 페이지)
- `index.html` — 텍스트 입력 + 합성 + 재생 UI
- `requirements.txt` — Python 의존성
- `Dockerfile` — 호스트 셋업 없이 한 번에 돌리고 싶을 때 사용

## ⚠️ 설치 전 체크

MeloTTS 의존성(`fugashi`, `mecab-python3`, `tokenizers`)이 네이티브 빌드를 요구합니다.
사전 빌드 wheel 이 없는 환경(특히 **Python 3.12+**)에서는
`ERROR: Failed building wheel for tokenizers` / `fugashi` / `mecab-python3` 가 발생합니다.

가장 빠른 해결은 둘 중 하나:

1. **Python 을 3.10 또는 3.11 로 맞추기** (권장, 기존 wheel 활용)
2. **Docker 사용** (호스트에 아무것도 설치하지 않음, 아래 "방법 B" 참조)

소스 빌드를 굳이 하고 싶으면 OS 별 시스템 패키지 설치 필요:

- Ubuntu/Debian: `sudo apt install build-essential mecab libmecab-dev mecab-ipadic-utf8 cargo`
- macOS: `brew install mecab rust` (그리고 Xcode CLT)
- Windows: WSL2 또는 Docker 권장 (네이티브에서는 MeCab 빌드가 까다로움)

## 방법 A — 로컬 Python (3.10 또는 3.11)

```bash
# 0. Python 버전 확인 — 반드시 3.10.x 또는 3.11.x
python --version

# 1. 가상환경
python -m venv .venv
source .venv/bin/activate         # Windows: .venv\Scripts\activate

# 2. 의존성
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

# 3. unidic 사전 데이터 다운로드 (~250MB, 한 번만)
#    한국어만 써도 MeloTTS 가 임포트 시점에 일본어 MeCab Tagger 를
#    무조건 초기화하므로 이 단계가 필수입니다. 생략하면 서버 시작 시
#    "no such file or directory: ...\unidic\dicdir\mecabrc" 로 죽음.
python -m unidic download

# 4. 실행
python server.py
# 포트 변경: PORT=8000 python server.py
```

> Python 3.12+ 에서 위 단계가 깨지면 → 3.11 설치 후 재시도하거나 방법 B 로 넘어가세요.
> pyenv 사용 예: `pyenv install 3.11.9 && pyenv local 3.11.9`

## 방법 B — Docker (호스트 셋업 0, Python 버전 신경 X)

```bash
# 빌드 (한 번만, MeCab/Rust/Python 모두 포함, 3~5분)
docker build -t melo-test .

# 실행
docker run --rm -p 7860:7860 melo-test

# 모델 가중치 캐시 유지 (다음 실행부터 다운로드 생략)
docker run --rm -p 7860:7860 \
  -v melo-cache:/root/.cache/huggingface \
  melo-test
```

브라우저에서 `http://localhost:7860`.

## 사용

서버가 뜨면 브라우저에서 `http://localhost:7860` 열기.
텍스트 입력 → `합성` 클릭 → 오디오 플레이어에서 즉시 재생.
응답 헤더 `X-Synth-Ms` 로 합성 소요 시간(ms) 확인 가능.

## API

```http
POST /tts
Content-Type: application/json

{ "text": "안녕하세요.", "speed": 1.0 }
```

응답: `audio/wav` 바이너리, 헤더 `X-Synth-Ms: 1234`.

## 환경 변수

| 키 | 기본값 | 설명 |
| --- | --- | --- |
| `PORT` | `7860` | 바인드 포트 |
| `MELO_DEVICE` | `auto` | `cpu` / `cuda` / `mps` / `auto` |

## 자주 발생하는 오류

`ERROR: Failed building wheel for tokenizers`
→ Python 3.12+ 에서 대부분 발생. 3.10/3.11 로 낮추거나 Docker 사용.
   소스 빌드를 강행하려면 Rust 설치: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`

`ERROR: Failed building wheel for fugashi / mecab-python3`
→ MeCab 시스템 라이브러리 부재. Ubuntu `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`, macOS `brew install mecab`.
   Korean 만 쓰지만 MeloTTS 설치 시 일본어 의존성이 같이 끌려옵니다(런타임엔 사용 안 됨).

`ModuleNotFoundError: melo`
→ `pip install -r requirements.txt` 가 실제로 끝까지 성공했는지 확인. 위 빌드 에러가 있으면 melo 가 설치되지 않은 상태.

첫 합성이 30초 이상 걸림
→ 정상 (모델 가중치 다운로드 + 워밍업). 두 번째 호출부터 ms 단위.

한국어 발음이 깨짐
→ 입력에 영문/이모지가 섞이면 운율이 어색해질 수 있음. 디스코드 봇 통합 단계에서 `TTSClient.textReplace` 같은 사전 치환을 그대로 활용.

`RuntimeError: Failed initializing MeCab` / `no such file or directory: ...\unidic\dicdir\mecabrc`
→ `unidic` 사전 데이터 미다운로드. 가상환경 활성화 상태에서 `python -m unidic download` 실행 후 재시작.
   한국어만 써도 MeloTTS 가 임포트 시점에 일본어 모듈을 강제 로딩하기 때문에 이 단계는 필수.

## 디스코드 봇 연동 (테스트 성공 후)

MeloTTS 서버를 LAN(예: 시그니처 서버 옆)에 띄우고,
`src/utils/tts/Chzzk.ts` 와 같은 시그니처의 `textToSpeech(text): Promise<Buffer>` 어댑터
(`src/utils/tts/Melo.ts`)를 추가한 뒤 `src/classes/TTSClient.ts` 의 import 만 교체.

## 참고

- MeloTTS: https://github.com/myshell-ai/MeloTTS
- MeloTTS-Korean 모델카드: https://huggingface.co/myshell-ai/MeloTTS-Korean
- 라이선스: MIT