dsh-web-ding
A DSH Cordis plugin that plays a "ding" in the browser the moment an
agent finishes (runs to idle). The sound is synthesized entirely by front-end
JavaScript (Web Audio API) — the Node/Host side never plays audio and no
Windows/system notification is used.
Built by following the architecture of
dsh-force-compact:
a pure-listener Host half + a browser client half connected by the official
settings/document-updated mirror channel.
What it does
| Layer | What happens |
|---|
Host (index.js + src/) | Listens for the agent/status idle transition (all turns done, including sub-agents, before the next human turn; a fresh idle session that never ran, and repeated idle ticks, stay silent). Publishes { phase:'done', at, sessionId, title } into the falling-ts-web-ding settings namespace — title is read here from the official sessionProjections title unit, so the browser never has to fetch it. Never emits audio, never calls the OS. |
Browser (web/client.js) | Mirrors the namespace live via configForms. On a strictly-newer done signal it synthesizes a short ding (three sine oscillators + exponential decay envelopes) with the Web Audio API and plays it through the tab — and, at the same moment, pops a Win11-style toast in the bottom-right corner. Clicking the toast slides in a notification drawer listing every turn-end message (kept in browser localStorage, capped at 100, deduped by signal at), with per-message delete and a clear-all button. Everything stays front-end: no backend audio, no OS notification. |
Install
dsh plugin --profile web add github:falling-ts/dsh-web-ding
Requires the web app to ship the client bundle (the dsh.client declaration in
package.json does that automatically).
Configuration (falling-ts-web-ding namespace, stored in the profile's cordis.patch.yml)
Two independent blocks, each with its own switch and its own tone:
Block 1 — 弹出用户选择 (question popup ding) — plays when the harness pops a
user-question chooser in the browser. Detection is client-side on the DOM
([data-question-key] anchor of the QuestionComposer): the Host half sees no
question frame, so this block is entirely browser-side.
| Field | Type | Default | Meaning |
|---|
questionEnabled | boolean | true | Switch for the question-popup ding. |
questionVolume | number 0..1 | 0.7 | Web Audio playback gain. |
questionFreq | number 80..4000 | 880 | Fundamental frequency of the ding (Hz). |
questionDecayMs | number 100..4000 | 900 | Tone decay length (ms). |
Block 2 — 回合结束 (turn-end ding) — the classic agent/status idle-transition
tone. The Host observes agent/status; on the idle transition (all turns done,
including sub-agents, before the next human turn; fresh sessions that never ran
and repeated idle ticks stay silent) it publishes the done signal.
| Field | Type | Default | Meaning |
|---|
turnEndEnabled | boolean | true | Switch for the turn-end ding (Host skips publishing when off). |
turnEndVolume | number 0..1 | 0.7 | Web Audio playback gain. |
turnEndFreq | number 80..4000 | 880 | Fundamental frequency of the ding (Hz). |
turnEndDecayMs | number 100..4000 | 900 | Tone decay length (ms). |
Besides the ring, each turn end drops a bottom-right toast (Win11-style,
auto-dismisses after 6 s). Click it to open the right-side notification
drawer: the last 100 turn-end messages are kept in the browser's
localStorage (key falling-ts-web-ding.notify.v1), each row can be
deleted individually, and a "全部删除" button clears them all. The message
log is front-end only — the Host never reads or writes it.
You can also adjust both blocks from the 设置 → 提示音配置 panel,
each with its own switch and its own "试听" (preview) button.
Browser autoplay policy
Browsers block audio until a user gesture. The client warms the
AudioContext on the first pointer/key interaction (and on the preview
button), so: interact with the page once (or press 试听) and you will hear the
ding at every agent turn end. An audio context in a background tab may be
suspended by the browser itself — keep the tab visible to hear the tone.
Development
# mount as a dev overlay (plain JS, no build step)
dsh web --patch $(pwd)/cordis.patch.yml # if supported by your CLI
# or install from a local path
dsh plugin --profile web add /path/to/dsh-web-ding
See AGENTS.md for the plugin's own rules (pure Host listener, no backend
audio, no OS notification, only sanctioned settings-mirror channel to the
browser).
Screenshots
Settings page: the 提示音配置 section, two blocks each with its own switch and tone
Settings page: the 提示音配置 section — "弹出用户选择" and "回合结束" blocks,
each with its own switch, volume, frequency and decay length, all live-editable
without a restart, each with a 试听 (preview) button to warm the browser
AudioContext.
License
MIT
