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. All files are stored in a single data directory.
This repository contains three components of the RaBe Klangbecken:
- The API
- The command line interface
- The liquidsoap playout script
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:
System requirements
- Unix-like operating system environment
- Python (>= v3.7)
- docopt library for parsing command line arguments
- Werkzeug library (>= v2.0) for WSGI support
- PyJWT library (>= v2.0) for creating and verifing JWT authentication tokens
- mutagen library for audio tag editing
- ffmpeg binary (>= v2.8) for audio analysis
- Liquidsoap audio player (v1.3 without inotify support)
Local 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
eval $(opam env)
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 backend server (API and data directory):
python -m klangbecken serve
Run the client development server (user interface):
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
For contributing to this project, fork this repository, and clone your local working copy from your personal fork. Push commits to your repository to create a pull request with your changes.
Python Package
The Python code is tested with a test suite and follows the flake8 coding guidelines.
Before submitting your code you might want to 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 (hopefully) meaningful 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
tox
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 installed, that is used in production (currently Python 3.9). tox is also what we use in continuos integration, so using it locally helps you to make your code pass it. To call it simply type:
tox
black
Manually fixing coding style mistakes is a pain. black formats your code automatically.
black .
isort
Finally, isort helps to consistently 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
Simulation
Apart from type checking, the inherent nature of the liquidsoap language generating a live audio stream makes it difficult to test the code with unit tests. Observing the behavior of the player script and the effects of changes in real-time take lot of time, usually weeks or even months. Accellerated simulation runs help to observe the long-time player behavior in a reasonable amount of time.
Deployment
Your code has passed continuous integration, and your pull request has been accepted. Now you want to deploy your (or somebody else's) code to production. First, some preparation is necessary, but then the deployment script deploy.sh automates most of the work deploying the code.
Preparation before deploying for the first time:
- Make sure that you have access to the production server (e.g. SSH publik key authentication).
- Configure a remote
prodpointing at the repository on the production system.git add remote prod root@YOUR_PRODUCTION_VM_NAME:klangbecken.git
- Optional: Install the Apache development libraries locally. E.g.
yum install httpd-devel
- Configure a remote repository
upstreampointing at this upstream repository:git remote add upstream [email protected]:radiorabe/klangbecken-ui.git
- Configure git to automatically fetch tags from
upstream:git config remote.upstream.tagOpt --tags
Preparation before deploying:
- When deploying both, the front-end and the back-end app, deploy the front-end first.
- Check again that the code you want to deploy passed continuous integration.
- Make sure that your working directory is clean, and that you are on the master branch:
git stash git checkout master
- Bring your code in sync with the latest version from
upstream:git fetch upstream git rebase upstream/master
- Verify that you are indeed in sync with
upstream:git show --no-patch
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(Requireshttpd-devellibraries to be installed locally. Use--no-mod-wsgito not reinstallmod_wsgi). - Copy 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
upstreamrepository.
Finalize deployment:
- If the liquidsoap script (
klangbecken.liq) changed, restart the liquidsoap player during a "off air" moment:systemctl restart liquidsoap@klangbecken
For detailed information on how to setup a productive server see Deployment.
License
Klangbecken is released under the terms of the GNU Affero General Public License. Copyright 2017-2021 Radio RaBe. See LICENSE for further information.
482 Dec 19, 2022
1.2k Jan 7, 2023
58 Jan 2, 2023
1 Dec 20, 2021
3 Jun 30, 2022
3 Jan 8, 2022
1 Dec 22, 2021
2 Dec 23, 2021
7 Oct 21, 2022
327 Dec 19, 2022
2 Oct 25, 2021
1 Oct 27, 2021
1 Nov 4, 2021
1 Nov 19, 2021
1 Dec 24, 2021
2 Feb 3, 2022
12 Nov 12, 2022
2 May 12, 2022
16 Oct 21, 2022
