developer-guide.md

Aura Engine Development Guide

This page gives insights on extending Aura Engine internals or through the API.

1. Aura Engine Development Guide
   1. AURA Components
   2. Engine Components
   3. Running for Development
   4. Testing
   5. API
   6. Scheduler
   7. Docker
   8. Read more

AURA Components

AURA Engine as part of the AURA Radio Suite uses an modulear architecture based on a REST API. All external information is retrieved using JSON data-structures.

To get the basic architectural overview, visit the Aura Meta repository.

Starting development of engine can be quite tedious, as it requires all most all other AURA components to be up and running.

For example:

• Steering, to get the main incredient of an play-out engine: schedules (or "timeslots" in Steering terms), which hold the actual information on playlists and their entries.
• Dashboard, to have a neat interface, being able to programme the timeslots
• Tank, to get the references to audio files and other audio sources. Plus the actual files.

If you need to test and develop against the Engine's API you'll also need to get the engine-api project running.

For a start it is recommended to create a general aura project folder. In there you start cloning all the sub-projects. After having all the sub-projects configured, and verified that they are working, take a look at the AURA meta project.

There's a convenience script to start all of the three main dependencies (Steering, Dashboard, Tank) all at once:

Engine Components

...TBD...

Running for Development

Ensure you have following other projects up and running:

• steering
• tank
• dashboard
• engine-api
• dashboard-clock (optional)

The following steps expect you having done the bases configuration and set up a database as outlined in the Native Installation document.

Start Liquidsoap which is part of Engine Core:

~/code/aura/engine-core$ ./run.sh

Now run the Engine:

~/code/aura/engine$ ./run.sh

If your IDE of choice is Visual Studio Code, then there are launch settings provided in .vscode/launch.json.

Testing

Test cases are located in ./tests are executed by running:

~/code/aura/engine$ ./run.sh test

API

You can find the AURA API definition here: https://gitlab.servus.at/autoradio/meta/blob/master/development/api-definition.md

OpenAPI definition for Engine API: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/

Scheduler

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:

========================================= [                  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 continuously, 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 is 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_offsetin 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 is "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 triggers a fallback using the silence detector.

Docker

Build your own, local Docker image

./run.sh docker:build

Run the locally build image

./run.sh docker:dev

Releasing a new version to DockerHub

./run.sh docker:push

Read more

• Bare Metal Installation
• Developer Guide
• Setting up the Audio Store [meta]