Minimalistic endless music player for Radio Bern RaBe based on liquidsoap

Klangbecken

Klangbecken is the minimalistic endless music player for Radio Bern RaBe based on liquidsoap.

It supports configurable and editable playlists, jingle insertion, metadata publishing and more.

It is designed for stand-alone operation, robustness and easy maintainability.

This repository contains three components of the RaBe-Klangbecken:

Two additional components are in their own repository:

The listener for the current "on air" status, the virtual Sämubox.
The web-based UI for playlist editing.

How they interact can be seen in the system overview diagram:

Klangbecken

System requirements

Unix-like operating system environment
Python >= 3.6
- docopt library for parsing command line arguments
- Werkzeug library for WSGI support
- PyJWT library (>= v2.0.0) for creating and verifing JWT authentication tokens
- mutagen library for audio tag editing
ffmpeg binary (>=4.0) for audio analysis
Liquidsoap audio player

Setup

Clone the repository

git clone https://github.com/radiorabe/klangbecken.git
cd klangbecken

We strongly recommend to create a virtual environment (see additional tools). E.g.

python -m venv .venv
source .venv/bin/activate

Install dependencies

Install Python dependencies

pip install -r requirements.txt

Install ffmpeg with your system's package manager. E.g.

yum install ffmpeg

Install Liquidsoap (on CentOS 7 you can also use our prebuilt package)

yum install opam
opam init
# we need liquidsoap 1.3.7 which does not run after OCaml 4.07.0
opam switch create klangbecken 4.07.0
opam depext alsa mad lame vorbis taglib liquidsoap.1.3.7
opam install alsa mad lame vorbis taglib liquidsoap.1.3.7

Install the client UI:

cd ..
git clone https://github.com/radiorabe/klangbecken-ui
cd klangbecken-ui
npm install

Run the programs

Initialize the data directory:

python -m klangbecken init

Run the development API server:

python -m klangbecken serve

Run the client UI development server:

cd ../klangbecken-ui
npm run serve

Browse to http://localhost:8080 and start uploading audio files.

Run the liquidsoap audio player:

eval $(opam env)
liquidsoap klangbecken.liq

Manually set the onair status of the player using netcat:

echo "klangbecken.on_air True" | nc -U -w 1 klangbecken.sock

Development

Python Package

The Python code is tested with a test suite and follows the flake8 coding guidelines.

Before submitting your code make sure that ...

... you have installed the test dependencies
```
pip install -r requirements-test.txt
```
... the test suite runs without failure
```
python -m unittest discover
```

... all your code is covered by unit tests

coverage run -m unittest discover
coverage report

... your code follows the coding style guidelines
```
flake8
```

Recommended Tools (optional)

We recommend the use of tox, black and isort for development.

pip install tox black isort

Instead of running all the above commands manually, tox lets you run them all at once for all installed Python versions. Make sure to have at least the Python version additionally installed, that is used in production (currently Python 3.6). tox is also what we use in continous integration, so using it locally helps you to make your code pass it.

tox

Manually fixing coding style mistakes is a pain. black formats your code automatically.

black .

Finally, isort helps to consistantly organize package imports.

isort .

All development tools are preconfigured in setup.cfg. For additional tools and tips & tricks and see additional tools.

Liquidsoap Script

Liquidsoap lets you syntax check and type check your script:

liquidsoap --check klangbecken.liq

Deployment

The deploy script deploy.sh automates deploying the code.

Preparation:

Configure a remote repository upstream pointing at the upstream repository (https://github.com/radiorabe/klangbecken).
Configure git to automatically fetch tags from upstream/master:
```
git config remote.upstream.tagOpt --tags
```
Configure a remote prod pointing at the repository on the production system.
Pull the latest version from upstream:
```
git pull upstream master --ff-only
```
Verify that the code you want to deploy passed continuous integration.
Make sure that your working directory is clean.

Run the script:

./deploy.sh [--no-mod-wsgi]

It perfoms the following steps:

Increment and commit a new version number.
Download all run-time dependencies.
Optionally download mod_wsgi (requires httpd-devel libraries to be installed locally).
scp the dependencies to production.
Push your code to production.
Install all dependencies in production.
Install the Python package (API and CLI) in production.
Reload the web server to load the new API code.
Copy the liquidsoap script to it's destination.
If everything was successful, tag the current commit with the new version number, and push it to the upstream repository.

Finalize deployment:

If the liquidsoap script (klangbecken.liq) changed, restart the liquidsoap player during a "off air" moment:
```
systemctl restart liquidsoap@klangbecken
```