---
read_when:
    - Робота над шляхами голосового пробудження або PTT
summary: Режими голосового пробудження та «натисни й говори», а також подробиці маршрутизації в застосунку для Mac
title: Голосове пробудження (macOS)
x-i18n:
    generated_at: "2026-05-06T05:29:55Z"
    model: gpt-5.5
    provider: openai
    source_hash: 312895b5767c447233bd77cbcd48ea81bb6c700080abc31974188b610a1b1ef0
    source_path: platforms/mac/voicewake.md
    workflow: 16
---

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

## Режими

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

## Поведінка під час виконання (слово пробудження)

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

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

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

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

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

Посилення:

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

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

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

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

- Перемикач **Голосове пробудження**: вмикає runtime слова пробудження.
- **Утримуйте Cmd+Fn, щоб говорити**: вмикає монітор «натисни й говори». Вимкнено на macOS < 26.
- Вибір мови й мікрофона, живий індикатор рівня, таблиця тригерних слів, тестер (лише локально; не пересилає).
- Вибір мікрофона зберігає останній вибір, якщо пристрій від’єднується, показує підказку про від’єднання й тимчасово повертається до системного стандартного пристрою, доки він не з’явиться знову.
- **Звуки**: сигнали під час виявлення тригера та надсилання; типово використовується системний звук macOS "Glass". Для кожної події можна вибрати будь-який файл, який завантажує `NSSound` (наприклад MP3/WAV/AIFF), або вибрати **Без звуку**.

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

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

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

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

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

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

## Пов’язане

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