README.md 7.87 KB
Newer Older
1
2
# AURA Engine

3
This piece of Software is part of 'AURA - AUtomated RAdio'.
4
5

AURA Engine does:
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 * request the radio-program from an external source
 * switch the soundserver at the correct time to a given source for a specific show
 * record what is broadcasted
 * stream to an icecast server
 * play to line-out

## Features

### Fallback Handling

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

1. **Timeslot Fallback**:
2. **Show Fallback**:
3. **Station Fallback**:


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

The AURA Project "**Steering**" provides the playouter calendar or schedule,
and details on the shows to be airred:

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


More informations you can find here: https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md


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


62
63
64

## Installation

65
### Hardware Requirements
66

67
68
69
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.
70

71
AURA Engine is tested with following audio devices
72

73
74
75
* ASUS Xonar DGX, 
* Roland Duo-Capture Ex 
* Onboard Soundcard (HDA Intel ALC262)
76

77
Both work well with jack and pulseaudio. For a good experience with ALSA, you may need better hardware.
78

79
* Native Instruments Komplete Audio 6
80

81

82
### Software Requirements
83

84
85
86
87
**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
88
89

```bash
90
git clone https://gitlab.servus.at/autoradio/engine
91
92
```

93
94
95
96
#### Install System Packages

On a Debian / Ubuntu machine:

97
98
```bash
sudo apt install \
99
100
101
102
103
104
105
    git \
    python3 python3-pip \
    redis-server \
    liquidsoap liquidsoap-plugin-icecast \
    mariadb-server libmariadbclient-dev \
    quelcom \
    liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio
106
107
108
```


109
**File Formats:** Depending on what stream you are going to send, and what recordings you are going to use:
110
111
112
113
114
115
116
117
118
```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
```

119
To simply install support for all available file formats do:
120
121
122
123
124
125

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

126

127
#### Install Python Packages
128

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
129
```bash
130
sudo pip3 install -r requirements.txt
131
132
```

133

134
#### Setup Database
135

136

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
137
```bash
138
139
mysql -u root -p

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
140
141
142
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
143
```
144

145
#### Alternative Sound Servers
146

147
Beside ALSA the sound servers **Jack Audio** and **Pulse Audio** are supported.
148

149
**Using JACK:**
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
150

151
Install the JACK daemon and GUI:
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
152
```bash
153
    sudo apt-get install jackd qjackctl 
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
154
```
155

156
157
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:
158

159
160
161
```bash
    qjackctl
```
162

163
Next you need to install the JACK plugin for Liquidsoap:
164

165
166
167
168
```bash
sudo apt install \
    liquidsoap-plugin-jack
```
169

170

171
#### Configuration
172

173
Run
174

175
176
177
```bash
  sh init.sh
```
178

179
180
This creates the folder */var/audio* and copies some default configuration
to */etc/aura/engine.ini*
181

182
After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take your time to carefully review those settings!
183
184
185



186
187
188

### Hardware

189
#### Soundcard
Gottfried Gaisbauer's avatar
newline    
Gottfried Gaisbauer committed
190

191
#### Hard/Soft
Gottfried Gaisbauer's avatar
newline    
Gottfried Gaisbauer committed
192

193
194
195
196
197
198
199
200
201
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.
202

203
#### Streams
204

205
You can configure up to **five** streams. You find the settings in the engine.ini. You can choose between different streaming formats.
206
207


208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279


### 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**  
280
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.
281

282
283
**If you experience 'hangs' or other artefacts on the output signal**
 * reduce the quality (especially, when hangs are on the stream) or
284
 * install the realtime kernel with
285

286
287
288
289
   ```bash
   apt install linux-image-rt-amd64
   reboot
   ```
290

291
   or
292
293
294
295
296
297
298
299
300
 * 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/