developer-guide.md

# Aura Engine Development Guide

This page gives insights on extending Aura Engine internals or through the API.

<!-- TOC -->

- [Aura Engine Development Guide](#aura-engine-development-guide)
    - [AURA Componentes](#aura-componentes)
    - [Engine Components](#engine-components)
    - [API](#api)
    - [Engine Startup Phases](#engine-startup-phases)
    - [More infos for debugging](#more-infos-for-debugging)
        - [Debugging Liquidsoap](#debugging-liquidsoap)
        - [Tips on configuring the audo interface](#tips-on-configuring-the-audo-interface)
    - [Read more](#read-more)

<!-- /TOC -->

## AURA Componentes

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.

To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.

Starting development of engine can be quite tedious, as it requires all most all other AURA components to be up and running.

For example:

    - Steering, to get the main incredient of an play-out engine: schedules (or "timeslots" in Steering terms), 
      which hold the actual information on playlists and their entries.
    - Dashboard, to have a neat interface, being able to programm the schedules
    - Tank, to get the references to audio files and other audio sources. Plus the actual files.

If you need to test and develop against the Engine's API you'll also need to get the `engine-api` project running.

For a start it's recommended to create a general `aura` project folder. In there you start cloning all the sub-projects.
After having all the sub-projects configured, and verified that they are working, take a look at the AURA `meta` project.

There's a convenience script to start all of the three main dependencies (Steering, Dashboard, Tank) all at once:

```bash
    ~/code/aura/meta$ ./run.sh aura local
```

## Engine Components


*...TBD...*


## API

You can find the AURA API definition here: https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md

OpenAPI definition for Engine API: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/

## Engine Startup Phases

When you start Engine the following is happening:

1. Python `run.py`: Initializes `src/core/engine.py` (The virtual mixer; class for remote-controlling Liquidsoap), Scheduler
2. Python `run.py`: Start Liquidsoap.
3. Liquidsoap: When Liquidsoap finished its startup, it creates a socket file as configured in `socketdir` of `engine.ini`.
4. Python `src/core/liquidsoap/client.py`: Connects to that socket file.
5. Python `src/schedulung/scheduler.py`: Continously loads schedules from the API endpoints, stores them in the local database and starts the playout as per the schedules.

## More infos for debugging

### Debugging Liquidsoap

Connect to Liquidsoap via 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 `queue 0`

    in_filesystem_0.push /path/to/your/file.mp3


### Tips on configuring the audo interface

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
`./src/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**: 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
```


## 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)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)