Added more details on the scheduling concept.

docs/engine-features.md

@@ -10,7 +10,7 @@ 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)
         - [Record output to filesystem](#record-output-to-filesystem)
-    - [Secure Scheduling](#secure-scheduling)
+    - [Scheduling](#scheduling)
         - [Fallback Stages](#fallback-stages)
         - [Scheduling Stages](#scheduling-stages)
         - [Pro-active Fallback Handling (1st Level Fallback)](#pro-active-fallback-handling-1st-level-fallback)
@@ -32,12 +32,12 @@ It's possible to schedules playlists with music or pre-recorded show stored on t
 via external **streams** or live from an **analog input** in the studio. All types of sources can
 be mixed in a single playlist.
 
-> Note: Since live sources and streams do not specific a length property, any playlists populated
+> Note: Since live sources and streams do not specify 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.
 
-The switching between types of audio source is handled automatically. To learn more check-out the
+The switching between types of audio source is handled automatically. To learn more check out the
 [Scheduling](### Secure Scheduling) section.
 
 ## Multi-channel output
@@ -59,10 +59,10 @@ To configure your Icecast connectivity check-out the `[stream]` section in your
 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
+## 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
+Engine performs scheduling with some handling for extended security, 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.
@@ -72,15 +72,15 @@ To avoid this, Engine implements multiple levels of fallback handling.
 
 The available fallbacks are evaluated in following order:
 
-1. **Show Fallback**: If the schedule for some show has no playlist assigned, the
+1. **Schedule Fallback**: If the show fallback is not assigned, a configured fallback
+    playlist for the related timeslot is used.
+
+2. **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.
 
     ![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
@@ -93,7 +93,12 @@ scheduling is structured. Below you see a timline with one schedule planned at a
 point in time and the involved phase before:
 
 ```
-=====[   Scheduling Window   ]-[   Pre-Rolling   ]-[   Schedule Play-out   ]=====
+================= [   Scheduling Window   ] ============= [        Schedule Play-out                 ] ====
+
+== (FILESYSTEM A) ========================== [ Pre-Roll ] [  Play 4  ] ====================================
+== (STREAM A) ========================================== [ Pre-Roll ] [ Play 1 ] ==========================
+== (LIVE 1) ====================================================== [ Pre-Roll ] [ Play 1 ] ================
+== (FILESYSTEM B) ========================================================== [ Pre-Roll ] [  Play 4  ] ====
 ```
 
 - **Scheduling Window**: Within the scheduling window any commands for controlling
@@ -114,20 +119,30 @@ point in time and the involved phase before:
     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`).
 
-    <u>Pro-active fallbach handling</u> is already happening at this phase.
+    <u>Pro-active fallback handling</u> by verifying the existence of playlists is already 
+    happening at this stage.
 
     > 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.
 
-- **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.
+- **Queuing and Pre-Rolling**: Before any playlist entries of the schedule can be turned into
+    sound, they need to be grouped, queued an pre-rolled.
 
     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).
 
+    1. First, all entries are aggregated when they hold filesystem entries.
+        Given you have a playlist with 10 entries, the first 4 are consisting of files, the next two
+        of a a stream and a live source. The last 4 are files again. These entries are now
+        aggregated into 4 groups: one for the files, one for the stream, one for the live entry
+        and another one for files. For each group a timer for executing the next step is created.
+
+    2. Now, the playlist entries are going to be "pre-rolled". This means that filesystem
+        entries are queued and 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.
+
     Set the maximum time reserved for pre-rolling in your configuration (compare `preroll_offset`
     in `engine.ini`).
 
@@ -136,11 +151,15 @@ point in time and the involved phase before:
     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.
+- **Play-out**: Finally the actual play-out is happening. The faders of the virtual mixers are pushed
+    all the way up, as soon it's "time to play" for one of the pre-rolled entries.
+    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.
+
+    Since each scheduled playlist can consist of multiple entry types such as *file*, *live*,
+    and *stream*, the play-out of the schedule is actually a bit more complex. The paragraphs
+    below go into more details.
 
     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).
@@ -148,7 +167,7 @@ point in time and the involved phase before:
 ### 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.
+window and queuing/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.