@goodandready/dsh-tts 0.3.16 → 0.3.20

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 dsh-tts 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

@@ -1,100 +1,205 @@
-# dsh-tts
-
-Text-to-speech for the DeepSeek Harness Web GUI. When **Speak agent replies**
-is on, each finished assistant turn is synthesized on the host and played in
-the browser. API keys never reach the browser.
-
-A later messenger hub can call the same host chain (`POST /dsh-tts/speak` or
-the `speak_text` tool). This package does not talk to Telegram itself.
+# 📦 @goodandready/dsh-tts
+
+<div align="center">
+
+<h3>Multi-Provider Text-to-Speech Voice Synthesis with Local Neural Engines, Sub-300ms Streaming, IT Dictionary & Messenger Integration for DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-tts"><img src="https://img.shields.io/npm/v/@goodandready/dsh-tts.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-tts`** provides robust, lifelike spoken voice synthesis for assistant replies in the **DeepSeek Harness** Web UI. When **Speak agent replies** is enabled, each finished assistant turn or real-time streaming chunk is synthesized on the host and streamed directly to the browser.
+
+API keys never reach client browsers: synthesis is executed entirely on the host backend across **independent multi-provider fallback chains**, including completely offline neural models (Kokoro-82M and F5-TTS).
+
+```mermaid
+graph LR
+    subgraph Input [Assistant Message]
+        Reply[💬 Agent Reply Text] --> Scrub[Smart Text Scrubbing & IT Dictionary]
+    end
+
+    subgraph Stream [Low-Latency Streaming]
+        Scrub --> SSE[SSE /dsh-tts/stream]
+        SSE --> Worklet[AudioWorklet PCM Processor]
+    end
+
+    subgraph Cache [Performance Layer]
+        Scrub --> LRU{Disk LRU Cache}
+        LRU -->|Cache Hit| Play[Immediate Audio Playback]
+    end
+
+    subgraph Fallback [TTS Provider Fallback Chain]
+        LRU -->|Cache Miss| Chain{Active Chain}
+        Chain -->|Priority 1| P1[Kokoro / F5-TTS Local Offline]
+        Chain -.->|Cloud Neural| P2[ElevenLabs / OpenAI / CosyVoice]
+        Chain -.->|Free Cloud / Edge| P3[EdgeTTS / SiliconFlow]
+        Chain -.->|System Fallback| P4[Local Piper / eSpeak NG]
+    end
+
+    subgraph Output [Delivery & Integrations]
+        P1 --> Store[Save to Cache]
+        P2 --> Store
+        P3 --> Store
+        P4 --> Store
+        Store --> Play
+        Store --> Msg[Telegram / Discord via dsh-messenger-gateway]
+    end
+
+    style Input fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Stream fill:#181825,stroke:#89dceb,stroke-width:2px,color:#cdd6f4
+    style Cache fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style Fallback fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style Output fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+```
 
-## Install
+---
+
+## 🚀 Key Features
+
+### 1. 📴 Offline Local Neural Engines (Kokoro CPU & F5-TTS GPU)
+* **Kokoro-82M (CPU)**: 82M-parameter lightweight neural model running locally on CPU via ONNX Runtime. High-speed synthesis with zero cloud dependencies.
+* **F5-TTS (GPU)**: Zero-shot diffusion transformer voice synthesis running on NVIDIA GPUs via a local inference daemon.
+* **ModelManager UI**: Direct manual installation in settings with real-time download progress bar, SHA-256 validation, and deletion. No silent or automatic multi-gigabyte downloads.
+
+### 2. ⚡ Real-Time Streaming Audio (< 300 ms Latency)
+* **AudioWorklet (`TTSWorklet`)**: High-performance Web Audio Worklet processor playing seamless Float32Array PCM chunks at 24 kHz without audible clicks or buffer underruns.
+* **Server-Sent Events (SSE)**: Dedicated `/dsh-tts/stream` route delivering synthesized chunks to connected browsers instantly.
+
+### 3. 🎙️ Voice Duplex & VAD Barge-In (with `@goodandready/dsh-voice`)
+* **Full-Duplex Conversation**: Automatic voice reply synthesis upon completion of speech dictation.
+* **VAD Barge-In**: Immediately mutes assistant speech playback when user voice activity is detected.
+* **Installation Guard**: If `@goodandready/dsh-voice` is not present, settings controls are disabled with an explicit instruction banner (`dsh plugin --profile web add @goodandready/dsh-voice`).
+
+### 4. 📚 Built-in IT Terminology Pronunciation Dictionary
+* **Pre-configured Lexicon**: Correct phonetic pronunciation for common technical abbreviations and developer terms:
+  - `SQL` $\rightarrow$ "сиквел"
+  - `Nginx` $\rightarrow$ "энджинкс"
+  - `Kubernetes` / `K8s` $\rightarrow$ "кубернетис"
+  - `Docker` $\rightarrow$ "докер", `API` $\rightarrow$ "апи", `JSON` $\rightarrow$ "джейсон", `YAML` $\rightarrow$ "ямл"
+  - `GUI`, `CLI`, `CI/CD`, `PR`, `Regex`, `OAuth`, `HTTP`, `HTTPS`, `CPU`, `GPU`, `RAM`
+* **Interactive UI Editor**: Edit rules, preview phonetic substitutions with the **▶ Listen** button, and populate standard IT terms with one click.
+
+### 5. 👥 Multi-Agent Personas & Subagent Voice Overrides
+* Assign distinct voices, providers, models, and audio chimes to individual subagents (e.g. `coder`, `reviewer`, `planner`, `tester`).
+* Automatically matches incoming assistant turn events (`session.agent` or `message.agent`).
+
+### 6. 💬 Messenger Voice Notes Integration (with `@goodandready/dsh-messenger-gateway`)
+* Generates voice audio for Telegram and Discord bot replies via `POST /dsh-tts/speak`.
+* Protective dependency check with installation hint when gateway plugin is missing.
+
+---
+
+## 🛠️ Complete Supported Providers Matrix (18 Backends)
+
+| Provider Key | Service Backend | Default Model | Default Voice | Credential Ref | Features & Notes |
+|---|---|---|---|---|---|
+| `kokoro` | Local Kokoro-82M ONNX | `hexgrad/Kokoro-82M` | `af_bella` | *None* | **100% offline CPU neural synthesis** |
+| `f5` | Local F5-TTS GPU Daemon | `F5-TTS` | Default | *None* | **High-fidelity GPU zero-shot voice synthesis** |
+| `elevenlabs` | ElevenLabs API | `eleven_multilingual_v2` | `Rachel` | `ELEVENLABS_API_KEY` | Ultra-realistic, emotional nuance |
+| `openai` | OpenAI Audio | `gpt-4o-mini-tts` / `tts-1` | `alloy` | `OPENAI_API_KEY` | High-quality industry standard |
+| `edge` | Microsoft Edge Online | `ru-RU-SvetlanaNeural` | `ru-RU-SvetlanaNeural` | *None* | **Free, high-fidelity neural TTS without API keys** |
+| `siliconflow` | SiliconFlow CosyVoice | `FunAudioLLM/CosyVoice2-0.5B` | Default | `SILICONFLOW_API_KEY` | State-of-the-art CosyVoice2 neural engine |
+| `deepinfra` | DeepInfra Kokoro | `hexgrad/Kokoro-82M` | Default | `DEEPINFRA_API_KEY` | Fast open-weights Kokoro synthesis |
+| `fireworks` | Fireworks AI | `kokoro` | Default | `FIREWORKS_API_KEY` | Ultra-low latency Kokoro inference |
+| `minimax` | MiniMax Speech | `speech-01-turbo` | Default | `MINIMAX_API_KEY` | High-expressiveness neural voice |
+| `mimo` | Xiaomi MiMo Audio | `mimo-v2.5-tts` | Default | `MIMO_API_KEY` | Low-latency streaming TTS |
+| `google` | Google Cloud TTS | `gemini-2.5-flash-preview-tts` | Language default | `GEMINI_API_KEY` | Multilingual Google Gemini voice synthesis |
+| `azure` | Azure Cognitive Speech | `en-US-JennyNeural` | Region default | `AZURE_SPEECH_KEY` | Enterprise neural synthesis |
+| `deepgram` | Deepgram Aura | `aura-asteria-en` | `asteria` | `DEEPGRAM_API_KEY` | Ultra-low latency voice output |
+| `groq` | Groq TTS | `playai-tts` | `default` | `GROQ_API_KEY` | Near-instant inference speed |
+| `openrouter` | OpenRouter Audio | `openai/gpt-4o-mini-tts` | `alloy` | `OPENROUTER_API_KEY` | Unified router access |
+| `custom` | Custom OpenAI-compatible | Configurable | Configurable | `CUSTOM_TTS_API_KEY` | Any `/v1/audio/speech` endpoint |
+| `piper` | Local Piper ONNX | Local ONNX weights | Model default | *None* | 100% offline neural engine |
+| `espeak` | Local eSpeak NG | System synth | `ru` / `en` | *None* | 100% offline lightweight fallback |
+
+---
+
+## 🧹 Smart Text Scrubbing & Formatting Engine
+
+Before text reaches speech synthesizers, `dsh-tts` intelligently sanitizes and filters the message so the assistant doesn't read out syntax noise:
+* **Fenced Code Blocks**: Spoken as *"code block, N lines"* / *"блок кода, N строк"*.
+* **Markdown Tables**: Spoken as *"table, N rows"* / *"таблица, N строк"*.
+* **Summary Intros**: Spoken as *"Summary of the reply"* / *"Пересказ ответа"*.
+* **Narration Filters**: Skip asterisk actions (`*smiles*`), narrate quotes only, and apply custom regex removal.
+
+---
+
+## 📦 Quick Installation
 
 ```bash
-# From npm (after a GitHub/npm release):
 dsh plugin --profile web add @goodandready/dsh-tts
-
-# From a local checkout:
-dsh plugin --profile web add file:/path/to/dsh-tts
 ```
 
-Restart the Web UI, then hard-refresh the browser.
-
-## Configure
-
-Settings -> **Speech**:
-
-- **Speak agent replies** -- off by default.
-- **Provider chain** -- pick a provider, paste its API key in that row, then
-  Save (or leave the key field). The value is written to the host credentials
-  store immediately and is never sent back to the browser. The row shows
-  **Configured** / **Not set**. Leave the field blank to keep an existing key.
-  Local providers (`edge`, `piper`, `espeak`) have no key field.
-- A provider without a credential is skipped, not fatal.
-- Piper / eSpeak / edge-tts binaries and the Piper model path.
-
-Keys land in the same store the rest of DSH uses (credentials file, then the
-process environment). The plugin stores names, never values:
-
-```text
-OPENAI_API_KEY
-ELEVENLABS_API_KEY
-GEMINI_API_KEY
-AZURE_SPEECH_KEY
-GROQ_API_KEY
-DEEPGRAM_API_KEY
-OPENROUTER_API_KEY
+> [!IMPORTANT]
+> Restart DSH Web UI after installation (`systemctl --user restart dsh-web`) and refresh your browser tab.
+
+---
+
+## ⚙️ Configuration Recipes (`settings.yaml`)
+
+```yaml
+dsh-tts:
+  speakReplies: true
+  enableLocalEngines: true
+  kokoroEnabled: true
+  streamingEnabled: true
+  enableItDictionary: true
+  voiceDuplexEnabled: true
+  vadBargeIn: true
+  messengerTtsEnabled: true
+  cache: true
+  cacheMaxMb: 150
+  autoDetect: true
+  chain:
+    - provider: kokoro
+    - provider: edge
+      voice: ru-RU-SvetlanaNeural
+    - provider: openai
+      model: tts-1
+      voice: alloy
+  roles:
+    coder:
+      provider: openai
+      voice: onyx
+    reviewer:
+      provider: edge
+      voice: ru-RU-DmitryNeural
 ```
 
-Put additional keys in the same pool (`<PROVIDER>_API_KEY_2`, ...) if you use
-a key-rotation plugin.
-
-## Providers
-
-| Key | Service | Default model / voice | Credential |
-|---|---|---|---|
-| `openai` | OpenAI Audio Speech | `gpt-4o-mini-tts` / `alloy` | `OPENAI_API_KEY` |
-| `elevenlabs` | ElevenLabs | `eleven_multilingual_v2` | `ELEVENLABS_API_KEY` |
-| `google` | Gemini TTS | `gemini-2.5-flash-preview-tts` / `Kore` | `GEMINI_API_KEY` |
-| `azure` | Azure Speech | neural voice + region | `AZURE_SPEECH_KEY` + region |
-| `groq` | Groq PlayAI | `playai-tts` | `GROQ_API_KEY` |
-| `deepgram` | Deepgram Aura | `aura-asteria-en` | `DEEPGRAM_API_KEY` |
-| `openrouter` | OpenRouter `/audio/speech` | `openai/gpt-4o-mini-tts-2025-12-15` | `OPENROUTER_API_KEY` |
-| `edge` | Microsoft Edge Neural via `edge-tts` CLI | `ru-RU-SvetlanaNeural` | none |
-| `piper` | local Piper | path to an ONNX model | none |
-| `espeak` | eSpeak NG | voice `ru` | none |
-
-Default chain: `edge` → `piper` → `espeak`. Deepgram Aura does not list Russian;
-keep it below a Russian-capable voice if you speak Russian.
-
-### Free local / CLI providers
-
-```bash
-pip install edge-tts          # provides the `edge-tts` binary
-# piper: install the Piper binary and point Settings at your .onnx model
-sudo apt install espeak-ng    # or the equivalent package on your OS
-```
-
-## Tool
-
-`speak_text(text)` — synthesize with the same chain. The tool result is a short
-status line; it does not inject audio into the model history.
-
-## Routes
+---
 
-| Route | Purpose |
-|---|---|
-| `GET /dsh-tts/status` | chain and whether auto-speak is on |
-| `GET` or `PUT /dsh-tts/config` | settings plus configured/writable/ref per cloud provider. PUT may include keys; values are stored as credentials and never echoed. |
-| `PUT` or `DELETE /dsh-tts/credential` | writes or clears one host credential immediately |
-| `GET /dsh-tts/pending?after=` | audio produced for finished replies |
-| `POST /dsh-tts/speak` | `{text}` -> `{ok, provider, mime, audioBase64}` |
+## 🤖 HTTP Endpoints Reference
 
-## Requirements
+* `GET /dsh-tts/stream` — Real-time Server-Sent Events (SSE) audio streaming.
+* `POST /dsh-tts/speak` — `{ text, voice?, model? }` → Returns synthesized audio.
+* `POST /dsh-tts/preview` — `{ provider, model, voice, text? }` → Test voice playback in UI.
+* `GET /dsh-tts/models/status` — Reports local Kokoro and F5-TTS model installation states.
+* `POST /dsh-tts/models/install` — `{ engine: 'kokoro' | 'f5' }` → Starts HuggingFace model download.
+* `DELETE /dsh-tts/models/delete` — `{ engine: 'kokoro' | 'f5' }` → Removes local model files.
+* `GET /dsh-tts/integrations` — Status of sibling plugins (`dsh-voice`, `dsh-messenger-gateway`).
+* `GET /dsh-tts/status` — Returns active chain state, cache statistics, and engine readiness.
 
-- DeepSeek Harness with the Web GUI
-- Node 20+
-- Optional: `edge-tts`, `piper`, `espeak-ng` for the free providers
+---
 
-## License
+## 📄 License
 
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.ru.md

@@ -0,0 +1,195 @@
+# 📦 @goodandready/dsh-tts
+
+<div align="center">
+
+<h3>Многопровайдерная озвучка ответов агента с локальными нейродвижками, потоковым звуком (<300 мс), IT-словарём и интеграцией с мессенджерами для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-tts"><img src="https://img.shields.io/npm/v/@goodandready/dsh-tts.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-tts`** обеспечивает качественное голосовое озвучивание ответов ассистента в веб-интерфейсе **DeepSeek Harness**. При включённой опции **«Читать ответы агента»**, каждая готовая реплика или потоковый фрагмент синтезируется на хосте и мгновенно воспроизводится в браузере.
+
+API-ключи никогда не передаются в браузер: синтез аудио выполняется на стороне хоста через **независимые цепочки отказоустойчивости (фолбеков)**, включая полностью локальные оффлайн-нейросети (Kokoro-82M и F5-TTS).
+
+```mermaid
+graph LR
+    subgraph Input [Ответ ассистента]
+        Reply[💬 Текст ответа агента] --> Scrub[Умная очистка и IT-словарь]
+    end
+
+    subgraph Stream [Потоковый звук < 300 мс]
+        Scrub --> SSE[SSE /dsh-tts/stream]
+        SSE --> Worklet[AudioWorklet PCM процессор]
+    end
+
+    subgraph Cache [Слой производительности]
+        Scrub --> LRU{Дисковый LRU кэш}
+        LRU -->|Попадание в кэш| Play[Мгновенное воспроизведение]
+    end
+
+    subgraph Fallback [Цепочка фолбеков TTS]
+        LRU -->|Промах кэша| Chain{Активная цепочка}
+        Chain -->|1-й приоритет| P1[Kokoro / F5-TTS Локально]
+        Chain -.->|Облачные нейросети| P2[ElevenLabs / OpenAI / CosyVoice]
+        Chain -.->|Бесплатные облака| P3[EdgeTTS / SiliconFlow]
+        Chain -.->|Системный фолбек| P4[Локальный Piper / eSpeak NG]
+    end
+
+    subgraph Output [Вывод и интеграции]
+        P1 --> Store[Сохранение в кэш]
+        P2 --> Store
+        P3 --> Store
+        P4 --> Store
+        Store --> Play
+        Store --> Msg[Telegram / Discord через dsh-messenger-gateway]
+    end
+
+    style Input fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style Stream fill:#181825,stroke:#89dceb,stroke-width:2px,color:#cdd6f4
+    style Cache fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style Fallback fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style Output fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+```
+
+---
+
+## 🚀 Ключевые возможности
+
+### 1. 📴 Полностью локальные оффлайн-движки (Kokoro CPU и F5-TTS GPU)
+* **Kokoro-82M (CPU)**: Компактная нейросетевая модель (82 млн параметров), работающая локально на CPU через ONNX Runtime. Быстрый синтез без внешних API и интернета.
+* **F5-TTS (GPU)**: Диффузионный трансформер нулевого выстрела (zero-shot) на видеокартах NVIDIA через выделенный локальный демон инференса.
+* **ModelManager в UI**: Ручная загрузка моделей прямо из настроек плагина с отображением процентов и прогресс-бара, проверкой SHA-256 и кнопкой удаления. Никаких скрытых или автозагрузок гигабайтных весов.
+
+### 2. ⚡ Потоковое воспроизведение звука с задержкой < 300 мс
+* **AudioWorklet (`TTSWorklet`)**: Высокопроизводительный процессор веб-аудио с бесшовным кольцевым буфером для воспроизведения PCM-чанков (24 кГц) без щелчков и пауз.
+* **Server-Sent Events (SSE)**: Роут `/dsh-tts/stream` передаёт синтезированные куски речи сразу в браузер, исключая задержки традиционного полинга.
+
+### 3. 🎙️ Голосовой диалог и VAD Barge-In (в связке с `@goodandready/dsh-voice`)
+* **Voice-to-Voice дуплекс**: Автоматический запуск озвучки ответа сразу после завершения голосовой диктовки.
+* **VAD Barge-In**: Мгновенное глушение речи ассистента, как только пользователь начинает говорить в микрофон.
+* **Защитная блокировка**: Если плагин `@goodandready/dsh-voice` не установлен, переключатели блокируются (`disabled`), а в интерфейсе отображается подсказка: `dsh plugin --profile web add @goodandready/dsh-voice`.
+
+### 4. 📚 Предустановленный словарь IT-произношения
+* **Корректная транскрипция терминов**: Автоматическая замена аббревиатур и названий:
+  - `SQL` $\rightarrow$ «сиквел»
+  - `Nginx` $\rightarrow$ «энджинкс»
+  - `Kubernetes` / `K8s` $\rightarrow$ «кубернетис»
+  - `Docker` $\rightarrow$ «докер», `API` $\rightarrow$ «апи», `JSON` $\rightarrow$ «джейсон», `YAML` $\rightarrow$ «ямл»
+  - `GUI`, `CLI`, `CI/CD`, `PR`, `Regex`, `OAuth`, `HTTP`, `HTTPS`, `CPU`, `GPU`, `RAM`
+* **Интерактивный редактор в UI**: Правка правил, кнопка **«▶ Прослушать»** для каждого слова и кнопка **«Вставить IT-термины в таблицу»** в один клик.
+
+### 5. 👥 Персонализация голосов субагентов (Multi-Agent Personas)
+* Назначение индивидуального голоса, провайдера, модели и сигнала (chime) для каждого субагента (`coder`, `reviewer`, `planner`, `tester` и др.).
+* Автоматический перехват имени агента из событий сессии (`session.agent` или `event.data.agent`).
+
+### 6. 💬 Голосовые сообщения в мессенджеры (`@goodandready/dsh-messenger-gateway`)
+* Озвучивание ответов и отправка войсов в Telegram и Discord через роут `POST /dsh-tts/speak`.
+* Защитная проверка наличия плагина-шлюза с подсказкой по установке.
+
+---
+
+## 🛠️ Матрица поддерживаемых провайдеров (18 бэкендов)
+
+| Ключ провайдера | Сервис | Модель по умолчанию | Голос по умолчанию | Имя ключа (credential) | Особенности |
+|---|---|---|---|---|---|
+| `kokoro` | Локальный Kokoro-82M ONNX | `hexgrad/Kokoro-82M` | `af_bella` | *Не требуется* | **100% локальный нейросинтез на CPU** |
+| `f5` | Локальный F5-TTS GPU | `F5-TTS` | По умолчанию | *Не требуется* | **Качественный zero-shot синтез на NVIDIA GPU** |
+| `elevenlabs` | ElevenLabs API | `eleven_multilingual_v2` | `Rachel` | `ELEVENLABS_API_KEY` | Реалистичный эмоциональный синтез |
+| `openai` | OpenAI Audio | `gpt-4o-mini-tts` / `tts-1` | `alloy` | `OPENAI_API_KEY` | Эталонное качество индустрии |
+| `edge` | Microsoft Edge Online | `ru-RU-SvetlanaNeural` | `ru-RU-SvetlanaNeural` | *Не требуется* | **Бесплатный нейросинтез без API-ключей** |
+| `siliconflow` | SiliconFlow CosyVoice | `FunAudioLLM/CosyVoice2-0.5B` | По умолчанию | `SILICONFLOW_API_KEY` | Нейродвижок CosyVoice2 |
+| `deepinfra` | DeepInfra Kokoro | `hexgrad/Kokoro-82M` | По умолчанию | `DEEPINFRA_API_KEY` | Быстрый Kokoro в облаке |
+| `fireworks` | Fireworks AI | `kokoro` | По умолчанию | `FIREWORKS_API_KEY` | Минимальная задержка инференса |
+| `minimax` | MiniMax Speech | `speech-01-turbo` | По умолчанию | `MINIMAX_API_KEY` | Выразительный эмоциональный голос |
+| `mimo` | Xiaomi MiMo Audio | `mimo-v2.5-tts` | По умолчанию | `MIMO_API_KEY` | Потоковый синтез речи |
+| `google` | Google Cloud TTS | `gemini-2.5-flash-preview-tts` | По умолчанию | `GEMINI_API_KEY` | Многоязычный Gemini TTS |
+| `azure` | Azure Cognitive Speech | `en-US-JennyNeural` | По умолчанию | `AZURE_SPEECH_KEY` | Корпоративный нейросинтез |
+| `deepgram` | Deepgram Aura | `aura-asteria-en` | `asteria` | `DEEPGRAM_API_KEY` | Сверхнизкая задержка ответа |
+| `groq` | Groq TTS | `playai-tts` | `default` | `GROQ_API_KEY` | Мгновенная генерация |
+| `openrouter` | OpenRouter Audio | `openai/gpt-4o-mini-tts` | `alloy` | `OPENROUTER_API_KEY` | Доступ через единый роутер |
+| `custom` | OpenAI-совместимый API | Настраивается | Настраивается | `CUSTOM_TTS_API_KEY` | Любой эндпоинт `/v1/audio/speech` |
+| `piper` | Локальный Piper ONNX | Локальные веса | По умолчанию | *Не требуется* | Полностью оффлайн движок |
+| `espeak` | Локальный eSpeak NG | Системный | `ru` / `en` | *Не требуется* | Легковесный системный синтезатор |
+
+---
+
+## 📦 Быстрая установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-tts
+```
+
+> [!IMPORTANT]
+> После установки перезапустите Web UI (`systemctl --user restart dsh-web`) и обновите вкладку браузера.
+
+---
+
+## ⚙️ Пример конфигурации (`settings.yaml`)
+
+```yaml
+dsh-tts:
+  speakReplies: true
+  enableLocalEngines: true
+  kokoroEnabled: true
+  streamingEnabled: true
+  enableItDictionary: true
+  voiceDuplexEnabled: true
+  vadBargeIn: true
+  messengerTtsEnabled: true
+  cache: true
+  cacheMaxMb: 150
+  autoDetect: true
+  chain:
+    - provider: kokoro
+    - provider: edge
+      voice: ru-RU-SvetlanaNeural
+    - provider: openai
+      model: tts-1
+      voice: alloy
+  roles:
+    coder:
+      provider: openai
+      voice: onyx
+    reviewer:
+      provider: edge
+      voice: ru-RU-DmitryNeural
+```
+
+---
+
+## 🤖 HTTP роуты API
+
+* `GET /dsh-tts/stream` — Потоковая передача аудио по SSE в реальном времени.
+* `POST /dsh-tts/speak` — `{ text, voice?, model? }` → Возвращает аудиофайл для воспроизведения.
+* `POST /dsh-tts/preview` — `{ provider, model, voice, text? }` → Тестовое прослушивание голоса в UI.
+* `GET /dsh-tts/models/status` — Статус установленных локальных моделей (Kokoro, F5-TTS).
+* `POST /dsh-tts/models/install` — `{ engine: 'kokoro' | 'f5' }` → Запуск загрузки модели с HuggingFace.
+* `DELETE /dsh-tts/models/delete` — `{ engine: 'kokoro' | 'f5' }` → Удаление локальной модели.
+* `GET /dsh-tts/integrations` — Проверка статуса связанных плагинов (`dsh-voice`, `dsh-messenger-gateway`).
+* `GET /dsh-tts/status` — Общий статус цепочки, статистика кэша и готовность движков.
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)