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 (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
    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
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
• 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

License

BSD-3-Clause