2bed5f38b7
User got past wheel build, then hit at startup:
RuntimeError: Failed initializing MeCab
[ifs] no such file or directory:
.../site-packages/unidic/dicdir/mecabrc
Root cause: MeloTTS's text/cleaner.py unconditionally imports the
japanese module, which initializes MeCab.Tagger() at module load
time. So even Korean-only use needs the unidic dictionary data,
which is a separate ~250MB download.
- README: add explicit `python -m unidic download` step after
pip install, and a troubleshooting entry for the mecabrc error.
- Dockerfile: run `python -m unidic download` during image build so
the container is usable immediately.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
# 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
|