flashyiyi/dsh-voice-announcer

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

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.

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