bragi/README.md

Bragi

About the Name

Bragi is named after the Norse god of poetry, music, and eloquence. In Norse mythology, Bragi was known for his wisdom and skill with words, and was considered the patron of poets and musicians. This makes him the perfect namesake for a Mumble music bot that brings music and audio content to voice channels.

---

🎵 Bragi - Mumble Music Bot 🎵

Bragi is a streamlined Mumble music bot forked from the original botamusique project. Designed as a self-contained, lightweight solution focused on core music playback functionality without unnecessary complexity.

Features

1. Support multiple music sources:
   • Music files in local folders
   • YouTube/SoundCloud URLs and playlists (via yt-dlp)
   • Radio stations from URL and radio-browser.info API
2. Text-based command interface - Control the bot entirely through Mumble text commands
3. Powerful command system - Commands are fully customizable with partial-match support
4. Ducking - Automatically lowers volume when people are talking
5. Stereo sound - Full stereo output support for Mumble 1.4.0+
6. Python 3.13 compatible - Modern Python support with integrated dependencies

Design Philosophy

Bragi focuses on being a self-contained, lightweight Mumble music bot without unnecessary complexity. The codebase prioritizes:

• Core music playback functionality
• Text-based command interface only
• Minimal external dependencies
• Direct Python execution

Quick Start Guide

1. Installation
2. Configuration
3. Run the bot
4. Commands

Installation

Dependencies

1. Python 3.6 or higher (Python 3.13 recommended)
2. Opus Codec - Usually installed with Mumble, or install opus-tools with your package manager
3. ffmpeg - For audio processing

Install Bragi

From source:

git clone https://git.stormux.org/storm/bragi
cd bragi
python3 -m venv venv
venv/bin/pip install wheel
venv/bin/pip install -r requirements.txt

Required system packages (Arch Linux example):

sudo pacman -S opus ffmpeg python-magic

Configuration

1. Copy configuration.example.ini to configuration.ini
2. Edit the configuration file with your server details:

[server]
host = your.mumble.server
port = 64738
channel = Music

[bot]
username = Bragi
music_folder = /path/to/your/music

DO NOT MODIFY configuration.default.ini - it contains default values that may be overridden during updates.

Basic Settings

Server Connection:

[server]
host = 127.0.0.1
port = 64738
channel = Music

Bot Configuration:

[bot]
username = Bragi
music_folder = music_folder/
tmp_folder = /tmp/
volume = 0.5

Generate Certificate (Recommended):

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout bragi.pem -out bragi.pem -subj "/CN=bragi"

Then add to configuration:

[server]
certificate = bragi.pem

Run the bot

With configuration file:

venv/bin/python mumbleBot.py --config configuration.ini

With command line arguments:

venv/bin/python mumbleBot.py -s HOST -u Bragi -P PASSWORD -p PORT -c CHANNEL -C /path/to/bragi.pem

Commands

All commands start with ! by default. Type !help in Mumble chat for a full list.

Basic Controls:

• !play <file/url> - Play a file or URL
• !pause - Pause playback
• !stop - Stop playback
• !skip - Skip current track
• !volume <0-100> - Set volume

File Management:

• !file <search> - Search for local files
• !queue - Show current playlist
• !clear - Clear playlist

Radio:

• !radio <station> - Play radio station
• !rb <search> - Search radio-browser.info

Admin Commands:

• !kill - Shut down the bot (admin only)
• !refresh - Refresh music cache (admin only)

Configuration Sections

• [server] - Mumble server connection settings
• [bot] - Basic bot configuration (name, folders, volume, etc.)
• [commands] - Customize command names
• [radio] - Default radio stations
• [debug] - Enable debug output for troubleshooting

Known Issues

1. Missing opus library:

   Exception: Could not find opus library. Make sure it is installed.
   

   Install opus: sudo pacman -S opus (Arch) or apt install libopus0 (Debian/Ubuntu)

2. Missing libmagic:

   ImportError: failed to find libmagic. Check your installation
   

   Install magic: sudo pacman -S python-magic (Arch) or apt install python3-magic (Debian/Ubuntu)

3. Large music libraries (>1000 files) may take time to scan on startup. Disable with:

   [bot]
   refresh_cache_on_startup = False
   

   Then use !refresh command manually.

Credits

Bragi is forked from botamusique by azlux.

Original contributors:

• azlux - Original botamusique creator
• TerryGeng - Major contributor
• mertkutay - Collaborator

License

This project maintains the same license as the original botamusique project.