Moved scheduling tech details to dev guide.

docs/developer-guide.md

@@ -9,6 +9,7 @@ This page gives insights on extending Aura Engine internals or through the API.
     - [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)
@@ -65,6 +66,70 @@ When you start Engine the following is happening:
 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
+
+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
+========================================= [                  Scheduling Window               ] ===========
+=======================================================  [        Timeslot Play-out                 ] ====
+
+== (FILESYSTEM A) ========================== [ Preload ] [  Play 4  ] ====================================
+== (STREAM A) ========================================== [ Preload ] [ Play 1 ] ==========================
+== (LIVE 1) ====================================================== [ Preload ] [ Play 1 ] ================
+== (FILESYSTEM B) ========================================================== [ Preload ] [  Play 4  ] ====
+```
+
+- **Scheduling Window**: Within the scheduling window any commands for controlling
+    the mixer of the soundsystem are prepared and queued.
+
+    Only until the start of the window, timeslots can be updated or removed via external API Endpoints
+    (e.g. using Steering or Dashboard). Until here any changes on the timeslot itself will be reflected
+    in the actual play-out. This only affects the start and end time of the "timeslot" itself.
+    It does not involve related playlists and their entries. Those can still be modified after the
+    scheduling window has started.
+
+    The start and the end of the window is defined by the start of the timeslot minus
+    a configured amount of seconds (see `scheduling_window_start` and `scheduling_window_end`
+    in `engine.ini`). The actual start of the window is calcuated by (timeslot start - window start)
+    and the end by (timeslot end - window end)
+
+    During the scheduling window, the external API Endpoints are pulled continiously, to
+    check for updated timeslots and related playlists. Also, any changes to playlists and
+    its entries are respected within that window (see `fetching_frequency` in `engine.ini`).
+
+    > 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.
+
+    > 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. This is limitation is required to avoid corrupted playout in case audio content has been
+    preloaded or started playing already.
+
+- **Queuing and Pre-Loading**: Before any playlist entries of the timeslot can be turned into
+    sound, they need to be queued and pre-loaded. Ideally the pre-loading happens somewhat before
+    the scheduled play-out time to avoid any delays in timing. Set the maximum time reserved for
+    pre-loading in your configuration (compare `preload_offset`in `engine.ini`).
+
+    If there is not enough time to reserve the given amount of time for preloading (i.e. some entry
+    should have started in the past already) the offset is ignored and the entry is played as soon as possible.
+
+    > Important: To ensure proper timings, the offset should not exceed the time between the start of
+    the scheduling-window and the start of the actual timeslot playout. Practically, of course there
+    are scenario where playout start later than planned e.g. during startup of the engine during a timeslot
+    or due to some severe connectivity issues to some external stream.
+
+- **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-loaded entries.
+    Transitions between playlist entries with different types of sources (file, stream and analog
+    inputs) are performed automatically. At the end of each timeslot 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 fallback using the silence detector</u>.
+
+
 ## More infos for debugging
 
 ### Debugging Liquidsoap

docs/engine-features.md

@@ -54,63 +54,19 @@ To configure your Icecast connectivity check-out the `[stream]` section in your
 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 user interface to
+also need [AURA Dashboard](https://gitlab.servus.at/aura/dashboard) which is an elegent web user interface to
 manage your shows, playlists and schedules.
 
-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:
+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.
 
-```ascii
-================= [   Scheduling Window   ] ============ [        Timeslot Play-out                 ] ====
+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).
 
-== (FILESYSTEM A) ========================== [ Preload ] [  Play 4  ] ====================================
-== (STREAM A) ========================================== [ Preload ] [ Play 1 ] ==========================
-== (LIVE 1) ====================================================== [ Preload ] [ Play 1 ] ================
-== (FILESYSTEM B) ========================================================== [ Preload ] [  Play 4  ] ====
-```
-
-- **Scheduling Window**: Within the scheduling window any commands for controlling
-    the mixer of the soundsystem are prepared and queued.
-
-    Only until the start of the window, timeslots can be updated or removed via external API Endpoints
-    (e.g. using Steering or Dashboard). Until here any changes on the timeslot itself will be reflected
-    in the actual play-out. This only affects the start and end time of the "timeslot" itself.
-    It does not involve related playlists and their entries. Those can still be modified after the
-    scheduling window has started.
-
-    The start and the end of the window is defined by the start of the timeslot minus
-    a configured amount of seconds (see `scheduling_window_start` and `scheduling_window_end`
-    in `engine.ini`). The actual start of the window is calcuated by (timeslot start - window start)
-    and the end by (timeslot end - window end)
-
-    During the scheduling window, the external API Endpoints are pulled continiously, to
-    check for updated timeslots and related playlists. Also, any changes to playlists and
-    its entries are respected within that window (see `fetching_frequency` in `engine.ini`).
-
-    > 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.
-
-- **Queuing and Pre-Loading**: Before any playlist entries of the timeslot can be turned into
-    sound, they need to be queued and pre-loaded. Ideally the pre-loading happens somewhat before
-    the scheduled play-out time to avoid any delays in timing. Set the maximum time reserved for
-    pre-loading in your configuration (compare `preload_offset`in `engine.ini`).
-
-    If there is not enough time to reserve the given amount of time for preloading (i.e. some entry
-    should have started in the past already) the offset is ignored and the entry is played as soon as possible.
-
-    > Important: To ensure proper timings, the offset should not exceed the time between the start of
-    the scheduling-window and the start of the actual timeslot playout. Practically, of course there
-    are scenario where playout start later than planned e.g. during startup of the engine during a timeslot
-    or due to some severe connectivity issues to some external stream.
-
-- **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-loaded entries.
-    Transitions between playlist entries with different types of sources (file, stream and analog
-    inputs) are performed automatically. At the end of each timeslot 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 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