docs: README — VAD smart command end

README.md

@@ -137,6 +137,33 @@ println!("{}", reply);
 
 Системный промпт (русский) описывает J.A.R.V.I.S. как британского дворецкого Тони Старка — короткие реплики (1–3 предложения), обращение «сэр», без излишней цензуры. Меняется в `config::LLM_SYSTEM_PROMPT_RU`.
 
+## VAD: умное завершение команды по тишине
+
+После срабатывания wake-word `jarvis-app` слушает команду. Раньше окно закрывалось либо по таймауту Vosk, либо по жёсткому пределу из `config::CMS_WAIT_DELAY` — короткие команды («стоп», «громче») всё равно ждали несколько секунд тишины.
+
+Теперь окно закрывается, как только пользователь замолчал. Реализовано через `webrtc-vad` (чистый Rust, тот же алгоритм, что в Python-версии). Это **паритет с Python v0.2.0**, где использовался `webrtcvad` с теми же параметрами.
+
+Логика (state-машина в `crates/jarvis-core/src/audio_processing/vad/listen_window.rs`):
+
+- Кадр VAD: 30 мс при 16 кГц = 480 сэмплов = 960 байт (mono i16). Кадры с микрофона (по 512 сэмплов от `pv_recorder`) аккумулируются и режутся на VAD-кадры адаптером `WebRtcVad::push_samples`.
+- Каждый VAD-кадр учитывается в счётчиках `speech_ms` / `silence_ms`.
+- Окно закрывается, когда `silence_ms >= VAD_COMMAND_END_SILENCE_MS` И `speech_ms >= VAD_COMMAND_MIN_SPEECH_MS`.
+- До истечения `VAD_COMMAND_MIN_LISTEN_MS` окно не закрывается — пользователю даётся время начать говорить.
+- При достижении `VAD_COMMAND_MAX_LISTEN_MS` срабатывает hard-cap и управление возвращается в режим ожидания wake-word.
+- На событии «закрыть окно» вызывается `stt::finalize_speech()` — Vosk форсированно отдаёт финальный результат, не дожидаясь собственного таймаута.
+
+Параметры (`crates/jarvis-core/src/config.rs`):
+
+| Константа                       | Значение | Назначение                                                  |
+|---------------------------------|----------|-------------------------------------------------------------|
+| `VAD_AGGRESSIVENESS`            | `2`      | Уровень WebRTC VAD: 0 — Quality, 3 — VeryAggressive.        |
+| `VAD_COMMAND_END_SILENCE_MS`    | `1200`   | Сколько тишины подряд считать «команда закончилась».        |
+| `VAD_COMMAND_MIN_SPEECH_MS`     | `500`    | Минимум речи в окне — иначе закрытие игнорируется.          |
+| `VAD_COMMAND_MIN_LISTEN_MS`     | `1000`   | Минимальная длительность окна (страховка от ранних закрытий)|
+| `VAD_COMMAND_MAX_LISTEN_MS`     | `15000`  | Жёсткий потолок окна.                                       |
+
+На короткие команды отзыв стал заметно быстрее (мы выходим на распознавание сразу после паузы пользователя, а не по 5-секундному порогу Vosk).
+
 ## Лицензия
 
 Creative Commons **Attribution-NonCommercial-ShareAlike 4.0 International** (CC BY-NC-SA 4.0).