Commit cfece4e6 authored by David Trattnig's avatar David Trattnig
Browse files

Moved scheduling tech details to dev guide.

parent 46512f6d
......@@ -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
......
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment