Commit 9925ceac authored by David Trattnig's avatar David Trattnig
Browse files

Simplified docs.

parent f90f2f10
# AURA Engine
<img src="./images/aura-logo.png" width="250" align="right" />
Aura Engine is a play-out engine as part of Automated Radio (Aura) system,
specifically build for the requirements of community radios.
<!-- TOC -->
- [AURA Engine](#aura-engine)
- [Features](#features)
- [Architecture](#architecture)
- [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)
- [Installation](#installation)
- [Start the Engine](#start-the-engine)
- [Logging](#logging)
- [Frequently Asked Questions](#frequently-asked-questions)
- [Which Audio Interface / Soundcard is compatible with Aura?](#which-audio-interface--soundcard-is-compatible-with-aura)
- [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 -->
# AURA Engine
Aura Engine is a play-out engine as part of Automated Radio (Aura) system,
specifically build for the requirements of community radios.
## Features
- Play audio from multiple sources
......@@ -57,15 +49,13 @@ To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or
It is tested and coded on Debian Stretch and Ubuntu 18.0 with Python 3.6+.
## Getting Started
## Installation
```bash
git clone https://gitlab.servus.at/autoradio/engine
```
### Install System Packages
On a Debian / Ubuntu machine:
**Install System Packages:**
```bash
sudo apt install \
......@@ -75,37 +65,17 @@ sudo apt install \
liquidsoap liquidsoap-plugin-icecast \
mariadb-server libmariadbclient-dev \
quelcom \
liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio
```
**File Formats:** Depending on what stream you are going to send, and what recordings you are going to use:
```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
```
To simply install support for all available file formats do:
```bash
sudo apt install \
liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio \
liquidsoap-plugin-all
```
### Install Python Packages
**Install Python Packages:**
```bash
sudo pip3 install -r requirements.txt
```
### Setup Database
**Setup Database:**
```bash
mysql -u root -p
......@@ -115,33 +85,7 @@ CREATE USER 'aura'@'localhost' IDENTIFIED BY 'secure-password';
GRANT ALL PRIVILEGES ON aura_engine.* TO 'aura'@'localhost';
```
### Alternative Sound Servers
Beside ALSA the sound servers **Jack Audio** and **Pulse Audio** are supported.
**Using JACK:**
Install the JACK daemon and GUI:
```bash
sudo apt-get install jackd qjackctl
```
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:
```bash
qjackctl
```
Next you need to install the JACK plugin for Liquidsoap:
```bash
sudo apt install \
liquidsoap-plugin-jack
```
### Configuration
**Configuration:**
Run
......@@ -152,82 +96,39 @@ Run
This creates the folder */var/audio* and copies some default configuration
to */etc/aura/engine.ini*
After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take your time to carefully review those settings!
After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take
your time to carefully review those settings!
Read more about detailed settings in the [Configuration Guide](docs/configuration-guide.md).
## Running the Engine ###
## Start the Engine
To start the AuRa Engine execute:
systemctl start aura-lqs
systemctl start aura-engine
```bash
systemctl start aura-lqs
systemctl start aura-engine
```
and on system boot run following:
systemctl enable aura-lqs
systemctl enable aura-engine
```bash
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:
You can access the service logs using one of:
```
journalctl -u aura-lqs
and
journalctl -u aura-engine
```
respectively.
## Frequently Asked Questions
### Which Audio Interface / Soundcard is compatible with Aura?
Basically any audio device which is supported by Linux Debian/Ubuntu and has ALSA drivers.
Engine has been tested with following audio interfaces:
- ASUS Xonar DGX,
- Roland Duo-Capture Ex
- Onboard Soundcard (HDA Intel ALC262)
- Native Instruments Komplete Audio 6
### 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**
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.
**If you experience 'hangs' or other artefacts on the output signal**
* reduce the quality (especially, when hangs are on the stream) or
* install the realtime kernel with
```bash
apt install linux-image-rt-amd64
reboot
```
or
* invest in better hardware
## Resources ##
......
......@@ -11,11 +11,37 @@ You can configure up to **five** line IN and OUT stereo channels. Your hardware
support that. When you use JACK, you will see the additional elements popping up when
viewing your connections (with e.g. Patchage).
When you use ALSA, you will have to play around with ALSA settings. In the folder
**Pulse Audio:** When using Ubuntu, Pulse Audio is selected by default. This is convenient,
as you won't have the need to adapt any Engine setting to get audio playing initially.
**ALSA:** 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
with 'liquidsoap -v --debug alsa_settings_tester.liq'. Changing and playing with
settings may help you to find correct ALSA settings.
**Jack Audio**: Beside ALSA the sound servers such as
is supported.
Install the JACK daemon and GUI:
```bash
sudo apt-get install jackd qjackctl
```
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:
```bash
qjackctl
```
Next you need to install the JACK plugin for Liquidsoap:
```bash
sudo apt install \
liquidsoap-plugin-jack
```
## Recordings
You can configure up to **five** recorders in the `[recording]`.
......@@ -67,3 +93,65 @@ Configure socket connectivity in the `[socket]` section.
## Redis
Configure Redis connectivity in the `[redis]` section.
## Frequently Asked Questions
### Which Audio Interface / Soundcard is compatible with Aura?
Basically any audio device which is supported by Linux Debian/Ubuntu and has ALSA drivers.
Engine has been tested with following audio interfaces:
- ASUS Xonar DGX,
- Roland Duo-Capture Ex
- Onboard Soundcard (HDA Intel ALC262)
- Native Instruments Komplete Audio 6
### ALSA Settings
#### Install: I don't want to install all Liquidsoap Audio plugins. How?
Depending on what stream you are going to send, and what recordings you are going to use,
install one or some of the following:
```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
```
#### 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**
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.
**If you experience 'hangs' or other artefacts on the output signal**
* reduce the quality (especially, when hangs are on the stream) or
* install the realtime kernel with
```bash
apt install linux-image-rt-amd64
reboot
```
or
* invest in better hardware
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment