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

# Голосова активація та натисни-і-говори

## Режими

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

## Поведінка під час виконання (ключове слово активації)

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

## Незмінні умови життєвого циклу

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

## Залипання накладки (попередній збій)

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

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

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

## Особливості натисни-і-говори

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

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

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

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

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

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

- `VoiceWakeForwarder.prefixedTranscript(_:)` додає підказку про машину перед надсиланням. Використовується спільно для шляхів ключового слова активації та натисни-і-говори.

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

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