docs: add music playback documentation

USAGE.md music section under Mumble, CHEATSHEET.md music commands,
TASKS.md sprint update for v2.3.0.
This commit is contained in:
user
2026-02-21 21:42:33 +01:00
parent 47b13c3f1f
commit 7206b27fb0
3 changed files with 59 additions and 2 deletions

View File

@@ -540,10 +540,27 @@ operators = []
trusted = []
```
TCP/TLS via SOCKS5 proxy by default (`proxy = true`). Text chat only (no voice). Minimal protobuf
TCP/TLS via SOCKS5 proxy by default (`proxy = true`). Minimal protobuf
codec (no external dep). HTML stripped on receive, escaped on send.
IRC-only commands are no-ops. ~90% of plugins work.
## Music (Mumble only)
```
!play <url> # Play audio (YouTube, SoundCloud, etc.)
!stop # Stop playback, clear queue
!skip # Skip current track
!queue # Show queue
!queue <url> # Add to queue (alias for !play)
!np # Now playing
!volume # Show current volume
!volume 75 # Set volume (0-100, default 50)
```
Requires: `yt-dlp`, `ffmpeg`, `libopus.so.0` on the host.
Max 50 tracks in queue. Volume applies on next track.
Mumble-only: `!play` replies with error on other adapters, others silently no-op.
## Plugin Template
```python

View File

@@ -1553,6 +1553,36 @@ Mumble uses HTML for text messages. On receive, the bot strips tags and
unescapes entities. On send, text is HTML-escaped. Action messages use
`<i>` tags for italic formatting.
### Music Playback
Stream audio from YouTube, SoundCloud, and other yt-dlp-supported sites
into the Mumble voice channel. Audio is decoded to PCM, encoded to Opus
via system libopus, and transmitted as voice packets over the TCP tunnel.
**System dependencies** (must be installed on the host):
- `yt-dlp` -- audio stream extraction
- `ffmpeg` -- decode to 48kHz mono s16le PCM
- `libopus.so.0` -- Opus codec (ctypes, no Python binding)
```
!play <url> Play audio or add to queue
!stop Stop playback, clear queue
!skip Skip current track
!queue Show queue
!queue <url> Add to queue (alias for !play)
!np Now playing
!volume [0-100] Get/set volume
```
- Queue holds up to 50 tracks
- Volume applies from the next track (default: 50%)
- Title resolved via `yt-dlp --get-title` before playback
- Audio pipeline: `yt-dlp | ffmpeg` subprocess, 20ms Opus frames
- Commands are Mumble-only; `!play` on other adapters replies with an error,
other music commands silently no-op
- Playback runs as an asyncio background task; the bot remains responsive
to text commands during streaming
### Transport
TCP connections route through the SOCKS5 proxy at `127.0.0.1:1080`