tts_bot/melo-test/README.md

MeloTTS-Korean 테스트 환경

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

구성

• server.py — FastAPI 서버 (POST /tts → wav 반환, / → 정적 페이지)
• index.html — 텍스트 입력 + 합성 + 재생 UI
• requirements.txt — Python 의존성

사전 요구

• Python 3.9 ~ 3.11 (MeloTTS 권장 범위)
• ffmpeg 불필요 (테스트는 wav 그대로 재생)
• 첫 실행 시 모델 가중치(수백 MB) 다운로드. 시간/디스크 여유 확인
• CPU 만으로 동작. GPU 있으면 자동으로 사용 (MELO_DEVICE=cuda 명시 가능)

설치 & 실행

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

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

# (선택) 일본어 모델을 함께 쓸 경우에만 필요
# python -m unidic download

# 3. 서버 실행
python server.py
# 또는 포트 변경: PORT=8000 python server.py

서버가 뜨면 브라우저에서 다음 주소 열기:

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

문제 해결

• 첫 합성이 30초 이상 걸리면 정상 (모델 로딩 + JIT 워밍업). 두 번째부터 ms 단위.
• ModuleNotFoundError: melo → pip install -r requirements.txt 가 실패한 경우. 가상환경 활성화 여부 확인.
• 한국어 발음이 깨질 때 → 입력에 영문/이모지가 섞이면 운율이 어색해질 수 있음. 디스코드 봇 통합 단계에서 TTSClient.textReplace 와 같은 사전 치환을 그대로 활용.
• 디스코드에 붙이려면: 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