README.md 6.78 KB
Newer Older
1

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

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

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

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

David Trattnig's avatar
David Trattnig committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
- [Aura Engine](#aura-engine)
    - [Features](#features)
    - [Architecture](#architecture)
    - [Requirements](#requirements)
    - [Installation](#installation)
        - [Install System Libraries](#install-system-libraries)
        - [Install Engine](#install-engine)
        - [Setup Database](#setup-database)
        - [Configuration](#configuration)
    - [Running Engine](#running-engine)
        - [Development](#development)
        - [Production](#production)
            - [API Server](#api-server)
    - [Logging](#logging)
    - [About](#about)
    - [Resources](#resources)
David Trattnig's avatar
David Trattnig committed
27
28

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

David Trattnig's avatar
David Trattnig committed
30
## Features
31

David Trattnig's avatar
David Trattnig committed
32
33
34
35
36
37
38
- Play audio from multiple sources
- Dynamic switching of sources
- Record output to filesystem
- Stream output to an Icecast Server
- Multichannel Line-out
- Blank Detenction / Silence Detecter
- Auto Pilot a.k.a. Fallback Handling
39
- API to query Track-Service
40
41
42
43
- API to query monthly reports
- API to query data for a studio clock
- Web Application for displaying the Track-Service
- Web Application for displaying the studio clock
44

David Trattnig's avatar
David Trattnig committed
45
Read more on the [Engine Features](docs/engine-features.md) page.
46

David Trattnig's avatar
David Trattnig committed
47
## Architecture
48
49
50
51

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 Trattnig's avatar
David Trattnig committed
52
53
To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or visit
 the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
54

David Trattnig's avatar
David Trattnig committed
55
## Requirements
56

David Trattnig's avatar
David Trattnig committed
57
58
59
**Hardware Requirements:** This depends on how many audio sources and targets you are
 going to use, but for the most common scenarios any current hardware should be sufficient.
 For the audio devices it is required to use an interface which has supported ALSA drivers.
60

61
62
63
**Operating System:** Any linux system with ALSA, PulseAudio or Jack2 support should work. 
It is tested and coded on Debian Stretch and Ubuntu 18.0 with Python 3.6+.

David Trattnig's avatar
David Trattnig committed
64

David Trattnig's avatar
David Trattnig committed
65
## Installation
66
67

```bash
68
git clone https://gitlab.servus.at/autoradio/engine
69
70
```

David Trattnig's avatar
David Trattnig committed
71
### Install System Libraries
72
73

Aura Engine requires at least Node 13 and Python 3.7.
74

75
76
```bash
sudo apt install \
77
    git \
78
79
    supervisor \
    nodejs \
80
    python3.7 python3.7-pip python3.7-dev \
81
    redis-server \
David Trattnig's avatar
David Trattnig committed
82
    libsndfile1 ffmpeg \
83
84
85
    liquidsoap liquidsoap-plugin-icecast \
    mariadb-server libmariadbclient-dev \
    quelcom \
David Trattnig's avatar
David Trattnig committed
86
    liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio \
87
88
89
    liquidsoap-plugin-all
```

David Trattnig's avatar
David Trattnig committed
90
### Install Engine
91
92

Development Environment:
93

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
94
```bash
95
sudo ./install.sh
96
97
```

98
99
100
101
102
103
Production Environment:

```bash
sudo ./install.sh prod
```

David Trattnig's avatar
David Trattnig committed
104
### Setup Database
105

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
106
```bash
107
108
mysql -u root -p

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
109
110
111
CREATE DATABASE aura_engine CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;  
CREATE USER 'aura'@'localhost' IDENTIFIED BY 'secure-password';  
GRANT ALL PRIVILEGES ON aura_engine.* TO 'aura'@'localhost';  
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
112
```
113

David Trattnig's avatar
David Trattnig committed
114
### Configuration
115

116
Run
117

118
119
120
```bash
  sh init.sh
```
121

122
123
This creates the folder */var/audio* and copies some default configuration
to */etc/aura/engine.ini*
124

David Trattnig's avatar
David Trattnig committed
125
126
After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take
your time to carefully review those settings!
127

David Trattnig's avatar
David Trattnig committed
128
Read more about detailed settings in the [Configuration Guide](docs/configuration-guide.md).
129

David Trattnig's avatar
David Trattnig committed
130
## Running Engine
131

132

David Trattnig's avatar
David Trattnig committed
133
### Development
134

135
While developing there is a simple convencience script `run.sh`
136
137
138
139
140
141
142
143
to get you started. Call the engine's components in following order:

```shell
    ./run.sh      # Starts the engine-core component
    ./run.sh lqs  # Starts the engine-liquidsoap component
    ./run.sh api  # Starts the engine-api component
```

144
145
146
147
In development mode Engine uses the [Flask](https://palletsprojects.com/p/flask/) development server.
This server should not be used in your production environment.


David Trattnig's avatar
David Trattnig committed
148
### Production
149
150

In production the process is slightly different to ensure the
151
152
engine's components are always running i.e. restart themselves after some system
restart or crash. Therefore they are executed using a system service:
153

David Trattnig's avatar
David Trattnig committed
154
155
```bash
  systemctl start aura-engine  
156
  systemctl start aura-lqs
David Trattnig's avatar
David Trattnig committed
157
```
158
159
160

and on system boot run following:

David Trattnig's avatar
David Trattnig committed
161
162
```bash
  systemctl enable aura-engine
163
  systemctl enable aura-lqs
David Trattnig's avatar
David Trattnig committed
164
```
165

David Trattnig's avatar
David Trattnig committed
166
#### API Server
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186

For production Engine API uses the WSGI HTTP Server [`Gunicorn`](https://gunicorn.org/).

[`Supervisor`](http://supervisord.org/) is a preferable solution to run the gunicorn server
in the background and also start it automatically on reboot.

**Start the API service with Supervisor**

```shell
    sudo supervisorctl reread
    sudo supervisorctl update
    sudo supervisorctl avail
    sudo supervisorctl restart engine-api
```

In case you want to reload whole supervisor service

```shell
    sudo service supervisor restart
```
187

David Trattnig's avatar
David Trattnig committed
188
## Logging
189

190
191
192
All Engine logs for production can be found in `/var/log/aura/engine`


David Trattnig's avatar
David Trattnig committed
193
You can access the service logs using one of:
194

David Trattnig's avatar
David Trattnig committed
195
```
196
197
    journalctl -u aura-lqs
    journalctl -u aura-engine
David Trattnig's avatar
David Trattnig committed
198
```
199

David Trattnig's avatar
David Trattnig committed
200
## About
David Trattnig's avatar
David Trattnig committed
201
202
203
204
205
206
207
208

<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-logo.png" width="150" />

Aura Engine is the play-out engine of the Aura Radio Software Suite. Aura stands for Automated Radio and is a swiss army knife for community radios. 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/autoradio/meta) repository or on the specific project pages.

| [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/pv)  |  [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/dashboard)  |  [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/tank) | [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/engine)  |
|---|---|---|---|
| [Steering](https://gitlab.servus.at/autoradio/pv)  | [Dashboard](https://gitlab.servus.at/autoradio/dashboard)  | [Tank](https://gitlab.servus.at/autoradio/tank)  | [Engine](https://gitlab.servus.at/autoradio/engine)  |
209
210


David Trattnig's avatar
David Trattnig committed
211
## Resources
212
213
214
215
216

* **Python**: https://docs.python.org/
* **Redis**: https://redis.io/
* **Liquidsoap**: https://www.liquidsoap.info/doc-1.4.0/
* **Jack Audio**: https://jackaudio.org/
217
218
219
* **Flask**: https://palletsprojects.com/p/flask/
* **Supervisor**: http://supervisord.org/
* **Gunicorn**: https://gunicorn.org/