README.md 8.83 KB
Newer Older
1

david's avatar
david committed
2

david's avatar
david committed
3
# Aura Engine
david's avatar
david 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's avatar
david committed
6

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

david's avatar
david committed
10
11
<!-- TOC -->

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

<!-- /TOC -->
david's avatar
david committed
25

david's avatar
david committed
26
## Functionality
27

Lars Kruse's avatar
Lars Kruse committed
28
In conjunction with other AURA components Engine provides several features:
david's avatar
david committed
29

Lars Kruse's avatar
Lars Kruse committed
30
- **Scheduler** to automatically broadcast your radio programme (see [AURA Dashboard](https://gitlab.servus.at/aura/dashboard) for a user interface to do scheduling)
david's avatar
david committed
31
32
- **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].
david's avatar
david committed
34
- **Auto DJ with Silcence Detector** provided by [Engine Core](https://gitlab.servus.at/aura/engine-core)
35
- **Web Application for a Track Service** (see [AURA Player](https://gitlab.servus.at/aura/player))
36
- **Web Application providing a Studio Clock** (see [Dashboard Clock](https://gitlab.servus.at/aura/dashboard-clock))
david's avatar
david committed
37
38
39
40
41
42
43
- **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.

Lars Kruse's avatar
Lars Kruse committed
44
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 is preloaded.
david's avatar
david committed
45
46
47
48
49
50
51

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

Lars Kruse's avatar
Lars Kruse committed
52
It is 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.
david's avatar
david committed
53
54
55

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

Lars Kruse's avatar
Lars Kruse committed
56
> Note: Any live sources or streams not specifying a length property, are automatically expanded to the left duration of the timeslot.
david's avatar
david committed
57
58
59

#### Default playlists

Lars Kruse's avatar
Lars Kruse committed
60
While a timeslot can have a specific playlist assigned, it is also possible to define default playlists
david's avatar
david committed
61
for schedules and shows:
62

david's avatar
david committed
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

david's avatar
david committed
66
- **Default Show Playlist**: This playlist can be assigned to some show. If neither the specific timeslot
Lars Kruse's avatar
Lars Kruse committed
67
    playlist nor the default schedule playlist is specified the *default show playlist* is broadcasted.
68

david's avatar
david committed
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

david's avatar
david committed
71
72
### Heartbeat Monitoring

Lars Kruse's avatar
Lars Kruse 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 continuously 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.
david's avatar
david committed
74
75
76
77
78
79
80
81
82
83
84
85
86

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

david's avatar
david committed
87
If you only want to run a single Engine Docker container, you can do this in a few, simple steps.
88
89

Before getting started copy the default configuration file to `config/engine.docker.ini`:
david's avatar
david committed
90
91

```shell
92
    cp config/sample-docker.engine.ini config/docker.engine.ini
david's avatar
david committed
93
94
```

David Trattnig's avatar
David Trattnig committed
95
You'll need update a few settings:
David Trattnig's avatar
David Trattnig committed
96
97
98
99

- 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.
david's avatar
david committed
100

david's avatar
david committed
101
At the moment production deployment using Docker and Docker Compose is [*work in progress*](https://gitlab.servus.at/aura/meta/-/issues/56).
102
103

If you would like to run the local codebase, starting Engine in Docker requires you to do a build first:
david's avatar
david committed
104
105

```shell
David Trattnig's avatar
David Trattnig committed
106
    ./run.sh docker:build
david's avatar
david committed
107
108
```

109
After your build has finished start the Engine with following command.
david's avatar
david committed
110

111
If no build is available it pulls the latest image from [Docker Hub](https://hub.docker.com/r/autoradio/engine).
david's avatar
david committed
112
113

```shell
David Trattnig's avatar
David Trattnig committed
114
    ./run.sh docker:dev
david's avatar
david committed
115
```
david's avatar
david committed
116
117
118

## Read more

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

123

david's avatar
david committed
124
## About
david's avatar
david committed
125

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

david's avatar
david committed
128
Automated Radio (AURA) is a open source software suite for community radio stations. Learn more about AURA in the [Meta repository](https://gitlab.servus.at/aura/meta).
129

David Trattnig's avatar
David Trattnig committed
130
| [<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)  |
david's avatar
david committed
131
|---|---|---|---|
132
| [Steering](https://gitlab.servus.at/aura/steering)  | [Dashboard](https://gitlab.servus.at/aura/dashboard)<br/>[Dashboard Clock](https://gitlab.servus.at/aura/dashboard-clock)  | [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)  |
david's avatar
david committed
133