Installation manual
Before proceeding, make sure to follow the preparation steps.
Service |
Required |
Description |
---|---|---|
engine |
✅ |
Control and scheduling for the play-out |
engine-core |
✅ |
Play-out Engine |
engine-api |
✅ |
API for playlogs and track service |
engine-recorder |
Record audio blocks, including archiving |
The required services are needed for minimal functionality.
Prerequisites
ALSA compatible audio interface.
PipeWire installed on the host machine.
WirePlumber installed on the host machine
In addition you will need the Pipewire JACK plugin (
pipewire-jack
).In production, we recommend to run PipeWire as a system wide daemon with the
aura
user
Setup PipeWire as a system wide daemon
While it is possible to run PipeWire completely inside containers, we recommend a slightly different approach. Instead, 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.
make aura-playout.pw.install
This creates the necessary system services, loads the default pipewire configuration to /etc/pipewire/pipewire.conf
and creates the socket which pipewire later uses to communicate with aura-playout. After everything is installed you need to reboot your machine for the changes to take effect.
sudo reboot
Check if PipeWire is running
Before proceeding, check if PipeWire is running with systemctl status pipewire.service
.
Deploy AURA Playout
To initialize the playout deployment execute:
make aura-playout.init
This creates a configuration file config/aura-playout/.env
based on the sample.env
located in
the same directory. Additionally this command creates the required folder structure and updates
relevant permissions.
Update the configuration file
For a production deployment verify at least the following settings. For testing the playout, the defaults should work in most cases.
Environment variable |
Description |
---|---|
|
The password should match the one configured in AURA Web. Avoid using the default one. |
|
The location where Tank is storing audio sources. It defaults to |
|
The location where M3U playlists are provided. This is optional and defaults to |
|
The location where fallback audio is retrieved from. Such audio is played when nothing is scheduled. It defaults to |
In case you prefer deploying AURA Web and AURA Playout on two distinct server instances (e.g. Advanced Deployment Scenario), you have to update the following variables too.
Environment variable |
Description |
---|---|
|
Points to Steering in the local Docker network by default. Change value to |
|
Points to Tank in the local Docker network by default. Change value to |
It is important to note, that the URLs have to end with a trailing slash (/
).
Verify if AURA Web is running
In order to avoid complicated debugging of the connection between AURA Playout and AURA Web, try
if the URL https://aura.myradio.org/steering/admin
is working. It works if you get a login
page served.
Provide some audio files for fallback
Now drop some music files into that folder audio/fallback
, respectively the directory you have
set for AURA_AUDIO_STORE_FALLBACK
.
Any audio files located here will be picked up and played whenever nothing else is scheduled.
Connect AURA Playout with your audio interface
There are three options to wire the playout with your audio interface:
Option 1: Use an UI tool like qpwgraph, simply draw connections between the desired devices
Option 2: Use the cli tool
pw-link
Option 3: Use the auto connect feature
When connecting the correct audio ports you will hear the fallback music playing immediately.
Option 1: UI tool
First, start AURA Playout with
docker compose up -d
Then open a graph manager compatible with PipeWire, like qpwgraph. Now simply connect the AURA Playout nodes aura_engine_line_in_0
and aura_engine_line_out_0
with your audio device.
Option 2: CLI tool pw-link
To connect AURA Playout with your audio device(s) start everything with
docker compose up -d
Now list your input and output ports. There is a port for each channel on your device and a port for the left and the right channel from AURA playout.
# List the input ports
pw-link -i
# List the output ports
pw-link -o
Connect your port like in the example below, where you replace alsa_input.usb-Yamaha_Corporation_Yamaha_AG06MK2-00.pro-input-0:capture_AUX0
with your audio device given from pw-link
.
# An example for connecting everything:
# line out
pw-link "aura_engine_line_out_0:out_0" "alsa_output.usb-Yamaha_Corporation_Yamaha_AG06MK2-00.pro-output-0:playback_AUX0"
pw-link "aura_engine_line_out_0:out_1" "alsa_output.usb-Yamaha_Corporation_Yamaha_AG06MK2-00.pro-output-0:playback_AUX1"
# line in
pw-link "alsa_input.usb-Yamaha_Corporation_Yamaha_AG06MK2-00.pro-input-0:capture_AUX0" "aura_engine_line_in_0:in_0"
pw-link "alsa_input.usb-Yamaha_Corporation_Yamaha_AG06MK2-00.pro-input-0:capture_AUX1" "aura_engine_line_in_0:in_1"
Option 3: Auto connect feature
If you don’t want to run Option 1 or Option 2 every time you start AURA Playout there is a way to connect everything when you start AURA Playout. For this you need to set the audio device(s) and channels in the .env
file before you start AURA Playout. Simply list the ports for your device(s) with
# List the input ports
pw-link -i
# List the output ports
pw-link -o
And enter the full names in your .env
.
Example Configuration
Given this device information, dumped by pw-link -io
:
Midi-Bridge:Midi Through:(capture_0) Midi Through Port-0
Midi-Bridge:Midi Through:(playback_0) Midi Through Port-0
alsa_output.pci-0000_00_1f.3.analog-stereo:monitor_FL
alsa_output.pci-0000_00_1f.3.analog-stereo:monitor_FR
alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FL
alsa_output.pci-0000_00_1f.3.analog-stereo:playback_FR
alsa_input.pci-0000_00_1f.3.analog-stereo:capture_FL
alsa_input.pci-0000_00_1f.3.analog-stereo:capture_FR
Set these values for the input and output settings in your .env
file:
# 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
Now that you have your device ports in the .env
file you can start AURA Playout with
docker compose up -d
Playout 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] -->|aura_engine_line_in_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]
Deploy Play-Out bundled with Recorder (optional)
By default the Docker Compose will not deploy the the AURA Recorder. If you want to deploy the AURA Recorder on the same Host start the compose service with
docker compose --profile engine-recorder-enabled up -d
Configure the audio source locations
You need to setup 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_folder="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 name is station-fallback-playlist.m3u
and located in:
audio_playlist_folder="audio/playlist"
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_folder="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 $PLAYOUT_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.
Features and how they work
Scheduler
Engine provide a scheduling functionality by polling external API endpoints frequently. Those API endpoints are provided by Steering to retrieve schedule information and Tank to retrieve playlist information. To define your schedule you’ll also need AURA Dashboard which is an elegent web user interface to manage your shows, playlists and schedules.
Ideally any audio is scheduled some time before the actual, planned playout to avoid timing issues with buffering and preloading. Nonetheless, playlists can also be scheduled after a given calendar timeslot has started already. In such case the playout starts as soon it is preloaded.
If for some reason the playout is corrupted, stopped or too silent to make any sense, then this triggers a fallback using the silence detector (see chapter below).
Note: If you delete any existing timeslot in Dashboard/Steering this is only reflected in Engine until the start of the scheduling window. The scheduling window is defined by the start of the timeslot minus a configured offset in seconds (compare your Engine configuration).
Versatile playlists
It is possible to schedules playlists with music or pre-recorded shows stored on the file system, via external streams or live from an line input in the studio. All types of sources can be mixed in a single playlist.
The switching between types of audio source is handled automatically, with configured fadings applied.
Note: Any live sources or streams not specifying a length property, are automatically expanded to the left duration of the timeslot.
Default playlists
While a timeslot can have a specific playlist assigned, it is also possible to define default playlists for schedules and shows:
Default Schedule Playlist: This playlist is defined on the level of some recurrence rules (Schedule). In case the timeslot doesn’t have any specific playlist assigned, this playlist is broadcasted.
Default Show Playlist: This playlist can be assigned to some show. If neither the specific timeslot playlist nor the default schedule playlist is specified the default show playlist is broadcasted.
If none of these playlists have been specified the Auto DJ feature of Engine Core takes over (optional).
Heartbeat Monitoring
Instead of checking all status properties, the Heartbeat only validates the vital ones required to run the engine. If all of those are valid, a network socket request is sent to a defined server. This heartbeat is sent continuously based on the configured heartbeat_frequency
. The service receiving this heartbeat ticks can decide what to do with that information. One scenario could be switching to another Engine instance or any other custom failover scenario. Under engine/contrib/heartbeat-monitor
you’ll find some sample application digesting these heartbeat signals.