---
read_when:
    - Работа с путями голосовой активации или PTT
summary: Режимы голосовой активации и push-to-talk, а также сведения о маршрутизации в приложении для Mac
title: Голосовое пробуждение (macOS)
x-i18n:
    generated_at: "2026-06-28T23:13:16Z"
    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.

## Режимы

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

## Поведение во время выполнения (слово пробуждения)

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

## Инварианты жизненного цикла

- Если голосовое пробуждение включено и разрешения выданы, распознаватель слова пробуждения должен слушать (кроме времени явного захвата через удержание клавиши для речи).
- Видимость оверлея (включая ручное закрытие кнопкой X) никогда не должна мешать возобновлению работы распознавателя.

## Предыдущий режим отказа с зависшим оверлеем

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

Усиление надежности:

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

## Особенности удержания клавиши для речи

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

## Пользовательские настройки

- Переключатель **Голосовое пробуждение**: включает runtime слова пробуждения.
- **Удерживать правую Option для речи**: включает монитор удержания клавиши для речи.
- Выбор языка и микрофона, индикатор уровня в реальном времени, таблица триггерных слов, тестер (только локально; не пересылает).
- Выбор микрофона сохраняет последний выбор, если устройство отключается, показывает подсказку об отключении и временно откатывается к системному микрофону по умолчанию, пока устройство не вернется.
- **Звуки**: сигналы при обнаружении триггера и при отправке; по умолчанию используется системный звук macOS "Glass". Для каждого события можно выбрать любой файл, загружаемый через `NSSound` (например MP3/WAV/AIFF), или выбрать **Без звука**.

## Поведение пересылки

- Когда голосовое пробуждение включено, расшифровки пересылаются активному gateway/agent (в том же локальном или удаленном режиме, который используется остальной частью приложения для Mac).
- Ответы доставляются в **последний использованный основной провайдер** (WhatsApp/Telegram/Discord/WebChat). Если доставка не удается, ошибка записывается в журнал, а запуск все равно виден через WebChat/журналы сеанса.

## Полезная нагрузка пересылки

- `VoiceWakeForwarder.prefixedTranscript(_:)` добавляет подсказку о машине перед отправкой. Используется совместно путями слова пробуждения и удержания клавиши для речи.

## Быстрая проверка

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

## Связанные разделы

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