README.md

# AURA Engine Core

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

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 management, 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 from a folder or M3U playlist.
- **ReplayGain** normalization done using passed [ReplayGain](https://en.wikipedia.org/wiki/ReplayGain) meta data.
- **Metadata** notifications for posting playlogs to [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 radio stations.

<!-- TOC -->

1. [AURA Engine Core](#aura-engine-core)
   1. [Prerequisites](#prerequisites)
   2. [Quickstart](#quickstart)
   3. [Audio Store](#audio-store)
   4. [Advanced Configuration](#advanced-configuration)
   5. [Channel Routing](#channel-routing)
   6. [Testing](#testing)
   7. [Logging](#logging)
   8. [Other AURA Components](#other-aura-components)
   9. [Read more](#read-more)
   10. [About](#about)

<!-- /TOC -->

## Prerequisites

To install the AURA Suite for testing or production we recommend using the [Docker Compose](https://docs.aura.radio/en/latest/administration/install-docker-compose.html) installation instead. The following steps are aiming for developers.

You'll need to have following installed before proceeding:

- [git](https://git-scm.com/)
- `apt-get 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`
- [Liquidsoap 2.1.x](https://www.liquidsoap.info/) installed using [OPAM (OCaml Package Manager)](https://opam.ocaml.org/) and these additional dependencies:
  - `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`

Now clone this repository to your target instance.

## Quickstart

Perform following commands inside the `engine-core` 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 `./run.sh` 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.

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.

After this is working you might be ready for a more sophisticated setup of the engine environment.

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

## Advanced 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]
```

## Testing

A basic _Test Suite_ can be executed with

```bash
./tests/$ liquidsoap engine_test_suite.liq
```

## Logging

The Engine Core logs can be found under `./logs`.

## 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://docs.aura.radio/en/latest/administration/overview.html).

## Read more

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

## About

[<img src="https://gitlab.servus.at/autoradio/meta/-/raw/main/assets/images/aura-logo.png" width="150" />](https://aura.radio)