---
read_when:
    - Робота над шляхами voice wake або PTT
summary: Режими voice wake і push-to-talk, а також деталі маршрутизації в застосунку macOS
title: Voice wake (macOS)
x-i18n:
    generated_at: "2026-04-23T21:01:34Z"
    model: gpt-5.4
    provider: openai
    source_hash: b49077200b34102e4d75d214249115450cbc690d13fc12c2979d87d6fae36f45
    source_path: platforms/mac/voicewake.md
    workflow: 15
---

# Voice Wake і push-to-talk

## Режими

- **Режим wake word** (типово): завжди ввімкнений розпізнавач Speech чекає на trigger token-и (`swabbleTriggerWords`). При збігу він починає захоплення, показує overlay з частковим текстом і автоматично надсилає після тиші.
- **Push-to-talk (утримання Right Option)**: утримуйте праву клавішу Option, щоб одразу почати захоплення — без trigger. Overlay з’являється під час утримання; відпускання завершує й пересилає після короткої затримки, щоб ви могли відкоригувати текст.

## Поведінка runtime (wake word)

- Розпізнавач Speech живе в `VoiceWakeRuntime`.
- Trigger спрацьовує лише коли є **значуща пауза** між wake word і наступним словом (розрив ~0.55s). Overlay/звуковий сигнал можуть початися на паузі ще до початку команди.
- Вікна тиші: 2.0s, коли мовлення триває, 5.0s, якщо було почуто лише trigger.
- Жорстка зупинка: 120s, щоб запобігти runaway-session.
- Debounce між sessions: 350ms.
- Overlay керується через `VoiceWakeOverlayController` із забарвленням committed/volatile.
- Після надсилання розпізнавач чисто перезапускається, щоб слухати наступний trigger.

## Інваріанти життєвого циклу

- Якщо Voice Wake увімкнено й дозволи надано, розпізнавач wake word має слухати (крім явного захоплення push-to-talk).
- Видимість overlay (включно з ручним закриттям через кнопку X) ніколи не повинна заважати відновленню розпізнавача.

## Режим залиплого overlay (раніше)

Раніше, якщо overlay зависав видимим і ви вручну його закривали, Voice Wake міг здаватися «мертвим», бо спроба перезапуску runtime могла блокуватися видимістю overlay, а подальший перезапуск не планувався.

Зміцнення:

- Перезапуск wake runtime більше не блокується видимістю overlay.
- Завершення закриття overlay запускає `VoiceWakeRuntime.refresh(...)` через `VoiceSessionCoordinator`, тож ручне закриття через X завжди відновлює прослуховування.

## Особливості push-to-talk

- Виявлення hotkey використовує глобальний монітор `.flagsChanged` для **right Option** (`keyCode 61` + `.option`). Ми лише спостерігаємо події (без їх перехоплення).
- Pipeline захоплення живе в `VoicePushToTalk`: одразу запускає Speech, stream-ить часткові результати в overlay і викликає `VoiceWakeForwarder` при відпусканні.
- Коли починається push-to-talk, ми ставимо wake-word runtime на паузу, щоб уникнути конфліктуючих audio tap; після відпускання він автоматично перезапускається.
- Дозволи: потрібні Microphone + Speech; для бачення подій потрібне схвалення Accessibility/Input Monitoring.
- Зовнішні клавіатури: деякі можуть не надавати right Option так, як очікується — запропонуйте fallback-shortcut, якщо користувачі повідомляють про пропуски.

## Користувацькі налаштування

- Перемикач **Voice Wake**: вмикає wake-word runtime.
- **Hold Cmd+Fn to talk**: вмикає монітор push-to-talk. Вимкнено на macOS < 26.
- Пікери мови й мікрофона, live level meter, таблиця trigger words, tester (лише локально; не пересилає).
- Пікер мікрофона зберігає останній вибір, якщо пристрій відключається, показує підказку про відключення й тимчасово повертається до системного значення за замовчуванням, доки пристрій не повернеться.
- **Sounds**: звукові сигнали при виявленні trigger і при надсиланні; типово використовується системний звук macOS “Glass”. Для кожної події можна вибрати будь-який файл, який завантажується через `NSSound` (наприклад, MP3/WAV/AIFF), або вибрати **No Sound**.

## Поведінка пересилання

- Коли Voice Wake увімкнено, транскрипти пересилаються до активного gateway/агента (той самий локальний чи віддалений режим, який використовує решта застосунку macOS).
- Відповіді доставляються до **останнього використаного main provider-а** (WhatsApp/Telegram/Discord/WebChat). Якщо доставлення не вдається, помилка логується, а запуск усе одно видно через WebChat/логи session.

## Payload пересилання

- `VoiceWakeForwarder.prefixedTranscript(_:)` додає machine hint перед надсиланням. Спільно використовується шляхами wake-word і push-to-talk.

## Швидка перевірка

- Увімкніть push-to-talk, утримуйте Cmd+Fn, говоріть, відпустіть: overlay має показувати часткові результати, а потім надсилати.
- Під час утримання ears у menu bar мають залишатися збільшеними (використовує `triggerVoiceEars(ttl:nil)`); після відпускання вони зменшуються.
