tangjx2007/dsh-audio-cue

English | 中文

Audio cues for DeepSeek Harness: a short sound when an agent needs your confirmation, finishes a turn, finishes a background job, or fails — so you do not have to watch the window.

Sounds are synthesized at runtime with Web Audio (the package ships no audio files), and the configuration lives in the host settings document, so it survives a reload, a different browser, and a restart of DSH.

Being listed is not an endorsement. Plugins are third-party code; install only what you trust. This plugin makes no network requests, touches no file outside the settings document, and never logs your message content or file paths.

What it does

Five kinds of event, each with its own switch and its own volume:

Event	When it sounds	Default
Approval needed	An agent asks to run a privileged tool	on, 80%
Question asked	An agent asks you a question and waits	on, 80%
Turn finished	The current conversation finishes a turn	on, 70%
Background job finished	Another session (background job or subagent) stops	on, 70%
Task failed	A session reports an error that needs attention	on, 90%
Privilege escalation	An approval is classified as a sandbox escalation	off (it would double up with Approval needed)

Five built-in sound packs — the same event keeps the same shape, only the timbre changes: marimba (wooden, the default), glass (bright), pulse (electronic), arcade (8-bit), minimal (a soft tap).

Do not disturb:

• Only when the window is not focused (on by default) — nothing sounds while you are looking at it.
• Quiet hours (off by default, 22:00–08:00) — inside the window only turn finished and background job finished go silent. Approvals, questions and failures are never silenced by the clock: those are the cases you have to know about.

Install

dsh plugin --profile desktop add github:tangjx2007/dsh-audio-cue

Replace desktop with your profile name (usually web when you run dsh web). Reload the page afterwards; the host settings section needs one restart of dsh.

The build output is committed (lib/), so installing from git runs no build script.

Settings

Settings → Plugins → Plugin configuration → Audio cues: master switch, sound pack, master volume, per-event switch/volume/preview, do-not-disturb rules, restore defaults. Bilingual, following the interface language.

To answer "why was there no sound?", type this in a conversation:

/audio-cue

It prints a table of every event and whether it would sound right now. /audio-cue test plays the approval cue immediately, which is the quickest way to confirm the audio path itself works.

How it differs from similar plugins

	dsh-audio-cue	Completion-chime plugins (e.g. dsh-turn-chime, dsh-sound-cue)
Events covered	5 kinds (including background jobs, failures, escalation)	usually 1–2
Timbre	5 packs, per-event preview	one or two fixed sounds
Configuration granularity	per-event switch and volume, plus a master volume	master switch and volume
Where the configuration lives	the host settings document ($DSH_HOME/settings.yaml)	browser storage
Audio assets	none (synthesized)	depends on the implementation

Known limitations

• Jobs that finish while the page is disconnected are not announced. The completion signal comes from a forwarded session-status event, which is a best-effort, non-replayed notification. Anything that finished while you were offline stays silent.
• Progress cues mean "it stopped". The client cannot tell a completed turn from an interrupted one, so an interruption also plays turn finished.
• Browser autoplay policy. Browsers do not allow sound before your first interaction with the page. The plugin does not error; it recovers on your first click or key press.
• Escalation classification reads the reason text. An approval carries only the tool name and a reason string (no tool arguments). The harness has exactly one producer of privilege escalations — dsh-sandbox, which always writes the reason as escalate sandbox to <mode>: <justification> — and the plugin matches that format, so a real escalation is not missed. Anything that does not match is reported as Approval needed: a mislabelled cue is preferable to a dropped event. The escalation cue is off by default.

Command reference

Input	Effect
/audio-cue	Print the current configuration and the suppression reason per event
/audio-cue test	Force one approval cue, bypassing every suppression rule

Marketplace information

• Entry: data/plugins/tangjx2007__dsh-audio-cue.yml (submitted to the awesome-dsh-plugin repository; a draft ships here)
• Category: notify
• Screenshots: screenshots.json in the repository root, 1–8 paths relative to that file
• License: MIT

Development

npm run build      # write lib/ (a dependency-free bundler)
npm run test       # node --test
npm run verify     # build freshness plus the full assertion set

Specification and design:

• Requirements (authoritative): docs/spec/audio-cue.md
• Design: docs/spec/audio-cue-design.md
• Task graph and execution log: docs/tasks/

src/ is layered: config, dnd, classify, events and cue-spec are pure logic with no browser dependency (unit-testable straight from Node), while synth, player, settings-ui and client are the glue that needs Web Audio, the DOM, or the Cordis context.