herdr-sound

Give your Herdr agents a game-style notification sound.

herdr-sound is a tiny CLI that switches Herdr's native notification sounds between chiptune "packs" — one sound when an agent finishes, another when it needs you. No plugin, no background process: it just copies the audio files next to your Herdr config and points [ui.sound] at them.

$ hsp use zelda
  done     -> ~/.config/herdr/sounds/zelda/done.mp3
  blocked  -> ~/.config/herdr/sounds/zelda/blocked.mp3
已切换音色包：zelda
  config: ~/.config/herdr/config.toml

中文文档 / Chinese README

Packs

Run herdr-sound list to see them with exact durations.

All audio is original. Every pack is synthesized from square waves by src/herdr_sound_plugin/gen.py — the notes and rhythm are original compositions in a genre style. No samples from any game are included, so the whole package is safe to redistribute.

Install

Requires Python 3.10+ and Herdr 0.9.3+.

# recommended: isolated install with uv
uv tool install herdr-sound

# or plain pip
pip install herdr-sound

Until the package is on PyPI, install straight from this repo:

uv tool install --from git+https://github.com/ezstack-dev/herdr-sound-plugin herdr-sound
# or, from a local clone
uv tool install .

Both herdr-sound and the short alias hsp are installed.

Usage

hsp list              # list packs, * marks the active one
hsp use mario         # switch to a pack
hsp status            # what is active right now, and where
hsp doctor            # health check: binary, config, sound files
hsp restore           # back to Herdr defaults (disable sound, remove copies)

hsp use <pack> does three things:

1. copies done.mp3 / blocked.mp3 into <herdr config dir>/sounds/<pack>/
2. writes the pack into [ui.sound] in your config.toml
3. runs herdr server reload-config so it takes effect without a restart

It edits your config in place and preserves comments and formatting, but backing it up first is still a good habit.

Which key does what

Custom config location

herdr-sound finds your config the same way Herdr does: $HERDR_CONFIG_PATH → $XDG_CONFIG_HOME/herdr/config.toml → ~/.config/herdr/config.toml. Set HERDR_CONFIG_PATH to operate on a different one:

HERDR_CONFIG_PATH=/tmp/test/config.toml hsp use pacman

Things worth knowing

Sounds play in the Herdr client, not the server. Herdr resolves [ui.sound] and plays the audio in the attached client process. If you run Herdr headlessly or only attach through a bridge, the config is still correct — you just won't hear anything until a real client is attached. hsp doctor tells you the config is valid either way.

There is no "failed" sound. Herdr's agent states are idle / working / blocked / done / unknown — there is no failed. A crashed or errored agent usually still ends as done, so it gets the finish sound. The blocked slot means "needs attention", which is the closest thing Herdr offers and is what we map the "something's wrong" sound onto.

restore only removes what it installed. Files under sounds/<pack>/ for known packs are deleted; anything else you put in the sounds directory is left alone.

Development

task check        # tests + sound-sync check + wheel packaging check
task sounds       # regenerate all mp3s from the note tables in packs.py
task list         # print packs and durations

Layout:

src/herdr_sound_plugin/
  cli.py        typer app (list / use / status / doctor / restore / version)
  config.py     locate + read + edit herdr's config.toml (tomlkit, keeps comments)
  install.py    copy sounds, compute [ui.sound] paths, uninstall
  herdr.py      thin wrapper: find the herdr binary, reload-config
  packs.py      the note tables — one "score" per pack and purpose
  synth.py      square-wave synthesis -> mp3
  gen.py        writes packs.py scores out to sounds/<pack>/<kind>.mp3
  sounds/       12 committed mp3s, shipped inside the wheel
packages/legacy-herdr-plugin/   ⚠️ dead code from the old plugin approach

packages/legacy-herdr-plugin/ is archived, not used, and excluded from test collection. See its README if you want the post-mortem.

License

Apache-2.0. See LICENSE.