# AURA Engine Core

<img src="https://gitlab.servus.at/autoradio/meta/-/raw/main/assets/images/aura-engine.png" width="250" align="right" />

AURA Engine Core is a multi-channel playout server for radio stations based on [Liquidsoap](https://www.liquidsoap.info/).

This documentation is meant for developers. For using the AURA Community Radio Suite check out the [aura.radio](https://docs.aura.radio/)

## Prerequisites

Before you begin, ensure you have met the following requirements:

- Operating system: Debian 11, Ubuntu 20.04 or newer
- [Liquidsoap 2.1.x](https://www.liquidsoap.info/) installed using [OPAM (OCaml Package Manager)](https://opam.ocaml.org/)
- git
- make

## Installation

Install system dependencies:

```bash
apt install curl alsa-utils libasound2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libflac-dev libjack-dev libpulse-dev libswresample-dev libswscale-dev libssl-dev ffmpeg opam
```

Build Liquidsoap with additional libraries:

```bash
opam depext alsa pulseaudio bjack ffmpeg samplerate flac taglib mad lame vorbis flac opus cry ocurl liquidsoap -y
opam install alsa pulseaudio bjack ffmpeg samplerate flac taglib mad lame vorbis flac opus cry ocurl liquidsoap -y
```

## Quickstart

After cloning the project perform following commands inside the project directory:

1. Create an initial configuration file based on an sample config: `cp config/sample.engine-core.ini config/engine-core.ini`
2. Create the folder structure `./audio/fallback/` in the project root and populate `fallback` 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.
3. Execute `make run` to get the _Engine Core_ server running. Voilá, you should hear some music!

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.

> Important: You get the most glitch-free experience when using [ALSA](https://www.alsa-project.org/) devices directly. To avoid any play-out malfunctions ensure that no PulseAudio server is not running.

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` or `~/asoundrc`. To check if PulseAudio is started, run `make audio.pa.status`. If this command returns an error, PulseAudio is deactivated.

## Audio Store

The aforementioned `audio` folder is the base for retrieving audio files. Engine Core is referencing three folders from this so-called _Audio Store_:

- **`audio/fallback/`**: 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. This fallback feature is enabled by default.
- **`audio/playlist/`**: Put a file `station-fallback-playlist.m3u` in here and it has the same effect as the fallback folder.
  he playlist is being watched for changes. Set `fallback_type="playlist"` to enable this instead of the fallback folder.
- **`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 from here to perform broadcasts. 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://docs.aura.radio/en/latest/administration/deployment-scenarios.html) you might think about more advanced options on how to sync your audio files between machines. You can find some ideas in the doc " [Setting up the Audio Store](https://docs.aura.radio/en/latest/administration/setup-audio-store.html)".

## Configuration

By default only audio output is enabled using the systems default device. If you want to use another audio interface or enable live audio, check the [Audio Device Configuration](docs/audio-device-configuration.md) document.

Also review the other 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).

## Channel Routing

Following diagram shows existing channels and their routing.

```mermaid
graph TD
    iq0[Queue A] -->|in_queue_0| mix
    iq1[Queue B] -->|in_queue_1| mix
    is0[Stream A] -->|in_stream_0| mix
    is1[Stream B] -->|in_stream_1| mix
    il0[Line In 1-5] -->|in_line_0..4| mix
    ff[Fallback Folder] -->|fallback_folder| which_fallback
    fpls[Fallback Playlist] -->|fallback_playlist| which_fallback
    mix["  Mixer  "] --> silence_detector
    which_fallback{or} -->| | silence_detector{Silence Detector}
    silence_detector -->| | output[Output]
    output --> |output.alsa| C[fa:fa-play Audio Interface]
    output --> |output.icecast| D[fa:fa-play Icecast]
```

## Read more

- [Audio Device Configuration](docs/audio-device-configuration.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)
- [aura.radio](https://aura.radio)