feat: add local audio test mode

README.md

@@ -1,10 +1,11 @@
 # realtime_voice_bot
 
-디스코드 음성 채널에서 여러 사용자의 음성을 개별로 받아 한국어로 인식하고, LLM 응답을 생성한 뒤 ElevenLabs TTS로 다시 읽어주는 최소 프로토타입입니다.
+디스코드 음성 채널 또는 로컬 PC 마이크/스피커에서 한국어 음성을 인식하고, LLM 응답을 생성한 뒤 ElevenLabs TTS로 다시 읽어주는 최소 프로토타입입니다.
 
 ## 현재 구현 범위
 
 - Discord slash command 기반 제어: `/join`, `/leave`, `/status`, `/reset`, `/say`
+- 로컬 테스트 모드: `pw-record` 입력, `pw-play` 출력
 - `@discordjs/voice` 기반 음성 채널 입장 및 유저별 오디오 수신
 - 48k stereo PCM을 16k mono로 내려서 유저별 VAD 처리
 - Silero 계열 VAD(`avr-vad`)로 발화 시작/종료 감지
@@ -28,16 +29,25 @@
 
 필수:
 
-- `DISCORD_BOT_TOKEN`
-- `DISCORD_APPLICATION_ID`
 - `OPENAI_API_KEY`
 - `ELEVENLABS_API_KEY`
 - `ELEVENLABS_VOICE_ID`
 
+Discord 모드에서만 필수:
+
+- `DISCORD_BOT_TOKEN`
+- `DISCORD_APPLICATION_ID`
+
 선택:
 
 - `DISCORD_COMMAND_GUILD_ID`
   - 테스트 서버에만 slash command를 즉시 반영하려면 설정
+- `LOCAL_AUDIO_SOURCE`
+  - `pw-record --target` 에 넣을 PipeWire source id 또는 node name
+- `LOCAL_AUDIO_SINK`
+  - `pw-play --target` 에 넣을 PipeWire sink id 또는 node name
+- `LOCAL_SPEAKER_NAME`
+  - 로컬 테스트에서 프롬프트에 넣을 화자 이름
 - `OPENAI_MODEL`
   - 기본값: `gpt-5.4-mini`
 - `ELEVENLABS_STT_MODEL`
@@ -51,13 +61,24 @@
 
 ```bash
 bun install
-bun run start
 ```
 
-개발 모드:
+디스코드 모드:
 
 ```bash
-bun run dev
+bun run start:discord
+```
+
+로컬 장치 목록:
+
+```bash
+bun run audio:devices
+```
+
+로컬 테스트 모드:
+
+```bash
+bun run start:local
 ```
 
 타입 체크:
@@ -74,9 +95,17 @@ bun run check
 4. 말을 하면 봇이 발화 단위로 인식하고 음성으로 짧게 답합니다.
 5. 다시 말하면 현재 읽고 있던 TTS는 즉시 중단됩니다.
 
+로컬 테스트:
+
+1. `bun run audio:devices` 로 source/sink id 또는 이름 확인
+2. 필요하면 `.env` 에 `LOCAL_AUDIO_SOURCE`, `LOCAL_AUDIO_SINK` 설정
+3. `bun run start:local`
+4. 마이크로 바로 말해서 응답 확인
+
 ## 설계 메모
 
 - 입력은 유저별 병렬 처리
 - 출력은 길드 세션당 단일 큐
+- 로컬 모드는 단일 화자 입력 기준
 - 화자 구분은 `speaker_id`, `speaker_name`을 LLM 프롬프트에 항상 포함
 - 최소 프로토타입이므로 Deepgram 대체 STT, 장기 메모리, 고급 명령 라우팅은 아직 포함하지 않았습니다.