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

# Режими

• Режим слова пробудження (типово): постійно ввімкнений розпізнавач мовлення чекає на тригерні слова (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)); вони зменшуються після відпускання.

# Пов’язане

• Голосове пробудження
• Голосова накладка
• Застосунок macOS