README.md 10.8 KB
Newer Older
1

David Trattnig's avatar
David Trattnig committed
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<!-- TOC -->

- [AURA Engine](#aura-engine)
    - [Features](#features)
        - [Play tracks from multiple sources](#play-tracks-from-multiple-sources)
        - [Blank Detenction / Silence Detecter](#blank-detenction--silence-detecter)
        - [Auto Pilot](#auto-pilot)
        - [Dynamically switching of source channels](#dynamically-switching-of-source-channels)
        - [Multiple Recorders](#multiple-recorders)
        - [Stream to an Icecast Server](#stream-to-an-icecast-server)
        - [Multichannel Line-out](#multichannel-line-out)
    - [Architecture](#architecture)
            - [Required Data Sources](#required-data-sources)
            - [Provided API Endpoints](#provided-api-endpoints)
    - [Installation](#installation)
        - [Hardware Requirements](#hardware-requirements)
        - [Software Requirements](#software-requirements)
        - [Getting Started](#getting-started)
            - [Install System Packages](#install-system-packages)
            - [Install Python Packages](#install-python-packages)
            - [Setup Database](#setup-database)
            - [Alternative Sound Servers](#alternative-sound-servers)
            - [Configuration](#configuration)
        - [Hardware](#hardware)
            - [Soundcard](#soundcard)
            - [Hard/Soft](#hardsoft)
            - [Line In](#line-in)
            - [Recordings](#recordings)
            - [Streams](#streams)
        - [Running the Engine](#running-the-engine)
        - [Logging](#logging)
    - [Development](#development)
        - [Components](#components)
    - [Frequently Asked Questions](#frequently-asked-questions)
        - [ALSA Settings](#alsa-settings)
            - [In the Liquidsoap Logs I get 'Error when starting output output_lineout_0: Failure("Error while setting open_pcm: Device or resource busy")!'. What does it mean?](#in-the-liquidsoap-logs-i-get-error-when-starting-output-output_lineout_0-failureerror-while-setting-open_pcm-device-or-resource-busy-what-does-it-mean)
            - [How can I find the audio device IDs, required for settings in engine.ini?](#how-can-i-find-the-audio-device-ids-required-for-settings-in-engineini)
    - [Resources](#resources)

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

# AURA Engine
44

David Trattnig's avatar
David Trattnig committed
45
46
Aura Engine is a play-out engine as part of Automated Radio (Aura) system,
specifically build for the requirements of community radios.
47
48
49

## Features

David Trattnig's avatar
David Trattnig committed
50
51
52
53
54
55
### Play tracks from multiple sources

It's possible to air playlists with music or recordings stored on the **filessystem**,
via external **streams** or live from a **studio**.

### Blank Detenction / Silence Detecter
56

David Trattnig's avatar
David Trattnig committed
57
58
59
60
61
62
63
The engine offers a simple way to detect scenarios where no music is on air.
It possible to configure the sensitivity of the Silence Detector and automatically
transition play-out to a Fallback Playlist (see Auto Pilot).

### Auto Pilot

In case there is no schedule delivered by Steering, engine provides multiple
64
65
fallback handling scenarios. The available fallbacks are evaluated in following order:

David Trattnig's avatar
David Trattnig committed
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
1. **Timeslot Fallback**: //TODO explain
2. **Show Fallback**: //TODO explain
3. **Station Fallback**: //TODO explain

### Dynamically switching of source channels

    TODO extend: * switch the soundserver at the correct time to a given source for a specific show

### Multiple Recorders

    TODO extend:  * record what is broadcasted


### Stream to an Icecast Server

    TODO extend:  * stream to an icecast server

### Multichannel Line-out

    TODO extend:  * play to line-out
86
87
88
89
90
91
92
93
94


## Architecture

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.

#### Required Data Sources

David Trattnig's avatar
David Trattnig committed
95
96
97
98
99
The AURA Project "**Dashboard**" provides the GUI to organize shows, schedules/timelsots
and organize uploads in form of playlists. Those playlists can be organized in timeslots
using a fancy calendar interface.

These data-sources need to be configurated in the "engine.ini" configuration file:
100
101
102
103
104
105
106
107
108
109
110
111
112
113

    # The URL to get the Calendar via PV/Steering
    calendarurl="http://localhost:8000/api/v1/playout"

    # The URL to get show details via PV/Steering
    api_show_url="http://localhost:8000/api/v1/shows/${ID}/"

The AURA Project "**Tank**" on the other hand delivers information on the tracks, playlists
to be played and its meta-data:

    # The URL to get playlist details via Tank
    importerurl="http://localhost:8040/api/v1/shows/${SLUG}/playlists"


David Trattnig's avatar
David Trattnig committed
114
More information you can find here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>
115
116
117
118
119
120
121
122
123
124
125
126
127


#### Provided API Endpoints

**Soundserverstate:** Returns true and false values of the internal In- and Outputs  

    /api/v1/soundserver_state

**Trackservice:**

/api/v1/trackservice/<selected_date>  
/api/v1/trackservice/

128
129
## Installation

130
### Hardware Requirements
131

132
133
134
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.
135

David Trattnig's avatar
David Trattnig committed
136
Aura Engine is tested with following audio devices
137

138
139
140
141
* ASUS Xonar DGX, 
* Roland Duo-Capture Ex 
* Onboard Soundcard (HDA Intel ALC262)
* Native Instruments Komplete Audio 6
142

143
### Software Requirements
144

145
146
147
148
**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+.

### Getting Started
149
150

```bash
151
git clone https://gitlab.servus.at/autoradio/engine
152
153
```

154
155
156
157
#### Install System Packages

On a Debian / Ubuntu machine:

158
159
```bash
sudo apt install \
160
161
162
163
164
165
166
    git \
    python3 python3-pip \
    redis-server \
    liquidsoap liquidsoap-plugin-icecast \
    mariadb-server libmariadbclient-dev \
    quelcom \
    liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio
167
168
169
```


170
**File Formats:** Depending on what stream you are going to send, and what recordings you are going to use:
171
172
173
174
175
176
177
178
179
```bash
sudo apt install \
    liquidsoap-plugin-aac # for aac support
    liquidsoap-plugin-flac # for flac support
    liquidsoap-plugin-lame liquidsoap-plugin-mad # for mp3 support
    liquidsoap-plugin-opus # for opus support
    liquidsoap-plugin-vorbis # for ogg support
```

180
To simply install support for all available file formats do:
181
182
183
184
185
186

```bash
sudo apt install \
    liquidsoap-plugin-all
```

187

188
#### Install Python Packages
189

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
190
```bash
191
sudo pip3 install -r requirements.txt
192
193
```

194

195
#### Setup Database
196

197

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
198
```bash
199
200
mysql -u root -p

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
201
202
203
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
204
```
205

206
#### Alternative Sound Servers
207

208
Beside ALSA the sound servers **Jack Audio** and **Pulse Audio** are supported.
209

210
**Using JACK:**
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
211

212
Install the JACK daemon and GUI:
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
213
```bash
214
    sudo apt-get install jackd qjackctl 
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
215
```
216

217
218
Please ensure to enable "*realtime process priority*" when installing JACK to keep latency low.
Now, you are able to configure your hardware settings using following command:
219

220
221
222
```bash
    qjackctl
```
223

224
Next you need to install the JACK plugin for Liquidsoap:
225

226
227
228
229
```bash
sudo apt install \
    liquidsoap-plugin-jack
```
230

231

232
#### Configuration
233

234
Run
235

236
237
238
```bash
  sh init.sh
```
239

240
241
This creates the folder */var/audio* and copies some default configuration
to */etc/aura/engine.ini*
242

243
After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take your time to carefully review those settings!
244
245
246



247
248
249

### Hardware

250
#### Soundcard
Gottfried Gaisbauer's avatar
newline    
Gottfried Gaisbauer committed
251

252
#### Hard/Soft
Gottfried Gaisbauer's avatar
newline    
Gottfried Gaisbauer committed
253

254
255
256
257
258
259
260
261
262
When you use ALSA, you will have to play around with ALSA settings. In the folder ./modules/liquidsoap is a scipt called alsa_settings_tester.liq. You can start it with 'liquidsoap -v --debug alsa_settings_tester.liq'. Changing and playing with settings may help you to find correct ALSA settings.

#### Line In

You can configure up to **five** line ins. Your hardware should support that. When you use JACK, you will see the additional elements popping up when viewing your connections (with e.g. Patchage).

#### Recordings

You can configure up to **five** recorders. You find the settings in the main config file engine.ini. You can choose between different output formats.
263

264
#### Streams
265

266
You can configure up to **five** streams. You find the settings in the engine.ini. You can choose between different streaming formats.
267
268


269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340


### Running the Engine ###

To start the AuRa Engine execute:

    systemctl start aura-lqs
    systemctl start aura-engine  

and on system boot run following:

    systemctl enable aura-lqs
    systemctl enable aura-engine

The first service starts the LiquidSoap Engine, while the latter boots the actual AuRa Engine.

### Logging

You can access the service logs using:

    journalctl -u aura-lqs

and

    journalctl -u aura-engine

respectively.



## Development

To run the LiquidSoap code during develpment execute:
    ./run.sh

### Components ###


**aura.py**: It is the server which is connected to the external programme source (e.g. aura steering and tank), to liquidsoap and is listening for redis pubsub messages. This precious little server is telling liquidsoap what to play and when.

**Guru**: The commandline tool for interacting with the server. Also provides the communication from Liquidsoap to the Python (Command-)Server.

**Liquidsoap**: The heart of AuRa Engine. It uses the built in mixer, to switch between different sources. It records everything and streams everything depending on your settings in aura.ini.







## Frequently Asked Questions ##

### ALSA Settings

#### In the Liquidsoap Logs I get 'Error when starting output output_lineout_0: Failure("Error while setting open_pcm: Device or resource busy")!'. What does it mean?

You probably have set a wrong or occupied device ID.


#### How can I find the audio device IDs, required for settings in engine.ini?

* **ALSA**: You can get the device numbers or IDs by executing:

    cat /proc/asound/cards

* **Pulse Audio**: You might not need this for Pulse Audio, but still, to see all available devices use:

    pactl list



**If you cannot find correct ALSA settings**  
341
Well, this is - at least for me - a hard one. I could not manage to find correct ALSA settings for the above mentioned soundcards. The best experience i had with the ASUS Xonar DGX, but still very problematic (especially the first couple of minutes after starting liquidsoap). Since i enabled JACK support i only use that. It is also a bit of trial and error, but works pretty much out of the box.
342

343
344
**If you experience 'hangs' or other artefacts on the output signal**
 * reduce the quality (especially, when hangs are on the stream) or
345
 * install the realtime kernel with
346

347
348
349
350
   ```bash
   apt install linux-image-rt-amd64
   reboot
   ```
351

352
   or
353
354
355
356
357
358
359
360
361
 * invest in better hardware


## Resources ##

* **Python**: https://docs.python.org/
* **Redis**: https://redis.io/
* **Liquidsoap**: https://www.liquidsoap.info/doc-1.4.0/
* **Jack Audio**: https://jackaudio.org/