# Aura Engine Configuration Guide

This page goes into detail on what is possible to configure within the engine.

<!-- TOC -->

- [Aura Engine Configuration Guide](#aura-engine-configuration-guide)
    - [Station](#station)
    - [Soundcard](#soundcard)
    - [Recordings](#recordings)
    - [Streams](#streams)
    - [Fallbacks](#fallbacks)
    - [Database](#database)
    - [Monitoring](#monitoring)
    - [API Endpoints](#api-endpoints)
    - [Fading](#fading)
    - [Logging](#logging)
    - [User](#user)
    - [Socket](#socket)
    - [Redis](#redis)
    - [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)
    - [Read more](#read-more)

<!-- /TOC -->

## Station

These properties are used to style the included web applications such as *Track Service*
and *Studio Clock* .

Set the radio station name

```ini
station_name="Radio Orange"
```

Set the URL to the radio station logo

```ini
station_logo_url="https://your-radio.station/logo.png"
```

Set the `width` of the radio station logo

```ini
station_logo_size="120px"
```

## 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).

**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
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]`.

## 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 such as admin emails in the `[monitoring]` section.

## API Endpoints

Configure connections to the other Aura components in the `[api]` section.

Sets the API URL exposed to external clients. This is required by the included
web applications which access the API.

```ini
exposed_api_url="https://your-radio.station/api/v3"
```

## 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.


## 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


## Read more

- [Overview](/README.md)
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)
- [Running with Docker](running-docker.md)
- [Setup the Audio Store](docs/setup-audio-store.md)
- [Configuration Guide](configuration-guide.md)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)