developer-guide.md 4.77 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
    - [AURA Componentes](#aura-componentes)
David Trattnig's avatar
David Trattnig committed
9
    - [Engine Components](#engine-components)
10
    - [API](#api)
David Trattnig's avatar
David Trattnig committed
11
    - [Engine Startup Phases](#engine-startup-phases)
12
13
    - [More infos for debugging](#more-infos-for-debugging)
        - [Debugging Liquidsoap](#debugging-liquidsoap)
David Trattnig's avatar
David Trattnig committed
14
        - [Tips on configuring the audo interface](#tips-on-configuring-the-audo-interface)
15
    - [Read more](#read-more)
David Trattnig's avatar
David Trattnig committed
16
17
18

<!-- /TOC -->

David Trattnig's avatar
David Trattnig committed
19
## AURA Componentes
David Trattnig's avatar
David Trattnig committed
20
21
22
23
24
25

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
26
27
28
29
30
31
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.
32
    - Dashboard, to have a neat interface, being able to programm the timeslots
David Trattnig's avatar
David Trattnig committed
33
34
35
36
37
38
39
40
41
42
43
44
45
    - 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
```

David Trattnig's avatar
David Trattnig committed
46
## Engine Components
47
48


49
*...TBD...*
50
51
52
53


## API

David Trattnig's avatar
David Trattnig committed
54
You can find the AURA API definition here: https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md
David Trattnig's avatar
David Trattnig committed
55

David Trattnig's avatar
David Trattnig committed
56
OpenAPI definition for Engine API: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/
David Trattnig's avatar
David Trattnig committed
57

David Trattnig's avatar
David Trattnig committed
58
## Engine Startup Phases
David Trattnig's avatar
David Trattnig committed
59

David Trattnig's avatar
David Trattnig committed
60
When you start Engine the following is happening:
David Trattnig's avatar
David Trattnig committed
61

62
1. Python `run.py`: Initializes `src/core/engine.py` (The virtual mixer; class for remote-controlling Liquidsoap), Scheduler
63
2. Python `run.py`: Start Liquidsoap.
David Trattnig's avatar
David Trattnig committed
64
3. Liquidsoap: When Liquidsoap finished its startup, it creates a socket file as configured in `socketdir` of `engine.ini`.
65
4. Python `src/core/liquidsoap/client.py`: Connects to that socket file.
66
5. Python `src/schedulung/scheduler.py`: Continously loads timeslots from the API endpoints, stores them in the local database and starts the playout as per the timeslots.
67

David Trattnig's avatar
David Trattnig committed
68
## More infos for debugging
69

70
### Debugging Liquidsoap
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

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
95
96


David Trattnig's avatar
David Trattnig committed
97
98
99
100
101
102
103
104
105
106
107
108
### Tips on configuring the audo interface

Configure your audio device in the `[soundcard]` section of `engine.ini`.

You can configure up to **five** line IN and OUT stereo channels. Your hardware should
support that. When you use JACK, you will see the additional elements popping up when
viewing your connections (with e.g. Patchage).

**Pulse Audio:** When using Ubuntu, Pulse Audio is selected by default. This is convenient,
as you won't have the need to adapt any Engine setting to get audio playing initially.

**ALSA:** When you use ALSA, you will have to play around with ALSA settings. In the folder
109
`./src/liquidsoap` is a scipt called alsa_settings_tester.liq. You can start it
David Trattnig's avatar
David Trattnig committed
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
with 'liquidsoap -v --debug alsa_settings_tester.liq'. Changing and playing with
settings may help you to find correct ALSA settings.

**Jack Audio**: Install the JACK daemon and GUI:

```bash
    sudo apt-get install jackd qjackctl 
```

Please ensure to enable "*realtime process priority*" when installing JACK to keep latency low.
Now, you are able to configure your hardware settings using following command:

```bash
    qjackctl
```

Next you need to install the JACK plugin for Liquidsoap:

```bash
sudo apt install \
    liquidsoap-plugin-jack
```


134
135
136
137
138
139
## Read more

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