Commit c750853c authored by David Trattnig's avatar David Trattnig
Browse files

Extended development documentation.

parent 7513ed3b
......@@ -6,10 +6,12 @@ This page gives insights on extending Aura Engine internals or through the API.
- [Aura Engine Development Guide](#aura-engine-development-guide)
- [Architecture](#architecture)
- [Components](#components)
- [API](#api)
- [Required Data Sources](#required-data-sources)
- [Provided API Endpoints](#provided-api-endpoints)
- [Components](#components)
- [Running the Engine](#running-the-engine)
- [Web Applications using the Engine API](#web-applications-using-the-engine-api)
- [More infos for debugging](#more-infos-for-debugging)
- [Default ports used by Engine](#default-ports-used-by-engine)
- [Debugging Liquidsoap](#debugging-liquidsoap)
- [Read more](#read-more)
......@@ -23,7 +25,18 @@ based on a REST API. All external information is retrieved using JSON data-struc
To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
## Required Data Sources
### Components
**engine-core.py**: It is the server which is connected to the external programme source (e.g. aura steering and tank), to liquidsoap and is listening for redis pubsub messages. This precious little server is telling liquidsoap what to play and when.
**Liquidsoap**: The heart of AuRa Engine. It uses the built in mixer, to switch between different sources. It records everything and streams everything depending on your settings in aura.ini.
**engine-api.py**: A Flask web server which provides the API endpoints. This component can be (re-) started independently from the core engine.
## API
### Required Data Sources
The AURA Project "**Dashboard**" provides the GUI to organize shows, schedules/timelsots
and organize uploads in form of playlists. Those playlists can be organized in timeslots
......@@ -47,7 +60,7 @@ to be played and its meta-data:
More information you can find here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>
## Provided API Endpoints
### Provided API Endpoints
**Soundserverstate:** Returns true and false values of the internal In- and Outputs
......@@ -59,32 +72,25 @@ More information you can find here: <https://gitlab.servus.at/autoradio/meta/blo
/api/v1/trackservice/
## Components
**aura.py**: It is the server which is connected to the external programme source (e.g. aura steering and tank), to liquidsoap and is listening for redis pubsub messages. This precious little server is telling liquidsoap what to play and when.
**Guru**: The commandline tool for interacting with the server. Also provides the communication from Liquidsoap to the Python (Command-)Server.
**Liquidsoap**: The heart of AuRa Engine. It uses the built in mixer, to switch between different sources. It records everything and streams everything depending on your settings in aura.ini.
## Running the Engine
Aura Engine is consisting of two components: The Python Engine and Liquidsoap Core.
## Web Applications using the Engine API
It's important to start both components in the correct order:
Under `./contrib` you'll find two Web Applications which utilize the Engine API:
1. Run the Python engine
- [Track Service](contrib/aura-player/README.md)
- [Studio Clock](contrib/aura-clock/README.md)
./run.sh
When you start the engine-api using
2. Run the Liquidsoap core
```shell
./run.sh api-dev
```
./run.sh lqs
this automatically builds these web applications and copies the resulting assets to the
relevant `./web/**` folders.
## More infos for debugging
## Default ports used by Engine
### Default ports used by Engine
Aura Engine requires a number of ports for internal and external communication.
......@@ -95,7 +101,7 @@ Those are the default port numbers:
* `5000` ... Svelte development mode; dynamically uses some other port if occupied
## Debugging Liquidsoap
### Debugging Liquidsoap
Connect to Liquidsoap via Telnet
......
......@@ -105,17 +105,17 @@ This includes the Liquidsoap audio engine, but does not start the API server.
**Run the Engine Core and Liquidsoap separately**
This requires to start the Liquidsoap component within some other terminal. This is helpful for
debugging purposes.
When developing and debugging engine it is helpful to start the core and the Liquidsoap
component separately. In such case it is important to start both in the correct order.
First start the core of the engine:
```shell
./run.sh core
```
**Run Liquidsoap only**
This requires to start the core component in another terminal. This is helpful for
debugging purposes.
When engine-core completed its boot phase, indicated by a log that it is waiting for
Liquidsoap, you can run following:
```shell
./run.sh lqs
......@@ -126,7 +126,7 @@ debugging purposes.
This requires to start the core component in another terminal.
```shell
./run.sh api
./run.sh api-dev
```
In development mode Engine uses the default [Flask](https://palletsprojects.com/p/flask/) web server.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment