macOS companion app

음성 깨우기(macOS)

음성 호출 및 눌러서 말하기

음성 호출 및 눌러서 말하기에는 macOS 26 이상이 필요합니다. 이전 버전의 macOS에서는 음성 설정 페이지에 컨트롤이 숨겨지고, 대신 macOS 26이 필요하다는 안내가 표시됩니다.

호출어 모드(기본값): 항상 켜져 있는 음성 인식기가 트리거 토큰(swabbleTriggerWords)을 기다립니다. 일치하면 캡처를 시작하고 부분 텍스트가 포함된 오버레이를 표시한 뒤, 침묵이 감지되면 자동으로 전송합니다.
눌러서 말하기(오른쪽 Option 길게 누르기): 트리거 없이 즉시 캡처하려면 오른쪽 Option 키를 길게 누릅니다. 누르는 동안 오버레이가 표시되며, 키를 놓으면 텍스트를 편집할 수 있도록 잠시 지연된 후 입력이 확정되고 전달됩니다.

인식기는 VoiceWakeRuntime에 있습니다.
호출어와 다음 단어 사이에 의미 있는 일시 정지가 있을 때만 트리거가 작동합니다(triggerPauseWindow = 0.55초). 명령이 시작되기 전이라도 일시 정지 시점에 오버레이/차임이 시작될 수 있습니다.
침묵 구간: 발화가 이어질 때는 2.0초(silenceWindow), 트리거만 들렸을 때는 5.0초(triggerOnlySilenceWindow)입니다.
강제 중지: 세션이 무한정 실행되는 것을 방지하기 위해 120초(captureHardStop)로 제한합니다.
세션 간 디바운스: 전송 후 350밀리초(debounceAfterSend)입니다.
오버레이는 VoiceWakeOverlayController를 통해 구동되며, 확정된 텍스트와 임시 텍스트를 서로 다른 색상으로 표시합니다.
전송 후 인식기가 정상적으로 다시 시작되어 다음 트리거를 기다립니다.

음성 호출이 활성화되어 있고 권한이 부여된 경우, 눌러서 말하기 캡처가 진행 중일 때를 제외하면 호출어 인식기는 계속 수신 대기 상태를 유지합니다.
X 버튼으로 직접 닫는 경우를 포함하여 오버레이가 닫히면 항상 인식기가 재개됩니다. VoiceSessionCoordinator.overlayDidDismiss는 모든 닫기 경로에서 VoiceWakeRuntime.refresh(state:)를 호출합니다. 세션/토큰 모델은 음성 오버레이를 참조하세요.

단축키 감지는 오른쪽 Option(keyCode 61 + .option)을 위한 전역 .flagsChanged 모니터를 사용합니다. 이벤트를 관찰하기만 하며 절대로 가로채지 않습니다.
캡처는 VoicePushToTalk에서 처리합니다. 즉시 음성 인식을 시작하고 부분 결과를 오버레이로 스트리밍하며, 키를 놓으면 VoiceWakeForwarder를 호출합니다.
눌러서 말하기를 시작하면 오디오 탭 충돌을 방지하기 위해 호출어 런타임이 일시 중지되며, 키를 놓으면 자동으로 다시 시작됩니다.
권한: 마이크 및 음성 인식 권한이 필요하며, 키 이벤트를 수신하려면 손쉬운 사용/입력 모니터링 승인이 필요합니다.
외부 키보드: 일부 키보드는 오른쪽 Option을 예상대로 노출하지 않습니다. 사용자가 입력 누락을 보고하면 대체 단축키를 제공하세요.

음성 호출 토글: 호출어 런타임을 활성화합니다.
오른쪽 Option을 길게 눌러 말하기: 눌러서 말하기 모니터를 활성화합니다.
언어 및 마이크 선택기, 실시간 레벨 미터, 트리거 단어 표, 테스터(로컬 전용이며 절대 전달하지 않음)가 제공됩니다.
마이크 선택기는 장치 연결이 끊겨도 마지막 선택을 유지하고 연결 끊김 안내를 표시하며, 장치가 다시 연결될 때까지 일시적으로 시스템 기본값을 사용합니다.
소리: 트리거 감지 및 전송 시 차임을 재생하며, 기본값은 macOS "Glass" 시스템 사운드입니다. 이벤트별로 NSSound에서 불러올 수 있는 파일(예: MP3/WAV/AIFF)을 선택하거나 소리 없음을 선택하세요.

전달 시 VoiceWakeForwarder.selectedSessionOptions는 활성 WebChat 세션 키가 설정되어 있으면 해당 키를 선택하고, 그렇지 않으면 Gateway의 기본 세션 키를 선택합니다.
sessions.list를 통해 해당 세션을 조회하고 세션의 전달 컨텍스트에서 전달 채널과 대상을 도출합니다. 필요한 경우 마지막 채널/대상, 그다음 파싱된 세션 키 순으로 대체하며, 아무것도 확인되지 않으면 WebChat을 기본값으로 사용합니다.
전달에 실패하면 오류가 기록되며(voicewake.forward 범주), 실행 내역은 계속 WebChat/세션 로그에서 확인할 수 있습니다.

VoiceWakeForwarder.prefixedTranscript(_:)는 음성 기록 앞에 시스템 힌트 줄(확인된 호스트 이름, 확인할 수 없으면 "이 Mac")을 추가하며, 호출어와 눌러서 말하기 경로에서 공통으로 사용됩니다.

눌러서 말하기를 켜고 오른쪽 Option을 길게 누른 상태에서 말한 다음 키를 놓습니다. 오버레이에 부분 결과가 표시된 후 전송되어야 합니다.
키를 누르는 동안 메뉴 막대의 귀 아이콘은 확대된 상태를 유지해야 하며(triggerVoiceEars(ttl: nil)), 키를 놓으면 원래 크기로 돌아갑니다.