From 2bed5f38b75c2a1056dd7ff07e8f890ffa57ab0d Mon Sep 17 00:00:00 2001
From: Claude Owner <claude@ejclaw.local>
Date: Tue, 26 May 2026 20:45:24 +0900
Subject: [PATCH] fix(melo-test): unidic download is mandatory, not optional

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>
---
 melo-test/Dockerfile |  4 ++++
 melo-test/README.md  | 12 +++++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/melo-test/Dockerfile b/melo-test/Dockerfile
index 3fd238f..42ee983 100644
--- a/melo-test/Dockerfile
+++ b/melo-test/Dockerfile
@@ -28,6 +28,10 @@ COPY requirements.txt .
 RUN pip install --upgrade pip setuptools wheel \
     && pip install -r requirements.txt
 
+# unidic 사전 데이터 (~250MB). MeloTTS 가 한국어만 써도 임포트 시점에
+# 일본어 MeCab Tagger 를 무조건 초기화하므로 생략 불가.
+RUN python -m unidic download
+
 COPY . .
 
 EXPOSE 7860
diff --git a/melo-test/README.md b/melo-test/README.md
index 609ec73..10f249a 100644
--- a/melo-test/README.md
+++ b/melo-test/README.md
@@ -40,7 +40,13 @@ source .venv/bin/activate         # Windows: .venv\Scripts\activate
 pip install --upgrade pip setuptools wheel
 pip install -r requirements.txt
 
-# 3. 실행
+# 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
 ```
@@ -108,6 +114,10 @@ Content-Type: application/json
 한국어 발음이 깨짐
 → 입력에 영문/이모지가 섞이면 운율이 어색해질 수 있음. 디스코드 봇 통합 단계에서 `TTSClient.textReplace` 같은 사전 치환을 그대로 활용.
 
+`RuntimeError: Failed initializing MeCab` / `no such file or directory: ...\unidic\dicdir\mecabrc`
+→ `unidic` 사전 데이터 미다운로드. 가상환경 활성화 상태에서 `python -m unidic download` 실행 후 재시작.
+   한국어만 써도 MeloTTS 가 임포트 시점에 일본어 모듈을 강제 로딩하기 때문에 이 단계는 필수.
+
 ## 디스코드 봇 연동 (테스트 성공 후)
 
 MeloTTS 서버를 LAN(예: 시그니처 서버 옆)에 띄우고,