Commit e82a07eb authored by david's avatar david
Browse files

General rework of the docs. #72

parent 1c8fd057
......@@ -5,63 +5,114 @@
<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-engine.png" width="250" align="right" />
Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for
the requirements of community radios.
the requirements of community radio stations.
<!-- TOC -->
- [Aura Engine](#aura-engine)
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Functionality](#functionality)
- [Scheduler](#scheduler)
- [Versatile playlists](#versatile-playlists)
- [Default playlists](#default-playlists)
- [Heartbeat Monitoring](#heartbeat-monitoring)
- [Logging](#logging)
- [Getting started](#getting-started)
- [Using Docker](#using-docker)
- [Read more](#read-more)
- [About](#about)
- [Resources](#resources)
<!-- /TOC -->
## Features
## Functionality
- **Scheduler** to automatically broadcast your radio programme (see [AURA Dashboard](https://gitlab.servus.at/aura/dashboard) for an schedule user interface)
- **Play audio from multiple sources** including files, streams and analog live audio
- **Dynamic switching of sources** organized as playlists
- **Stream output** to an Icecast Server
- **Multichannel Line-out**
- **Silence Detector** to avoid [Dead Air](https://en.wikipedia.org/wiki/Dead_air)
- **Auto DJ** which plays random music when silence is detected
- **ReplayGain** normalization done using passed [ReplayGain](https://en.wikipedia.org/wiki/ReplayGain) meta data
- **API** to query Track-Service, monthly reports and information for displaying the Studio Clock (see [Engine API](https://gitlab.servus.at/aura/engine-api))
In conjuction with other AURA components Engine provides several features:
- **Scheduler** to automatically broadcast your radio programme (see [AURA Dashboard](https://gitlab.servus.at/aura/dashboard) for an user interface to do scheduling)
- **Analog input and outputs** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
- **Streaming to an [Icecast](https://icecast.org/) Server including [Icy Metadata](https://cast.readme.io/docs/icy)** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
- **Auto DJ with Silcence Detector** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
- **Web Application for a Track Service** (see [AURA Player](https://gitlab.servus.at/aura/player))
- **Web Application providing a Studio Clock** (see [Engine Clock](https://gitlab.servus.at/aura/engine-clock))
- **Bulk and Timeslot Recorder** (This will be provided after v1.1 by a planned `engine-recorder` component)
- **Bulk and Timeslot Recorder** (*Not yet available*, this will be provided after v1.1 by a planned `engine-recorder` component)
- **API** to query Track-Service, monthly reports and information for displaying the Studio Clock (see [Engine API](https://gitlab.servus.at/aura/engine-api))
### Scheduler
Engine provide a scheduling functionality by polling external API endpoints frequently. Those API endpoints are provided by [Steering](https://gitlab.servus.at/aura/steering) to retrieve schedule information and [Tank](https://gitlab.servus.at/aura/tank) to retrieve playlist information. To define your schedule you'll also need [AURA Dashboard](https://gitlab.servus.at/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's preloaded.
If for some reason the playout is corrupted, stopped or too silent to make any sense, then this <u>triggers a fallback using the silence detector</u> (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's possible to schedules playlists with music or pre-recorded shows stored on the **file system**, via external **streams** or live from an **analog 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 specifing 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's also possible to define default playlists
for schedules and shows:
Read more on the [Engine Features](docs/engine-features.md) page.
- **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.
## Architecture
- **Default Show Playlist**: This playlist can be assigned to some show. If neither the specific timeslot
playlist nor the default schedule playlist is specificed the *default show playlist* is broadcasted.
AURA Engine as part of the AURA Radio Suite uses an modulear architecture
based on a REST API. All external information is retrieved using JSON data-structures.
To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or visit
the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
![Setting a default show playlist in AURA Dashboard](images/dashboard-fallback-setting.png "Default Show Playlist in Dashboard")
## Installation
If none of these playlists have been specified the *Auto DJ* feature of [Engine Core](https://gitlab.servus.at/aura/engine-core) takes over (optional).
- [Installation for Development](docs/installation-development.md)
- [Installation for Production](docs/installation-production.md)
- [Running with Docker](docs/running-docker.md)
- [Setup the Audio Store](docs/setup-audio-store.md)
### 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, as network socket request is sent to a defined server. This heartbeat is sent continiously 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 failover scenario. Under `contrib/heartbeat-monitor` you'll find some sample application digesting these heartbeat signals.
### Logging
All Engine logs can be found in the local `./logs` directory. Adapt the log-level within your configuration to get more or less verbose log output. Whenever the Engine's status turns into some unhealthy state, additionally this is logged to [Engine API](https://gitlab.servus.at/aura/engine-api). Also, when it returns to some valid state this is logged to the Engine API.
## Getting started
Ensure that you have also dependencies such as `steering`, `tank`, `dashboard`, `engine-core`, and `engine-api` up and running. There's a how-to in the [Meta](https://gitlab.servus.at/aura/meta) repository to get quickly started using [Docker Compose](https://docs.docker.com/compose/).
For production we recommend running Engine using Docker Compose. If you want to install for AURA development or simply prefer to run natively, check out the [Bare Metal Installation](docs/bare-metal-installation.md).
## Using Docker
If you only want to run the single Engine Docker container, you can do this in a few, simple steps. Before getting started copy the default configuration file to `config/engine.docker.ini`:
```shell
cp config/sample-docker.engine.ini config/engine.docker.ini
```
You'll need to do a few configurations which are required:
- The password `db_pass` for the local database holding scheduling information
- The app secret `api_tank_secret` for connecting to [AURA Tank](https://gitlab.servus.at/aura/tank)
- Also check the `ENV` variables defined in the `run.sh` script.
Now start the engine with:
```shell
./run.sh docker:engine
```
## Read more
- [Bare Metal Installation](docs/bare-metal-installation.md)
- [Developer Guide](docs/developer-guide.md)
- [Engine Features](docs/engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)
- [Setting up the Audio Store [meta]](https://gitlab.servus.at/aura/meta/-/blob/master/docs/setup-audio-store.md)
## About
Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for
the requirements of community radios.
Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for the requirements of community radios.
[<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-logo.png" width="150" />](https://gitlab.servus.at/aura/meta)
......@@ -69,15 +120,5 @@ AURA stands for Automated Radio and is a swiss army knife for community radio st
| [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/aura/steering) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/aura/dashboard) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/aura/tank) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/aura/engine) |
|---|---|---|---|
| [Steering](https://gitlab.servus.at/aura/steering) | [Dashboard](https://gitlab.servus.at/aura/dashboard) | [Tank](https://gitlab.servus.at/aura/tank) | [Engine](https://gitlab.servus.at/aura/engine)<br/>[Engine API](https://gitlab.servus.at/aura/engine-api)<br/>[Engine Clock](https://gitlab.servus.at/aura/engine-clock) |
## Resources
* **Python**: https://docs.python.org/
* **OPAM (OCaml Package Manager)**: https://opam.ocaml.org/
* **Liquidsoap**: https://www.liquidsoap.info/doc-1.4.0/
* **Jack Audio**: https://jackaudio.org/
* **Flask**: https://palletsprojects.com/p/flask/
* **Systemd**: https://systemd.io/
* **Supervisor**: http://supervisord.org/
* **Gunicorn**: https://gunicorn.org/
\ No newline at end of file
| [Steering](https://gitlab.servus.at/aura/steering) | [Dashboard](https://gitlab.servus.at/aura/dashboard) | [Tank](https://gitlab.servus.at/aura/tank) | [Engine](https://gitlab.servus.at/aura/engine)<br/>[Engine Core](https://gitlab.servus.at/aura/engine-core)<br/>[Engine API](https://gitlab.servus.at/aura/engine-api)<br/>[Engine Clock](https://gitlab.servus.at/aura/engine-clock) |
# Install for Development
<!-- TOC -->
- [Install for Development](#install-for-development)
- [Prerequisites](#prerequisites)
- [Setting up the database](#setting-up-the-database)
- [Preparation](#preparation)
- [Configuration](#configuration)
- [Running Engine](#running-engine)
- [Daemonized Engine](#daemonized-engine)
- [Running with Systemd](#running-with-systemd)
- [Running with Supervisor](#running-with-supervisor)
- [Logging](#logging)
- [Read more](#read-more)
<!-- /TOC -->
## Prerequisites
Aura Engine runs on any modern Debian-based OS. It requires at least
- [`Python 3.8+`](https://www.python.org/downloads/release/python-380/)
- [`pip`](https://pip.pypa.io/en/stable/)
- [`git`](https://git-scm.com/)
- ['virtualenv'](https://pypi.org/project/virtualenv/) (development only)
- DBMS server/client libraries for MariaDB or PostgreSQL (see below)
# Setting up the database
Depending on the DBMS you are planning to use you'll need to have the relevant server/client libaries to be present.
**MariaDB**
```shell
sudo apt install \
python3.8-dev \
default-libmysqlclient-dev \
mariadb-server \
libmariadbclient-dev
```
The following installation script sets up the initial databases and users.
```bash
bash scripts/setup-db.sh
```
As soon as this is completed, carefully check if any error occured. In case your database has been setup automatically, note the relevant credentials for later use in your `engine.ini` configuration.
**Setting up the project structure**
Then clone all `engine` related projects to some development folder. In production we recommend `/opt/aura/` as the system base.
```bash
mkdir ~/code/aura
cd ~/code/aura
git clone https://gitlab.servus.at/autoradio/engine
git clone https://gitlab.servus.at/autoradio/engine-core
git clone https://gitlab.servus.at/autoradio/engine-api
...
```
If you are developing engine you also might want the projects `steering`, `dashboard` and `tank` in there, or you'll start them with Docker Compose (see [how to run Aura Web with Docker](https://gitlab.servus.at/autoradio/meta) in the [meta](https://gitlab.servus.at/autoradio/meta) repository)
## Preparation
In case of an development environment, create a virtual env for your Python dependencies:
```shell
virtualenv -p python3.8 python
```
No worries, the resulting `python` directory is excluded from the git respostory.
To activate that environment, run
```shell
source python/bin/activate
```
Then, install the required dependencies
```shell
pip install -r requirements.txt
```
Create your base configuration from the sample configuration
```shell
# Development
cp config/sample.development.engine.ini config/engine.ini
# Production
cp config/sample.production.engine.ini config/engine.ini
```
## Configuration
In your development environment edit following file to configure the engine:
```shell
./config/engine.ini
```
> Please note, if some configuration exists under `/etc/aura/engine.ini` the configuration by default is drawn from there.
While the configuration has plenty of configuration options, you only need to set a few mandatory ones, given you are running the other components (such as 'engine-core', "engine-api" etc.) at the default settings too.
Required modifications are:
- The password `db_pass` for the local database holding scheduling information
- The app secret `api_tank_secret` for connecting to [AURA Tank](https://gitlab.servus.at/aura/tank)
## Running Engine
If you have defined a virtual env during the installation step you'll need to activate it first. You'll have to do so whenever you gonna start your development environment:
```shell
source python/bin/activate
```
There's a convencience script `run.sh` to get engine started
```shell
engine$ ./run.sh
```
Keep in mind you'll also need to start Engine Core separately
```shell
engine-core$ ./run.sh
```
In order to have a full engine experience also the other AURA Components are required to be running. For convencience in starting the full environment checkout how to run Aura Web using Docker Compose within the [Meta Repository](https://gitlab.servus.at/aura/tank)
## Daemonized Engine
For this you can utilize either [Systemd](https://systemd.io/) or [Supervisor](http://supervisord.org/). Please check the their manuals on how to use these services.
The daemon configs are expecting you run engine under the user `engineuser` and being located under `/opt/aura/engine`, `/opt/aura/engine-api` and `/opt/aura/engine-core` respectively. Do prepare the project root and permissions you can use the script `scripts/initialize-systemd.sh`. To create the matching user and audio group membership run `scripts/create-engineuser.sh`.
### Running with Systemd
Copy the unit files in `/opt/aura/engine/config/systemd/aura-engine.service` to your systemd unit directory, and reload the systemd daemon:
```shell
cp /opt/aura/engine/config/systemd/* /etc/systemd/system/
systemctl daemon-reload
```
### Running with Supervisor
Now, given you are in the engine's home directory `/opt/aura/engine/`, simply type following to start the services:
```shell
supervisord
```
This picks up the supervisor configuration provided in the local `supervisord.conf` and the service configurations located in `config/supervisor/*.conf`.
Then you'll need to reload the supervisor configuration using `sudo`:
```shell
sudo supervisorctl reload
```
## Logging
All Engine logs can be found under `./logs`.
## Read more
- [Bare Metal Installation](docs/bare-metal-installation.md)
- [Developer Guide](docs/developer-guide.md)
- [Setting up the Audio Store [meta]](https://gitlab.servus.at/aura/meta/-/blob/master/docs/setup-audio-store.md)
......@@ -8,19 +8,15 @@ This page gives insights on extending Aura Engine internals or through the API.
- [AURA Componentes](#aura-componentes)
- [Engine Components](#engine-components)
- [API](#api)
- [Engine Startup Phases](#engine-startup-phases)
- [Scheduling](#scheduling)
- [More infos for debugging](#more-infos-for-debugging)
- [Debugging Liquidsoap](#debugging-liquidsoap)
- [Tips on configuring the audo interface](#tips-on-configuring-the-audo-interface)
- [Scheduler](#scheduler)
- [Docker](#docker)
- [Read more](#read-more)
<!-- /TOC -->
## AURA Componentes
AURA Engine as part of the AURA Radio Suite uses an modulear architecture
based on a REST API. All external information is retrieved using JSON data-structures.
AURA Engine as part of the AURA Radio Suite uses an modulear architecture based on a REST API. All external information is retrieved using JSON data-structures.
To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
......@@ -35,8 +31,7 @@ For example:
If you need to test and develop against the Engine's API you'll also need to get the `engine-api` project running.
For a start it's recommended to create a general `aura` project folder. In there you start cloning all the sub-projects.
After having all the sub-projects configured, and verified that they are working, take a look at the AURA `meta` project.
For a start it's recommended to create a general `aura` project folder. In there you start cloning all the sub-projects. After having all the sub-projects configured, and verified that they are working, take a look at the AURA `meta` project.
There's a convenience script to start all of the three main dependencies (Steering, Dashboard, Tank) all at once:
......@@ -49,24 +44,13 @@ There's a convenience script to start all of the three main dependencies (Steeri
*...TBD...*
## API
You can find the AURA API definition here: https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md
OpenAPI definition for Engine API: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/
## Engine Startup Phases
When you start Engine the following is happening:
1. Python `run.py`: Initializes `src/core/engine.py` (The virtual mixer; class for remote-controlling Liquidsoap), Scheduler
2. Python `run.py`: Start Liquidsoap.
3. Liquidsoap: When Liquidsoap finished its startup, it creates a socket file as configured in `socket_dir` of `engine.ini`.
4. Python `src/core/liquidsoap/client.py`: Connects to that socket file.
5. Python `src/schedulung/scheduler.py`: Continously loads timeslots from the API endpoints, stores them in the local database and starts the playout as per the timeslots.
## Scheduling
## Scheduler
Scheduling is split into multiple phases. Below you see a timeline with one timeslot planned at a certain
point in time and the involved phase before:
......@@ -130,79 +114,22 @@ point in time and the involved phase before:
this <u>triggers a fallback using the silence detector</u>.
## More infos for debugging
### Debugging Liquidsoap
Connect to Liquidsoap via Telnet
telnet 127.0.0.1 1234
List available commands
help
List all available channels
list
List all input channels connected to the mixer
mixer.input
Set the volume of mixer `input 0` to `100%`
mixer.volume 0 100
## Docker
Push some audio file to the filesystem `queue 0`
Build your own, local Docker image
in_filesystem_0.push /path/to/your/file.mp3
### Tips on configuring the audo interface
Configure your audio device in the `[soundcard]` section of `engine.ini`.
You can configure up to **five** line IN and OUT stereo channels. Your hardware should
support that. When you use JACK, you will see the additional elements popping up when
viewing your connections (with e.g. Patchage).
**Pulse Audio:** When using Ubuntu, Pulse Audio is selected by default. This is convenient,
as you won't have the need to adapt any Engine setting to get audio playing initially.
**ALSA:** When you use ALSA, you will have to play around with ALSA settings. In the folder
`./src/liquidsoap` is a scipt called alsa_settings_tester.liq. You can start it
with 'liquidsoap -v --debug alsa_settings_tester.liq'. Changing and playing with
settings may help you to find correct ALSA settings.
**Jack Audio**: Install the JACK daemon and GUI:
```bash
sudo apt-get install jackd qjackctl
```shell
./run.sh docker:build
```
Please ensure to enable "*realtime process priority*" when installing JACK to keep latency low.
Now, you are able to configure your hardware settings using following command:
Releasing a new version to DockerHub
```bash
qjackctl
```shell
./run.sh docker:push
```
Next you need to install the JACK plugin for Liquidsoap:
```bash
sudo apt install \
liquidsoap-plugin-jack
```
## Read more
- [Overview](/README.md)
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)
- [Running with Docker](running-docker.md)
- [Setup the Audio Store](docs/setup-audio-store.md)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)
\ No newline at end of file
- [Bare Metal Installation](docs/bare-metal-installation.md)
- [Developer Guide](docs/developer-guide.md)
- [Setting up the Audio Store [meta]](https://gitlab.servus.at/aura/meta/-/blob/master/docs/setup-audio-store.md)
# Aura Engine Features
This page gives a more detailed overview of the Aura Engine features and how to configure them.
<!-- TOC -->
- [Aura Engine Features](#aura-engine-features)
- [Multi-channel Input (Filesystem, Stream, Analog)](#multi-channel-input-filesystem-stream-analog)
- [Multi-channel output](#multi-channel-output)
- [Analog line-out](#analog-line-out)
- [Stream to Icecast](#stream-to-icecast)
- [Scheduling](#scheduling)
- [Default Playlists](#default-playlists)
- [Auto DJ](#auto-dj)
- [Silence Detector](#silence-detector)
- [ReplayGain and LoudNorm Normalization](#replaygain-and-loudnorm-normalization)
- [Monitoring](#monitoring)
- [Send mails on errors and warnings](#send-mails-on-errors-and-warnings)
- [Engine Health Information via Engine API](#engine-health-information-via-engine-api)
- [Engine Heartbeat](#engine-heartbeat)
- [Logging](#logging)
- [Read more](#read-more)
<!-- /TOC -->
## Multi-channel Input (Filesystem, Stream, Analog)
It's possible to schedules playlists with music or pre-recorded show stored on the **file system**,
via external **streams** or live from an **analog input** in the studio. All types of sources can
be mixed in a single playlist.
> Note: Any live sources or streams not specifing a length property, are automatically expanded to
the left duration of the timeslot.
The switching between types of audio source is handled automatically. To learn more check out the
[Scheduling](### Secure Scheduling) section.
## Multi-channel output
### Analog line-out
In most scenarios it might be sufficient to broadcast via only one analog stereo output.
If needed you can configure up to five stereo pairs.
### Stream to Icecast
Engine allows to stream to multiple Icecast Servers simultaniousely. It is also sending meta information
to the streaming server, using the *Icy* protocol.
To configure your Icecast connectivity check-out the `[stream]` section in your configuration.
## Scheduling
Engine provide a scheduling functionality by polling external API endpoints frequently. Those API endpoints
are provided by [Steering](https://gitlab.servus.at/aura/steering) to retrieve schedule information and
[Tank](https://gitlab.servus.at/aura/tank) to retrieve playlist information. To define your schedule you'll
also need [AURA Dashboard](https://gitlab.servus.at/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's preloaded.
If for some reason the playout is corrupted, stopped or too silent to make any sense, then
this <u>triggers a fallback using the silence detector</u> (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).
## Default Playlists
While a timeslot can have a specific playlist assigned, it's 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 specificed the *default show playlist* is broadcasted.
![Setting a default show playlist in AURA Dashboard](images/dashboard-fallback-setting.png "Default Show Playlist in Dashboard")
If none of these playlists have been specified the *Fallback Handling* mechanism takes over (see next chapter).
## Auto DJ
There might be scenarios where some user has forgotting to assign a playlist to a timeslot or even
missed to define a timeslot. To avoid such broadcast ending up in [Dead Air](https://en.wikipedia.org/wiki/Dead_air),
Engine provides a *Fallback Handling* or *Auto DJ* feature.
There a two ways to feed music into the Auto DJ:
- **Audio Folder on your harddrive**
- **[M3U Playlist](https://en.wikipedia.org/wiki/M3U)**
Both are watched and automatically updated upon content change. Media is played in an randomized order, meaning
they are shuffled and played until nothing is left for the given playlist/folder. Then it starts all over again.
To configure the behavior of fallbacks, check out the `[fallback]` section in your `engine.ini` configuration.
Please note that engine also extracts meta-information from music played by the Auto DJ and updates the *Studio
Clock* and *Track Service* feature accordingly.
It's also possible to report incidents where Auto DJ starts playing to e.g. programme coordinators. To do so
you simple have to define a mail server (see section [Monitoring](#Monitoring)) and a valid email address:
```ini
# Set to "true" if you want to notify programme-coordinators about about fallback situations, otherwise "false"
mail_coordinator_enabled="true"
# If you want to address multiple programme-coordinators separate their emails by space
coordinator_mail="programme-coordinator@your-radio.org"
```
### Silence Detector
In order to avoid [Dead Air](https://en.wikipedia.org/wiki/Dead_air), the aforementioned Auto DJ feature is
triggered using a Silence Detector reacting to situations where no or unwanted sound is on air. The Silence
Detector allows detection of absoulte silence, weak signals or even noise.
To configure the sensitivity of the Silence Detector adapt following properties in
`engine.ini`:
```ini
# max_blank => maximum time of blank from source (defaults to 20., seconds, float)
# min_noise => minimum duration of noise on source to switch back over (defaults to 0, seconds, float)
# threshold => power in dB under which the stream is considered silent (defaults to -40., float)
fallback_max_blank="10."
fallback_min_noise="0."
fallback_threshold="-50."
```
Let's assume you want to broadcast a live show. At the given example the Silence Detector will
react upon 10 seconds of silence, it will evaluate if there is a schedule or show fallback playlist
defined. If yes, it will immediately schedule and play such playlist. If there is no such playlist
the station fallback will kick in by playing any randomized music.
As soon some signal from the live source is sensed again, the audio routing switches back to the live
channel.
> Note, all these fallback source are fully integrated with the Engine's playlog and track-service