---
read_when:
    - Робота над шляхами голосового пробудження або PTT
summary: Режими голосового пробудження та push-to-talk, а також деталі маршрутизації в застосунку для macOS
title: Голосове пробудження (macOS)
x-i18n:
    generated_at: "2026-04-24T04:17:28Z"
    model: gpt-5.4
    provider: openai
    source_hash: 0273c24764f0baf440a19f31435d6ee62ab040c1ec5a97d7733d3ec8b81b0641
    source_path: platforms/mac/voicewake.md
    workflow: 15
---

# Голосове пробудження та Push-to-Talk

## Режими

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

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

- Розпізнавач мовлення живе в `VoiceWakeRuntime`.
- Тригер спрацьовує лише тоді, коли між wake word і наступним словом є **суттєва пауза** (приблизно розрив у 0,55 с). Накладка/сигнал може початися на цій паузі ще до початку команди.
- Вікна тиші: 2,0 с, коли мовлення триває, і 5,0 с, якщо було почуто лише тригер.
- Жорстка зупинка: 120 с, щоб запобігти неконтрольованим сесіям.
- Debounce між сесіями: 350 мс.
- Накладкою керує `VoiceWakeOverlayController` із забарвленням committed/volatile.
- Після надсилання розпізнавач коректно перезапускається, щоб слухати наступний тригер.

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

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

## Режим збою «залиплої» накладки (раніше)

Раніше, якщо накладка зависала у видимому стані й ви закривали її вручну, Voice Wake міг виглядати “мертвим”, бо спроба перезапуску runtime могла блокуватися видимістю накладки, а наступний перезапуск уже не планувався.

Посилення надійності:

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

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

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

## Налаштування, видимі користувачу

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

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

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

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

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

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

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

## Пов’язане

- [Голосове пробудження](/uk/nodes/voicewake)
- [Голосова накладка](/uk/platforms/mac/voice-overlay)
- [Застосунок для macOS](/uk/platforms/macos)
