README.md 6.74 KB
Newer Older
1

David Trattnig's avatar
David Trattnig committed
2
3
4
5
6
<!-- TOC -->

- [AURA Engine](#aura-engine)
    - [Features](#features)
    - [Architecture](#architecture)
David Trattnig's avatar
David Trattnig committed
7
8
9
10
11
12
13
14
15
    - [Requirements](#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)
    - [Running the Engine](#running-the-engine)
    - [Logging](#logging)
David Trattnig's avatar
David Trattnig committed
16
    - [Frequently Asked Questions](#frequently-asked-questions)
David Trattnig's avatar
David Trattnig committed
17
        - [Which Audio Interface / Soundcard is compatible with Aura?](#which-audio-interface--soundcard-is-compatible-with-aura)
David Trattnig's avatar
David Trattnig committed
18
19
20
21
22
23
        - [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
24
25

# AURA Engine
26

David Trattnig's avatar
David Trattnig committed
27
28
Aura Engine is a play-out engine as part of Automated Radio (Aura) system,
specifically build for the requirements of community radios.
29
30
31

## Features

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

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

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

David Trattnig's avatar
David Trattnig committed
47
48
To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or visit
 the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
49

David Trattnig's avatar
David Trattnig committed
50
## Requirements
51

David Trattnig's avatar
David Trattnig committed
52
53
54
**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.
55

56
57
58
**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
59
60

## Getting Started
61
62

```bash
63
git clone https://gitlab.servus.at/autoradio/engine
64
65
```

David Trattnig's avatar
David Trattnig committed
66
### Install System Packages
67
68
69

On a Debian / Ubuntu machine:

70
71
```bash
sudo apt install \
72
73
74
75
76
77
78
    git \
    python3 python3-pip \
    redis-server \
    liquidsoap liquidsoap-plugin-icecast \
    mariadb-server libmariadbclient-dev \
    quelcom \
    liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio
79
80
81
```


82
**File Formats:** Depending on what stream you are going to send, and what recordings you are going to use:
83
84
85
86
87
88
89
90
91
```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
```

92
To simply install support for all available file formats do:
93
94
95
96
97
98

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

99

David Trattnig's avatar
David Trattnig committed
100
### Install Python Packages
101

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
102
```bash
103
sudo pip3 install -r requirements.txt
104
105
```

106

David Trattnig's avatar
David Trattnig committed
107
### Setup Database
108

109

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
110
```bash
111
112
mysql -u root -p

Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
113
114
115
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
116
```
117

David Trattnig's avatar
David Trattnig committed
118
### Alternative Sound Servers
119

120
Beside ALSA the sound servers **Jack Audio** and **Pulse Audio** are supported.
121

122
**Using JACK:**
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
123

124
Install the JACK daemon and GUI:
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
125
```bash
126
    sudo apt-get install jackd qjackctl 
Gottfried Gaisbauer's avatar
Gottfried Gaisbauer committed
127
```
128

129
130
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:
131

132
133
134
```bash
    qjackctl
```
135

136
Next you need to install the JACK plugin for Liquidsoap:
137

138
139
140
141
```bash
sudo apt install \
    liquidsoap-plugin-jack
```
142

143

David Trattnig's avatar
David Trattnig committed
144
### Configuration
145

146
Run
147

148
149
150
```bash
  sh init.sh
```
151

152
153
This creates the folder */var/audio* and copies some default configuration
to */etc/aura/engine.ini*
154

155
After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take your time to carefully review those settings!
156
157
158



David Trattnig's avatar
David Trattnig committed
159
## Running the Engine ###
160
161
162
163
164
165
166
167
168
169
170
171
172

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.

David Trattnig's avatar
David Trattnig committed
173
## Logging
174
175
176
177
178
179
180
181
182
183
184

You can access the service logs using:

    journalctl -u aura-lqs

and

    journalctl -u aura-engine

respectively.

David Trattnig's avatar
David Trattnig committed
185
## Frequently Asked Questions
186

David Trattnig's avatar
David Trattnig committed
187
### Which Audio Interface / Soundcard is compatible with Aura?
188

David Trattnig's avatar
David Trattnig committed
189
190
Basically any audio device which is supported by Linux Debian/Ubuntu and has ALSA drivers.
Engine has been tested with following audio interfaces:
191

David Trattnig's avatar
David Trattnig committed
192
193
194
195
- ASUS Xonar DGX,
- Roland Duo-Capture Ex
- Onboard Soundcard (HDA Intel ALC262)
- Native Instruments Komplete Audio 6
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217


### 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**  
218
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.
219

220
221
**If you experience 'hangs' or other artefacts on the output signal**
 * reduce the quality (especially, when hangs are on the stream) or
222
 * install the realtime kernel with
223

224
225
226
227
   ```bash
   apt install linux-image-rt-amd64
   reboot
   ```
228

229
   or
230
231
232
233
234
235
236
237
238
 * 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/