Update docs on default and fallback playlists. #52

README.md

@@ -21,16 +21,16 @@ the requirements of community radios.
 
 ## Features
 
-- Play audio from multiple sources
-- Dynamic switching of sources
-- Record output to filesystem
-- Stream output to an Icecast Server
-- Multichannel Line-out
-- Blank Detenction / Silence Detecter
-- Auto Pilot a.k.a. Fallback Handling
-- API to query Track-Service, monthly reports and information for displaying the Studio Clock (see [Engine API](https://gitlab.servus.at/aura/engine-api))
-- Web Application for displaying the Track-Service (see [AURA Player](https://gitlab.servus.at/aura/player))
-- Web Application for displaying the Studio Clock (see [Engine Clock](https://gitlab.servus.at/aura/engine-clock))
+- **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*
+- **Auto DJ** which plays random music when silence is detected
+- **API** to query Track-Service, monthly reports and information for displaying the Studio Clock (see [Engine API](https://gitlab.servus.at/aura/engine-api))
+- **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)
 
 Read more on the [Engine Features](docs/engine-features.md) page.
 

docs/engine-features.md

@@ -10,7 +10,8 @@ This page gives a more detailed overview of the Aura Engine features and how to
         - [Analog line-out](#analog-line-out)
         - [Stream to Icecast](#stream-to-icecast)
     - [Scheduling](#scheduling)
-    - [Fallback Handling](#fallback-handling)
+    - [Default Playlists](#default-playlists)
+    - [Auto DJ](#auto-dj)
         - [Silence Detector](#silence-detector)
     - [Monitoring](#monitoring)
         - [Send mails on errors and warnings](#send-mails-on-errors-and-warnings)
@@ -49,9 +50,11 @@ To configure your Icecast connectivity check-out the `[stream]` section in your
 
 ## Scheduling
 
-Engine provide a scheduling functionality by polling external API endpoints frequently.
+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.
 
-Scheduling is split into multiple phase. Below you see a timline with one timeslot planned at a certain
+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:
 
 ```ascii
@@ -106,43 +109,55 @@ point in time and the involved phase before:
     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).
 
-## Fallback Handling
+## Default Playlists
 
-Engine is able to react to common community radio scenarios, like the upload of some
-pre-recorded show has been forgotten, or some live show is actually not taking place.
-Usually in such cases the broadcast might end up with some timeslot filled with silence.
-To avoid this, Engine provides multiple levels of fallback handling.
+While a timeslot can have a specific playlist assigned, it's also possible to define default playlists
+for schedules and shows:
 
-The available fallbacks are evaluated in following order:
+- **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.
 
-1. **Schedule Fallback**: If the show fallback is not assigned, a configured fallback
-    playlist for the related timeslot is used. This playlist is aired in normal order.
-    It's important to note, in case that playlists containing anything different than
-    file entries, are ignored (i.e. live or stream content).
+- **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.
 
-2. **Show Fallback**: If the timeslot for some show has no playlist assigned, the
-    playlist assigned as a *show fallback* is used instead. In the dashboard this can
-    be done as seen in the screenshot below. 
 
-    ![Setting for the Show Fallback in AURA Dashboard](images/dashboard-fallback-setting.png "Show Fallback in Dashboard")
+![Setting a default show playlist in AURA Dashboard](images/dashboard-fallback-setting.png "Default Show Playlist in Dashboard")
 
-    This playlist is aired in normal order. It's important to note, in case that playlists
-    containing anything different than file entries, are ignored (i.e. live or stream content).
+If none of these playlists have been specified the *Fallback Handling* mechanism takes over (see next chapter).
+## Auto DJ
 
-3. **Station Fallback**: If everything goes wrong, meaning all the previous fallback
-    playlists are not assigned or are invalid, the *station fallback* will be triggered. This
-    fallback type is specified by either some **M3U Playlist** or an **Audio Folder**. Both are watched
-    and automatically updated upon content change. Media is played in an randomized way, meaning
-    they are shuffled and played until nothing is left for the given playlist/folder. Then it
-    starts all over again.
+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
 
-The aforementioned fallback levels are 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.
+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`: