---
read_when:
    - 음성 깨우기 또는 PTT 경로 작업 중
summary: Mac 앱의 음성 호출 및 눌러서 말하기 모드와 라우팅 세부 정보
title: 음성 깨우기(macOS)
x-i18n:
    generated_at: "2026-07-12T00:54:54Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 2a0a5ac44931b578daa4f74b3728a65a1c19ab9742e2d4b9f4c6db49fa5d7b8a
    source_path: platforms/mac/voicewake.md
    workflow: 16
---

# 음성 호출 및 눌러서 말하기

## 요구 사항

음성 호출 및 눌러서 말하기에는 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:)`를 호출합니다. 세션/토큰 모델은 [음성 오버레이](/ko/platforms/mac/voice-overlay)를 참조하세요.

## 눌러서 말하기 세부 정보

- 단축키 감지는 오른쪽 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)`), 키를 놓으면 원래 크기로 돌아갑니다.

## 관련 문서

- [음성 호출](/ko/nodes/voicewake)
- [음성 오버레이](/ko/platforms/mac/voice-overlay)
- [macOS 앱](/ko/platforms/macos)