diff --git a/README.md b/README.md index eca98f7f95636577aff73f97493f76a0ae1156ec..35375365ce7664b5ea7ed5c86f7ac206905574eb 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 4877aab8a9292dff7a03bd871098e3c57a857994..bccfbdc0e0709df7144fd6e57278d3731a122d2b 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