---
read_when:
    - Працюєте над шляхами голосового пробудження або PTT
summary: Режими голосової активації та «натисни й говори», а також подробиці маршрутизації в застосунку для Mac
title: Голосове пробудження (macOS)
x-i18n:
    generated_at: "2026-06-27T17:47:34Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 33c6132d03efb837ae06f4810ff87eb981ad742d793657bc607f4ec214bc2afa
    source_path: platforms/mac/voicewake.md
    workflow: 16
---

# Голосове пробудження та «натисни й говори»

## Вимоги

Для Голосового пробудження та режиму «натисни й говори» потрібна macOS 26 або новіша. У старіших версіях macOS елементи керування приховано зі сторінки налаштувань голосу, де показано вимогу macOS 26.

## Режими

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

## Поведінка під час виконання (wake-word)

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

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

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

## Режим збою із застряглим оверлеєм (раніше)

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

Посилення:

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

## Особливості «натисни й говори»

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

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

- Перемикач **Voice Wake**: вмикає wake-word runtime.
- **Hold Right Option to talk**: вмикає монітор «натисни й говори».
- Вибір мови й мікрофона, живий індикатор рівня, таблиця тригерних слів, тестер (лише локально; не пересилає).
- Вибір мікрофона зберігає останній вибір, якщо пристрій від’єднується, показує підказку про від’єднання й тимчасово повертається до системного типового пристрою, доки він не повернеться.
- **Звуки**: дзвінки під час виявлення тригера та надсилання; типово використовується системний звук macOS «Glass». Для кожної події можна вибрати будь-який файл, який завантажує `NSSound` (наприклад, MP3/WAV/AIFF), або вибрати **Без звуку**.

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

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

## Корисне навантаження пересилання

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

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

- Увімкніть «натисни й говори», утримуйте праву Option, говоріть, відпустіть: оверлей має показати часткові результати, а потім надіслати.
- Під час утримання вуха в рядку меню мають залишатися збільшеними (використовує `triggerVoiceEars(ttl:nil)`); вони зменшуються після відпускання.

## Пов’язано

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