Engine API Server

Engine API stores and provides playlog and studio clock information for the playout engine.

Its features include:

• Playlogs: A history of all audio played by the Engine.
• Track Service: Same as playlogs, but stripped-down information for public use.
• Studio Clock: Information on the current and next shows to be used in a Studio Clock application.
• Health Information: The history of health status records.
• Data Synchronization: In high-availability deployment scenarios, data is aggregated from various Engine API instances. This can be extended to other audio sources, like physical silence detectors or other studio equipment.

This documentation is primarily meant for developers. For using the AURA Community Radio Suite visit aura.radio.

Prerequisites

• Python 3.9+
• pip
• git
• PostgreSQL 13+

Preparation

Initialize environment

Install dependencies and prepare config file

make init.app

This also creates a default configuration file at config/engine-api.ini.

For development install with

make init.dev

Note, if some configuration exists under /etc/aura/engine-api.ini the configuration by default is drawn from there. This overrides any configuration located in the local configuration file.

Initialize database

Engine requires a PostgreSQL database to cache any programme info locally.

sudo -u postgres psql -f contrib/postgresql-create-database.sql

This creates a database and tables with default password 1234.

Configuration

Edit the configuration file at config/engine-api.ini. Verify or change the database password.

db_pass="1234"

Running Engine

To start the Engine execute

make run

Docker

For production deployments follow the Docker Compose installation instruction for AURA Playout at docs.aura.radio.

The following instructions are meant for development.

Build with Docker

Build your own, local Docker image

make docker.build

Run with Docker

Run the locally build image

make docker.run

Release to DockerHub

Releasing a new version to DockerHub

make docker.push

Usually this is not required, as this is automatically performed by the CI/CD pipeline.

Development

This project is based on a Flask server using an API First approach. The API is specified using Open API 3. The resulting API implementation is utilizing the popular Connexion library on top of Flask.

Using the API as a developer

You can find details on the available API endpoints at api.aura.radio.

Adding some entry to the playlog:

curl -d '{ "track_start": "2020-06-27 19:14:00", "track_artist": "Mazzie Star", "track_title": "Fade Into You", "log_source": 1 }' -H "Content-Type: application/json" -X POST http://localhost:8008/api/v1/playlog

This newly added entry can be queried using your browser in one of the following ways:

# Get the latest entry
http://localhost:8008/api/v1/trackservice/current
# Get a set of the most recent entries
http://localhost:8008/api/v1/trackservice/
# Filter some specific page (the three most recent entries)
http://localhost:8008/api/v1/trackservice?page=0&limit=3

The local OpenAPI UI can be found at /api/v1/ui/ and your OpenAPI definition lives at /api/v1/openapi.json:

Extending the API as a developer

The workflow for extending the API follows the API First approach. This means you have to edit the API at https://app.swaggerhub.com/apis/AURA-Engine/engine-api/, using the SwaggerHub web editor. Then download the python-flask server stubs, and replace & merge the existing generated sources in src/aura_engine_api/rest.

All model files can usually be overwritten. Only controller classes need to undergo a merge action. Test classes can be skipped.

Due to Swagger account limitations, you'll have to get in touch with the maintainer, when modifying the API specification. In the future it might be favorable to use a local OpenAPI editor and Codegen to generate the API artifacts.

Read more

• Advanced configuration of Engine API
• Engine Overview
• docs.aura.radio
• aura.radio