storm/bragi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More cleanup, merged pymumble into the project so I don't have to maintain 2 separate things, tested working version.

Browse Source
This commit is contained in:
Storm Dragon
2025-06-14 00:23:09 -04:00
parent bfbfe30be4
commit 947ec68754
36 changed files with 5861 additions and 551 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
README.md
View File

@@ -1,292 +1,190 @@
# Important Announcement
# Bragi
Hello everyone,
## About the Name
First, let's look at the problems:
1. I don't use mumble anymore, working on a bot you don't use produces a leak of testing and motivation.
2. I don't code like before, my hobbies have changed, I maintain stuff I still use, but no real coding anymore.
3. Botamusique is monolitique
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.
I've been trying to make a POC to change the monolitique part, to have a fully modulable bot, with asyncio and and feature/backend as plugins. But asyncio was blocking for me, especially to make the bot with fastapi, discord api / pymumble. It's 2 async loop and I don't have the knowledge to make it work.
To be transparent, botamusique was the biggest project I've done, one of the funniest. Thanks @TerryGeng for joining the adventure.
I don't think I will be looking for a maintainer, the monolithic part of this project is not something that needs to be maintained.
**This projet will be archived.**
BUT If someone want to rewrite a bot, I'm ready to help with the projet : what to do, Errors to avoid, Design/architecture help (but no code). I think **_8 years_** on this projet (have start with [this small projet](https://github.com/azlux/MumbleRadioPlayer/commit/56ca276c5519fcb0e1af043beb043202e65c2cca)) can help someone.
It was really funny, thank all, for your support !
See you in space cowboy.
-- Azlux
-----
---
<div align="center">
<img src="static/image/logo.png" alt="botamusique" width="200px" />
<h1>botamusique</h1>
<h1>🎵 Bragi - Mumble Music Bot 🎵</h1>
</div>
Botamusique is a [Mumble](https://www.mumble.info/) music bot.
Predicted functionalities will be those people would expect from any classic music player.
[![Build Status](https://ci.azlux.fr/api/badges/azlux/botamusique/status.svg)](https://ci.azlux.fr/azlux/botamusique)
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 (which can be uploaded through the web interface).
- Youtube/Soundcloud URLs and playlists (everything supported by youtube-dl).
- Radio stations from URL and http://www.radio-browser.info API.
2. **Modern and powerful web remote control interface.** Powered by Flask. Which supports:
- Playlist management.
- Music library management, including uploading, browsing all files and edit tags, etc.
3. **Powerful command system.** Commands and words the bot says are fully customizable. Support partial-match for commands.
4. **Ducking.** The bot would automatically lower its volume if people are talking.
5. **Stereo sound.** After Mumble 1.4.0, stereo output support has been added. Our bot is designed to work nicely with it naturally.
6. **Multilingual support.** A list of supported languages can be found below.
- 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
## Screenshots
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
![botamusique in Mumble channel](https://user-images.githubusercontent.com/2306637/75210917-68fbf680-57bd-11ea-9cf8-c0871edff13f.jpg)
![botamusique web interface](https://user-images.githubusercontent.com/2306637/77822763-b4911f80-7130-11ea-9bc5-83c36c995ab9.png)
-----
## Quick Start Guide
1. [Installation](#installation)
1. [Configuration](#configuration)
1. [Run the bot](#run-the-bot)
1. [Operate the bot](#operate-the-bot)
1. [Update](#update)
1. [Known issues](#known-issues)
1. [Contributors](#contributors)
2. [Configuration](#configuration)
3. [Run the bot](#run-the-bot)
4. [Commands](#commands)
## Installation
### Dependencies
1. Install python. We require a python version of 3.6 or higher.
1. Install [Opus Codec](https://www.opus-codec.org/) (which should be already installed if you installed Mumble or Murmur, or you may try to install `opus-tools` with your package manager).
1. Install ffmpeg. If ffmpeg isn't in your package manager, you may need to find another source. I personally use [this repository](http://repozytorium.mati75.eu/) on my raspberry.
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
### Docker
See https://github.com/azlux/botamusique/wiki/Docker-install
### Install Bragi
Both stable and nightly (developing) builds are available!
### Manual install
**Stable release (recommended)**
This is current stable version, with auto-update support. To install the stable release, run these lines in your terminal:
```
curl -Lo botamusique.tar.gz http://packages.azlux.fr/botamusique/sources-stable.tar.gz
tar -xzf botamusique.tar.gz
cd botamusique
**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
```
**Nightly build (developing version)**
<details>
<summary>Click to expand!</summary>
This build reflects any newest change in the master branch, with auto-update support baked in. This version follow all commits into the master branch.
**Required system packages (Arch Linux example):**
```bash
sudo pacman -S opus ffmpeg python-magic
```
curl -Lo botamusique.tar.gz http://packages.azlux.fr/botamusique/sources-testing.tar.gz
tar -xzf botamusique.tar.gz
cd botamusique
python3 -m venv venv
venv/bin/pip install wheel
venv/bin/pip install -r requirements.txt
```
</details>
**Build from source code**
<details>
<summary>Click to expand!</summary>
You can checkout the master branch of our repo and compile everything by yourself.
We will test new features in the master branch, maybe sometimes post some hotfixes.
Please be noted that the builtin auto-update support doesn't track this version.
If you have no idea what these descriptions mean to you, we recommend you install the stable version above.
```
git clone https://github.com/azlux/botamusique.git
cd botamusique
python3 -m venv venv
venv/bin/pip install wheel
venv/bin/pip install -r requirements.txt
(cd web && npm install && npm run build)
venv/bin/python3 ./scripts/translate_templates.py --lang-dir lang/ --template-dir web/templates/
```
</details>
## Configuration
Please copy `configuration.example.ini` into `configuration.ini`, follow the instructions in that file and uncomment options you would like to modify. Not all sections are needed. You may just keep the options that matter to you. For example, if you only would like to set `host`, all you need you is keep
```
1. Copy `configuration.example.ini` to `configuration.ini`
2. Edit the configuration file with your server details:
```ini
[server]
host=xxxxxx
host = your.mumble.server
port = 64738
channel = Music
[bot]
username = Bragi
music_folder = /path/to/your/music
```
in your `configuration.ini`.
Please DO NOT MODIFY `configuration.default.ini`, since if the bot realizes one option is undefined in `configuration.ini`, it will look into `configuration.default.ini` for the default value of that option. This file will be constantly overridden in each update.
**DO NOT MODIFY** `configuration.default.ini` - it contains default values that may be overridden during updates.
We list some basic settings for you to quickly get things working.
### Basic Settings
### Basic settings
1. Usually, the first thing is to set the Murmur server you'd like the bot to connect to. You may also specify which channel the bot stays, and tokens used by the bot.
```
**Server Connection:**
```ini
[server]
host = 127.0.0.1
port = 64738
channel = Music
```
2. You need to specify a folder that stores your music files. The bot will look for music and upload files into that folder. You also need to specify a temporary folder to store music file downloads from URLs.
```
**Bot Configuration:**
```ini
[bot]
username = Bragi
music_folder = music_folder/
tmp_folder = /tmp/
volume = 0.5
```
3. **Web interface is disabled by default** for performance and security reasons. It is extremely powerful, so we encourage you to have a try. To enable it, set
```
[webinterface]
enabled = True
**Generate Certificate (Recommended):**
```bash
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout bragi.pem -out bragi.pem -subj "/CN=bragi"
```
Default binding address is
```
listening_addr = 127.0.0.1
listening_port = 8181
```
You can access the web interface through http://127.0.0.1:8181 if you keep it unchanged.
Note: Listening to address `127.0.0.1` will only accept requests from localhost. _If you would like to connect from the public internet, you need to set it to `0.0.0.0`, and set up username and password to impose access control._ In addition, if the bot is behind a router, you should also properly set forwarding rules in you NAT configuration to forward requests to the bot.
4. The default language is English, but you can change it in `[bot]` section:
```
[bot]
language=en_US
```
Available translations can be found inside `lang/` folder. Currently, options are
- `en_US`, English
- `es_ES`, Spanish
- `fr_FR`, French
- `it_IT`, Italian
- `ja_JP`, Japanese
- `zh_CN`, Chinese
5. Generate a certificate (Optional, but recommended)
By default, murmur server uses certificates to identify users. Without a valid certificate, you wouldn't able to register the bot into your Murmur server. Some server even refused users without a certificate. Therefore, it is recommended to generate a certificate for the bot. If you have a certificate (for say, `botmusique.pem` in the folder of the bot), you can specify its location in
```
Then add to configuration:
```ini
[server]
certificate=botamusique.pem
certificate = bragi.pem
```
If you don't have a certificate, you may generate one by:
`openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout botamusique.pem -out botamusique.pem -subj "/CN=botamusique"`
### Sections explained
- `server`: configuration about the server. Will be overridden by the `./mumbleBot.py` parameters.
- `bot`: basic configuration of the bot, eg. name, comment, folder, default volume, etc.
- `webinterface`: basic configuration about the web interface.
- `commands`: you can customize the command you want for each action (eg. put `help = helpme` , the bot will respond to `!helpme`)
- `radio`: a list of default radio (eg. play a jazz radio with the command `!radio jazz`)
- `debug`: option to activate ffmpeg or pymumble debug output.
## Run the bot
If you have set up everything in your `configuration.ini`, you can
`venv/bin/python mumbleBot.py --config configuration.ini`
Or you can
`venv/bin/python mumbleBot.py -s HOST -u BOTNAME -P PASSWORD -p PORT -c CHANNEL -C /path/to/botamusique.pem`
If you want information about auto-starting and auto-restarting of the bot, you can check out the wiki page [Run botamusique as a daemon In the background](https://github.com/azlux/botamusique/wiki/Run-botamusique-as-a-daemon-In-the-background).
**For the detailed manual of using botamusique, please see the [wiki](https://github.com/azlux/botamusique/wiki).**
## Operate the bot
You can control the bot by both commands sent by text message and the web interface.
By default, all commands start with `!`. You can type `!help` in the text message to see the full list of commands supported, or see the examples on the [wiki page](https://github.com/azlux/botamusique/wiki/Command-Help-and-Examples).
The web interface can be used if you'd like an intuitive way of interacting with the bot. Through it is fairly straightforward, a walk-through can be found on the [wiki page](https://github.com/azlux/botamusique/wiki/Web-interface-walk-through).
## Update
If you enable `auto_check_update`, the bot will check for updates every time it starts.
If you are using the recommended install, you can send `!update` to the bot (command by default).
If you are using git, you need to update manually:
```
git pull --all
git submodule update
venv/bin/pip install --upgrade -r requirements.txt
```
## Known issues
1. During installation, you may encounter the following error:
```
ImportError: libtiff.so.5: cannot open shared object file: No such file or directory
```
You need to install a missing library: `apt install libtiff5`
2. In the beginning, you may encounter the following error even if you have installed all requirements:
```
Exception: Could not find opus library. Make sure it is installed.
```
You need to install the opus codec (not embedded in all system): `apt install libopus0`
3. MacOS Users may encounter the following error:
```
ImportError: failed to find libmagic. Check your installation
```
This is caused by missing `libmagic` binaries and can be solved by
**With configuration file:**
```bash
brew install libmagic
venv/bin/python mumbleBot.py --config configuration.ini
```
One may also install `python-magic-bin` instead of `python-magic`.
5. If you have a large amount of music files (>1000), it may take some time for the bot to boot, since
it will build up the cache for the music library on booting. You may want to disable this auto-scanning by
setting ``refresh_cache_on_startup=False`` in `[bot]` section and control the scanning manually by
``!rescan`` command and the *Rescan Files* button on the web interface.
6. Alpine Linux requires some extra dependencies during the installation (in order to compile Pillow):
**With command line arguments:**
```bash
venv/bin/python mumbleBot.py -s HOST -u Bragi -P PASSWORD -p PORT -c CHANNEL -C /path/to/bragi.pem
```
python3-dev musl-lib libmagic jpeg-dev zlib-dev gcc
```
For more information, see [#122](https://github.com/azlux/botamusique/issues/122).
## _I need help!_
## Commands
If you ran into some problems in using the bot, or discovered bugs and want to talk to us, you may
All commands start with `!` by default. Type `!help` in Mumble chat for a full list.
- Start a new issue,
- Ask in the Matrix channel of Mumble [#mumble:matrix.org](https://matrix.to/#/#mumble:matrix.org) (we are usually there to help).
**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
## Contributors
If you want to help us develop, you're welcome to fork and submit pull requests (fixes and new features).
We are looking for people helping us translating the bot. If you'd like to add a new language or fix errors in existed translations,
feel free to catch us in the IRC channel #mumble, or just email us!
**File Management:**
- `!file <search>` - Search for local files
- `!queue` - Show current playlist
- `!clear` - Clear playlist
The following people joined as collaborators for a faster development, big thanks to them:
- @TerryGeng
- @mertkutay
**Radio:**
- `!radio <station>` - Play radio station
- `!rb <search>` - Search radio-browser.info
Feel free to ask me if you want to help actively without using pull requests.
**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.