A Mumble bot written in Go that streams YouTube audio into a voice channel. Users paste YouTube URLs in chat and the bot plays them using yt-dlp + ffmpeg.

Features#

Paste a YouTube URL in chat to play audio
Song queue with auto-advance
Chat commands: !skip, !stop, !queue, !np, !vol <0-100>, !help
Fetches and displays video titles
Configurable via environment variables

Building#

The bot is packaged as a Docker image. Build it from this directory:

# Linux / macOS
./build.sh

# Windows (PowerShell)
.\build.ps1

This produces an image tagged mumble-music-bot:latest.

Deployment#

The image is self-contained — it includes ffmpeg, yt-dlp, and the compiled bot binary. No files from this repository are needed at the deployment location, only the image and your configuration.

Adding to an existing Docker Compose stack#

In your compose file (wherever your Mumble server is defined), add the bot as a service referencing the built image:

services:
  mumble-server:
    # ... your existing mumble server config ...

  mumble-bot:
    image: mumble-music-bot
    restart: unless-stopped
    environment:
      MUMBLE_SERVER: mumble-server:64738
      MUMBLE_USERNAME: MusicBot
      MUMBLE_PASSWORD: your-server-password
      MUMBLE_INSECURE: "true"
    depends_on:
      - mumble-server

Alternatively, use an env file:

  mumble-bot:
    image: mumble-music-bot
    restart: unless-stopped
    env_file: ./mumble-bot.env
    depends_on:
      - mumble-server

Configuration#

All configuration is done through environment variables:

Variable	Default	Description
`MUMBLE_SERVER`	`localhost:64738`	Mumble server address (`host:port`)
`MUMBLE_USERNAME`	`MusicBot`	Bot display name
`MUMBLE_PASSWORD`	(empty)	Server password (leave empty if none)
`MUMBLE_CHANNEL`	(empty)	Channel to auto-join (e.g. `Music Room`). Empty = stay in root
`MUMBLE_INSECURE`	`false`	Accept self-signed TLS certificates

See .env.example for a template.

Chat Commands#

Command	Description
(YouTube URL)	Queue and play a YouTube video
`!skip`	Skip the current track
`!stop`	Stop playback and clear the queue
`!queue` / `!q`	Show the current queue
`!np` / `!nowplaying`	Show what's currently playing
`!vol <0-100>`	Set playback volume
`!help`	Show available commands

Project Structure#

├── cmd/bot/main.go            # Entrypoint
├── internal/
│   ├── bot/
│   │   ├── bot.go             # Mumble connection and lifecycle
│   │   └── handler.go         # Chat command handling and URL parsing
│   └── player/
│       ├── player.go          # Audio streaming (yt-dlp → ffmpeg → Mumble)
│       └── queue.go           # Thread-safe song queue
├── Dockerfile                 # Multi-stage build (Go builder + Alpine runtime)
├── build.sh / build.ps1       # Image build scripts
├── .env.example               # Configuration template
└── README.md

Configure Feed