AURA Engine Core

Engine Core is a multi-channel playout server for radio stations based on Liquidsoap. It is able to broadcast via audio device outputs or connect to Icecast streams.

This documentation is primarily meant for developers. For using the AURA Community Radio Suite check out the documentation at docs.aura.radio

To learn more about Automated Radio go to aura.radio.

Channel Routing

Playout channels are routed this way:

graph TD
    iq0[Queue A] -->|in_queue_0| mix
    iq1[Queue B] -->|in_queue_1| mix
    is0[Stream A] -->|in_stream_0| mix
    is1[Stream B] -->|in_stream_1| mix
    il0[Line In 1-5] -->|in_line_0..4| mix
    ff[Fallback Folder] -->|fallback_folder| which_fallback
    fpls[Fallback Playlist] -->|fallback_playlist| which_fallback
    mix["  Mixer  "] --> silence_detector
    which_fallback{or} -->| | silence_detector{Silence Detector}
    silence_detector -->| | output[Output]
    output --> |output.alsa| C[fa:fa-play Audio Interface]
    output --> |output.icecast| D[fa:fa-play Icecast]

Prerequisites

Before you begin, ensure you have met the following requirements:

• Operating system: Debian 11, Ubuntu 20.04 or newer
• Audio device which has good ALSA support
• Liquidsoap 2.2.4 installed using OPAM (OCaml Package Manager)
• PipeWire installed
• WirePlumber installed as a session / policy manager for PipeWire
• qpwgraph, optional as an UI to manage audio devices
• Docker, optional if you want to run in a container
• git, make

Installing Engine Core

Install system dependencies:

apt install curl alsa-utils libasound2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libflac-dev libjack-dev libpulse-dev libswresample-dev libswscale-dev libssl-dev ffmpeg opam pipewire-jack

Build Liquidsoap with additional libraries:

opam depext alsa pulseaudio bjack ffmpeg samplerate flac taglib mad lame vorbis flac opus cry ocurl liquidsoap -y
opam install alsa pulseaudio bjack ffmpeg samplerate flac taglib mad lame vorbis flac opus cry ocurl liquidsoap -y

Now initialize the project environment for development

make init.dev

This command also creates a default configuration file config/engine-core.ini.

Configuring Engine Core

Configure the audio interface

You get the most glitch-free experience when using PipeWire as your media server. To avoid any play-out malfunctions ensure that no other media server is running. PipeWire is capable of replacing PulseAudio while still having the full functionality of PulseAudio if you want to keep PulseAudio.

To check if PipeWire is up and running you can use

systemctl --user status pipewire

Choose your audio system ALSA / JACK

At the moment we recommend running engine-core with JACK. ALSA support for the complete AURA system was dropped in favour of JACK but might be added back in. In either case PipeWire takes care of your devices and connections.

Configure JACK/ALSA

Have a look at config/sample.engine-core.ini. Here you can set things like the log level and much more. For JACK no adaptations are necessary. When you are finished copy the configuration config/sample.engine-core.ini to config/engine-core.ini.

cp config/sample.engine-core.ini config/engine-core.ini

Configure the audio source locations

Engine Core is requires different audio sources in order to perform the playout.

Configure the location for fallback music

By default fallback audio is retrieved from the fallback folder. A local folder for any emergency playback, also called Station Fallback.

audio/fallback/

All audio files inside are played in a randomized order, in situations where nothing is scheduled. The folder is being watched for changes. So you can add/remove audio on the fly.

This fallback feature is enabled by default, but can be turned off in via the configuration.

Instead of the fallback folder you can use a playlist in the playlist folder for fallback scenarios. Its default file location is:

audio/playlist/station-fallback-playlist.m3u

Also this playlist is being watched for changes. You'll need to set the configuration option fallback_type="playlist" to enable this instead of the fallback folder.

Configure the audio source folder

This is the location for actually scheduled audio files. They are provided by Tank.

audio/source

If you are running all AURA services on a single instance you should be fine with just creating a symbolic link to the relevant Tank folder (ln -s $TANK_STORE_PATH audio/source). But in some distributed and redundant production scenario you might think about more advanced options on how to sync your audio files between machines.

You can find some ideas in the doc "Setting up the Audio Store".

Configure via environment variables

Many settings of Engine Core can also be set via environment variables. They are primarily used for Docker deployments. Check the Makefile and sample.env for hints on environment variables.

Running Engine Core

To make the playout server play some music first create the folder audio/fallback/ if it doesn't exist and drop some music files. This folder is picked up as a so-called Station Fallback in case no other music is scheduled or if silence is detected.

To start the server execute

make run

Connect Audio Device

Now connect your audio device(s) with engine-core. There are two ways to achieve this:

• use an UI like qpwgraph, simply draw connections between the desired devices
• use the PipeWire cli tool pw-link

# List the input ports
pw-link -i
# List the output ports
pw-link -o
# An example for connecting an output port with an input port
pw-link "lineout_0:out_1" "alsa_output.usb-BEHRINGER_UMC202HD_192k_12345678-00.stereo-fallback:playback_FR"
# An example for connecting an input port with an output port
pw-link "alsa_input.usb-Yamaha_Corporation_Yamaha_AG06MK2-00.pro-input-0:capture_AUX0" "in_line_0:in_0"

Voilá, you should hear some music!

Running Engine Core with docker compose

Setup PipeWire

While it is possible to run everything inside containers, we recommend a slightly different approach. Instead of running everything in containers we create a service to run pipewire and wireplumber in a headless session directly on your host. This provides better performance and still allows you to use your audio devices on the host machine.

First of all you need some preparation: make sure that you have pipewire and wireplumber installed. Also make sure to have a user called aura(872:872), this user will be used to run the global pipewire session. If you run the complete aura setup this user will be created during the installation so you probably only need this user if you run a dev setup. Replace $AURA_HOME with a suitable directory and make sure that the user aura can write in this directory.

sudo useradd --system --gid 872 --no-user-group --uid 872 --home-dir ${AURA_HOME} --no-create-home aura; \
sudo passwd aura; \

Then configure PipeWire to run in a headless session:

make audio.pw.install

For these changes to take affect, reboot now.

sudo reboot

You can now check the status of your PipeWire session with

systemctl status pipewire

Setup Docker

Have a look at the sample.env and copy this file to .env. Make sure the directories in .env are read and writable for the user used in the container, mainly aura(872:872).

You can now build the container with

docker compose build

And start it with

docker compose up

Connect your audio device(s) with engine-core as mentioned above. If you want engine-core to automatically connect your device every time you start it, you can also pass the device ports via the .env file to engine-core. For this you need the device name of your in- and output device. To get these run

pw-link -i
pw-link -o

This dumps the name of every connected audio device. Grab the full name, for example alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FL of your device port and enter it in the .env.

alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FL
alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FR
Midi-Bridge:Midi Through:(playback_0) Midi Through Port-0

# Audio Device Settings
AURA_ENGINE_OUTPUT_DEVICE=default
AURA_ENGINE_OUTPUT_CHANNEL_LEFT=alsa_input.pci-0000_00_1f.3.analog-stereo:capture_FL
AURA_ENGINE_OUTPUT_CHANNEL_RIGHT=alsa_input.pci-0000_00_1f.3.analog-stereo:capture_FR
AURA_ENGINE_INPUT_DEVICE=default
AURA_ENGINE_INPUT_CHANNEL_LEFT=alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FL
AURA_ENGINE_INPUT_CHANNEL_RIGHT=alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FR

Voilá, you should hear some music!

Advanced tips for development

Control playout via telnet

Connect to Liquidsoap via Telnet

make tns

List available commands

help

List all available channels

list

List all input channels connected to the mixer

mixer.inputs

Set the volume of mixer input 0 to 100%

mixer.volume 0 100

Push some audio file to the filesystem in_queue_0

in_queue_0.push /path/to/your/file.mp3

Select line in as your input where 4 is the number from mixer.inputs

mixer.select 4 true