@goodandready/dsh-tts 0.3.22 → 0.4.0

package/README.md

@@ -29,7 +29,7 @@
 
 **`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).
+API keys never reach client browsers: synthesis is executed entirely on the host backend across **independent multi-provider fallback chains**, including local system engines (Edge TTS, Piper, eSpeak). Kokoro-82M and F5-TTS weights can be downloaded for future runtime support, but neural inference is **not bundled** in this package — those providers fail honestly and the chain continues.
 
 ```mermaid
 graph LR
@@ -49,10 +49,10 @@ graph LR
 
     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]
+        Chain -->|Offline| P1[Edge TTS / Piper / eSpeak]
+        Chain -.->|Cloud Neural| P2[OpenAI / ElevenLabs / Google / Azure / Groq]
+        Chain -.->|OpenAI-compatible| P3[SiliconFlow / DeepInfra / Fireworks / OpenRouter]
+        Chain -.->|Other| P4[MiMo / MiniMax / Custom]
     end
 
     subgraph Output [Delivery & Integrations]
@@ -75,9 +75,9 @@ graph LR
 
 ## 🚀 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.
+### 1. 📴 Offline system engines + optional future neural runtimes
+* **Edge TTS / Piper / eSpeak**: fully offline or free local/system synthesis without cloud API keys (Edge needs the `edge-tts` CLI).
+* **Kokoro-82M / F5-TTS**: weight download and status UI only. **Neural inference is not bundled** in this package — those providers fail with a clear reason and the fallback chain continues. Do not enable them expecting speech until a supported runtime is wired.
 * **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)
@@ -112,8 +112,8 @@ graph LR
 
 | 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** |
+| `kokoro` | Local Kokoro-82M ONNX | `hexgrad/Kokoro-82M` | `af_bella` | *None* | Weights downloadable; **ONNX inference not bundled** — fails honestly |
+| `f5` | Local F5-TTS GPU Daemon | `F5-TTS` | Default | *None* | Daemon ping only; **GPU inference not bundled** — fails honestly |
 | `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** |
@@ -170,8 +170,8 @@ dsh-tts:
   cacheMaxMb: 150
   autoDetect: true
   chain:
-    - provider: kokoro
     - provider: edge
+    - provider: espeak
       voice: ru-RU-SvetlanaNeural
     - provider: openai
       model: tts-1
@@ -192,7 +192,7 @@ dsh-tts:
 * `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.
+* `GET /dsh-tts/models/status` — Reports Kokoro/F5 weight installation states (download only; inference not bundled).
 * `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`).

package/README.ru.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-<h3>Многопровайдерная озвучка ответов агента с локальными нейродвижками, потоковым звуком (<300 мс), IT-словарём и интеграцией с мессенджерами для DeepSeek Harness</h3>
+<h3>Многопровайдерная озвучка ответов агента: облачные и системные offline-движки, потоковый звук, 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>
@@ -27,9 +27,12 @@
 
 ## ⚡ Обзор
 
+> **Честно про локальные нейросети:** Kokoro/F5 — только статус и загрузка весов. Inference **не входит** в пакет; эти провайдеры падают с понятной причиной, цепочка идёт дальше. Рабочий offline: Edge TTS, Piper, eSpeak.
+
+
 **`dsh-tts`** обеспечивает качественное голосовое озвучивание ответов ассистента в веб-интерфейсе **DeepSeek Harness**. При включённой опции **«Читать ответы агента»**, каждая готовая реплика или потоковый фрагмент синтезируется на хосте и мгновенно воспроизводится в браузере.
 
-API-ключи никогда не передаются в браузер: синтез аудио выполняется на стороне хоста через **независимые цепочки отказоустойчивости (фолбеков)**, включая полностью локальные оффлайн-нейросети (Kokoro-82M и F5-TTS).
+API-ключи никогда не передаются в браузер: синтез аудио выполняется на стороне хоста через **независимые цепочки отказоустойчивости (фолбеков)**, включая системные offline-движки (Edge TTS, Piper, eSpeak). Kokoro/F5 — только загрузка весов; inference не входит в пакет.
 
 ```mermaid
 graph LR
@@ -49,8 +52,8 @@ graph LR
 
     subgraph Fallback [Цепочка фолбеков TTS]
         LRU -->|Промах кэша| Chain{Активная цепочка}
-        Chain -->|1-й приоритет| P1[Kokoro / F5-TTS Локально]
-        Chain -.->|Облачные нейросети| P2[ElevenLabs / OpenAI / CosyVoice]
+        Chain -->|Offline| P1[Edge TTS / Piper / eSpeak]
+        Chain -.->|Cloud| P2[OpenAI / ElevenLabs / Google / Azure / Groq]
         Chain -.->|Бесплатные облака| P3[EdgeTTS / SiliconFlow]
         Chain -.->|Системный фолбек| P4[Локальный Piper / eSpeak NG]
     end
@@ -75,9 +78,9 @@ graph LR
 
 ## 🚀 Ключевые возможности
 
-### 1. 📴 Полностью локальные оффлайн-движки (Kokoro CPU и F5-TTS GPU)
-* **Kokoro-82M (CPU)**: Компактная нейросетевая модель (82 млн параметров), работающая локально на CPU через ONNX Runtime. Быстрый синтез без внешних API и интернета.
-* **F5-TTS (GPU)**: Диффузионный трансформер нулевого выстрела (zero-shot) на видеокартах NVIDIA через выделенный локальный демон инференса.
+### 1. 📴 Offline-системные движки и честный статус нейросетей
+* **Edge TTS / Piper / eSpeak**: рабочий offline/системный синтез без облачных API-ключей.
+* **Kokoro-82M / F5-TTS**: только UI и загрузка весов. **Inference не входит в пакет** — провайдер падает с понятной причиной, цепочка идёт дальше.
 * **ModelManager в UI**: Ручная загрузка моделей прямо из настроек плагина с отображением процентов и прогресс-бара, проверкой SHA-256 и кнопкой удаления. Никаких скрытых или автозагрузок гигабайтных весов.
 
 ### 2. ⚡ Потоковое воспроизведение звука с задержкой < 300 мс
@@ -112,8 +115,8 @@ graph LR
 
 | Ключ провайдера | Сервис | Модель по умолчанию | Голос по умолчанию | Имя ключа (credential) | Особенности |
 |---|---|---|---|---|---|
-| `kokoro` | Локальный Kokoro-82M ONNX | `hexgrad/Kokoro-82M` | `af_bella` | *Не требуется* | **100% локальный нейросинтез на CPU** |
-| `f5` | Локальный F5-TTS GPU | `F5-TTS` | По умолчанию | *Не требуется* | **Качественный zero-shot синтез на NVIDIA GPU** |
+| `kokoro` | Веса Kokoro-82M (ONNX) | `hexgrad/Kokoro-82M` | `af_bella` | *Не требуется* | Веса скачать можно; **inference не bundled** — честный fail |
+| `f5` | Демон F5 (ping) | `F5-TTS` | По умолчанию | *Не требуется* | Только ping; **GPU inference не bundled** — честный fail |
 | `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-ключей** |
@@ -182,7 +185,7 @@ dsh-tts:
 * `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).
+* `GET /dsh-tts/models/status` — Статус загрузки весов Kokoro/F5 (inference не в комплекте).
 * `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`).

package/README.zh.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-<h3>DeepSeek Harness 多引擎语音合成：本地离线神经网络引擎、低延迟流式音频（<300ms）、IT术语词典与即时通讯集成</h3>
+<h3>DeepSeek Harness 多引擎语音合成：云端与系统离线引擎、流式音频、IT 术语词典与即时通讯集成</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>
@@ -29,7 +29,7 @@
 
 **`dsh-tts`** 为 **DeepSeek Harness** Web 界面提供高保真智能体回复语音朗读服务。开启 **朗读智能体回复** 后，每条生成的助手回复或实时流式片段均由服务端合成并即时推流至浏览器播放。
 
-API 密钥绝不暴露给前端：音频合成全程在服务端通过**多服务商独立备用链**执行，包括完全离线的本地神经网络模型（Kokoro-82M 和 F5-TTS）。
+API 密钥绝不暴露给前端：音频合成全程在服务端通过**多服务商独立备用链**执行，包括系统离线引擎（Edge TTS、Piper、eSpeak）。Kokoro/F5 仅可下载权重，**推理未捆绑**。
 
 ```mermaid
 graph LR
@@ -49,8 +49,8 @@ graph LR
 
     subgraph Fallback [TTS 引擎备用链]
         LRU -->|未命中| Chain{生效备用链}
-        Chain -->|首选| P1[Kokoro / F5-TTS 本地离线]
-        Chain -.->|云端神经网络| P2[ElevenLabs / OpenAI / CosyVoice]
+        Chain -->|离线| P1[Edge TTS / Piper / eSpeak]
+        Chain -.->|云端| P2[OpenAI / ElevenLabs / Google / Azure / Groq]
         Chain -.->|免费云端| P3[EdgeTTS / SiliconFlow]
         Chain -.->|系统兜底| P4[本地 Piper / eSpeak NG]
     end
@@ -75,9 +75,9 @@ graph LR
 
 ## 🚀 核心功能
 
-### 1. 📴 完全离线本地神经网络引擎（Kokoro CPU 与 F5-TTS GPU）
-* **Kokoro-82M (CPU)**：8200万参数轻量级神经网络模型，通过 ONNX Runtime 在 CPU 上本地运行，零云端依赖。
-* **F5-TTS (GPU)**：零样本扩散 Transformer 语音合成，通过本地推理守护进程运行于 NVIDIA GPU。
+### 1. 📴 离线系统引擎与诚实的神经引擎状态
+* **Edge TTS / Piper / eSpeak**：可用的离线/系统合成，无需云 API Key。
+* **Kokoro-82M / F5-TTS**：仅权重下载与状态展示。**推理未捆绑在本包中**，provider 会明确失败并继续 fallback。
 * **ModelManager 管理界面**：在设置中手动安装模型，实时显示下载进度条、SHA-256 校验和一键删除。无任何静默或自动下载。
 
 ### 2. ⚡ 实时流式音频播放（延迟 < 300ms）
@@ -107,8 +107,8 @@ graph LR
 
 | 服务商 Key | 对应引擎 | 默认模型 | 默认发音人 | 凭证变量名 | 说明与亮点 |
 |---|---|---|---|---|---|
-| `kokoro` | 本地 Kokoro-82M ONNX | `hexgrad/Kokoro-82M` | `af_bella` | *无需密钥* | **100% 离线 CPU 神经网络合成** |
-| `f5` | 本地 F5-TTS GPU 守护进程 | `F5-TTS` | 默认 | *无需密钥* | **高保真 GPU 零样本语音合成** |
+| `kokoro` | Kokoro 权重（ONNX） | `hexgrad/Kokoro-82M` | `af_bella` | *无需密钥* | 可下载权重；**推理未捆绑** — 明确失败 |
+| `f5` | F5 守护进程（ping） | `F5-TTS` | 默认 | *无需密钥* | 仅 ping；**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` | 微软 Edge 在线 | `zh-CN-XiaoxiaoNeural` | `zh-CN-XiaoxiaoNeural` | *无需密钥* | **免费免 Key 高保真神经网络语音** |
@@ -177,7 +177,7 @@ dsh-tts:
 * `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）。
+* `GET /dsh-tts/models/status` — 查询 Kokoro/F5 权重下载状态（推理未捆绑）。
 * `POST /dsh-tts/models/install` — `{ engine: 'kokoro' | 'f5' }` → 启动模型下载。
 * `DELETE /dsh-tts/models/delete` — `{ engine: 'kokoro' | 'f5' }` → 删除本地模型。
 * `GET /dsh-tts/integrations` — 查询关联插件状态（`dsh-voice`、`dsh-messenger-gateway`）。

package/lib/cache.js

@@ -1,7 +1,6 @@
-// Кэш синтеза на диске: ключ — хеш (текст, провайдер, модель, голос),
-// значение — ответ провайдера как есть (байты + MIME). Вытеснение самых
-// давних по времени последнего обращения; ограничение задаётся настройкой
-// cacheMaxMb и может меняться на живую, поэтому приходит функцией.
+// Disk speech cache: key is a hash of (text, provider, model, voice),
+// value is the provider response as-is (bytes + MIME). LRU eviction;
+// cacheMaxMb is live config so the limit is passed as a function.
 import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -68,7 +67,7 @@ export function createSpeechCache({ root, maxBytes }) {
       try {
         const meta = JSON.parse(await fs.promises.readFile(path.join(dir, key + '.json'), 'utf8'))
         const audio = await fs.promises.readFile(path.join(dir, key + AUDIO_EXT))
-        // Последнее обращение двигаем асинхронно: чтение тормозить нельзя.
+        // Touch LRU asynchronously so reads are never blocked.
         fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime: meta.mime, at: Date.now() })).catch(() => {})
         return { mime: meta.mime || 'audio/mpeg', audio }
       } catch (miss) {