feat: scaffold realtime Korean voice assistant bot

README.md

@@ -0,0 +1,82 @@
+# realtime_voice_bot
+
+디스코드 음성 채널에서 여러 사용자의 음성을 개별로 받아 한국어로 인식하고, LLM 응답을 생성한 뒤 ElevenLabs TTS로 다시 읽어주는 최소 프로토타입입니다.
+
+## 현재 구현 범위
+
+- Discord slash command 기반 제어: `/join`, `/leave`, `/status`, `/reset`, `/say`
+- `@discordjs/voice` 기반 음성 채널 입장 및 유저별 오디오 수신
+- 48k stereo PCM을 16k mono로 내려서 유저별 VAD 처리
+- Silero 계열 VAD(`avr-vad`)로 발화 시작/종료 감지
+- ElevenLabs Scribe Realtime WebSocket으로 발화 단위 STT
+- OpenAI Responses API로 짧은 한국어 답변 생성
+- ElevenLabs Flash v2.5 스트리밍 TTS
+- 채널 단위 단일 재생 큐
+- 사용자 발화 시작 시 현재 TTS와 대기열 중단(barge-in)
+
+## 권장 환경
+
+- Bun `1.3+`
+- Node.js `22.12+`
+- Discord bot with Voice permissions
+- ElevenLabs API key + 사용할 Voice ID
+- OpenAI API key
+
+## 환경 변수
+
+`.env.example`를 참고해서 `.env`를 채우면 됩니다.
+
+필수:
+
+- `DISCORD_BOT_TOKEN`
+- `DISCORD_APPLICATION_ID`
+- `OPENAI_API_KEY`
+- `ELEVENLABS_API_KEY`
+- `ELEVENLABS_VOICE_ID`
+
+선택:
+
+- `DISCORD_COMMAND_GUILD_ID`
+  - 테스트 서버에만 slash command를 즉시 반영하려면 설정
+- `OPENAI_MODEL`
+  - 기본값: `gpt-5.4-mini`
+- `ELEVENLABS_STT_MODEL`
+  - 기본값: `scribe_v2_realtime`
+- `ELEVENLABS_TTS_MODEL`
+  - 기본값: `eleven_flash_v2_5`
+- `DEBUG_TEXT_EVENTS`
+  - `true`면 명령을 실행한 텍스트 채널에 transcript/reply를 같이 올림
+
+## 실행
+
+```bash
+bun install
+bun run start
+```
+
+개발 모드:
+
+```bash
+bun run dev
+```
+
+타입 체크:
+
+```bash
+bun run check
+```
+
+## 사용 흐름
+
+1. 봇을 서버에 초대하고 음성 권한을 부여합니다.
+2. 음성 채널에 들어갑니다.
+3. 텍스트 채널에서 `/join` 실행
+4. 말을 하면 봇이 발화 단위로 인식하고 음성으로 짧게 답합니다.
+5. 다시 말하면 현재 읽고 있던 TTS는 즉시 중단됩니다.
+
+## 설계 메모
+
+- 입력은 유저별 병렬 처리
+- 출력은 길드 세션당 단일 큐
+- 화자 구분은 `speaker_id`, `speaker_name`을 LLM 프롬프트에 항상 포함
+- 최소 프로토타입이므로 Deepgram 대체 STT, 장기 메모리, 고급 명령 라우팅은 아직 포함하지 않았습니다.