From 9ccc5f3826e585cb37d54b98fbd7dc13b0b7d93a Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Fri, 19 Feb 2021 12:57:36 +0100
Subject: [PATCH] Improved Readme for standalone server. #72
---
README.md | 125 ++++++++++++++++++++++++++++++++++--------------------
1 file changed, 79 insertions(+), 46 deletions(-)
diff --git a/README.md b/README.md
index 699f9af..3428ee4 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,111 @@
-# Aura Engine
+# AURA Engine Core
<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-engine.png" width="250" align="right" />
-Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for
-the requirements of community radios.
+AURA Engine Core is a play-out server for radio stations based on [Liquidsoap](https://www.liquidsoap.info/).
+
+For full utilization Engine Core might be combined with [Engine](https://gitlab.servus.at/aura/engine) providing a managment, monitoring and scheduling layer atop. Engine Core provides following features out of the box:
+
+- **Play audio from various sources** including files, streams and analog live audio
+- **Analog audio or digital stream output** which is able to connect to an Icecast Server. It allows to stream to multiple Icecast Servers simultaniousely including sending of meta information using the *Icy* protocol.
+- **Auto DJ** triggered by a silence detector to avoid [Dead Air](https://en.wikipedia.org/wiki/Dead_air). Play randomized music form a folder or M3U playlist.
+- **ReplayGain** normalization done using passed [ReplayGain](https://en.wikipedia.org/wiki/ReplayGain) meta data.
+- **Track Service** notifications when used in conjunction with [Engine API](https://gitlab.servus.at/aura/engine-api)
+
+This project is part of [Aura Radio Software Suite](https://gitlab.servus.at/aura/meta), specifically build for the requirements of community radios.
<!-- TOC -->
-- [Aura Engine](#aura-engine)
- - [Features](#features)
- - [Architecture](#architecture)
- - [Installation](#installation)
+- [AURA Engine Core](#aura-engine-core)
+ - [Prerequisites](#prerequisites)
+ - [Quickstart](#quickstart)
+ - [Audio Store](#audio-store)
+ - [Advanced Configuration](#advanced-configuration)
+ - [Other AURA Components](#other-aura-components)
+ - [Liquidsoap Server Debugging](#liquidsoap-server-debugging)
- [Read more](#read-more)
- [About](#about)
- - [Resources](#resources)
<!-- /TOC -->
-## Features
+## Prerequisites
+
+To [install the AURA Suite](https://gitlab.servus.at/aura/meta) we recommend using [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/).
+
+In certain scenarios like for development you might want to do a bare metal installation though. In that case you'll need to have following installed:
+
+ * [git](https://git-scm.com/)
+ * [OPAM (OCaml Package Manager)](https://opam.ocaml.org/)
+ * [Liquidsoap 1.4.3](https://www.liquidsoap.info/doc-1.4.3/install.html) installed using OPAM
+
+## Quickstart
-- **Scheduler** to automatically broadcast your radio programme (see [AURA Dashboard](https://gitlab.servus.at/aura/dashboard) for an schedule user interface)
-- **Play audio from multiple sources** including files, streams and analog live audio
-- **Dynamic switching of sources** organized as playlists
-- **Stream output** to an Icecast Server
-- **Multichannel Line-out**
-- **Silence Detector** to avoid [Dead Air](https://en.wikipedia.org/wiki/Dead_air)
-- **Auto DJ** which plays random music when silence is detected
-- **ReplayGain** normalization done using passed [ReplayGain](https://en.wikipedia.org/wiki/ReplayGain) meta data
-- **API** to query Track-Service, monthly reports and information for displaying the Studio Clock (see [Engine API](https://gitlab.servus.at/aura/engine-api))
-- **Web Application for a Track Service** (see [AURA Player](https://gitlab.servus.at/aura/player))
-- **Web Application providing a Studio Clock** (see [Engine Clock](https://gitlab.servus.at/aura/engine-clock))
-- **Bulk and Timeslot Recorder** (This will be provided after v1.1 by a planned `engine-recorder` component)
+1. Create the folder structure `./audio/station/` in the project root and populate `station` with some music files. This folder is picked up as a so-called *Station Fallback* in case no other music is scheduled or if silence is detected.
+2. Execute `./run.sh` to get the *Engine Core* server running.
+3. Voilá, you should hear some music!
-Read more on the [Engine Features](docs/engine-features.md) page.
+If the audio device desired for playback is set as `default`, the Engine now should be ready to play sound. If you are not hearing any sound set a working output device for `output_device_0` in `engine-core.ini` and carefully review the logs.
-## Architecture
+You can check the systems default audio hardware by executing `aplay -L` on the command line. If that's not the case you can set the default device in `/etc/asound.conf`. The most glitch-free experience you'll get when the [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) Sound Server is set as you default [ALSA](https://www.alsa-project.org/) device. For production you might want to check for any latency issues though.
-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.
+After this is working you might be ready for a more sophisticated setup of the engine environment.
-To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or visit
- the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
+## Audio Store
-## Installation
+The aformentioned `audio` folder is the base for retrieving audio files. Engine Core is referencing three folders from the *Audio Store*:
+
+- **`audio/station/`**: A local folder for any emergency playback, also called *Station Fallback*. All audio files inside are played in a randomized order, if no actually scheduled music is played by the engine. The folder is being watched for changes. So you can add/remove audio on the fly.
+- **`audio/playlist/`**: Put a file `station-fallback-playlist.m3u` in here and it has the same effect as the fallback folder. If nothing else is scheduled, the M3U Playlist is played with higher priority than the folder. The playlist is being watched for changes.
+- **`audio/source/`**: This is the location for audio files provided by [Tank](https://gitlab.servus.at/aura/tank). Usually any audio files which are part of the scheduled programme are read for their broadcast from here. If you are running all AURA components on a single machine you should be fine with just creating a symbolic link to the relevant Tank folder (`ln -s ../engine/audio ./audio`). But in some [distributed and redundant production scenario](https://gitlab.servus.at/aura/meta/-/blob/master/docs/installation-guide.md) you might think about more advanced options on how to sync your audio files between machines. You can find some ideas in the do
- [Installation for Development](docs/installation-development.md)
- [Installation for Production](docs/installation-production.md)
- [Running with Docker](docs/running-docker.md)
-- [Setup the Audio Store](docs/setup-audio-store.md)
+- [Setting up the Audio Store](https://gitlab.servus.at/aura/meta/-/blob/master/docs/setup-audio-store.md)
+
+## Advanced Configuration
+
+Review the settings in your `engine-core.ini` to fine-tune the heart of your engine. If you are experiencing issues also check out the [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md).
+
+## Other AURA Components
+
+After successfully running Engine Core you might look into getting started with [the other Engine Components](https://gitlab.servus.at/aura/engine) and [AURA Web](https://gitlab.servus.at/aura/meta).
+
+## Liquidsoap Server Debugging
+
+Connect to Liquidsoap via [Telnet](https://en.wikipedia.org/wiki/Telnet)
+
+ telnet 127.0.0.1 1234
+
+List available commands
+
+ help
+
+List all available channels
+
+ list
+
+List all input channels connected to the mixer
+
+ mixer.input
+
+Set the volume of mixer `input 0` to `100%`
+
+ mixer.volume 0 100
+
+Push some audio file to the filesystem `in_filesystem_0`
+
+ in_filesystem_0.push /path/to/your/file.mp3
## Read more
-- [Developer Guide](docs/developer-guide.md)
-- [Engine Features](docs/engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)
-
## About
-Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for
-the requirements of community radios.
+Aura Engine is a scheduling and play-out engine as part of [Aura Radio Software Suite](#About), specifically build for the requirements of community radios.
[<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-logo.png" width="150" />](https://gitlab.servus.at/aura/meta)
@@ -69,15 +113,4 @@ AURA stands for Automated Radio and is a swiss army knife for community radio st
| [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/aura/steering) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/aura/dashboard) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/aura/tank) | [<img src="https://gitlab.servus.at/aura/meta/-/raw/master/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/aura/engine) |
|---|---|---|---|
-| [Steering](https://gitlab.servus.at/aura/steering) | [Dashboard](https://gitlab.servus.at/aura/dashboard) | [Tank](https://gitlab.servus.at/aura/tank) | [Engine](https://gitlab.servus.at/aura/engine)<br/>[Engine API](https://gitlab.servus.at/aura/engine-api)<br/>[Engine Clock](https://gitlab.servus.at/aura/engine-clock) |
-
-## Resources
-
-* **Python**: https://docs.python.org/
-* **OPAM (OCaml Package Manager)**: https://opam.ocaml.org/
-* **Liquidsoap**: https://www.liquidsoap.info/doc-1.4.0/
-* **Jack Audio**: https://jackaudio.org/
-* **Flask**: https://palletsprojects.com/p/flask/
-* **Systemd**: https://systemd.io/
-* **Supervisor**: http://supervisord.org/
-* **Gunicorn**: https://gunicorn.org/
\ No newline at end of file
+| [Steering](https://gitlab.servus.at/aura/steering) | [Dashboard](https://gitlab.servus.at/aura/dashboard) | [Tank](https://gitlab.servus.at/aura/tank) | [Engine](https://gitlab.servus.at/aura/engine)<br/>[Engine Core](https://gitlab.servus.at/aura/engine-core)<br/>[Engine API](https://gitlab.servus.at/aura/engine-api)<br/>[Engine Clock](https://gitlab.servus.at/aura/engine-clock) |
--
GitLab