npm - @goodandready/dsh-voice - Versions diffs - 0.8.9 → 0.8.11 - Mend

@goodandready/dsh-voice 0.8.9 → 0.8.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/LICENSE CHANGED Viewed

@@ -1,6 +1,6 @@
 MIT License
-Copyright (c) 2026 dsh-voice contributors
+Copyright (c) 2026 GooDAnDReaDY
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md CHANGED Viewed

@@ -1,216 +1,172 @@
-# dsh-voice
-Voice input for the DeepSeek Harness Web GUI, in two modes, each with its own
-provider fallback chain.
-**Dictation** — press the mic, talk, and the text lands in the composer as you
-go: speech is cut into phrases on silence and each phrase is transcribed on its
-own. Press again to stop; sending stays in your hands.
-**Voice message** — press the wave button, record, press again. The transcript
-is inserted and sent to the agent after a short cancel window.
-Both modes fall back across providers, so one outage or rate limit does not
-lose your recording. API keys never reach the browser: audio is posted to the
-plugin's own route and the host talks to the providers.
-## Install
-```bash
-# From npm:
-dsh plugin --profile web add @goodandready/dsh-voice
-# Locally from a checkout:
-dsh plugin --profile web add file:/path/to/dsh-voice
+# 📦 @goodandready/dsh-voice
+<div align="center">
+<h3>Zero-Latency Streaming Dictation & Multi-Provider Voice Input for DeepSeek Harness</h3>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-voice"><img src="https://img.shields.io/npm/v/@goodandready/dsh-voice.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a>
+</p>
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+</div>
+---
+## ⚡ Overview
+**`dsh-voice`** brings voice superpowers to the **DeepSeek Harness** Web UI. Whether you need hands-free real-time streaming dictation segmented on natural breath pauses or crisp voice notes with keyboard/mouse Push-to-Talk gestures, `dsh-voice` ensures your audio is never lost thanks to **automatic multi-provider fallback chains**.
+```mermaid
+graph LR
+    subgraph Client [Browser Web UI]
+        Mic[🎙️ Dictation Mic] -->|VAD Cut on Pause| Stream[Audio Chunks]
+        Wave[🌊 Voice Message] -->|Hold / Release| PTT[Push-to-Talk]
+    end
+    subgraph Host [DSH Host Backend]
+        Stream --> FFMPEG[ffmpeg 16kHz Transcoder]
+        PTT --> FFMPEG
+        FFMPEG --> Chain{Fallback Chain}
+        Chain -->|1st Priority| P1[Deepgram / Nova-2]
+        Chain -.->|On Rate Limit / 429| P2[Groq / Whisper Turbo]
+        Chain -.->|On Failure| P3[Local whisper.cpp / Offline]
+    end
+    subgraph Output [Target]
+        P1 --> Composer[💬 Web Composer / Chat]
+        P2 --> Composer
+        P3 --> Composer
+    end
+    style Client fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Host fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style Output fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
 ```
-Restart the Web UI afterwards, then hard-refresh the browser.
+---
-## Providers
+## ✨ Key Features
-| Key | Service | Default model | Credential |
-|---|---|---|---|
-| `browser` | the browser's own speech recognition | — | none, and nothing is uploaded to the host |
-| `deepgram` | Deepgram | `nova-2` | `DEEPGRAM_API_KEY` |
-| `groq` | Groq | `whisper-large-v3-turbo` | `GROQ_API_KEY` |
-| `hf` | HuggingFace Inference | `openai/whisper-large-v3` | `HF_TOKEN` |
-| `local-whisper` | local whisper.cpp server | model given at server start | none, fully offline |
+* 🎙️ **Streaming Dictation with VAD**: Speech is automatically sliced at natural pauses (`vadSilenceMs`, default 700ms) and typed into the composer in real time.
+* 🌊 **Voice Notes with Cancel Window**: Record your thought and have it automatically dispatched to the agent after a safety countdown (`autoSendMs`, default 4000ms).
+* 🎮 **Tactile Push-to-Talk**:
+  * **Mouse**: Hold the wave button — releasing sends the message; dragging pointer away discards.
+  * **Keyboard**: Hold <kbd>Ctrl</kbd> (or custom hotkey) for hands-free speaking; press <kbd>Esc</kbd> to cancel.
+* ⚡ **Zero-Latency In-Browser Captions (`browser`)**: Chrome Web Speech API recognition runs 100% locally with live floating captions as you speak.
+* 🛡️ **Ironclad Multi-Provider Fallbacks**: If your primary cloud provider runs out of credits or hits a 429 rate limit, requests seamlessly fail over down the chain.
+* 🧠 **Context Glossary Injection**: Automatically extracts code variables and identifiers from your composer draft to steer STT model accuracy on technical jargon.
+* 🎵 **Embedded Audio Player**: Preview, scrubber, and playback of your recorded voice message directly in chat and the composer dock.
+* 🔇 **Hardware Noise Suppression Toggle**: Configurable in settings to toggle browser-level noise suppression, echo cancellation, and auto gain control.
+* 📊 **Provider Latency & Health Dashboard**: Live visual telemetry of provider latency (ms), success rates, and errors directly within the settings UI.
+* 🔒 **Zero API Key Leakage**: Keys are resolved on the host via `ctx.credentials` (`credentialRef`) and never transmitted to browser clients.
+* 🖥️ **Offline Local Whisper Server**: Automatically boots and manages [whisper.cpp](https://github.com/ggerganov/whisper.cpp) (`whisper-server`) with on-the-fly `ffmpeg` transcode.
+* ⚡ **SenseVoice-ONNX / Sherpa-ONNX** *(0.8.11)*: Ultra-fast (~50–100ms) non-autoregressive local STT engine with automatic emotion/event tag stripping. Supports both Sherpa-ONNX HTTP and OpenAI-compatible endpoints.
+* 🌐 **Realtime Audio Streaming** *(0.8.11)*: Low-latency WebSocket bridge (`/dsh-voice/realtime`) for OpenAI Realtime API or local Sherpa-ONNX streaming. API keys stay securely on the host.
-Keys are read through the DSH credentials service (Settings → Credentials, or
-`$DSH_HOME/.credentials.yaml`), falling back to the process environment. A
-provider without a key is skipped, not fatal.
+---
-### Ready-made providers
+## 🎮 Four Ways to Speak
-Six providers are filled in already — put the name in a chain and add the key:
-| Name | Model | Credential |
+| Mode | Gesture / Trigger | Behavior |
 |---|---|---|
-| `openai` | `whisper-1` | `OPENAI_API_KEY` |
-| `siliconflow` | `FunAudioLLM/SenseVoiceSmall` | `SILICONFLOW_API_KEY` |
-| `deepinfra` | `openai/whisper-large-v3-turbo` | `DEEPINFRA_API_KEY` |
-| `fireworks` | `whisper-v3-turbo` | `FIREWORKS_API_KEY` |
-| `mistral` | `voxtral-mini-latest` | `MISTRAL_API_KEY` |
-| `openrouter` | `google/gemini-2.5-flash` | `OPENROUTER_API_KEY` |
-```yaml
-- id: dsh-voice
-  config:
-    message:
-      chain:
-        - provider: openai
-        - provider: local-whisper
-```
-Every endpoint was probed without a key before being written down: all six answered `401`, the answer of a path that exists and wants credentials. The model ids are starting points — override `model` in a chain row to change one.
+| **Dictation** | Click <kbd>🎙️ Mic</kbd> | Speech is sliced on pauses (`vadSilenceMs`) and typed live into composer |
+| **Voice Message** | Click <kbd>🌊 Wave</kbd> | Records until stopped, then sends after cancel window (`autoSendMs`) |
+| **Mouse PTT** | Hold <kbd>🌊 Wave</kbd> | Records while held; release sends message, drag off button to discard |
+| **Keyboard PTT** | Hold <kbd>Ctrl</kbd> | Hands-free recording; release sends message, press <kbd>Esc</kbd> to discard |
-A preset is the same form as a custom provider with the fields filled in, so a `customProviders` entry under the same name replaces it outright.
+> [!TIP]
+> You can customize the keyboard modifier in settings (`hotkey`: `Control`, `Alt`, `Shift`, or any `KeyboardEvent.code`).
-### Your own providers
+---
-Any OpenAI-compatible API can be added as a provider and used in the chains
-next to the built-in ones. Two templates, because those APIs disagree on how
-audio is sent:
+## 🛠️ Supported Providers Matrix
-| Template | Endpoint | Request | Transcript read from |
-|---|---|---|---|
-| `openai-transcriptions` | `{baseURL}/audio/transcriptions` | multipart: file, model, language | `text` |
-| `openai-chat-audio` | `{baseURL}/chat/completions` | JSON with `input_audio`: base64 and format | `choices[0].message.content` |
+| Provider Key | Service Backend | Default Model | Credential Ref | Features & Notes |
+|---|---|---|---|---|
+| `browser` | Web Speech API | Native Browser | *None* | Zero latency, floating live captions in Chrome |
+| `deepgram` | Deepgram API | `nova-2` | `DEEPGRAM_API_KEY` | Ultra-fast cloud transcription |
+| `groq` | Groq Whisper | `whisper-large-v3-turbo` | `GROQ_API_KEY` | Near-instant inference speed |
+| `hf` | HuggingFace Inference | `openai/whisper-large-v3` | `HF_TOKEN` | High-accuracy open Whisper |
+| `local-whisper` | Local whisper.cpp | Server defined | *None* | 100% private, offline, no internet needed |
+| `sensevoice` | SenseVoice-ONNX / Sherpa-ONNX | `SenseVoiceSmall` | *None* | Ultra-fast (~50ms) local non-autoregressive STT |
-OpenRouter has no `/audio/transcriptions` endpoint at all — use the chat
-template there:
+### 🚀 Ready-Made Presets (Plug & Play)
-```yaml
-- id: dsh-voice
-  config:
-    customProviders:
-      - key: openrouter
-        template: openai-chat-audio
-        baseURL: https://openrouter.ai/api/v1
-        model: google/gemini-2.5-flash
-        keyEnv: OPENROUTER_API_KEY
-    message:
-      chain:
-        - provider: openrouter
-        - provider: local-whisper
-```
+Just specify the name in your fallback chain and add the corresponding API key:
+* `openai` (`whisper-1`) → `OPENAI_API_KEY`
+* `siliconflow` (`SenseVoiceSmall`) → `SILICONFLOW_API_KEY`
+* `mistral` (`voxtral-mini-latest`) → `MISTRAL_API_KEY`
+* `openrouter` (`google/gemini-2.5-flash`) → `OPENROUTER_API_KEY`
+* `deepinfra` (`whisper-large-v3-turbo`) → `DEEPINFRA_API_KEY`
+* `fireworks` (`whisper-v3-turbo`) → `FIREWORKS_API_KEY`
-Fields: `key` is the name the chains refer to (it cannot shadow a built-in
-one), `keyEnv` names the credential holding the API key (empty means no
-authorization header), and `prompt` overrides the instruction sent with the
-audio in the chat template. A row in a chain may still override `model`.
+---
-The chat template accepts WAV and MP3 only, while the browser records
-webm/opus — the plugin converts with ffmpeg, the same way the local whisper
-provider does, so **ffmpeg is required for `openai-chat-audio`**.
+## 📦 Quick Installation
-## Three ways to speak
+```bash
+dsh plugin --profile web add @goodandready/dsh-voice
+```
-| Gesture | What happens |
-|---|---|
-| Click the microphone | dictation: speech is cut on pauses and each phrase is appended to the composer |
-| Click the wave | a voice message: recording runs until you stop it, then the text is sent after a cancel window |
-| **Hold the wave** | records only while held; release sends it, moving the pointer off the button discards |
-| **Hold `Ctrl`** | the same without reaching for the mouse; `Escape` discards |
+> [!IMPORTANT]
+> Restart DSH Web UI after installation (`systemctl --user restart dsh-web`) and refresh your browser tab.
-The hotkey is `hotkey` in the settings — a modifier name (`Control`, `Alt`, `Shift`) or a `KeyboardEvent` code. Empty turns it off.
+---
-## Recognition in the browser
+## ⚙️ Configuration
-Put `browser` first in a chain and speech is recognised by the browser itself: no key, no upload to this host, and the text appears **while you are still speaking** — an interim caption in the recording bar, with each finished phrase going into the composer.
+Open **Settings → Plugins → Plugin settings → Voice** in the Web UI:
 ```yaml
 - id: dsh-voice
   config:
     dictation:
+      language: ru
+      vadSilenceMs: 700
       chain:
-        - provider: browser
-        - provider: local-whisper   # если браузер не умеет — обычный путь
-```
-Two things to know before choosing it:
-- **Chrome sends the audio to Google.** Firefox has no such API at all. Everything else in this plugin keeps audio between your browser and your own host, so this provider is the one exception — it is never used unless you put it in a chain yourself.
-- It needs a secure context (HTTPS or localhost), like the microphone itself.
-Put a normal provider after it: if the browser cannot do it, recording falls back to the chain as usual.
-## Configure (Web GUI)
-Settings → **Plugins → Plugin settings → Voice** — the plugin's own
-collapsible card in the plugins tab; the sidebar keeps no separate row for it.
-The card has four blocks:
-- **Dictation** — fallback chain (provider + optional model per row, order is
-  the order of attempts), language, and the silence threshold that ends a
-  phrase (`vadSilenceMs`, default 700 ms).
-- **Voice message** — its own independent chain, language, and the cancel
-  window before the message is sent (`autoSendMs`, default 4000 ms).
-- **Your own providers** — an OpenAI-compatible API per card: name, template,
-  base URL, model, credential name. The name becomes selectable in both chains
-  as soon as it is filled in.
-- **General** — local whisper endpoint, binary, model, autostart, beep, localOnly,
-  microphone, custom vocabulary, offline polish endpoint (`polishBaseUrl`/`polishModel`/`polishKeyEnv`).
-- **Voice message** also has `polishSend` (polish the whole draft before sending) and
-  `sessionCommands` ("send", "cancel", "stop", "continue" act on the session instead of text).
-- **Dictation** also has a wake word: browser recognition starts recording when speech
-  begins with that phrase (empty disables it).
-Speed matters for dictation and accuracy for messages, which is why the chains
-are separate: a sensible pair is Deepgram → Groq → local for dictation and
-Groq → HuggingFace → local for messages.
-## Local whisper.cpp
-The local provider needs a running [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
-server:
-```bash
-whisper-server -m /path/to/ggml-medium-q8_0.bin --host 127.0.0.1 --port 8001
+        - provider: deepgram
+        - provider: groq
+        - provider: local-whisper
+    message:
+      language: ru
+      autoSendMs: 4000
+      chain:
+        - provider: openai
+        - provider: local-whisper
+    hotkey: Control
+    autoStart: true
+    whisperModel: /models/ggml-medium-q8_0.bin
 ```
-Set `whisperModel` (and `whisperBin` if it is not in `PATH`) and the plugin
-launches the server itself when `autoStart` is on. While `whisperModel` is
-empty, autostart stays off.
-**ffmpeg is required for this provider.** whisper.cpp accepts WAV only and
-rejects the webm/opus the browser records, so the host converts each recording
-to 16 kHz mono WAV before forwarding it. Point `ffmpegBin` at your binary if it
-is not in `PATH`.
-## Tool
+---
-The plugin also registers `transcribe_audio(file_path, language?)` for the
-agent, using the voice-message chain. Useful for recordings and interviews that
-are already files on disk.
-## Routes
-| Route | Purpose |
-|---|---|
-| `POST /dsh-voice/transcribe` | `{dataBase64, mimeType, mode}` → `{ok, text, provider, tookMs}` |
-| `GET /dsh-voice/status` | whisper server state and the effective chains |
-## Structure
-```
-lib/index.js       host: config, routes, transcribe_audio, whisper autostart
-lib/providers.js   the four providers, pure functions (network injected)
-lib/chain.js       fallback walk over a chain
-lib/wav.js         webm/opus → WAV 16 kHz mono via ffmpeg
-lib/client.js      browser: composer buttons, recording, settings page
-test/              node --test units for the chain and the providers
-```
+## 🤖 Agent Tool & HTTP API
-Run the tests with `npm test` (no dependencies, Node's built-in runner).
+### Agent Tool (`transcribe_audio`)
+Registers `transcribe_audio(file_path, language?)` in `ctx.tools`, allowing agents to analyze audio files, interview recordings, and voice notes directly from disk.
-## Requirements
+### Internal HTTP Endpoints
+* `POST /dsh-voice/transcribe` — `{ dataBase64, mimeType, mode }` → `{ ok, text, provider, tookMs }`
+* `POST /dsh-voice/polish` — `{ text }` → `{ ok, text }`
+* `GET /dsh-voice/status` — Returns daemon status, active chains, SenseVoice and realtime config.
+* `GET /dsh-voice/realtime` — **WebSocket upgrade** for low-latency audio streaming (OpenAI Realtime API / Sherpa-ONNX). Accepts binary audio chunks, returns JSON text deltas.
-- DeepSeek Harness with the Web GUI
-- Node 20+
-- ffmpeg, for the local whisper provider
-- a microphone reachable from the browser (HTTPS or localhost)
+---
-## License
+## 📄 License
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.ru.md ADDED Viewed

@@ -0,0 +1,172 @@
+# 📦 @goodandready/dsh-voice
+<div align="center">
+<h3>Потоковая диктовка без задержек и мультиязычный голосовой ввод для DeepSeek Harness</h3>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-voice"><img src="https://img.shields.io/npm/v/@goodandready/dsh-voice.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+</div>
+---
+## ⚡ Обзор
+**`dsh-voice`** добавляет полноценные голосовые возможности в веб-интерфейс **DeepSeek Harness**. Будь то непрерывная диктовка с нарезкой фраз по естественным паузам или голосовые сообщения с удобными жестами Push-to-Talk (мышь и клавиатура) — `dsh-voice` гарантирует сохранность каждой записи благодаря **автоматическим цепочкам отказоустойчивости**.
+```mermaid
+graph LR
+    subgraph Client [Браузер Web UI]
+        Mic[🎙️ Микрофон диктовки] -->|Нарезка фраз VAD| Stream[Аудио-чанки]
+        Wave[🌊 Голосовое сообщение] -->|Зажатие / Отпускание| PTT[Push-to-Talk]
+    end
+    subgraph Host [Бэкенд DSH Host]
+        Stream --> FFMPEG[Транскодер ffmpeg 16кГц]
+        PTT --> FFMPEG
+        FFMPEG --> Chain{Цепочка фолбеков}
+        Chain -->|1-й приоритет| P1[Deepgram / Nova-2]
+        Chain -.->|При лимитах / 429| P2[Groq / Whisper Turbo]
+        Chain -.->|При сбое| P3[Локальный whisper.cpp]
+    end
+    subgraph Output [Результат]
+        P1 --> Composer[💬 Строка ввода чата]
+        P2 --> Composer
+        P3 --> Composer
+    end
+    style Client fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Host fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style Output fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+```
+---
+## ✨ Ключевые возможности
+* 🎙️ **Потоковая диктовка с VAD**: аудиопоток режется по естественным паузам речи (`vadSilenceMs`, по умолчанию 700 мс) и мгновенно печатается в поле ввода.
+* 🌊 **Голосовые заметки с окном отмены**: запишите законченную мысль — сообщение автоматически уйдёт агенту по истечении таймера (`autoSendMs`, по умолчанию 4000 мс).
+* 🎮 **Тактильный Push-to-Talk**:
+  * **Мышь**: зажмите кнопку волны — запись идёт пока кнопка зажата; отпускание отправляет, увод курсора отменяет запись.
+  * **Клавиатура**: зажмите <kbd>Ctrl</kbd> для записи без мыши; нажмите <kbd>Esc</kbd> для отмены.
+* ⚡ **Субтитры браузера в реальном времени (`browser`)**: локальное распознавание Chrome Web Speech API без отправки звука на сервер с плавающими субтитрами.
+* 🛡️ **Надёжные цепочки фолбеков**: при исчерпании квоты или ошибке 429 плагин мгновенно обращается к следующему провайдеру в списке.
+* 🧠 **Контекстный словарь (Context Glossary)**: автоматическое извлечение переменных и технических терминов из черновика композера для точного распознавания редких слов и кода.
+* 🎵 **Встроенный аудиоплеер**: предпросмотр и воспроизведение записанного голосового сообщения в чате и доке перед отправкой или для переслушивания.
+* 🔇 **Аппаратное шумоподавление**: переключатель в настройках для включения/выключения браузерного шумоподавления, эхоподавления и АРУ.
+* 📊 **Дашборд задержки и здоровья провайдеров**: мониторинг скорости ответа (мс), процента успешных транскрипций и ошибок в реальном времени.
+* 🔒 **Безопасность API-ключей**: ключи читаются на сервере через `ctx.credentials` и никогда не попадают в браузер клиента.
+* 🖥️ **Автозапуск локального whisper.cpp**: управление жизненным циклом `whisper-server` с авто-конвертацией через `ffmpeg`.
+* ⚡ **SenseVoice-ONNX / Sherpa-ONNX** *(0.8.11)*: сверхбыстрый (~50–100мс) неавторегрессивный локальный STT с автоматической очисткой тегов эмоций/событий. Поддержка Sherpa-ONNX HTTP и OpenAI-совместимых эндпоинтов.
+* 🌐 **Потоковое аудио в реальном времени** *(0.8.11)*: низколатентный WebSocket-мост (`/dsh-voice/realtime`) для OpenAI Realtime API или локального Sherpa-ONNX. API-ключи остаются на хосте.
+---
+## 🎮 4 способа голосового ввода
+| Режим | Жест / Активация | Поведение |
+|---|---|---|
+| **Диктовка** | Клик <kbd>🎙️ Микрофон</kbd> | Речь режется по паузам (`vadSilenceMs`) и вставляется прямо в строку ввода |
+| **Голосовое сообщение** | Клик <kbd>🌊 Волна</kbd> | Запись до нажатия стоп, затем отправка с окном отмены (`autoSendMs`) |
+| **PTT Мышью** | Зажатие <kbd>🌊 Волна</kbd> | Запись пока зажата кнопка; отпускание отправляет, увод мыши сбрасывает |
+| **PTT Клавиатурой** | Зажатие <kbd>Ctrl</kbd> | Запись без мыши; отпускание отправляет, нажатие <kbd>Esc</kbd> отменяет |
+> [!TIP]
+> Клавиатурную клавишу можно легко переопределить в настройках (`hotkey`: `Control`, `Alt`, `Shift` или любой код клавиши).
+---
+## 🛠️ Матрица поддерживаемых провайдеров
+| Ключ | Сервис | Модель по умолчанию | Переменная секрета | Особенности |
+|---|---|---|---|---|
+| `browser` | Web Speech API | Нативная в браузере | *Не требуется* | Нулевая задержка, живые субтитры в Chrome |
+| `deepgram` | Deepgram API | `nova-2` | `DEEPGRAM_API_KEY` | Сверхбыстрая облачная транскрипция |
+| `groq` | Groq Whisper | `whisper-large-v3-turbo` | `GROQ_API_KEY` | Мгновенная скорость генерации |
+| `hf` | HuggingFace Inference | `openai/whisper-large-v3` | `HF_TOKEN` | Высокоточный облачный Whisper |
+| `local-whisper` | Локальный whisper.cpp | из параметров сервера | *Не требуется* | 100% приватность, оффлайн, без интернета |
+| `sensevoice` | SenseVoice-ONNX / Sherpa-ONNX | `SenseVoiceSmall` | *Не требуется* | Сверхбыстрый (~50мс) локальный неавторегрессивный STT |
+### 🚀 Готовые пресеты (Plug & Play)
+Достаточно указать имя в цепочке и добавить API-ключ:
+* `openai` (`whisper-1`) → `OPENAI_API_KEY`
+* `siliconflow` (`SenseVoiceSmall`) → `SILICONFLOW_API_KEY`
+* `mistral` (`voxtral-mini-latest`) → `MISTRAL_API_KEY`
+* `openrouter` (`google/gemini-2.5-flash`) → `OPENROUTER_API_KEY`
+* `deepinfra` (`whisper-large-v3-turbo`) → `DEEPINFRA_API_KEY`
+* `fireworks` (`whisper-v3-turbo`) → `FIREWORKS_API_KEY`
+---
+## 📦 Быстрая установка
+```bash
+dsh plugin --profile web add @goodandready/dsh-voice
+```
+> [!IMPORTANT]
+> Перезапустите Web UI после установки (`systemctl --user restart dsh-web`) и обновите страницу в браузере.
+---
+## ⚙️ Настройка конфигурации
+Откройте **Настройки → Плагины → Настройки плагинов → Голос** в Web UI:
+```yaml
+- id: dsh-voice
+  config:
+    dictation:
+      language: ru
+      vadSilenceMs: 700
+      chain:
+        - provider: deepgram
+        - provider: groq
+        - provider: local-whisper
+    message:
+      language: ru
+      autoSendMs: 4000
+      chain:
+        - provider: openai
+        - provider: local-whisper
+    hotkey: Control
+    autoStart: true
+    whisperModel: /models/ggml-medium-q8_0.bin
+```
+---
+## 🤖 Инструмент агента и HTTP API
+### Инструмент агента (`transcribe_audio`)
+Регистрирует `transcribe_audio(file_path, language?)` в `ctx.tools`, позволяя агентам распознавать аудиофайлы, интервью и записи с диска.
+### Внутренние HTTP эндпоинты
+* `POST /dsh-voice/transcribe` — `{ dataBase64, mimeType, mode }` → `{ ok, text, provider, tookMs }`
+* `POST /dsh-voice/polish` — `{ text }` → `{ ok, text }`
+* `GET /dsh-voice/status` — состояние демонов, цепочки, конфигурация SenseVoice и реалтайма.
+* `GET /dsh-voice/realtime` — **WebSocket upgrade** для низколатентного аудио-стриминга (OpenAI Realtime API / Sherpa-ONNX). Принимает бинарные аудио-чанки, возвращает JSON-дельты текста.
+---
+## 📄 Лицензия
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)