From b7b85b5c17137de86ed76f052722da2a4b2e3ef8 Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Tue, 25 Feb 2020 17:14:19 +0100
Subject: [PATCH] Updated documentation.

---
 README.md                   | 205 ++++++++----------------------------
 docs/configuration-guide.md |  69 ++++++++++++
 docs/developer-guide.md     |  71 +++++++++++++
 docs/engine-features.md     |  43 ++++++++
 4 files changed, 224 insertions(+), 164 deletions(-)
 create mode 100644 docs/configuration-guide.md
 create mode 100644 docs/developer-guide.md
 create mode 100644 docs/engine-features.md

diff --git a/README.md b/README.md
index 90788657..eca98f7f 100644
--- a/README.md
+++ b/README.md
@@ -3,36 +3,18 @@
 
 - [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)
+    - [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)
     - [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)
@@ -47,111 +29,41 @@ specifically build for the requirements of community radios.
 
 ## Features
 
-### 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
-
-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
-fallback handling scenarios. The available fallbacks are evaluated in following order:
-
-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
+- 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
 
+Read more on the [Engine Features](docs/engine-features.md) page.
 
 ## 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 "**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:
-
-    # 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 information 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
+To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or visit
+ the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
 
-### Hardware Requirements
+## 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.
-
-Aura Engine is tested with following audio devices
-
-* ASUS Xonar DGX, 
-* Roland Duo-Capture Ex 
-* Onboard Soundcard (HDA Intel ALC262)
-* Native Instruments Komplete Audio 6
-
-### Software Requirements
+**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.
 
 **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
+
+## Getting Started
 
 ```bash
 git clone https://gitlab.servus.at/autoradio/engine
 ```
 
-#### Install System Packages
+### Install System Packages
 
 On a Debian / Ubuntu machine:
 
@@ -185,14 +97,14 @@ sudo apt install \
 ```
 
 
-#### Install Python Packages
+### Install Python Packages
 
 ```bash
 sudo pip3 install -r requirements.txt
 ```
 
 
-#### Setup Database
+### Setup Database
 
 
 ```bash
@@ -203,7 +115,7 @@ CREATE USER 'aura'@'localhost' IDENTIFIED BY 'secure-password';
 GRANT ALL PRIVILEGES ON aura_engine.* TO 'aura'@'localhost';  
 ```
 
-#### Alternative Sound Servers
+### Alternative Sound Servers
 
 Beside ALSA the sound servers **Jack Audio** and **Pulse Audio** are supported.
 
@@ -229,7 +141,7 @@ sudo apt install \
 ```
 
 
-#### Configuration
+### Configuration
 
 Run
 
@@ -244,31 +156,7 @@ After that, you have to edit the settings in */etc/aura/engine.ini*. Ensure to t
 
 
 
-
-### Hardware
-
-#### Soundcard
-
-#### 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.
-
-#### 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.
-
-#### Streams
-
-You can configure up to **five** streams. You find the settings in the engine.ini. You can choose between different streaming formats.
-
-
-
-
-### Running the Engine ###
+## Running the Engine ###
 
 To start the AuRa Engine execute:
 
@@ -282,7 +170,7 @@ and on system boot run following:
 
 The first service starts the LiquidSoap Engine, while the latter boots the actual AuRa Engine.
 
-### Logging
+## Logging
 
 You can access the service logs using:
 
@@ -294,29 +182,18 @@ and
 
 respectively.
 
+## Frequently Asked Questions
 
+### Which Audio Interface / Soundcard is compatible with Aura?
 
-## 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.
-
-
-
-
-
+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
 
-## Frequently Asked Questions ##
 
 ### ALSA Settings
 
diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md
new file mode 100644
index 00000000..4877aab8
--- /dev/null
+++ b/docs/configuration-guide.md
@@ -0,0 +1,69 @@
+
+# Aura Engine Configuration Guide
+
+This page goes into detail on what is possible to configure within the engine.
+
+## Soundcard
+
+Configure your audio device in the `[soundcard]` section of `engine.ini`.
+
+You can configure up to **five** line IN and OUT stereo channels. 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).
+
+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.
+
+## Recordings
+
+You can configure up to **five** recorders in the `[recording]`.
+
+## Streams
+
+You can configure up to **five** streams in the `[streams]`.
+
+## Fallbacks
+
+Configure fallback handling in the `[fallback]` section.
+
+## Database
+
+Configure your engine database in the `[database]` section.
+
+## Monitoring
+
+Configure monitoring parameters in the `[monitoring]` section.
+
+## Web User Interface
+
+Configure the web interface in the `[web-ui]` section.
+
+## Administrator Emails
+
+Configure the email server for admin mails in the `[mail]` section.
+
+## API Endpoints
+
+Configure connections to the other Aura components in the `[dataurls]` section.
+
+## Fading
+
+Configure fading parameters in the `[fading]` section.
+
+## Logging
+
+Configure log handling in the `[logging]` section.
+
+## User
+
+Configure the executing system user in the `[user]` section.
+
+## Socket
+
+Configure socket connectivity in the `[socket]` section.
+
+## Redis
+
+Configure Redis connectivity in the `[redis]` section.
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
new file mode 100644
index 00000000..b355469c
--- /dev/null
+++ b/docs/developer-guide.md
@@ -0,0 +1,71 @@
+# Aura Engine Development Guide
+
+This page gives insights on extending Aura Engine internals or through the API.
+
+
+## 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.
+
+To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
+
+## Required Data Sources
+
+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:
+
+    # 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 information 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/
+
+
+## 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.
+
+
+## Running the Engine
+
+Aura Engine is consisting of two components: The Python Engine and Liquidsoap Core.
+
+It's important to start both components in the correct order:
+
+    1. Run the Python engine
+
+    ./run.sh
+
+    2. Run the Liquidsoap core
+
+    ./run.sh lqs
diff --git a/docs/engine-features.md b/docs/engine-features.md
new file mode 100644
index 00000000..e05247b1
--- /dev/null
+++ b/docs/engine-features.md
@@ -0,0 +1,43 @@
+# Aura Engine Features
+
+This page gives a more detailed overview of the Aura Engine features.
+
+## Input
+
+### Play audio 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**.
+
+### Dynamic switching of sources
+
+    TODO extend: * switch the soundserver at the correct time to a given source for a specific show
+
+## Output
+
+### Record output to filesystem
+
+    TODO extend:  * record what is broadcasted
+
+### Stream output to an Icecast Server
+
+    TODO extend:  * stream to an icecast server
+
+### Multichannel Line-out
+
+    TODO extend:  * play to line-out
+
+## Blank Detenction / Silence Detecter
+
+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 a.k.a. Fallback Handling
+
+In case there is no schedule delivered by Steering, engine provides multiple
+fallback handling scenarios. The available fallbacks are evaluated in following order:
+
+1. **Timeslot Fallback**: //TODO explain
+2. **Show Fallback**: //TODO explain
+3. **Station Fallback**: //TODO explain
-- 
GitLab