dsh-chime-sound

English · 中文

Notification sounds for dsh-tui (originally named dsh-notice-sound, renamed on 2026-09-07).

• Triggers: the agent calling ask_user_question (session/event tool/call — a nudge to come back and answer) and a reply finishing (session/event turn/end; agent-loop emits this once per turn, while assistant/message fires on every tool step and is deliberately not used). Both distinguish a focused from an unfocused terminal.
• 9 sound groups × 4 situations, selectable (or off) in the settings page's “Notice Sounds” section: g1 Crisp / g2 Wood / g3 Chiptune / g4 Warm (synthesised in code), g5 Bell / g6 Bubble / g7 Arcade / g8 Marimba / g9 Soft Synth (CC0 samples).
• New in 0.2.0 — master volume (the “Volume” field): 0–150% in 5% steps (31 steps), default 100% = the original level. ←/→ steps 5%; holding the key repeats, because dsh-tui's input layer expands the auto-repeat into per-step events. The new level is auditioned immediately. Above 100% the samples are 16-bit saturated (peak ≈ 105%, clipping only for very short stretches). The gain is applied to the WAV samples inside the plugin and never touches system volume.
• g1–g4 are synthesised by this repository's scripts/gen-sounds.mjs (WAV, 16-bit / 48 kHz); g5–g9 are Freesound CC0 1.0 material, decoded and then trimmed, faded and loudness-normalised to the same format. Sources and conversion parameters are recorded in assets/sounds/CREDITS.md (CC0 needs no attribution and may be redistributed with this plugin).
• Settings and copy are bilingual (Chinese/English); the settings card is localised by the host according to the language dsh-tui's /lang selected.

⚠️ Platform support (Windows only)

Sound is played through Win32 APIs (koffi → winmm.dll PlaySoundW, with focus detection via user32.dll), so this plugin is Windows-only (Windows Terminal and classic conhost). On Linux and macOS it degrades silently to a no-op — no sound, no boot failure — and logs a Win32-only warning. Do not expect notification sounds elsewhere.

Install

Option 1 — dsh CLI (recommended):

dsh plugin --profile <profile> add dsh-chime-sound

(Or from the dsh plugin market / GitHub: dsh plugin add github:VviLliAm-qwq/dsh-chime.)

Option 2 — manual:

1. Copy the package to ~/.dsh/profiles/dsh-tui/node_modules/dsh-chime-sound/
2. Append "dsh-chime-sound" to dsh.profile.bundles in ~/.dsh/profiles/dsh-tui/package.json (the package declares dsh.bundle.patch, so it mounts itself at boot)
3. Restart dsh-tui (/restart)

Compatibility: dsh-tui 0.10.x (the ctx.tuiSettingsSections and session/event seams, both soft-probed); dsh 0.1.2-rc.1+; Node ^22.19 || >=24; pure ESM. Every configuration key has a default, and a missing configuration degrades to “nothing happens”.

Configuration

The settings live in dsh-tui's “Notice Sounds” section (or the chime: namespace of ~/.dsh/settings.yaml):

chime:
  doneFocus: g2   # reply finished, terminal focused: g1-g9 / off
  doneBlur: g2    # reply finished, terminal unfocused
  askFocus: g2    # question asked, terminal focused
  askBlur: g2     # question asked, terminal unfocused
  volume: "50"    # 0-150, 5% steps, default "100"

Why session/event and not the message observer

dsh-tui's mediated tuiMessageObserver.subscribe() is unusable here: the API requires the activation to hold a verified Component identity through host admission, and a plugin mounted by a bundle patch never goes through admission — its subscriptions are refused (COMPONENT_NOT_ADMITTED) and no sound ever plays.

This plugin therefore listens on the session/event cordis bus published by @deepseek-ai/dsh-session (the same channel the official dsh-working-activity extension uses), which needs no Component identity:

• tool/call with name === 'ask_user_question' → the question sound (askFocus / askBlur)
• turn/end → the completion sound (doneFocus / doneBlur); subagent sessions are ignored
• Focus detection: the GetForegroundWindow handle equals GetConsoleWindow, or the window class matches (CASCADIA_HOSTING_WINDOW_CLASS = Windows Terminal, ConsoleWindowClass = classic conhost). Under ConPTY GetConsoleWindow returns a hidden PseudoConsoleWindow that is never foreground, so the earlier handle-only and class-only readings were both flawed; the check is now a pair of criteria with a corrected class read.
• dsh-plugin.json no longer declares the unused messages.observe capability.

Restart dsh-tui after installing.

Publishing

• Repository: https://github.com/VviLliAm-qwq/dsh-chime (public)
• Release: v* tags drive .github/workflows/release.yml, which publishes to npm through trusted publishing (OIDC) — no token is stored in the repository.

License

MIT — see LICENSE. Sound assets are licensed and attributed in assets/sounds/CREDITS.md.