docs: add music discovery, autoplay, and Mumble admin sections
Some checks failed
CI / gitleaks (push) Failing after 3s
CI / lint (push) Failing after 23s
CI / test (3.11) (push) Has been skipped
CI / test (3.12) (push) Has been skipped
CI / test (3.13) (push) Has been skipped
CI / build (push) Has been skipped

- USAGE.md: music discovery (!similar, !tags), autoplay discovery
  config, Mumble admin (!mu) command reference
- CHEATSHEET.md: music discovery and Mumble admin quick reference
- ROADMAP.md: mark v2.4.0 as done, add MB fallback + !mu + autoplay
- TODO.md: mark music discovery and performance items as done
- PROJECT.md: update plugin categories table
- TASKS.md: close open doc items

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-23 22:04:03 +01:00
parent 62a4191200
commit ad12843e75
6 changed files with 122 additions and 15 deletions

View File

@@ -1760,6 +1760,53 @@ file (natural dedup).
missing (e.g. after a cleanup or volume mount issue)
- On cancel/error, files are not deleted (needed for `!resume`)
### Music Discovery
Find similar music and genre tags for artists. Uses Last.fm when an API
key is configured; falls back to MusicBrainz automatically (no key
required).
```
!similar Similar to currently playing track
!similar <artist> Similar artists to named artist
!similar play Queue a random similar track
!similar play <artist> Queue a similar track for named artist
!tags Genre tags for currently playing artist
!tags <artist> Genre tags for named artist
```
- When an API key is set, Last.fm is tried first for richer results
- When no API key is set (or Last.fm returns empty), MusicBrainz is
used as a fallback (artist search -> tags -> similar recordings)
- `!similar play` picks a random result and delegates to `!play`
(searches YouTube for the artist + title)
- MusicBrainz rate limit: 1 request/second (handled automatically)
Configuration (optional):
```toml
[lastfm]
api_key = "" # Last.fm API key (or set LASTFM_API_KEY env var)
```
### Autoplay Discovery
During autoplay, the bot periodically discovers new tracks instead of
only playing from the kept library. Every Nth autoplay pick (configurable
via `discover_ratio`), it queries Last.fm or MusicBrainz for a track
similar to the last-played one. Discovered tracks are searched on YouTube
and queued automatically.
Configuration (optional):
```toml
[music]
autoplay = true # Enable autoplay (default: true)
autoplay_cooldown = 30 # Seconds between autoplay tracks (default: 30)
discover = true # Enable discovery during autoplay (default: true)
discover_ratio = 3 # Discover every Nth pick (default: 3)
```
### Extra Mumble Bots
Run additional bot identities on the same Mumble server. Each extra bot
@@ -1856,3 +1903,24 @@ Available voices:
To switch the active voice, set `piper_tts_voice` (e.g.
`fr_FR-siwis-medium`) and redeploy the TTS service.
### Mumble Server Admin (admin)
Manage Mumble users and channels via chat commands. All subcommands
require admin tier. Mumble-only (no-op on other adapters).
```
!mu kick <user> [reason] Kick user from server
!mu ban <user> [reason] Ban user from server
!mu mute <user> Server-mute user
!mu unmute <user> Remove server-mute
!mu deafen <user> Server-deafen user
!mu undeafen <user> Remove server-deafen
!mu move <user> <channel> Move user to channel
!mu users List connected users
!mu channels List server channels
!mu mkchan <name> [parent] Create channel (under parent or root)
!mu rmchan <name> Remove empty channel
!mu rename <old> <new> Rename channel
!mu desc <channel> <text> Set channel description
```