dsh-voice-announcer
English | 简体中文
A voice announcement plugin for DSH (DeepSeek Harness). It listens for each session's turn/end event and speaks the session title, round number, and outcome — so you know which conversation finished and whether it encountered an error, without watching the screen.
Features
- Clear announcements —
Session title: Round N ended, with dedicated copy for errors, aborts, truncation, and interruptions
- Per-session voices — each session is assigned a Chinese voice from your checked pool (all 14 by default), rotating by index so new sessions differ; the assignment is fixed and persists across restarts
- Voice filtering — check any subset of the 14 Chinese voices in the settings UI; checking one voice means every session uses that single voice
- Subagent control — subagent sessions are silent by default; enable them with one toggle
- Live reading — while a reply streams in, sentences are spoken as they complete (both engines: edge-tts streams and pre-synthesizes for gapless playback, sapi speaks locally); optionally restrict to the currently active session only, with catch-up jumping when the reading falls behind
- Web settings UI — configure everything in Settings → Plugin configuration; changes apply live, no config-file editing
- Voice preview — every voice row has a "Preview" button that synthesizes a sample with the current rate and pitch
- Two engines — edge-tts (neural voices, requires network) or sapi (offline Windows voices); automatic fallback to sapi when edge-tts cannot reach Microsoft, so you never end up with silence
- Streaming playback — audio plays as it is synthesized (no temp files, no conversion); the first syllable arrives within ~0.6s
- Concurrency-safe — each announcement is independent; concurrent sessions never drop or interfere with announcements
Install
dsh plugin --profile web add dsh-voice-announcer
The edge-tts engine is built into the plugin (zero third-party npm dependencies).
Other dependencies
- ffplay (streaming playback for edge-tts mode):
winget install ffmpeg (bundles ffplay)
- Node.js ≥ 22 (edge-tts mode; the built-in WebSocket client requires no external packages)
- Windows (SAPI engine)
Configuration
Option 1: Web settings UI (recommended)
Open Settings → Plugin configuration → Voice announcement in the sidebar. Edits are applied live after saving.
Option 2: Config file
Append the following to ~/.dsh/profiles/<profile>/cordis.patch.yml:
- id: dsh-voice-announcer
config:
enabled: true
engine: edge-tts # edge-tts / sapi
voices: [] # [] = all Chinese voices (default); or a list, e.g. [zh-CN-XiaoxiaoNeural, zh-CN-YunxiNeural]
overlapLive: true # sessions with different voices read aloud simultaneously (default); set false for a single global queue
announceCompleted: true
announceError: true
announceSubagent: false # announce subagent sessions too
announceWait: true # speak when a session waits for you (question / plan review / approval request)
liveRead: true # live-read replies as they stream in (both engines)
liveReadActiveOnly: false # live-read only the currently active session
liveReadMaxQueue: 5 # catch-up jump threshold (pending sentences)
sapiVoice: '' # sapi system voice name, e.g. Microsoft Huihui ('' = system default)
sapiRate: 0 # sapi speech rate, -10 (slowest) ~ +10 (fastest)
sapiVolume: 100 # sapi volume, 0 ~ 100
autoFallbackSapi: true # fall back to local sapi when edge-tts cannot reach Microsoft
Options
| Option | Default | Description |
|---|
| enabled | true | Master switch |
| engine | edge-tts | Engine. Both engines support live reading; the voice/rate/pitch controls are edge-tts-specific and the sapi* options are sapi-specific |
| voices | [] | Voice pool (edge-tts Chinese voices). New sessions pick one by round-robin index from this pool and keep it. Empty = all 14 Chinese voices (default); one entry = every session uses that single voice |
| rate | +0% | Speech rate (edge-tts), slider -50% ~ +50% |
| pitch | +0Hz | Speech pitch (edge-tts), slider -50Hz ~ +50Hz |
| announceCompleted | true | Announce normal completion |
| announceError | true | Announce errors, aborts, and truncations |
| announceSubagent | false | Announce subagent sessions too |
| announceWait | true | Speak when a session pauses waiting for you: it asks a question, presents a plan for review, or requests approval |
| liveRead | true | Live-read replies sentence by sentence while they stream (edge-tts streams from the network, sapi speaks locally) |
| liveReadActiveOnly | false | Live-read only the currently active session (the browser reports it) |
| overlapLive | true | Overlap live-reading across sessions: on (default) = sessions with different voices can speak simultaneously (same session still serial); off = one session speaks at a time (global queue) |
| liveReadMaxQueue | 5 | Catch-up jump: when the pending queue exceeds this many sentences, drop the stale ones and jump to the latest content |
| sapiVoice | (empty) | sapi system voice name (e.g. Microsoft Huihui). Empty = system default. Use voice_health to list installed voices |
| sapiRate | 0 | sapi speech rate: -10 (slowest) ~ +10 (fastest), 0 = normal |
| sapiVolume | 100 | sapi volume: 0 ~ 100 |
| autoFallbackSapi | true | When edge-tts cannot reach Microsoft (403 / offline), automatically speak through local sapi instead of going silent |
Voices (edge-tts, 14 Chinese voices)
All voices are Chinese (Mandarin / dialects / Cantonese / Taiwanese) — every edge-tts voice can also read English text, so mixed content works.
| Group | Voices |
|---|
| Mandarin (zh-CN) | Xiaoxiao · Xiaoyi · Yunxi · Yunyang · Yunjian · Yunxia |
| Dialects (zh-CN) | Xiaobei (Liaoning) · Xiaoni (Shaanxi) |
| Cantonese (zh-HK) | HiuGaai · HiuMaan · WanLung |
| Taiwanese (zh-TW) | HsiaoChen · HsiaoYu · YunJhe |
Per-session assignment: a new session (the first time it is read aloud) is assigned the voice at index allocationCount % voices.length of your checked pool, then keeps it permanently (persisted to voice-announcer-session-voices.json). Changing the filter only affects future assignments — existing sessions keep their voice, and the modulo keeps new sessions aligned to the new list length.
Behavior
- Subagent sessions are not announced by default (enable via
announceSubagent)
- Each session keeps its assigned voice until the session ends; a session that already spoke before an upgrade keeps its previous single-voice behavior
- Live reading overlaps across sessions by default — sessions with different voices can read aloud simultaneously (same session stays serial). Set overlapLive to false to fall back to a single global queue (one session speaks at a time)
- Each announcement is synthesized and streamed straight to the player — no temp files, no conversion; if ffplay is missing, or edge-tts cannot reach Microsoft, it falls back to SAPI
- When a session pauses waiting for you — it asks a question, presents a plan for review, or requests approval — a prompt is spoken with that session's voice, interrupting only that session's live reading (control via
announceWait)
- Error messages are included (truncated to 60 characters); aborts distinguish "by you" from "by the parent agent"
Development
# Build the host (requires the tsc from a DSH source checkout)
DSH_CHECKOUT=<path-to-dsh-harness> bash scripts/build.sh
# Build the client (web settings card)
npx tsdown
Changelog
- 0.1.14 — Fixed the Microsoft endpoint migration (October 2026 broke the old
speech.platform.bing.com host in many regions with HTTP 403). Synthesis now uses the new api.msedgeservices.com host with the Ocp-Apim-Subscription-Key parameter, keeping the legacy host as a fallback. Added automatic sapi fallback on any edge-tts failure (403 / network / missing ffplay) so announcements never go silent. sapi now supports live reading (previously edge-tts only), using a persistent local process to avoid per-sentence PowerShell startup. New settings: sapiVoice, sapiRate, sapiVolume, autoFallbackSapi.
- 0.1.7 — Performance fix: the session-title lookup no longer calls
sessionProjections.snapshot(), which synchronously folds the entire event log of a huge session (millions of events × every registered projection key) and can freeze the DSH web server for seconds to minutes. Titles are now read with a lightweight reverse scan for the latest session/title event.
License
BSD-3-Clause
