realtime_voice_bot

출력장치로 재생되는 소리를 파일 저장 없이 바로 받아서 faster-whisper로 STT 테스트를 하고, 별도로 Ollama LLM 에이전트 CLI 테스트를 할 수 있는 최소 프로토타입입니다.

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

현재 범위

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

빠른 시작

bun install
bun run setup
copy .env.example .env

장치 목록 확인:

bun run devices

실행:

bun run test:stt

LLM 단독 테스트:

bun run test:llm

환경 변수

AUDIO_SOURCE
- bun run devices 에서 보이는 ffmpeg dshow 오디오 장치 이름
- 보통 Stereo Mix, 오디오 인터페이스 loopback 채널, 가상 케이블 입력 같은 이름을 넣습니다
DEBUG
- true면 상세 로그 출력
- false면 전사 결과만 출력
WHISPER_MODEL
- 기본값 large-v3-turbo
OLLAMA_BASE_URL
- 기본값 http://127.0.0.1:11434
OLLAMA_MODEL
- 기본값 qwen3:8b
OLLAMA_KEEP_ALIVE
- 기본값 5m
MAX_CONVERSATION_TURNS
- 기본값 6
- 최근 대화 몇 턴까지 LLM 문맥으로 넘길지 정합니다
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 테스트와 LLM 테스트를 따로 합니다.
최소 지연을 위해 파일 저장은 하지 않습니다.
VAD는 현재 모델 기반이 아니라 진폭 기반 단순 분리입니다.
Windows에서는 보통 출력 루프백이 가능한 장치나 Stereo Mix, 오디오 인터페이스 loopback 채널을 AUDIO_SOURCE로 잡아야 합니다.
단순히 스피커 이름을 넣는 구조가 아니라, 루프백/캡처 가능한 입력 장치 이름을 넣어야 합니다.
ffmpeg가 PATH에 잡혀 있어야 합니다.
cmd 기준으로 .env는 copy .env.example .env로 만들면 됩니다.

Windows 테스트 순서

bun install
bun run setup:stt
copy .env.example .env
bun run devices
.env에서 AUDIO_SOURCE=에 루프백 장치 이름 입력
bun run test:stt
유튜브, 디스코드 통화, 동영상 같은 소리를 재생해서 전사 확인

Windows LLM 테스트 순서

bun run setup:llm
bun run test:llm
콘솔에 직접 문장을 입력하고 답변 확인
/reset 으로 문맥 초기화, /exit 로 종료

현재 test:llm 에이전트 도구:

현재 시간 조회
현재 런타임 설정 조회
주요 bun 명령 목록 조회
간단한 산술식 계산

Windows용 .env 예시

LOCAL_AI_PYTHON=python
AUDIO_SOURCE=
DEBUG=false
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=qwen3:8b
OLLAMA_KEEP_ALIVE=5m
MAX_CONVERSATION_TURNS=6
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