-# botamusique
+# botaradio
-======
+Botaradio is a fork of botamusique, a [Mumble](https://www.mumble.info/) music bot.
+Its functionalities are those people would expect from any classic music player,
+Botaradio is itself focused on functionalities expected in a broadcast radio
+context.
-Botamusique is a mumble bot which goal is to allow users to listen music together with its audio output.
-Predicted functionalities will be ones you could expect from any classic music player.
+References to Botamusique are still present all around the source code, and
+this document, they pretty much apply.
-Bot the can play :
-- Radio url
-- Youtube/Soundcloud URL (everything supported by youtube-dl)
-- Local folder (disabled, I need to work on the web interface)
-#### Web interface
-* Disable * I need to work on it. Since I use this bot for radio, youtube/soundcloud and folder music, the web interace isn't ready.
+## Features
-You need to create a folder for all your music. Organize your music by subfolder.
-The main folder needs to be declared in the config (with a '/' at the end)
+1. **Support multiple music sources:**
+ - Music 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 (query from > 24k stations).
+2. **User-friendly web remote control interface.** Powered by Flask. Which supports
+ - Playlist management,
+ - File management,
+ - Upload files, 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.
-#### Installation
-1. You need python 3 with opuslib and protobuf (look at the requirement of pymumble)
-2. The Bot uses ffmpeg, so you know what you have to do if ffmpeg isn't in your package manager. I personally use [this repository](http://repozytorium.mati75.eu/) on my raspberry.
-Example installation commands for Debian and Ubuntu:
+## Screenshots
+
+
+
+
+
+
+-----
+## Menu
+1. [Installation](#installation)
+1. [Configuration](#configuration)
+1. [Web Interface](#web-interface)
+1. [Starting the bot](#starting-the-bot)
+1. [Update](#update)
+1. [Known issues](#known-issues)
+1. [Contributors](#contributors)
+
+### Installation
+
+#### Dependencies
+1. Install python3.
+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.
+
+#### Install botamusique
+Stable release (**recommended**):
+```
+curl -Lo botamusique.tar.gz http://packages.azlux.fr/botamusique/sources.tar.gz
+tar -xzf botamusique.tar.gz
+cd botamusique
+python3 -m venv venv
+venv/bin/pip install wheel
+venv/bin/pip install -r pymumble/requirements.txt
+venv/bin/pip install -r requirements.txt
+```
+
+Testing version (from master):
+```
+git clone --recurse-submodules https://github.com/azlux/botamusique.git
+cd botamusique
+python3 -m venv venv
+venv/bin/pip install wheel
+venv/bin/pip install -r pymumble/requirements.txt
+venv/bin/pip install -r requirements.txt
```
-# apt install python3-pip python3-venv
-# apt install ffmpeg
-# apt install youtube-dl
-$ git clone --recurse-submodules https://github.com/azlux/botamusique.git
-$ cd botamusique
-$ python -m venv venv
-$ venv/bin/pip install -r requirements.txt
+
+
+### Configuration
+Please copy `configuration.example.ini` into `configuration.ini`, follow the instructions in the file and uncomment options you would like to modify. Please DO NOT MODIFY `configuration.default.ini`, since options undefined in `configuration.ini` will fall back into `configuration.default.ini`. This file will be constantly overridden in each update.
+
+#### 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]
+host = 127.0.0.1
+port = 64738
+````
+
+2. You need to specify a folder that stores your music file. The bot will look for music and upload files into that folder. You also need to specify a temporary folder to store music files download from URLs.
+```
+[bot]
+music_folder = music_folder/
+tmp_folder = /tmp/
```
-#### Starting the bot
-`$ venv/bin/python mumbleBot.py -s HOST -u BOTNAME -P PASSWORD -p PORT -c CHANNEL`
+#### Sections explained
+- `server`: configuration about the server. This 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 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`)
+- `strings`: you can customize all words the bot can say.
+- `debug`: option to activate ffmpeg or pymumble debug. (Can be very verbose)
-The bot listen to the 8181 port so you should redirect to this one in you NAT configuration to let others peoples access the web interface. (DISABLED)
+#### (Optional) Generate a certificate
+Otherwise, you wouldn't able to register the bot into your Murmur server.
+Please do the following:
+`openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout botamusique.pem -out botamusique.pem -subj "/CN=botamusique"`
-#### Custom commands
-You can copy the file `configuration.default.ini` to `configuration.ini` and customize all variable.
-you have the section :
-- bot : basic configuration of the bot : comment, folder, volume at start ....
-- command : you can customize the command you want for each action (if you put `help = helpme` , the bot will response to `!helpme` )
-- radio : here you can have a list of default radio ( I can play a jazz radio with the command `!radio jazz`)
-- strings : you can customize all string the bot can say.
+
+### Web interface
+**Disabled by default** for performance and security reasons. You need to enable it in `configuration.ini`.
+```
+[webinterface]
+enabled = True
+```
+
+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 accept requests 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 your router to the bot.
+
+
+### Starting 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).**
+
+
+### Update
+If you enable `audo_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`
-2.TODO list
+### Contributors (botamusique)
+If you want to participate, You're welcome to fork and submit pull requests (fixes and new features).
-### TODOLIST
+The following people joined the collaborators for a faster development, big thanks to them:
+- @TerryGeng
+- @mertkutay
-Check the issue #3
+Feel free to ask me if you want to help actively without using pull requests.
projects / botaradio.git / blobdiff