tts_bot/melo-test/README.md

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)

# 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)

# 빌드 (한 번만, 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

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