​

음성 웨이크 & 푸시 투 토크

​

모드

• 웨이크 워드 모드 (기본값): 항상 켜진 음성 인식기가 트리거 토큰(swabbleTriggerWords)을 기다립니다. 일치 시 캡처를 시작하고 부분 텍스트가 포함된 오버레이를 표시하며, 침묵 후 자동으로 전송합니다.
• 푸시 투 토크 (오른쪽 Option 길게 누르기): 오른쪽 Option 키를 누르고 있는 동안 즉시 캡처합니다—트리거가 필요 없습니다. 누르는 동안 오버레이가 나타나며, 놓으면 약간의 지연 후 최종화되어 전달되므로 텍스트를 약간 조정할 수 있습니다.

​

런타임 동작 (웨이크 워드)

• 음성 인식기는 VoiceWakeRuntime에 상주합니다.
• 트리거는 웨이크 워드와 다음 단어 사이에 의미 있는 일시 정지가 있을 때만 발화됩니다(약 0.55초 간격). 오버레이/차임은 명령이 시작되기 전이라도 일시 정지 시점에 시작될 수 있습니다.
• 침묵 윈도우: 발화가 진행 중일 때 2.0초, 트리거만 들렸을 때 5.0초.
• 하드 스톱: 무한 세션을 방지하기 위해 120초.
• 세션 간 디바운스: 350ms.
• 오버레이는 확정/가변 색상 처리를 사용하여 VoiceWakeOverlayController를 통해 구동됩니다.
• 전송 후 인식기는 다음 트리거를 듣기 위해 깔끔하게 재시작합니다.

​

라이프사이클 불변 조건

• 음성 웨이크가 활성화되고 권한이 부여되면, 웨이크 워드 인식기는 항상 청취 상태여야 합니다(명시적인 푸시 투 토크 캡처 중에는 제외).
• 오버레이 가시성(X 버튼을 통한 수동 닫기 포함)은 인식기의 재개를 절대 방해해서는 안 됩니다.

​

끈적 오버레이 실패 모드 (이전)

이전에는 오버레이가 표시된 채로 멈춘 상태에서 수동으로 닫으면, 런타임의 재시작 시도가 오버레이 가시성에 의해 차단되고 이후 재시작이 예약되지 않아 음성 웨이크가 “죽은” 것처럼 보일 수 있었습니다. 강화 사항:

• 웨이크 런타임 재시작은 더 이상 오버레이 가시성에 의해 차단되지 않습니다.
• 오버레이 닫기 완료 시 VoiceSessionCoordinator를 통해 VoiceWakeRuntime.refresh(...)가 트리거되므로, X 버튼으로 수동 닫기를 해도 항상 청취가 재개됩니다.

​

37. 푸시 투 토크 세부 사항

• 핫키 감지는 오른쪽 Option(keyCode 61 + .option)에 대해 전역 .flagsChanged 모니터를 사용합니다. 이벤트는 관찰만 하며 가로채지 않습니다.
• 캡처 파이프라인은 VoicePushToTalk에 위치합니다. 즉시 음성 인식을 시작하고 부분 결과를 오버레이로 스트리밍하며, 해제 시 VoiceWakeForwarder를 호출합니다.
• 푸시 투 토크가 시작되면 오디오 탭 충돌을 피하기 위해 웨이크 워드 런타임을 일시 중지하며, 해제 후 자동으로 재시작합니다.
• 권한: 마이크 + 음성 권한이 필요하며, 이벤트를 보려면 접근성/입력 모니터링 승인이 필요합니다.
• 외부 키보드: 일부는 오른쪽 Option을 예상대로 노출하지 않을 수 있습니다—사용자가 누락을 보고하면 대체 단축키를 제공하십시오.

​

사용자 노출 설정

• 음성 웨이크 토글: 웨이크 워드 런타임을 활성화합니다.
• Cmd+Fn을 길게 눌러 말하기: 푸시 투 토크 모니터를 활성화합니다. macOS < 26 에서는 비활성화됩니다.
• 언어 및 마이크 선택기, 실시간 레벨 미터, 트리거 워드 표, 테스터(로컬 전용; 전달하지 않음).
• 마이크 선택기는 장치가 연결 해제되면 마지막 선택을 유지하고 연결 해제 힌트를 표시하며, 복귀할 때까지 일시적으로 시스템 기본값으로 대체합니다.
• 사운드: 트리거 감지 및 전송 시 차임; 기본값은 macOS “Glass” 시스템 사운드입니다. 각 이벤트에 대해 NSSound 로드 가능한 파일(예: MP3/WAV/AIFF)을 선택하거나 무음을 선택할 수 있습니다.

​

전달 동작

• 음성 웨이크가 활성화되면 전사 결과가 활성 Gateway(게이트웨이)/에이전트로 전달됩니다(mac 앱의 나머지와 동일한 로컬 vs 원격 모드).
• 응답은 마지막으로 사용한 메인 프로바이더(WhatsApp/Telegram/Discord/WebChat)로 전달됩니다. 전달에 실패하면 오류가 로깅되며, 실행은 WebChat/세션 로그를 통해 계속 확인할 수 있습니다.

​

전달 페이로드

• VoiceWakeForwarder.prefixedTranscript(_:)은 전송 전에 머신 힌트를 접두로 추가합니다. 웨이크 워드 및 푸시 투 토크 경로 간에 공유됩니다.

​

빠른 검증

• 푸시 투 토크를 켜고 Cmd+Fn을 길게 누른 뒤 말하고 놓습니다: 오버레이에 부분 결과가 표시된 후 전송되어야 합니다.
• 누르고 있는 동안 메뉴 바의 귀 아이콘은 확대된 상태를 유지해야 합니다(triggerVoiceEars(ttl:nil) 사용); 해제 후에는 축소됩니다.