# realtime_voice_bot

출력장치로 재생되는 소리를 파일 저장 없이 바로 받아서, 메모리 버퍼에서 발화 구간을 나눈 뒤 `faster-whisper`로 STT 하는 최소 프로토타입입니다.

현재 문서는 **Windows PC에서 실행하는 기준**으로 적었습니다.

## 현재 범위

- Node.js + TypeScript 메인 프로세스
- 출력 오디오 실시간 캡처
- 메모리 버퍼 기반 간단한 저지연 발화 분리
- 미리 로드한 `faster-whisper` 워커에 PCM 직접 전달
- 디스크에 WAV 저장 없이 바로 전사

## 빠른 시작

```bat
bun install
bun run setup:python
copy .env.example .env
```

장치 목록 확인:

```bat
bun run devices
```

실행:

```bat
bun run start:loopback
```

## 환경 변수

- `AUDIO_SOURCE`
  - `bun run devices` 에서 보이는 `ffmpeg dshow` 오디오 장치 이름
  - 보통 `Stereo Mix`, 오디오 인터페이스 loopback 채널, 가상 케이블 입력 같은 이름을 넣습니다
- `DEBUG`
  - `true`면 상세 로그 출력
  - `false`면 전사 결과만 출력
- `WHISPER_MODEL`
  - 기본값 `large-v3-turbo`
- `WHISPER_LANGUAGE`
  - 기본값 `ko`
- `WHISPER_DEVICE`
  - `auto`, `cuda`, `cpu`
- `WHISPER_COMPUTE_TYPE`
  - `auto`, `float16`, `int8_float16`, `int8`, `float32`
- `WHISPER_BEAM_SIZE`
  - 기본값 `2`
- `SEGMENT_END_FRAMES`
  - 기본값 `24`
  - 끝을 조금 더 늦게 잘라서 문장이 잘게 끊기는 현상을 줄입니다
- `SEGMENT_MAX_SPEECH_SAMPLES`
  - 기본값 `160000`
  - 너무 긴 구간은 강제로 끊어서 지연이 과하게 커지는 걸 막습니다

## 메모

- 이 버전은 일단 `STT`만 합니다.
- 최소 지연을 위해 파일 저장은 하지 않습니다.
- VAD는 현재 모델 기반이 아니라 진폭 기반 단순 분리입니다.
- Windows에서는 보통 출력 루프백이 가능한 장치나 `Stereo Mix`, 오디오 인터페이스 loopback 채널을 `AUDIO_SOURCE`로 잡아야 합니다.
- 단순히 스피커 이름을 넣는 구조가 아니라, **루프백/캡처 가능한 입력 장치 이름**을 넣어야 합니다.
- `ffmpeg`가 PATH에 잡혀 있어야 합니다.
- `cmd` 기준으로 `.env`는 `copy .env.example .env`로 만들면 됩니다.

## Windows 테스트 순서

1. `bun install`
2. `bun run setup:python`
3. `copy .env.example .env`
4. `bun run devices`
5. `.env`에서 `AUDIO_SOURCE=`에 루프백 장치 이름 입력
6. `bun run start:loopback`
7. 유튜브, 디스코드 통화, 동영상 같은 소리를 재생해서 전사 로그 확인

## Windows용 .env 예시

```env
LOCAL_AI_PYTHON=python
AUDIO_SOURCE=
DEBUG=false
WHISPER_MODEL=large-v3-turbo
WHISPER_LANGUAGE=ko
WHISPER_DEVICE=auto
WHISPER_COMPUTE_TYPE=auto
WHISPER_BEAM_SIZE=2
SEGMENT_END_FRAMES=24
SEGMENT_MAX_SPEECH_SAMPLES=160000
DEBUG_TRANSCRIPTS=true
LOG_LEVEL=info
```