From 9925ceacfbba14b64479cf1779a4ccf565cc9940 Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Tue, 25 Feb 2020 18:09:37 +0100
Subject: [PATCH] Simplified docs.

---
 README.md                   | 159 +++++++-----------------------------
 docs/configuration-guide.md |  92 ++++++++++++++++++++-
 2 files changed, 120 insertions(+), 131 deletions(-)

diff --git a/README.md b/README.md
index eca98f7f..35375365 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,24 @@
 
+# 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 ##
diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md
index 4877aab8..bccfbdc0 100644
--- a/docs/configuration-guide.md
+++ b/docs/configuration-guide.md
@@ -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
-- 
GitLab