developer-guide.md 7.67 KB
Newer Older
david's avatar
david committed
1
# Aura Engine Development Guide
david's avatar
david committed
2
3
4

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

david's avatar
david committed
5
<!-- TOC -->
david's avatar
david committed
6

David Trattnig's avatar
David Trattnig committed
7
8
9
10
11
12
13
14
15
1. [Aura Engine Development Guide](#aura-engine-development-guide)
   1. [AURA Componentes](#aura-componentes)
   2. [Engine Components](#engine-components)
   3. [Running for Development](#running-for-development)
   4. [Testing](#testing)
   5. [API](#api)
   6. [Scheduler](#scheduler)
   7. [Docker](#docker)
   8. [Read more](#read-more)
david's avatar
david committed
16
17
18

<!-- /TOC -->

david's avatar
david committed
19
## AURA Componentes
david's avatar
david committed
20

david's avatar
david committed
21
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.
david's avatar
david committed
22
23
24

To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.

david's avatar
david committed
25
26
27
28
Starting development of engine can be quite tedious, as it requires all most all other AURA components to be up and running.

For example:

david's avatar
david committed
29
30
31
32
- 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 programm the timeslots
- Tank, to get the references to audio files and other audio sources. Plus the actual files.
david's avatar
david committed
33
34
35

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

david's avatar
david committed
36
For a start it's 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.
david's avatar
david committed
37
38
39
40
41
42
43

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

```bash
    ~/code/aura/meta$ ./run.sh aura local
```

david's avatar
david committed
44
## Engine Components
david's avatar
david committed
45
46


david's avatar
david committed
47
*...TBD...*
david's avatar
david committed
48

david's avatar
david committed
49

50
## Running for Development
david's avatar
david committed
51
52
53
54
55
56
57

Ensure you have following other projects up and running:

- steering
- tank
- dashboard
- engine-api
58
- dashboard-clock (optional)
david's avatar
david committed
59

david's avatar
david committed
60
61
62
The following steps espect you having done the bases configuration and set up a database as outlined in the [Native Installation](https://gitlab.servus.at/aura/engine/-/blob/master/docs/bare-metal-installation.md) document.

If you don't have already, you'll need to create an virtual environment:
63
64

```shell
david's avatar
david committed
65
~/code/aura/engine$ python3.8 -m venv python
66
67
```

david's avatar
david committed
68
69
70
71
72
73
74
75
76
77
78
79
Then you can start the engine. The following command includes the activation of your virtual environment, which you have created during the installation step (`source python/bin/activate`):

```shell
~/code/aura/engine$ ./run.sh dev
```

Now start Liquidsoap which is part of Engine Core:

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

david's avatar
david committed
80
81
If your IDE of choice is *Visual Studio Code*, then there are launch settings provided in `.vscode/launch.json`.

82
83
84
85
86
87
88
89
## Testing

Test cases are located in `./tests`. The test command expects a virtual environment in `./python` which gets activated automatically as soon you run the tests with

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

david's avatar
david committed
90
91
## API

David Trattnig's avatar
David Trattnig committed
92
You can find the AURA API definition here: https://gitlab.servus.at/autoradio/meta/blob/master/development/api-definition.md
david's avatar
david committed
93

david's avatar
david committed
94
OpenAPI definition for Engine API: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/
david's avatar
david committed
95

david's avatar
david committed
96
## Scheduler
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

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>.


david's avatar
david committed
160
## Docker
david's avatar
david committed
161

david's avatar
david committed
162
Build your own, local Docker image
david's avatar
david committed
163

david's avatar
david committed
164
165
```shell
./run.sh docker:build
david's avatar
david committed
166
167
```

david's avatar
david committed
168
Releasing a new version to DockerHub
david's avatar
david committed
169

david's avatar
david committed
170
171
```shell
./run.sh docker:push
david's avatar
david committed
172
173
```

david's avatar
david committed
174
175
## Read more

david's avatar
david committed
176
177
- [Bare Metal Installation](docs/bare-metal-installation.md)
- [Developer Guide](docs/developer-guide.md)
David Trattnig's avatar
David Trattnig committed
178
- [Setting up the Audio Store [meta]](https://gitlab.servus.at/aura/meta/-/blob/master/docs/administration/setup-audio-store.md)