README.md

# Aura Engine

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

Aura Engine is a play-out engine as part of [Aura Radio Software Suite](#About),
specifically build for the requirements of community radios.

<!-- TOC -->

- [Aura Engine](#aura-engine)
    - [Features](#features)
    - [Architecture](#architecture)
    - [Requirements](#requirements)
    - [Installation](#installation)
    - [Configuration](#configuration)
    - [Running Engine](#running-engine)
        - [Development](#development)
        - [Production](#production)
            - [API Server](#api-server)
    - [Logging](#logging)
    - [About](#about)
    - [Resources](#resources)

<!-- /TOC -->

## Features

- Play audio from multiple sources
- Dynamic switching of sources
- Record output to filesystem
- Stream output to an Icecast Server
- Multichannel Line-out
- Blank Detenction / Silence Detecter
- Auto Pilot a.k.a. Fallback Handling
- API to query Track-Service
- API to query monthly reports
- API to query data for a studio clock
- Web Application for displaying the Track-Service
- Web Application for displaying the studio clock

Read more on the [Engine Features](docs/engine-features.md) page.

## Architecture

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 learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or visit
 the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.

## Requirements

**Hardware Requirements:** This depends on how many audio sources and targets you are
 going to use, but for the most common scenarios any current hardware should be sufficient.
 For the audio devices it is required to use an interface which has supported ALSA drivers.

**Operating System:** Any linux system with ALSA, PulseAudio or Jack2 support should work.
It is tested and coded on Debian Stretch and Ubuntu 18.0.


## Installation

Aura Engine requires at least `Node 13`, `Python 3.7`. Then install `Liquidsoap 1.4.1` using [OPAM](https://www.liquidsoap.info/doc-1.4.1/install.html).

```bash
git clone https://gitlab.servus.at/autoradio/engine
```

By default Aura Engine uses MariaDB for persistence. When starting the installation, please
ensure you have root access to your database instance. The installation script automatically
creates a database plus an associated user with password. If you want to use your own database
system, select "Other / Manually" during the database installation step.

Development Environment

```bash
sudo ./install.sh
```

Production Environment

```bash
sudo ./install.sh prod
```


## Configuration

In your development envirnment edit the file

```shell
./configuration/engine.ini
```

to configure the engine.

In production, or if the file exists, Engine uses the config location

```shell
/etc/aura/engine.ini
```

Read more about detailed settings in the [Configuration Guide](docs/configuration-guide.md).

## Running Engine

### Development

While developing there is a simple convencience script `run.sh`
to get you started. Call the engine's components in following order:

```shell
    ./run.sh      # Starts the engine-core component
    ./run.sh lqs  # Starts the engine-liquidsoap component
    ./run.sh api  # Starts the engine-api component
```

In development mode Engine uses the [Flask](https://palletsprojects.com/p/flask/) development server.
This server should not be used in your production environment.


### Production

In production the process is slightly different to ensure the
engine's components are always running i.e. restart themselves after some system
restart or crash. Therefore they are executed using a system service:

```bash
  systemctl start aura-engine  
  systemctl start aura-lqs
```

and on system boot run following:

```bash
  systemctl enable aura-engine
  systemctl enable aura-lqs
```

#### API Server

For production Engine API uses the WSGI HTTP Server [`Gunicorn`](https://gunicorn.org/).

In production Gunicorn is used in combination with some proxy server, such as Nginx.

> Although there are many HTTP proxies available, we strongly advise that you use Nginx. If you choose another proxy server you need to make sure that it buffers slow clients when you use default Gunicorn workers. Without this buffering Gunicorn will be easily susceptible to denial-of-service attacks. You can use Hey to check if your proxy is behaving properly. — [**Gunicorn Docs**](http://docs.gunicorn.org/en/latest/deploy.html).




[`Supervisor`](http://supervisord.org/) is a preferable solution to run the gunicorn server
in the background and also start it automatically on reboot.

**Start the API service with Supervisor**

```shell
    sudo supervisorctl reread
    sudo supervisorctl update
    sudo supervisorctl avail
    sudo supervisorctl restart engine-api
```

In case you want to reload whole supervisor service

```shell
    sudo service supervisor restart
```

## Logging

All Engine logs for production can be found in `/var/log/aura/engine`


You can access the service logs using one of:

```
    journalctl -u aura-lqs
    journalctl -u aura-engine
```

## About

<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-logo.png" width="150" />

Aura Engine is the play-out engine of the Aura Radio Software Suite. Aura stands for Automated Radio and is a swiss army knife for community radios. Beside the Engine it provides Steering (Admin Interface for the radio station), Dashboard (Collaborative scheduling and programme coordination), Tank (Audio uploading, pre-processing and delivery). Read more in the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository or on the specific project pages.

| [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/pv)  |  [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/dashboard)  |  [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/tank) | [<img src="https://gitlab.servus.at/autoradio/meta/-/raw/master/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/autoradio/engine)  |
|---|---|---|---|
| [Steering](https://gitlab.servus.at/autoradio/pv)  | [Dashboard](https://gitlab.servus.at/autoradio/dashboard)  | [Tank](https://gitlab.servus.at/autoradio/tank)  | [Engine](https://gitlab.servus.at/autoradio/engine)  |


## Resources

* **Python**: https://docs.python.org/
* **Redis**: https://redis.io/
* **Liquidsoap**: https://www.liquidsoap.info/doc-1.4.0/
* **Jack Audio**: https://jackaudio.org/
* **Flask**: https://palletsprojects.com/p/flask/
* **Supervisor**: http://supervisord.org/
* **Gunicorn**: https://gunicorn.org/