Add local MeloTTS support

README.md

@@ -14,6 +14,7 @@
 - STT 전용 테스트
 - STT 결과에 대해 답변 가치 판단 후 필요할 때만 LLM 답변하는 통합 테스트
 - 로컬 `Ollama` LLM 에이전트 CLI 테스트
+- 무료 로컬 `MeloTTS` 기반 음성 출력 테스트
 
 ## 빠른 시작
 
@@ -47,6 +48,12 @@ LLM 단독 테스트:
 bun run test:llm
 ```
 
+TTS 단독 테스트:
+
+```bat
+bun run test:tts -- "안녕하세요. 로컬 티티에스 테스트입니다."
+```
+
 ## 환경 변수
 
 - `AUDIO_SOURCE`
@@ -61,6 +68,19 @@ bun run test:llm
   - 기본값 `http://127.0.0.1:11434`
 - `OLLAMA_MODEL`
   - 기본값 `qwen3:8b`
+- `TTS_ENABLED`
+  - 기본값 `true`
+- `TTS_IMAGE`
+  - 기본값 `realtime-voice-bot-melotts:v0.1.2`
+- `TTS_LANGUAGE`
+  - 기본값 `KR`
+- `TTS_SPEAKER`
+  - 기본값 `KR`
+- `TTS_DEVICE`
+  - 기본값 `cpu`
+  - Docker GPU passthrough를 쓸 때만 `cuda`로 바꿉니다
+- `TTS_SPEED`
+  - 기본값 `1`
 - `OLLAMA_KEEP_ALIVE`
   - 기본값 `5m`
 - `MAX_CONVERSATION_TURNS`
@@ -84,12 +104,15 @@ bun run test:llm
 ## 메모
 
 - 이 버전은 `STT`, `STT+LLM`, `LLM` 테스트를 따로 제공합니다.
+- `test:sttllm`에서 TTS가 켜져 있으면 답변을 스피커로 읽어줍니다.
+- `test:sttllm`에서는 자기 음성을 다시 전사하지 않도록 TTS 재생 중에는 캡처를 잠시 멈춥니다.
 - LLM 프롬프트는 `prompts/*.md` 에 분리되어 있습니다.
 - 최소 지연을 위해 파일 저장은 하지 않습니다.
 - VAD는 현재 모델 기반이 아니라 진폭 기반 단순 분리입니다.
 - Windows에서는 보통 출력 루프백이 가능한 장치나 `Stereo Mix`, 오디오 인터페이스 loopback 채널을 `AUDIO_SOURCE`로 잡아야 합니다.
 - 단순히 스피커 이름을 넣는 구조가 아니라, **루프백/캡처 가능한 입력 장치 이름**을 넣어야 합니다.
 - `ffmpeg`가 PATH에 잡혀 있어야 합니다.
+- TTS는 Windows에서 Docker Desktop이 필요합니다. MeloTTS 공식 문서도 Windows/macOS에서는 Docker 실행을 권장합니다.
 - `cmd` 기준으로 `.env`는 `copy .env.example .env`로 만들면 됩니다.
 
 ## Windows 테스트 순서
@@ -105,8 +128,9 @@ bun run test:llm
 ## Windows STT+LLM 통합 테스트 순서
 
 1. `bun run setup:llm`
-2. `bun run test:sttllm`
-3. 유튜브, 디스코드 통화, 동영상 같은 소리를 재생해서 전사와 답변 확인
+2. `bun run setup:tts`
+3. `bun run test:sttllm`
+4. 유튜브, 디스코드 통화, 동영상 같은 소리를 재생해서 전사와 답변, 음성 출력 확인
 
 ## Windows LLM 테스트 순서
 
@@ -115,6 +139,12 @@ bun run test:llm
 3. 콘솔에 직접 문장을 입력하고 답변 확인
 4. `/reset` 으로 문맥 초기화, `/exit` 로 종료
 
+## Windows TTS 테스트 순서
+
+1. Docker Desktop 실행
+2. `bun run setup:tts`
+3. `bun run test:tts -- "안녕하세요. 로컬 티티에스 테스트입니다."`
+
 현재 `test:llm` 에이전트 도구:
 - 현재 시간 조회
 - 현재 런타임 설정 조회
@@ -141,6 +171,14 @@ bun run test:llm
 LOCAL_AI_PYTHON=python
 AUDIO_SOURCE=
 DEBUG=false
+TTS_ENABLED=true
+TTS_IMAGE=realtime-voice-bot-melotts:v0.1.2
+TTS_LANGUAGE=KR
+TTS_SPEAKER=KR
+TTS_DEVICE=cpu
+TTS_SPEED=1
+TTS_CACHE_DIR=.local-ai/tts-cache
+TTS_OUTPUT_DIR=.local-ai/tts-output
 OLLAMA_BASE_URL=http://127.0.0.1:11434
 OLLAMA_MODEL=qwen3:8b
 OLLAMA_KEEP_ALIVE=5m