README.md

   1 # botamusique
   2
   3 Botamusique is a [Mumble](https://www.mumble.info/) music bot.
   4 Predicted functionalities will be those people would expect from any classic music player.
   5
   6
   7 ## Features
   8
   9 1. **Support multiple music sources:**
  10     - Music in local folders (which can be uploaded through the web interface).
  11     - Youtube/Soundcloud URLs and playlists (everything supported by youtube-dl).
  12     - Radio stations from url and from http://www.radio-browser.info API (query from > 24k stations).
  13 2. **User-friendly web remote control interface.** Powered by flask. Which supports
  14     - Playlist management,
  15     - File management,
  16     - Upload files, etc.
  17 3. **Powerful command system.** Commands and words the bot says are fully customizable. Support partial-match for commands.
  18 4. **Ducking.** The bot would automatically lower its volume if people are talking.
  19
  20
  21 ## Screenshots
  22
  23 ![botamusique in Mumble channel](https://user-images.githubusercontent.com/2306637/75210917-68fbf680-57bd-11ea-9cf8-c0871edff13f.jpg)
  24
  25 ![botamusique web interface](https://user-images.githubusercontent.com/2306637/75210648-9b592400-57bc-11ea-851a-c56907acf702.jpg)
  26
  27
  28 -----
  29 ## Menu
  30 1. [Installation](#installation)
  31 1. [Configuration](#configuration)
  32 1. [Web Interface](#web-interface)
  33 1. [Starting the bot](#starting-the-bot)
  34 1. [Update](#udpate)
  35 1. [Known issues](#known-issues)
  36 1. [Contributors](#contributors)
  37
  38 ### Installation
  39
  40 #### Dependencies
  41 1. Install python3.
  42 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 you package manager).
  43 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.
  44
  45 #### Install botamusique
  46 Stable release (**recommended**, with build-in auto-update support):
  47 ```
  48 curl -Lo botamusique.tar.gz https://azlux.fr/botamusique/sources.tar.gz
  49 tar -xzf botamusique.tar.gz
  50 cd botamusique
  51 python3 -m venv venv
  52 venv/bin/pip install wheel
  53 venv/bin/pip install -r pymumble/requirements.txt
  54 venv/bin/pip install -r requirements.txt
  55 ```
  56
  57 For the version of the master branch (no build-in auto-update support):
  58 ```
  59 git clone --recurse-submodules https://github.com/azlux/botamusique.git
  60 cd botamusique
  61 python3 -m venv venv
  62 venv/bin/pip install wheel
  63 venv/bin/pip install -r pymumble/requirements.txt
  64 venv/bin/pip install -r requirements.txt
  65 ```
  66
  67
  68 ### Configuration
  69 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.
  70
  71 #### Basic settints
  72 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.
  73 ```
  74 [server]
  75 host = 127.0.0.1
  76 port = 64738
  77 ````
  78
  79 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.
  80 ```
  81 [bot]
  82 music_folder = music_folder/
  83 tmp_folder = /tmp/
  84 ```
  85
  86 #### Sections explained
  87 - `server`: configuration about the server. This will be overridden by the `./mumbleBot.py` parameters.
  88 - `bot`: basic configuration of the bot, eg. name, comment, folder, default volume, etc.
  89 - `webinterface`: basic configuration about the interface.
  90 - `commands`: you can customize the command you want for each action (eg. put `help = helpme` , the bot will respond to `!helpme`)
  91 - `radio`: a list of default radio (eg. play a jazz radio with the command `!radio jazz`)
  92 - `strings`: you can customize all words the bot can say.
  93 - `debug`: option to activate ffmpeg or pymumble debug. (Can be very verbose)
  94
  95 #### (Optional) Generate a certificate
  96 Otherwise you wouldn't able to register the bot into your Murmur server.
  97 Please do the following:
  98 `openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout botamusique.pem -out botamusique.pem -subj "/CN=botamusique"`
  99
 100
 101 ### Web interface
 102 **Disabled by default** for performance and security reasons. You need to enable it in `configuration.ini`.
 103 ```
 104 [webinterface]
 105 enabled = True
 106 ```
 107
 108 Default binding address is
 109 ```
 110 listening_addr = 127.0.0.1
 111 listening_port = 8181
 112 ```
 113
 114 You can access the web interface through http://127.0.0.1:8181 if you keep it unchanged.
 115
 116 Note: Listening to address `127.0.0.1` will only accept requests from localhost. If you would to accept requests from 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.
 117
 118
 119 ### Starting the bot
 120 If you have set up everything in your `configuration.ini`, you can
 121 `venv/bin/python mumbleBot.py --config configuration.ini`
 122
 123 Or you can
 124 `venv/bin/python mumbleBot.py -s HOST -u BOTNAME -P PASSWORD -p PORT -c CHANNEL -C /path/to/botamusique.pem`
 125
 126 If you want information about auto-starting and auto-restarting of the bot, [you can check out the wiki.](https://github.com/azlux/botamusique/wiki/AutoStart---AutoRestart)
 127
 128
 129 ### Update
 130 If you enable `audo_check_update`, the bot will check for updates every time it starts.
 131 If you are using the recommended install, you can send `!update` to the bot (command by default).
 132
 133 If you are using git, you need to update manually:
 134 ```
 135 git pull --all
 136 git submodule update
 137 venv/bin/pip install --upgrade -r requirements.txt
 138 ```
 139
 140
 141 ### Known Issues
 142
 143 1. During installation, you may encounter the following error:
 144 ```
 145 ImportError: libtiff.so.5: cannot open shared object file: No such file or directory
 146 ```
 147 You need to install a missing library: `apt install libtiff5`
 148
 149 2. In the beginning, you may encounter the following error even if you have installed all requirements:
 150 ```
 151 Exception: Could not find opus library. Make sure it is installed.
 152 ```
 153 You need to install the opus codec (not embedded in all system): `apt install libopus0`
 154
 155
 156 ### Contributors
 157 If you want to participate, You're welcome to fork and submit pull requests (fixes and new features).
 158
 159 The following people joined the collaborators for a faster development, big thanks to them:
 160 - @TerryGeng
 161 - @mertkutay
 162
 163 Feel free to ask me if you want to help actively without using pull requests.