음성 시스템

Claude Code의 음성 시스템은 푸시투톡(Push-to-Talk) 파이프라인을 통해 음성 입력을 텍스트로 변환합니다. 전체 흐름은 다음과 같습니다:

1. 키 입력 — 사용자가 음성 키를 누름
2. 녹음 — 오디오 백엔드가 마이크 입력을 캡처
3. WebSocket STT — 실시간 스트리밍으로 음성을 텍스트로 변환
4. 텍스트 — 변환된 텍스트를 프롬프트 입력란에 삽입
5. 프롬프트 제출 — 사용자 확인 후 제출

3계층 게이트

음성 기능은 세 단계의 게이트를 통과해야 활성화됩니다:

1. GrowthBook 컴파일타임 — 기능 플래그가 빌드 시점에 활성화되어 있어야 음성 관련 코드가 포함됩니다
2. OAuth 토큰 — 유효한 인증 토큰이 있어야 STT 서비스에 접근 가능
3. /voice 사전 검사 (5단계) — 런타임에 마이크 권한, 오디오 백엔드 가용성, 네트워크 연결, 서버 상태, 사용자 자격을 순차적으로 확인

마이크 권한 타이밍

마이크 권한 요청은 사전 검사의 일부로 수행됩니다. 사용자가 처음 음성 기능을 활성화할 때 OS 수준의 권한 대화 상자가 표시되며, 이후 세션에서는 캐시된 권한이 사용됩니다.

우선순위 체인

오디오 녹음 백엔드는 플랫폼과 가용성에 따라 우선순위 체인으로 선택됩니다:

// 녹음 백엔드 우선순위 체인
const RECORDING_BACKENDS = [
  { name: 'napi',    probe: () => hasNativeAddon('audio-recorder') },
  { name: 'arecord', probe: () => raceWithTimeout(spawn('arecord', ['--version']), 150) },
  { name: 'sox',     probe: () => commandExists('sox') },
  { name: 'windows', probe: () => process.platform === 'win32' },
]

런타임 arecord 프로브 (150ms 경쟁)

arecord 프로브는 150ms 타임아웃이 있는 경쟁(race)으로 실행됩니다. arecord --version을 spawn하되, 150ms 내에 응답하지 않으면 다음 백엔드로 넘어갑니다. arecord가 행(hang)에 걸릴 수 있는 환경(예: ALSA 디바이스 없음)에서 무한 대기를 방지합니다.

SoX 침묵 감지 설정

SoX 백엔드는 내장 침묵 감지 기능을 활용하여 녹음 종료 시점을 자동 판별할 수 있습니다. 설정 가능한 임계값과 지속 시간으로 환경 소음과 실제 침묵을 구분합니다.

연결 엔드포인트

STT 서비스는 wss://api.anthropic.com/api/ws/speech_to_text/voice_stream에 WebSocket으로 연결합니다.

와이어 프로토콜

WebSocket 프레임은 다음 메시지 타입을 사용합니다:

• KeepAlive — 연결 유지를 위한 주기적 핑
• Binary PCM — 원시 오디오 데이터 (16비트 PCM)
• CloseStream — 녹음 종료 신호
• TranscriptText — 중간 전사 텍스트 (서버 → 클라이언트)
• Endpoint — 발화 종료 감지 (서버 → 클라이언트)
• Error — 오류 보고 (서버 → 클라이언트)

api.anthropic.com 사용 이유

별도 STT 서비스 대신 api.anthropic.com을 사용하는 이유는 JA3 핑거프린트 호환성입니다. 엔터프라이즈 환경에서 방화벽이나 프록시가 알려지지 않은 도메인을 차단할 수 있으므로, 이미 허용된 API 도메인을 통해 STT 트래픽을 전달합니다.

finalize() 해석 경로

finalize()는 4가지 소스에서 전사 결과를 받을 수 있으며, 가장 빠른 소스를 사용합니다:

가장 빠른 소스를 사용하는 이유는 체감 지연 시간 최소화입니다 — 사용자가 말을 멈춘 후 텍스트가 나타나기까지의 시간이 핵심 경험 지표이며, 가장 빠른 소스가 충분히 정확합니다.

터미널 키 이벤트 재구성

터미널은 "키 다운"과 "키 업" 이벤트를 구분하지 않습니다. 홀드투톡은 키 반복(repeat) 이벤트의 타이밍 패턴을 분석하여 키가 눌려 있는 상태를 재구성합니다.

홀드 임계값

• 5회 빠른 누르기 — 키 반복이 5회 이상 감지되면 "홀드" 상태로 전환
• 120ms 갭 — 키 반복 이벤트 간 120ms 이상 갭이 있으면 해제로 판단
• 2번째 누르기에서 워밍업 — 첫 번째 누르기 시점에는 홀드인지 탭인지 구분 불가하므로, 2번째 누르기부터 오디오 백엔드 워밍업을 시작합니다

stripTrailing()

stripTrailing()은 키 반복으로 입력된 후행 문자를 제거합니다. 전각 공백(일본어/한국어 IME)도 지원하여, 다양한 키보드 레이아웃에서 올바르게 동작합니다.

해제 감지 타이머

키 해제를 감지하기 위해 3단계 타이머를 사용합니다:

• 200ms — 첫 번째 갭 감지. 짧은 멈춤일 수 있으므로 아직 해제로 확정하지 않음
• 600ms — 두 번째 확인. 높은 확률로 해제
• 2000ms — 최종 타임아웃. 어떤 경우든 해제로 처리

3가지 상태

음성 세션은 idle, recording, processing 세 가지 상태로 동작합니다:

• idle — 대기 중. 키 입력을 기다림
• recording — 녹음 중. 오디오를 캡처하여 WebSocket으로 스트리밍
• processing — 처리 중. 녹음 종료 후 최종 전사 결과를 기다림

비동기 await 전 동기 상태 전환

상태 전환은 비동기 작업을 await하기 전에 동기적으로 수행됩니다. 이는 경합 조건을 방지합니다 — await 사이에 다른 이벤트가 상태를 변경할 수 있으므로, 먼저 상태를 전환한 후 비동기 작업을 시작합니다.

전체 세션 생명주기 타임라인 (8단계)

1. 키 입력 감지 — 음성 키가 눌림
2. 상태 전환: idle → recording — 동기적으로 상태 변경
3. 오디오 백엔드 시작 — 선택된 녹음 백엔드 활성화
4. WebSocket 연결 — STT 서버에 연결
5. PCM 스트리밍 — 오디오 데이터를 실시간 전송
6. 키 해제 감지 / 침묵 감지 — 녹음 종료 조건 충족
7. 상태 전환: recording → processing — CloseStream 전송
8. 상태 전환: processing → idle — 전사 결과 수신, 프롬프트에 삽입

6가지 감지 조건

무음으로 판단하여 오디오를 드롭하는 조건은 6가지입니다:

• RMS 레벨이 임계값 미만
• 녹음 시간이 너무 짧음 (실수 누르기)
• WebSocket 연결 실패
• 전사 결과가 빈 문자열
• 오디오 버퍼가 비어 있음
• 백엔드가 오디오를 캡처하지 못함

리플레이 코드

무음으로 드롭된 오디오가 실제로는 유효한 발화였을 수 있습니다. 리플레이는 32KB 슬라이스로 오디오를 재전송하며, 각 슬라이스 사이에 250ms 백오프를 적용하여 서버 부하를 제한합니다.

오디오 버퍼 바운딩

리플레이용 오디오 버퍼는 크기가 제한됩니다. 제한 없는 버퍼는 장시간 녹음 시 메모리를 소진할 수 있으므로, 최근 N초분의 오디오만 유지합니다.

홀드투톡과의 비교

5초 침묵 타이머

포커스 모드에서는 5초간 침묵이 지속되면 녹음이 자동 종료됩니다. 이는 사용자가 말을 멈추고 생각하는 짧은 멈춤과 실제 발화 종료를 구분하기 위한 임계값입니다.

normalizeLanguageForSTT()

normalizeLanguageForSTT()는 다양한 로케일 형식을 BCP-47 표준으로 정규화합니다. 사용자 시스템의 로케일 설정이 ko_KR.UTF-8, ko-KR, Korean 등 다양한 형식일 수 있으므로, STT 서버가 요구하는 표준 형식으로 통일합니다.

getVoiceKeyterms()

getVoiceKeyterms()는 3가지 소스에서 최대 50개의 핵심 용어를 수집합니다:

• 프로젝트의 CLAUDE.md 파일
• 최근 대화 기록의 기술 용어
• 현재 작업 디렉토리의 파일명/변수명

이 핵심 용어는 STT 서버에 전달되어 도메인 특화 용어의 인식 정확도를 높입니다.

splitIdentifier()

splitIdentifier()는 코드 식별자를 단어로 분리합니다:

• camelCase → ["camel", "Case"]
• kebab-case → ["kebab", "case"]
• snake_case → ["snake", "case"]

분리된 단어는 핵심 용어로 STT 서버에 전달되어, "카멜케이스"라고 발음해도 camelCase로 올바르게 인식되도록 돕습니다.

RMS 계산

오디오 레벨은 16비트 PCM 샘플에서 RMS(Root Mean Square)로 계산됩니다. 각 오디오 프레임의 샘플 값을 제곱하여 평균을 구한 후 제곱근을 취합니다.

sqrt 곡선

RMS 값은 제곱근 곡선으로 변환되어 시각화에 사용됩니다. 선형 매핑보다 제곱근 곡선이 인간의 음량 인식에 더 가깝습니다 — 조용한 소리의 변화가 더 뚜렷하게 표시되고, 큰 소리의 변화는 압축됩니다.

16바 파형

터미널에 16개의 바로 실시간 파형이 표시됩니다. 각 바의 높이는 해당 주파수 대역의 에너지를 반영하며, 녹음 중 시각적 피드백을 제공합니다.