From 81c9034a6ffa39366ac726c57e1e824fbea643ea Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Sat, 16 Nov 2019 09:10:43 +0100
Subject: [PATCH] Improved structure of documentation; added some content.
---
README.md | 285 +++++++++++++++++++++++++++++++++++++-----------------
1 file changed, 195 insertions(+), 90 deletions(-)
diff --git a/README.md b/README.md
index 614d3a0..86528c8 100644
--- a/README.md
+++ b/README.md
@@ -1,62 +1,112 @@
# AURA Engine
-This piece of Software is part of 'AURA - AUtomated RAdio'.
+This piece of Software is part of 'AURA - AUtomated RAdio'.
AURA Engine does:
- * requesting the programme from an external Source
- * switches the soundserver at the correct time to a given source for a specific show
- * records what is broadcasted
- * streams to an icecast server
- * plays to lineout
+ * 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/
+
+
## Installation
-### Software
+### Hardware Requirements
-#### Operating System
+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.
-Any linux system with ALSA, pulseaudio or Jack2 support should work. It is tested and coded on a **debian stretch**
+AURA Engine is tested with following audio devices
-#### Packages
+* ASUS Xonar DGX,
+* Roland Duo-Capture Ex
+* Onboard Soundcard (HDA Intel ALC262)
-On a debian machine:
+Both work well with jack and pulseaudio. For a good experience with ALSA, you may need better hardware.
-```bash
-sudo apt install \
- git \
- python3 python3-pip \
- redis-server \
- liquidsoap liquidsoap-plugin-icecast \
- mariadb-server libmariadbclient-dev \
- quelcom
-```
+* Native Instruments Komplete Audio 6
-##### Liquidsoap Plugins
-###### Soundcard
-How liquidsoap is using your soundcard is depending on what you are going to use:
+### Software Requirements
-with ALSA:
-```bash
-sudo apt install \
- liquidsoap-plugin-alsa liquidsoap-plugin-pulseaudio
-```
+**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
-With pulseaudio:
```bash
-sudo apt install \
- liquidsoap-plugin-pulseaudio
+git clone https://gitlab.servus.at/autoradio/engine
```
-with jack:
+#### Install System Packages
+
+On a Debian / Ubuntu machine:
+
```bash
sudo apt install \
- liquidsoap-plugin-jack
+ git \
+ python3 python3-pip \
+ redis-server \
+ 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:
+**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
@@ -66,7 +116,7 @@ sudo apt install \
liquidsoap-plugin-vorbis # for ogg support
```
-###### Simple
+To simply install support for all available file formats do:
```bash
sudo apt install \
@@ -74,24 +124,15 @@ sudo apt install \
```
-#### Python Packages
+#### Install Python Packages
```bash
-sudo pip3 install \
- Flask Flask-SQLAlchemy \
- mysqlclient redis \
- mutagen validators
+sudo pip3 install -r requirements.txt
```
-#### Grab the code
-
-```bash
-git clone https://gitlab.servus.at/autoradio/engine
-```
-#### Set up a database
+#### Setup Database
-##### Command line way
```bash
mysql -u root -p
@@ -101,66 +142,52 @@ CREATE USER 'aura'@'localhost' IDENTIFIED BY 'secure-password';
GRANT ALL PRIVILEGES ON aura_engine.* TO 'aura'@'localhost';
```
-##### phpmyadmin / adminer way
-
-Log into your phpmyadmin or adminer with correct privileges, create a database and a user for the aura engine.
+#### Alternative Sound Servers
-#### Files and Folders
+Beside ALSA the sound servers **Jack Audio** and **Pulse Audio** are supported.
-* Create the audio folder defined in your aura.ini
+**Using JACK:**
+Install the JACK daemon and GUI:
```bash
-mkdir /var/audio
-mkdir /etc/aura
-cp {where you cloned the repo}/configuration/engine.ini /etc/aura/engine.ini
-edit engine.ini to your needs
+ sudo apt-get install jackd qjackctl
```
-* Edit settings in aura.ini. Take your time for that.
+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:
-#### 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
+```bash
+ qjackctl
+```
-The commandline tool for interacting with the server. Also provides the communication from Liquidsoap to the python (Command-)Server.
+Next you need to install the JACK plugin for Liquidsoap:
-#### Liquidsoap
+```bash
+sudo apt install \
+ liquidsoap-plugin-jack
+```
-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.
-#### Find Help
+#### Configuration
-##### Liquidsoap
-Reference: \
-http://savonet.sourceforge.net/doc-svn/reference.html
-##### Python
-Reference: \
-https://docs.python.org/3.5/
+Run
-#### Interfaces
+```bash
+ sh init.sh
+```
-##### From Aura Engine
+This creates the folder */var/audio* and copies some default configuration
+to */etc/aura/engine.ini*
-_Soundserverstate_ \
-Returns true and false values of the internal In- and Outputs \
-/api/v1/soundserver_state
+After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to take your time to carefully review those settings!
-_Trackservice_ \
-/api/v1/trackservice/<selected_date> \
-/api/v1/trackservice/
-##### To Aura Engine
-Interfaces are needed from pv/steering to engine and from tank to engine. More informations you can find here: https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md
### Hardware
#### Soundcard
-AURA Engine is tested with a ASUS Xonar DGX, a Roland Duo-Capture Ex and also on an Onboard Soundcard (HDA Intel ALC262). Both work well with jack and pulseaudio. For a good experience with ALSA, you may need better hardware.
-
#### Hard/Soft
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.
@@ -177,19 +204,97 @@ You can configure up to **five** recorders. You find the settings in the main co
You can configure up to **five** streams. You find the settings in the engine.ini. You can choose between different streaming formats.
-### Troubleshooting
-**If you cannot find correct ALSA settings** \
+
+
+### 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**
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
+ * 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/
--
GitLab