@falling-ts/dsh-web-ding

dsh plugin --profile web add @falling-ts/dsh-web-ding

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 — "弹出用户选择" 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