Voice Wake 및 Push-to-Talk 가이드

개발을 하다 보면 키보드에서 손을 떼고 싶지 않을 때가 많죠. 코드를 작성하거나 디버깅하는 도중에 명령어를 입력하기 위해 컨텍스트를 전환하는 과정은 생각보다 흐름을 많이 방해해요. 더 자연스럽게 음성으로 도구를 제어하고 싶지만, 트리거가 제대로 작동하지 않거나 시스템이 멈추는 문제 때문에 스트레스를 받기도 합니다.

이런 불편함을 해결하기 위해 Voice Wake와 Push-to-Talk 기능을 제공해요. 이 가이드를 통해 음성만으로 명령을 내리고 Gateway에 텍스트를 전달하는 방법을 알아보세요.

필요한 것

시작하기 전에 다음 조건이 충족되었는지 확인해 주세요.

1. Microphone 및 Speech 인식 권한 허용
2. Accessibility 및 Input Monitoring 승인 (Hotkey 감지용)
3. macOS 26 이상 (Cmd+Fn 단축키를 사용하는 경우)
4. 사용 가능한 마이크 입력 장치

빠른 시작

5분 안에 Voice Wake를 설정하고 첫 음성 명령을 보내보세요.

1. Voice Wake 활성화: 설정에서 Voice Wake 토글을 켜세요. 이제 VoiceWakeRuntime이 백그라운드에서 트리거 단어를 기다립니다.
2. 트리거 단어 설정: swabbleTriggerWords에 등록된 단어를 말해 보세요. 트리거 단어와 명령어 사이에 약 0.55s의 공백을 두어야 인식이 시작됩니다.
3. Push-to-Talk (PTT) 사용: 트리거 단어 없이 바로 말하고 싶다면 오른쪽 Option 키를 길게 누르세요. 키를 누르고 있는 동안 음성이 캡처됩니다.
4. 전송 및 확인: 말을 마치면 overlay에 텍스트가 나타나고, 잠시 후 활성화된 Gateway로 자동 전송됩니다. 메뉴바의 귀 모양 아이콘이 커지는지 확인하여 작동 상태를 알 수 있습니다.

문제 해결

사용 중에 문제가 발생하면 다음 해결 방법을 참고하세요.

• Overlay를 닫았는데 인식이 안 되나요?: 이전에는 overlay가 떠 있는 상태에서 수동으로 닫으면 VoiceWakeRuntime이 멈추는 경우가 있었어요. 이제는 X 버튼으로 overlay를 닫으면 VoiceSessionCoordinator가 VoiceWakeRuntime.refresh(...)를 호출하여 즉시 인식을 재개합니다.
• 오른쪽 Option 키가 반응하지 않나요?: 일부 외부 키보드는 오른쪽 Option 키(keyCode 61)를 표준 방식으로 전달하지 않을 수 있어요. 이 경우 설정에서 제공하는 대체 단축키를 사용해 보세요.

Forwarding Behavior

Voice Wake가 활성화되면 모든 트랜스크립트는 현재 설정된 Gateway나 Agent로 전달됩니다. 이때 VoiceWakeForwarder.prefixedTranscript(_:)를 통해 머신 힌트가 포함된 페이로드가 생성됩니다.

전달된 메시지의 답장은 WhatsApp, Telegram, Discord, WebChat 중 마지막으로 사용한 메인 Provider로 전송돼요. 만약 전송에 실패하더라도 WebChat이나 세션 로그를 통해 기록을 확인할 수 있습니다.

설정에 대해 더 자세한 도움이 필요하다면 AI Setup Assistant에게 문의해 주세요.

다음 단계

• Gateway 연결 설정하기
• 커스텀 트리거 단어 관리
• 음성 인식 언어 변경하기
• 오디오 장치 문제 해결