From 1b81d66d31408f26e8bff1129a1edb099b9e316f Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Thu, 11 Jun 2020 12:35:54 +0200
Subject: [PATCH] Documentation for scheduling and fallbacks.

---
 docs/engine-features.md                    | 171 +++++++++++++++++----
 docs/images/dashboard-fallback-setting.png | Bin 0 -> 21379 bytes
 2 files changed, 138 insertions(+), 33 deletions(-)
 create mode 100644 docs/images/dashboard-fallback-setting.png

diff --git a/docs/engine-features.md b/docs/engine-features.md
index 8ab817e8..272372e8 100644
--- a/docs/engine-features.md
+++ b/docs/engine-features.md
@@ -5,15 +5,16 @@ This page gives a more detailed overview of the Aura Engine features and how to
 <!-- TOC -->
 
 - [Aura Engine Features](#aura-engine-features)
-    - [Input](#input)
-        - [Play audio from multiple sources](#play-audio-from-multiple-sources)
-        - [Dynamic switching of sources](#dynamic-switching-of-sources)
-    - [Output](#output)
+    - [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)
         - [Record output to filesystem](#record-output-to-filesystem)
-        - [Stream output to an Icecast Server](#stream-output-to-an-icecast-server)
-        - [Multichannel Line-out](#multichannel-line-out)
-    - [Blank Detenction / Silence Detecter](#blank-detenction--silence-detecter)
-    - [Auto Pilot a.k.a. Fallback Handling](#auto-pilot-aka-fallback-handling)
+    - [Secure Scheduling](#secure-scheduling)
+        - [Fallback Stages](#fallback-stages)
+        - [Scheduling Stages](#scheduling-stages)
+        - [Pro-active Fallback Handling (1st Level Fallback)](#pro-active-fallback-handling-1st-level-fallback)
+        - [Fallback Handling using the Silence Detector (2nd Level Fallback)](#fallback-handling-using-the-silence-detector-2nd-level-fallback)
     - [API Endpoints](#api-endpoints)
     - [Web Applications](#web-applications)
     - [Monitoring](#monitoring)
@@ -25,53 +26,157 @@ This page gives a more detailed overview of the Aura Engine features and how to
 
 <!-- /TOC -->
 
-## Input
+## Multi-channel Input (Filesystem, Stream, Analog)
 
-### Play audio from multiple sources
+It's possible to schedules playlists with music or pre-recorded show stored on the **filessystem**,
+via external **streams** or live from an **analog input** in the studio. All types of sources can
+be mixed in a single playlist.
 
-It's possible to air playlists with music or recordings stored on the **filessystem**,
-via external **streams** or live from a **studio**.
+> Note: Since live sources and streams do not specific a length property, any playlists populated
+with such source are expecting this item to run until the end of the schedule. Any other entries
+following such item are therfore skipped. This might change in a future version of AURA Tank,
+allowing to set a length property.
 
-### Dynamic switching of sources
+The switching between types of audio source is handled automatically. To learn more check-out the
+[Scheduling](### Secure Scheduling) section.
 
-    TODO extend: * switch the soundserver at the correct time to a given source for a specific show
+## Multi-channel output
 
-## Output
+### Analog line-out
+
+In most scenarios it might be sufficient to broadcast via only one analog stereo output channel.
+If need 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.
 
 ### Record output to filesystem
 
-    TODO extend:  * record what is broadcasted
+Engine allows recording broadcasts to the filesystem using up to multiple recorders. Each recorder can
+be configured to save in a different resolution in audio quality.
+
+## Secure Scheduling
+
+Engine performs scheduling in a secured way, to meet the requirements of community
+radios. It tries to pro-actively reacted to scenarios, where the upload of some
+pre-recorded show has been forgotten, or some live schedule is not taking place.
+
+Usually in such cases the broadcast might end up with some timeslot filled with silence.
+To avoid this, Engine implements multiple levels of fallback handling.
 
-### Stream output to an Icecast Server
+### Fallback Stages
 
-    TODO extend:  * stream to an icecast server
+The available fallbacks are evaluated in following order:
 
-### Multichannel Line-out
+1. **Show Fallback**: If the schedule 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.
 
-    TODO extend:  * play to line-out
+    ![Setting for the Show Fallback in AURA Dashboard](images/dashboard-fallback-setting.png "Show Fallback in Dashboard")
+
+2. **Timeslot Fallback**: If the show fallback is not assigned, a configured fallback
+    playlist for the related timeslot is used.
+
+3. **Station Fallback**: If everything goes wrong, meaning all the previous fallback
+    playlists are missing or are invalid, the *station fallback* will be triggered. This
+    fallback type is specified by a playlist ID set in the Engine's configuration
+    (see `scheduling_station_fallback_id` in `engine.ini`)
+
+### Scheduling Stages
+
+To understand how fallbacks are handled by Engine, it's good to know how the Engine's
+scheduling is structured. Below you see a timline with one schedule planned at a certain
+point in time and the involved phase before:
+
+```
+=====[   Scheduling Window   ]-[   Pre-Rolling   ]-[   Schedule Play-out   ]=====
+```
 
-## Blank Detenction / Silence Detecter
+- **Scheduling Window**: Within the scheduling window any commands for controlling
+    the mixer of the soundsystem are prepared and queued.
 
-The engine offers a simple way to detect scenarios where no music is on air.
-It possible to configure the sensitivity of the Silence Detector and automatically
-transition play-out to a Fallback Playlist (see Auto Pilot).
+    Until the start of the window, schedules can be added or removed
+    via external API Endpoints (e.g. using Steering or Dashboard). Until here any
+    changes on the schedule itself will be reflected in the actual play-out. Be aware,
+    that this only affects the schedule ("timeslot") itself, it does not involve related
+    playlists and their entries. The latter can still be modified within the scheduling
+    window.
 
-## Auto Pilot a.k.a. Fallback Handling
+    The start and the end of the window is defined by the start of the schedule minus
+    a configured amount of seconds (see `scheduling_window_start` and `scheduling_window_end`
+    in `engine.ini`).
 
-In case there is no schedule delivered by Steering, engine provides multiple
-fallback handling scenarios. The available fallbacks are evaluated in following order:
+    During the scheduling window, the external API Endpoints are pulled continiously, to
+    check for updated schedules and related playlists. Also, any changes to playlists and
+    its entries are respected within that window (see `fetching_frequency` in `engine.ini`).
 
-1. **Timeslot Fallback**:
+    <u>Pro-active fallbach handling</u> is already happening at this phase.
 
-2. **Show Fallback**:
+    > Important: It's vital that the the scheduling window is wider than the fetching frequency.
+    Otherwise one fetch might never hit a scheduling window, hence not being able to schedule stuff.
 
-3. **Station Fallback**:
+- **Pre-Rolling**: Now, the playlist entries are going to be "pre-rolled". This means that filesystem
+    entries are pre-loaded and entries which are based on audio streams are buffered. This
+    is required to allow a seamless play-out, when its time to do so (in the next stage).
+    Due to their nature, playlist entries which hold live audio sources are not affected by
+    this stage at all.
 
-3.1 Station Fallback via remote playlist
+    Within this stage users can neither change playlists nor its entries anymore. <u>Pro-active
+    fallback handling</u> will happen though (see next chapter below for an explanation).
 
-3.2 Station Fallback via local music folder
+    Set the maximum time reserved for pre-rolling in your configuration (compare `preroll_offset`
+    in `engine.ini`).
+
+    > Important: This stage can require up to 4x pre-rolling steps, one for default play-out
+    and for each of the 3 fallback types. So the expected time to load some source multiplied
+    by 4 should be set as the actual value. Also, the offset should not exceed the time between
+    the end of the scheduling-window and the start of the actual schedule playout.
+
+- **Schedule-Playout**: Finally the actual play-out is happening. The faders of the virtual
+    mixers are pushed all the way up and transitions between playlist entries with different
+    types of sources (file, stream and analog inputs) are performed automatically. At the end
+    of each schedule the channel is faded-out, no matter if the total length of the playlist
+    entries would require a longer timeslot.
+
+    If for some reason the playout is corrupted, stopped or too silent to make any sense, then
+    this <u>triggers a 2nd level fallback using the silence detector</u> (see chapter below).
+
+### Pro-active Fallback Handling (1st Level Fallback)
+
+This type of fallback handling is performed before the actual playout, within the scheduling
+window and pre-rolling stage. Here Engine pro-actively verifies the validity of the playlists.
+For example it checks if some playlist ist existing at all, if it holds entries or if the
+entries are existing.
+
+Furthermore, it checks for any unexpected error when entries are pre-rolled. For example Engine
+tries to buffer some HTTP Audio Stream, but it is not reachable. In this case this will
+trigger the scheduling of some fallback playlist.
+
+Pro-active fallback handling has the advantage that any (even short) periods of silence
+during playlist can be avoided. Still, there are cases, where any failure cannot be detected
+beforehand. Therefore a 2nd level fallback solution is required (see below).
+
+### Fallback Handling using the Silence Detector (2nd Level Fallback)
+
+Engine offers a simple way to detect situations where no sound is on air, the so-called
+Silence Detector. It allows detection of absoulte silence, weak signals or even noise.
+
+To configure the sensitivity of the Silence Detector check-out following properties in
+`engine.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="20."
+fallback_min_noise="0."
+fallback_threshold="-50."
+```
 
-Note: All filenames in the music folder should be ASCII encoded, otherwise this may cause engine failures.
 
 ## API Endpoints
 
diff --git a/docs/images/dashboard-fallback-setting.png b/docs/images/dashboard-fallback-setting.png
new file mode 100644
index 0000000000000000000000000000000000000000..5c00586fe02a3d26c32d6ab58fd9eb5f8f03150d
GIT binary patch
literal 21379
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
L7{hDsI7Iyi>6s@j

literal 0
HcmV?d00001

-- 
GitLab