@@ -39,6 +39,9 @@ Before you begin, ensure you have met the following requirements:
- Operating system: Debian 11, Ubuntu 20.04 or newer
- Audio device which has good [ALSA](https://alsa-project.org/wiki/Main_Page) support
-[Liquidsoap 2.1.x](https://www.liquidsoap.info/) installed using [OPAM (OCaml Package Manager)](https://opam.ocaml.org/)
-[PipeWire](https://pipewire.org/) installed
-[WirePlumber](https://pipewire.pages.freedesktop.org/wireplumber/) installed as a session / policy manager for PipeWire
-[qpwgraph](https://gitlab.freedesktop.org/rncbc/qpwgraph), optional as an UI to manage audio devices
-[Docker](https://www.docker.com/), optional if you want to run in a container
-`git`, `make`
...
...
@@ -69,32 +72,32 @@ This command also creates a default configuration file `config/engine-core.ini`.
### Configure the audio interface
By default only audio output is enabled using the systems default ALSA device.
You get the most glitch-free experience when using [PipeWire](https://pipewire.org/) as your media server. To avoid any play-out malfunctions ensure that no other media server is running. PipeWire is capable of replacing PulseAudio while still having the full functionality of PulseAudio if you want to keep PulseAudio. To check if PipeWire has replaced PulseAudio, run `make audio.pa.status`. This command should return a line like
$`\textcolor{red}{\text{Ensure PulseAudio server is disabled}}`$
```
Server Name: PulseAudio (on PipeWire 0.3.80)
```
You get the most glitch-free experience when using [ALSA](https://www.alsa-project.org/) devices
directly. To avoid any play-out malfunctions ensure that no PulseAudio server is running.
To check if PipeWire is up and running you can use
To check if PulseAudio is started, run `make audio.pa.status`. If this command returns an error,
PulseAudio is deactivated.
```bash
systemctl --user status pipewire
```
If you want to choose a different device, edit the configuration file and set a value for `output_device_0`.
### Choose your audio system ALSA / JACK
It is also possible to set ALSA hardware device IDs like `hw:0,0`. Check the FAQ below on how to
retrieve available audio device IDs.
At the moment we recommend running engine-core with [JACK](https://jackaudio.org/). [ALSA](https://alsa.opensrc.org/) support for the complete AURA system was dropped in favour of JACK but might be added back in. In either case PipeWire takes care of your devices and connections.
For better I/O performance it is recommended to create a custom ALSA PCM device named `pcm.aura_engine`, matching your device settings.
Have a look at `config/sample.engine-core.ini`. Here you can set things like the log level and much more. For JACK no adaptations are necessary.
You can use the sample configuration [`sample.asoundrc`](https://gitlab.servus.at/aura/engine-core/-/blob/main/config/sample.asoundrc) as a basis for creating such device. Consult the ALSA documentation on details. After creating such device verify its properly
assigned in the configuration file as `output_device_0="pcm.aura_engine"`.
For ALSA you might want to set a different audio device or even configure your own. An example can be found in `config/sample.asoundrc`. Very important is the `alsa_buffer`, if you experience jitter, cracklings or other audio artifacts you should increase this number. If the buffer is to large you will experience bad latency, to reduce the latency you have to reduce the buffer size.
The following command creates a symlink in `config/.asoundrc` to your ALSA config in your home directory:
When you are finished copy the configuration `config/sample.engine-core.ini` to `config/engine-core.ini`.
@@ -147,9 +150,7 @@ for Docker deployments. Check the `Makefile` and `sample.env` for hints on envir
## Running Engine Core
To make the playout server play some music first create a folder `audio/fallback/` drop some
music files. This folder is picked up as a so-called _Station Fallback_ in case no other music
is scheduled or if silence is detected.
To make the playout server play some music first create the folder `audio/fallback/` if it doesn't exist and drop some music files. This folder is picked up as a so-called _Station Fallback_ in case no other music is scheduled or if silence is detected.
To start the server execute
...
...
@@ -157,8 +158,40 @@ To start the server execute
make run
```
Now connect your audio device(s) with engine-core. There are two ways to achieve this:
- use a UI like [qpwgraph](https://gitlab.freedesktop.org/rncbc/qpwgraph), simply draw connections between the desired devices
- use the PipeWire cli tool `pw-link`
```bash
# List the input ports
pw-link -i
# List the output ports
pw-link -o
# A example for connecting a output port with a input port
When running engine-core with docker compose you need a different configuration file to start with. Have a look at `config/sample.engine-core.docker.ini` and copy it to `config/engine-core.ini` (FIXME: this uses the overwrite in /etc/aura/ and is not the best of options). Do not change the paths here, rather change them in `sample.env` and copy this file to `.env`. Make sure the directories in `.env` are read and writable for the user used in the container, mainly `aura(2872:2872)`.
You can now build the container with
```bash
docker compose build
```
And start it with
```bash
docker compose up
```
Connect your audio device(s) with engine-core as mentioned above. Voilá, you should hear some music!
## Advanced tips for development
### Control playout via telnet
...
...
@@ -186,3 +219,9 @@ Set the volume of mixer `input 0` to `100%`
Push some audio file to the filesystem `in_queue_0`
`in_queue_0.push /path/to/your/file.mp3`
Select line in as your input where 4 is the number from `mixer.inputs`
