developer-guide.md 4.2 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
8
- [Aura Engine Development Guide](#aura-engine-development-guide)
    - [Architecture](#architecture)
9
10
11
12
13
14
15
16
        - [Components](#components)
    - [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 -->

21
## Architecture
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.

28
29
30
31
32
33
34
35
36
37
38
39
### 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
David Trattnig's avatar
David Trattnig committed
40
41
42
43
44
45
46

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:

David Trattnig's avatar
David Trattnig committed
47
48
    # The URL to get the Calendar via Steering
    api_calendar_url="http://localhost:8000/api/v1/playout"
David Trattnig's avatar
David Trattnig committed
49

David Trattnig's avatar
David Trattnig committed
50
    # The URL to get show details via Steering
David Trattnig's avatar
David Trattnig committed
51
52
    api_show_url="http://localhost:8000/api/v1/shows/${ID}/"

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

    # The URL to get playlist details via Tank
David Trattnig's avatar
David Trattnig committed
57
    api_playlist_url="http://localhost:8040/api/v1/shows/${SLUG}/playlists"
David Trattnig's avatar
David Trattnig committed
58
59
60
61


More information you can find here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>

62
### Provided API Endpoints
David Trattnig's avatar
David Trattnig committed
63
64
65
66
67
68
69
70
71
72
73

**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/


74
## Web Applications using the Engine API
David Trattnig's avatar
David Trattnig committed
75

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

78
79
- [Track Service](contrib/aura-player/README.md)
- [Studio Clock](contrib/aura-clock/README.md)
David Trattnig's avatar
David Trattnig committed
80

81
When you start the engine-api using
David Trattnig's avatar
David Trattnig committed
82

83
84
85
```shell
    ./run.sh api-dev
```
David Trattnig's avatar
David Trattnig committed
86

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

90
## More infos for debugging
David Trattnig's avatar
David Trattnig committed
91

92
### Default ports used by Engine
David Trattnig's avatar
David Trattnig committed
93
94
95
96
97
98
99
100

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

Those are the default port numbers:

* `1234` ... Liquidsoap Telnet Server
* `3333` ... Exposes the Engine API
* `5000` ... Svelte development mode; dynamically uses some other port if occupied
101
102


103
### Debugging Liquidsoap
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

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
128
129
130
131
132
133
134
135


## Read more

- [Overview](/README.md)
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)
- [Running with Docker](running-docker.md)
136
- [Setup the Audio Store](docs/setup-audio-store.md)
137
138
139
- [Configuration Guide](configuration-guide.md)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)