username/derp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update Mumble docs for pymumble transport

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-21 23:16:56 +01:00
parent d884d2bb55
commit eae36aa1f9
3 changed files with 26 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/USAGE.md
View File

@@ -1480,30 +1480,30 @@ proxy at `127.0.0.1:1080` via `derp.http.urlopen` when `proxy = true`
## Mumble Integration
Connect derp to a Mumble server via TCP/TLS protobuf control channel.
Text chat only (no voice). TCP is routed through the SOCKS5 proxy when
`proxy = true` (default). No protobuf library dependency -- uses a
minimal built-in varint/field encoder/decoder for the ~7 message types
needed.
Connect derp to a Mumble server with text chat and voice playback.
Uses [pymumble](https://github.com/azlux/pymumble) for the Mumble
protocol (connection, SSL, voice encoding). Text commands are bridged
from pymumble's thread callbacks to asyncio for plugin dispatch.
### How It Works
The bot connects to the Mumble server over TLS, sends
Version and Authenticate messages, then enters a read loop. It tracks
channels (ChannelState), users (UserState), and dispatches commands
from TextMessage messages through the shared plugin registry.
pymumble handles the Mumble protocol: TLS connection, ping keepalives,
channel/user tracking, and Opus voice encoding. The bot registers
callbacks for text messages and connection events, then bridges them
to asyncio via `run_coroutine_threadsafe()`. Voice playback feeds raw
PCM to `sound_output.add_sound()` -- pymumble handles Opus encoding,
packetization, and timing.
### Configuration
```toml
[mumble]
enabled = true
proxy = true # Route TCP through SOCKS5
proxy = false # SOCKS5 proxy (pymumble connects directly)
host = "mumble.example.com" # Mumble server hostname
port = 64738 # Default Mumble port
username = "derp" # Bot username
password = "" # Server password (optional)
tls_verify = false # Mumble commonly uses self-signed certs
admins = ["admin_user"] # Mumble usernames
operators = [] # Mumble usernames
trusted = [] # Mumble usernames
@@ -1511,8 +1511,7 @@ trusted = [] # Mumble usernames
### Mumble Setup
1. **Ensure a Mumble server** (Murmur/Mumble-server) is running and
accessible through the SOCKS5 proxy
1. **Ensure a Mumble server** (Murmur/Mumble-server) is running
2. **Configure the bot** with the server hostname, port, and credentials
@@ -1556,13 +1555,14 @@ unescapes entities. On send, text is HTML-escaped. Action messages use
### 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.
into the Mumble voice channel. Audio is decoded to PCM via a
`yt-dlp | ffmpeg` subprocess pipeline; pymumble handles Opus encoding
and voice transmission.
**System dependencies** (must be installed on the host):
**System dependencies** (container image includes these):
- `yt-dlp` -- audio stream extraction
- `ffmpeg` -- decode to 48kHz mono s16le PCM
- `libopus.so.0` -- Opus codec (ctypes, no Python binding)
- `libopus` -- Opus codec (used by pymumble/opuslib)
```
!play <url> Play audio or add to queue
@@ -1572,21 +1572,14 @@ via system libopus, and transmitted as voice packets over the TCP tunnel.
!queue <url> Add to queue (alias for !play)
!np Now playing
!volume [0-100] Get/set volume
!testtone Play 3-second 440Hz test tone
```
- 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
- Audio pipeline: `yt-dlp | ffmpeg` subprocess, PCM fed to pymumble
- 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`
via `derp.http.create_connection` when `proxy = true` (default). Set
`proxy = false` to connect directly. TLS is applied on top of the
socket. Mumble commonly uses self-signed certificates, so `tls_verify`
defaults to `false`.