New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Multi-backend network speaker plugin that installs servers and clients, debugs playback, and manages rooms.

version
1.0.0
GitHub stars
32
View on GitHub

What it does

  • Adds audioctl.py with scan, ma-players, snap-status, test-play, announce, and transfer subcommands for JSON output
  • Covers install, inventory, speaker switching, grouping, announcements, sleep timers, and podcast or radio playback across Music Assistant, Lyrion, and Snapcast
  • Keeps your servers, endpoints, and history in a private overlay folder, with tokens read from environment variables rather than stored
  • Designed for home setups that mix Squeezelite, snapclient, and Music Assistant and need to drive Home Assistant from one place

Network speakers and multi-room audio across backends (Music Assistant, Lyrion/Squeezelite, Snapcast): install servers and clients, inventory, set speakers, debug, drive the MA and Home Assistant APIs. Your installation lives in a private overlay.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install home-audio@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Announce

Load

Overlay DIR via bash ${CLAUDE_PLUGIN_ROOT}/scripts/overlay-paths.sh dir; read profile.env and installation.json (rooms -> player names). Run calls through the user's secrets route if profile.env names one. A="python3 ${CLAUDE_PLUGIN_ROOT}/scripts/audioctl.py". Resolve rooms to players by name; $A ma-players lists them. Never guess IDs.

Steps

  1. Pick the engine once: $A ma players/tts_engines lists uids (hass/tts.<entity> when TTS comes from Home Assistant). Record the user's choice as HOME_AUDIO_TTS_ENGINE in profile.env, and pass it with --engine.
  2. $A announce "<text>" -p "<room>" [-p ...] [--engine <uid>] [--language en] [--volume 50] [--no-chime]. A sound file instead of speech: --url <http url MA can reach>. MA ducks or pauses what is playing and resumes it afterwards.
  3. This makes sound in someone's room: say where before sending, unless asked directly.
  4. MA unreachable or no engine: Home Assistant tts.speak ({"entity_id":"tts.<engine>","media_player_entity_id":"media_player.<x>","message"}) or music_assistant.play_announcement (message, tts_entity_id, url, use_pre_announce, announce_volume); see the home-assistant skill.

Commands underneath

players/cmd/play_announcement {"player_id","message"|"url","tts_engine?","language?", "volume_level?","pre_announce?","pre_announce_url?"} (source: 2.10.11; message and tts_engine are newer than the url-only form). Player config keys announce_volume, announce_volume_strategy, announce_volume_min/max set the default level.

Data storage

HOME_AUDIO_TTS_ENGINE in profile.env, only on the user's choice.

Readme

Home Audio

Agent skills for a home network-speaker system, whatever the backend: Music Assistant, Lyrion (LMS) + Squeezelite, Snapcast, with AirPlay and Spotify Connect endpoints covered where they meet those. Install servers and endpoint clients, document what is on the network, change the speaker an endpoint plays to, debug, group rooms, and drive the Music Assistant and Home Assistant APIs.

The plugin is generic. Your installation (servers, endpoints, rooms, sinks, history) lives in a private overlay folder outside the plugin, which the setup skill can turn into a private git repo.

Skills

SkillDoes
setupCreates the private record: profile.env, installation.json; offers a private repo
inventoryScans the LAN, asks each server, reads endpoint configs, writes installation.json/.md
install-serverMusic Assistant (HA add-on or Docker), Lyrion, or snapserver
install-clientSqueezelite or snapclient (or shairport-sync, librespot) as a resilient systemd unit
connect-serverPoints clients at a server, enables MA providers, migrates between backends
set-speakerChanges an endpoint's output device: ALSA card, PipeWire sink, second speaker
debugWalks source -> server -> network -> client -> device, with a 10-90 s test play to a speaker or group; records the fix
groupsMulti-room sync in MA, Snapcast, LMS or HA
now-playingWhat each room is playing, sleep timers, recent and in-progress items
move-musicMove the playing queue to another room, or extend it
announceSpeak or play an announcement on rooms or groups (MA TTS or HA)
sleep-and-alarmsSleep timers, fade-outs, wake-up music via an HA automation
podcasts-radioAdd feeds or an OPML, latest episodes, resume, radio streams
library-providersProvider health, add a source via the setup flow, reload, resync
music-assistantMA API: players, play media, volume, queues, playlists, DSP presets, logs, announcements
home-assistantmusic_assistant / snapcast / squeezebox integrations, media_player calls, automations

audioctl.py

One stdlib-only CLI the skills share (scripts/audioctl.py, JSON output):

audioctl.py scan --subnet 192.168.1.0/24   # which hosts expose audio ports
audioctl.py mdns                            # audio-related mDNS services
audioctl.py ma-players                      # Music Assistant players
audioctl.py ma players/cmd/volume_set '{"player_id":"<id>","volume_level":30}'
audioctl.py lms serverstatus 0 100          # LMS, or MA's Squeezelite provider
audioctl.py snap-status                     # Snapcast groups and clients
audioctl.py ha GET /api/states/media_player.kitchen
audioctl.py test-play -p "Living Room" -s 30 --volume 40   # 10/30/60/90 s of known media
audioctl.py ma-add-podcast --opml https://example.com/feeds.opml
audioctl.py now-playing --history 5
audioctl.py transfer --to Kitchen
audioctl.py announce "Dinner is ready" -p Kitchen --engine <uid>
audioctl.py sleep 30 -p Bedroom
audioctl.py episodes "<podcast>" --play "Living Room"
audioctl.py providers --problems

Overlay (your private data)

scripts/overlay-paths.sh prints where it is and why. Order: $HOME_AUDIO_HOME, $CLAUDE_USER_DATA/home-audio, ~/.claude-user-data/home-audio (if that root exists), $XDG_DATA_HOME/claude-plugins/home-audio (if that root exists), else ~/.claude-user-data/home-audio.

profile.env          settings (keys below)
installation.json    servers, endpoints, groups, HA entities, history
installation.md      human rendering
endpoints/<host>.md  per-endpoint notes and fixes
dsp-presets/*.json   your EQ presets (same name overrides a built-in)
changelog.md         dated changes made by the skills
<skill>.md           private notes for one skill; they override its defaults
KeyUsed byDefault
HOME_AUDIO_BACKENDallmusic-assistant
HOME_AUDIO_SUBNETinventory, setupnone
HOME_AUDIO_MA_URLmusic-assistant, inventory, groupsnone
HOME_AUDIO_MA_TOKEN_VARmusic-assistantMA_TOKEN (name of the env var, not the token)
HOME_AUDIO_LMSinventory, groups, debugnone
HOME_AUDIO_SNAPSERVERinventory, groups, debugnone
HOME_AUDIO_HA_URLhome-assistantnone
HOME_AUDIO_HA_TOKEN_VARhome-assistantHA_TOKEN
HOME_AUDIO_SSH_USERinstall-*, set-speaker, inventorySSH config

Tokens are never written by the plugin; profile.env names the environment variables.

Installation

claude plugins install home-audio@danielrosehill

Then run setup.

History

Replaces the Snapcast and Spotify-network parts of smart-home, and the media-assistant-ops and music-assistant-ops plugins (2026-11-14).

License

MIT

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Home-Audio
Author
Daniel Rosehill
Category
Network & Smart Home
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to home-audio

More Media & Audio/Video