Extended Readme.

README.md

-# AURA Engine
 
-This piece of Software is part of 'AURA - AUtomated RAdio'.
+<!-- TOC -->autoauto- [AURA Engine](#aura-engine)auto    - [Features](#features)auto        - [Play tracks from multiple sources](#play-tracks-from-multiple-sources)auto        - [Blank Detenction / Silence Detecter](#blank-detenction--silence-detecter)auto        - [Auto Pilot](#auto-pilot)auto        - [Dynamically switching of source channels](#dynamically-switching-of-source-channels)auto        - [Multiple Recorders](#multiple-recorders)auto        - [Stream to an Icecast Server](#stream-to-an-icecast-server)auto        - [Multichannel Line-out](#multichannel-line-out)auto    - [Architecture](#architecture)auto            - [Required Data Sources](#required-data-sources)auto            - [Provided API Endpoints](#provided-api-endpoints)auto    - [Installation](#installation)auto        - [Hardware Requirements](#hardware-requirements)auto        - [Software Requirements](#software-requirements)auto        - [Getting Started](#getting-started)auto            - [Install System Packages](#install-system-packages)auto            - [Install Python Packages](#install-python-packages)auto            - [Setup Database](#setup-database)auto            - [Alternative Sound Servers](#alternative-sound-servers)auto            - [Configuration](#configuration)auto        - [Hardware](#hardware)auto            - [Soundcard](#soundcard)auto            - [Hard/Soft](#hardsoft)auto            - [Line In](#line-in)auto            - [Recordings](#recordings)auto            - [Streams](#streams)auto        - [Running the Engine](#running-the-engine)auto        - [Logging](#logging)auto    - [Development](#development)auto        - [Components](#components)auto    - [Frequently Asked Questions](#frequently-asked-questions)auto        - [ALSA Settings](#alsa-settings)auto            - [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)auto            - [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)auto    - [Resources](#resources)autoauto<!-- /TOC -->
+
+
+# AURA Engine
 
-AURA Engine does:
- * 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
+Aura Engine is a play-out engine as part of Automated Radio (Aura) system,
+specifically build for the requirements of community radios.
 
 ## Features
 
-### Fallback Handling
+### 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
 
-In case there is no schedule delivered by the schedule, engine provides multiple
+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**:
-2. **Show Fallback**:
-3. **Station Fallback**:
+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
 
 
 ## Architecture
@@ -28,8 +54,11 @@ based on a REST API. All external information is retrieved using JSON data-struc
 
 #### Required Data Sources
 
-The AURA Project "**Steering**" provides the playouter calendar or schedule,
-and details on the shows to be airred:
+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"
@@ -44,7 +73,7 @@ to be played and its meta-data:
     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
+More information you can find here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>
 
 
 #### Provided API Endpoints
@@ -58,8 +87,6 @@ More informations you can find here: https://gitlab.servus.at/autoradio/meta/blo
 /api/v1/trackservice/<selected_date>  
 /api/v1/trackservice/
 
-
-
 ## Installation
 
 ### Hardware Requirements
@@ -68,17 +95,13 @@ This depends on how many audio sources and targets you are going to use, but for
 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
+Aura Engine is tested with following audio devices
 
 * ASUS Xonar DGX, 
 * Roland Duo-Capture Ex 
 * Onboard Soundcard (HDA Intel ALC262)
-
-Both work well with jack and pulseaudio. For a good experience with ALSA, you may need better hardware.
-
 * Native Instruments Komplete Audio 6
 
-
 ### Software Requirements
 
 **Operating System:** Any linux system with ALSA, PulseAudio or Jack2 support should work.