developer-guide.md 5.45 KB
Newer Older
1
# Aura Engine Development Guide
David Trattnig's avatar
David Trattnig committed
2
3
4

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

David Trattnig's avatar
David Trattnig committed
5
<!-- TOC -->
David Trattnig's avatar
David Trattnig committed
6

7
- [Aura Engine Development Guide](#aura-engine-development-guide)
David Trattnig's avatar
David Trattnig committed
8
9
    - [AURA Componentes](#aura-componentes)
        - [Engine Components](#engine-components)
10
11
12
13
14
15
16
    - [API](#api)
        - [Required Data Sources](#required-data-sources)
        - [Provided API Endpoints](#provided-api-endpoints)
    - [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)
17
    - [Read more](#read-more)
David Trattnig's avatar
David Trattnig committed
18
19
20

<!-- /TOC -->

David Trattnig's avatar
David Trattnig committed
21
## AURA Componentes
David Trattnig's avatar
David Trattnig committed
22
23
24
25
26
27

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.

David Trattnig's avatar
David Trattnig committed
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
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
49
50
51
52
53
54
55
56
57
58
59


**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
David Trattnig's avatar
David Trattnig committed
60
61
62
63
64
65
66

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
using a fancy calendar interface.

These data-sources need to be configurated in the "engine.ini" configuration file:

67
68
    # STEERING
    api_steering_status = "http://localhost:8000/api/v1/"
David Trattnig's avatar
David Trattnig committed
69
    # The URL to get the Calendar via Steering
70
    api_steering_calendar="http://localhost:8000/api/v1/playout"
David Trattnig's avatar
David Trattnig committed
71
    # The URL to get show details via Steering
72
73
    api_steering_show="http://localhost:8000/api/v1/shows/${ID}/"

David Trattnig's avatar
David Trattnig committed
74

David Trattnig's avatar
David Trattnig committed
75
The AURA Project "**Tank**" on the other hand delivers information on the tracks, related playlists
David Trattnig's avatar
David Trattnig committed
76
77
to be played and its meta-data:

78
79
    # TANK
    api_tank_status = "http://localhost:8040/ui/"
David Trattnig's avatar
David Trattnig committed
80
    # The URL to get playlist details via Tank
81
    api_tank_playlist="http://localhost:8040/api/v1/shows/${SLUG}/playlists"
David Trattnig's avatar
David Trattnig committed
82
83


David Trattnig's avatar
David Trattnig committed
84
You can find more information here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>
David Trattnig's avatar
David Trattnig committed
85

86
### Provided API Endpoints
David Trattnig's avatar
David Trattnig committed
87
88
89
90
91
92
93
94
95
96
97

**Soundserverstate:** Returns true and false values of the internal In- and Outputs  

    /api/v1/soundserver_state

**Trackservice:**

/api/v1/trackservice/<selected_date>  
/api/v1/trackservice/


98
## Web Applications using the Engine API
David Trattnig's avatar
David Trattnig committed
99

100
Under `./contrib` you'll find two Web Applications which utilize the Engine API:
David Trattnig's avatar
David Trattnig committed
101

102
103
- [Track Service](contrib/aura-player/README.md)
- [Studio Clock](contrib/aura-clock/README.md)
David Trattnig's avatar
David Trattnig committed
104

105
When you start the engine-api using
David Trattnig's avatar
David Trattnig committed
106

107
108
109
```shell
    ./run.sh api-dev
```
David Trattnig's avatar
David Trattnig committed
110

111
112
this automatically builds these web applications and copies the resulting assets to the
relevant `./web/**` folders.
David Trattnig's avatar
David Trattnig committed
113

114
## More infos for debugging
David Trattnig's avatar
David Trattnig committed
115

116
### Default ports used by Engine
David Trattnig's avatar
David Trattnig committed
117
118
119
120
121
122

Aura Engine requires a number of ports for internal and external communication.

Those are the default port numbers:

* `1234` ... Liquidsoap Telnet Server
David Trattnig's avatar
David Trattnig committed
123
* `8008` ... Exposes the Engine API
David Trattnig's avatar
David Trattnig committed
124
* `5000` ... Svelte development mode; dynamically uses some other port if occupied
125
126


127
### Debugging Liquidsoap
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

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
152
153
154
155
156
157
158
159


## Read more

- [Overview](/README.md)
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)
- [Running with Docker](running-docker.md)
160
- [Setup the Audio Store](docs/setup-audio-store.md)
161
162
163
- [Configuration Guide](configuration-guide.md)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)
David Trattnig's avatar
David Trattnig committed
164
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)