README.md 8.59 KB
Newer Older
1

David Trattnig's avatar
David Trattnig committed
2

David Trattnig's avatar
David Trattnig committed
3
# Aura Engine
David Trattnig's avatar
David Trattnig committed
4

David Trattnig's avatar
David Trattnig committed
5
<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/assets/images/aura-engine.png" width="250" align="right" />
David Trattnig's avatar
David Trattnig committed
6

7
Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for
8
the requirements of community radio stations.
David Trattnig's avatar
David Trattnig committed
9

David Trattnig's avatar
David Trattnig committed
10
11
<!-- TOC -->

David Trattnig's avatar
David Trattnig committed
12
- [Aura Engine](#aura-engine)
David Trattnig's avatar
David Trattnig committed
13
14
15
16
17
18
19
20
21
22
  - [Functionality](#functionality)
    - [Scheduler](#scheduler)
      - [Versatile playlists](#versatile-playlists)
      - [Default playlists](#default-playlists)
    - [Heartbeat Monitoring](#heartbeat-monitoring)
    - [Logging](#logging)
  - [Getting started](#getting-started)
  - [Using Docker](#using-docker)
  - [Read more](#read-more)
  - [About](#about)
David Trattnig's avatar
David Trattnig committed
23
24

<!-- /TOC -->
David Trattnig's avatar
David Trattnig committed
25

26
## Functionality
27

28
29
30
31
32
In conjuction with other AURA components Engine provides several features:

- **Scheduler** to automatically broadcast your radio programme (see [AURA Dashboard](https://gitlab.servus.at/aura/dashboard) for an user interface to do scheduling)
- **Analog input and outputs** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
- **Streaming to an [Icecast](https://icecast.org/) Server including [Icy Metadata](https://cast.readme.io/docs/icy)** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
David Trattnig's avatar
David Trattnig committed
33
- **Autonomous playout** by caching the schedule information pulled from [Steering](https://gitlab.servus.at/aura/steering) in a local database. This allows Engine be keep running, independently from any network or service outages. This enables the application of (*High Availability* infrastructure scenarios)[https://gitlab.servus.at/aura/meta/-/blob/master/docs/administration/installation-guide.md#high-availability].
34
- **Auto DJ with Silcence Detector** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
35
36
- **Web Application for a Track Service** (see [AURA Player](https://gitlab.servus.at/aura/player))
- **Web Application providing a Studio Clock** (see [Engine Clock](https://gitlab.servus.at/aura/engine-clock))
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
- **Bulk and Timeslot Recorder** (*Not yet available*, this will be provided after v1.1 by a planned `engine-recorder` component)
- **API** to query Track-Service, monthly reports and information for displaying the Studio Clock (see [Engine API](https://gitlab.servus.at/aura/engine-api))

### Scheduler

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 web user interface to manage your shows, playlists and schedules.

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.

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

#### Versatile playlists

It's possible to schedules playlists with music or pre-recorded shows stored on the **file system**, via external **streams** or live from an **analog input** in the studio. All types of sources can be mixed in a single playlist.

The switching between types of audio source is handled automatically, with configured fadings applied.

> Note: Any live sources or streams not specifing a length property, are automatically expanded to the left duration of the timeslot.

#### Default playlists

While a timeslot can have a specific playlist assigned, it's also possible to define default playlists
for schedules and shows:
62

63
64
- **Default Schedule Playlist**: This playlist is defined on the level of some recurrence rules (*Schedule*).
    In case the timeslot doesn't have any specific playlist assigned, this playlist is broadcasted.
65

66
67
- **Default Show Playlist**: This playlist can be assigned to some show. If neither the specific timeslot
    playlist nor the default schedule playlist is specificed the *default show playlist* is broadcasted.
68

69
If none of these playlists have been specified the *Auto DJ* feature of [Engine Core](https://gitlab.servus.at/aura/engine-core) takes over (optional).
70

71
72
### Heartbeat Monitoring

David Trattnig's avatar
David Trattnig committed
73
Instead of checking all status properties, the Heartbeat only validates the vital ones required to run the engine. If all of those are valid, a network socket request is sent to a defined server. This heartbeat is sent continiously based on the configured `heartbeat_frequency`. The service receiving this heartbeat ticks can decide what to do with that information. One scenario could be switching to another Engine instance or any other custom failover scenario. Under `contrib/heartbeat-monitor` you'll find some sample application digesting these heartbeat signals.
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

### Logging

All Engine logs can be found in the local `./logs` directory. Adapt the log-level within your configuration to get more or less verbose log output. Whenever the Engine's status turns into some unhealthy state, additionally this is logged to [Engine API](https://gitlab.servus.at/aura/engine-api). Also, when it returns to some valid state this is logged to the Engine API.

## Getting started

Ensure that you have also dependencies such as `steering`, `tank`, `dashboard`, `engine-core`, and `engine-api` up and running. There's a how-to in the [Meta](https://gitlab.servus.at/aura/meta) repository to get quickly started using [Docker Compose](https://docs.docker.com/compose/).

For production we recommend running Engine using Docker Compose. If you want to install for AURA development or simply prefer to run natively, check out the [Bare Metal Installation](docs/bare-metal-installation.md).

## Using Docker

If you only want to run the single Engine Docker container, you can do this in a few, simple steps. Before getting started copy the default configuration file to `config/engine.docker.ini`:

```shell
    cp config/sample-docker.engine.ini config/engine.docker.ini
```

You'll need to do a few configurations which are required:
    - The password `db_pass` for the local database holding scheduling information
    - The app secret `api_tank_secret` for connecting to [AURA Tank](https://gitlab.servus.at/aura/tank)
    - Also check the `ENV` variables defined in the `run.sh` script.

Now start the engine with:

```shell
    ./run.sh docker:engine
```
103
104
105

## Read more

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

110

David Trattnig's avatar
David Trattnig committed
111
## About
David Trattnig's avatar
David Trattnig committed
112

David Trattnig's avatar
David Trattnig committed
113
[<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/assets/images/aura-logo.png" width="150" />](https://gitlab.servus.at/aura/meta)
David Trattnig's avatar
David Trattnig committed
114

115
AURA stands for Automated Radio and is a swiss army knife for community radio stations. Beside the Engine it provides Steering (Admin Interface for the radio station), Dashboard (Collaborative scheduling and programme coordination), Tank (Audio uploading, pre-processing and delivery). Read more in the [Aura Meta](https://gitlab.servus.at/aura/meta) repository or on the specific project pages.
116

David Trattnig's avatar
David Trattnig committed
117
| [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/aura/steering)  |  [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/aura/dashboard)  |  [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/aura/tank) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/aura/engine)  |
118
|---|---|---|---|
119
120
| [Steering](https://gitlab.servus.at/aura/steering)  | [Dashboard](https://gitlab.servus.at/aura/dashboard)  | [Tank](https://gitlab.servus.at/aura/tank)  | [Engine](https://gitlab.servus.at/aura/engine)<br/>[Engine Core](https://gitlab.servus.at/aura/engine-core)<br/>[Engine API](https://gitlab.servus.at/aura/engine-api)<br/>[Engine Clock](https://gitlab.servus.at/aura/engine-clock)  |