dsh-voice-announcer

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 (edge-tts, sentence-buffered, pre-synthesized for gapless playback); 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)
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 (edge-tts only)
    liveReadActiveOnly: false # live-read only the currently active session
    liveReadMaxQueue: 5      # catch-up jump threshold (pending sentences)

Options

Option	Default	Description
enabled	true	Master switch
engine	edge-tts	Engine; voice/rate/pitch controls are disabled when sapi is selected
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 only)
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

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 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.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

dsh-voice-announcer

Installation

README