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.

---

<div align="center">
<h1>🎵 Bragi - Mumble Music Bot 🎵</h1>
</div>

Bragi is a streamlined [Mumble](https://www.mumble.info/) 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](#installation)
2. [Configuration](#configuration)
3. [Run the bot](#run-the-bot)
4. [Commands](#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:**
```bash
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):**
```bash
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:

```ini
[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:**
```ini
[server]
host = 127.0.0.1
port = 64738
channel = Music
```

**Bot Configuration:**
```ini
[bot]
username = Bragi
music_folder = music_folder/
tmp_folder = /tmp/
volume = 0.5
```

**Generate Certificate (Recommended):**
```bash
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout bragi.pem -out bragi.pem -subj "/CN=bragi"
```

Then add to configuration:
```ini
[server]
certificate = bragi.pem
```

## Run the bot

**With configuration file:**
```bash
venv/bin/python bragi.py --config configuration.ini
```

**With command line arguments:**
```bash
venv/bin/python bragi.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:
   ```ini
   [bot]
   refresh_cache_on_startup = False
   ```
   Then use `!refresh` command manually.

## Credits

Bragi is forked from [botamusique](https://github.com/azlux/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.