From 6a84306c320902aac4906b56b0a9730c2b4e4681 Mon Sep 17 00:00:00 2001
From: Loxbie <ole@freirad.at>
Date: Thu, 19 Oct 2023 13:01:16 +0200
Subject: [PATCH] docs: new installation guide for PipeWire + JACK

---
 CHANGELOG.md | 16 +++++++++++
 README.md    | 75 +++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 73 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2f5822c..847328b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - ...
 
+## [1.0.0-alpha3] - 
+
+### Changed
+
+- Default sound system is now JACK, not ALSA
+- Docs: Update README with new PipeWire based installation
+
+### Added
+
+- PipeWire as the media server inside the docker container
+- Docker compose support for easier building of local containers
+
+### Removed
+
+- Dropped ALSA in Docker support in favour of PipeWire + JACK
+
 ## [1.0.0-alpha2] - 2023-06-19
 
 ### Changed
diff --git a/README.md b/README.md
index 0b7dfc1..a820eef 100644
--- a/README.md
+++ b/README.md
@@ -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.
 
-$`\textcolor{green}{\text{Recommended audio device configuration}}`$
+### Configure JACK/ALSA
 
-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`. 
 
 ```bash
-make audio.alsa.init
+cp config/sample.engine-core.ini config/engine-core.ini
 ```
 
 ## Configure the audio source locations
@@ -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
+pw-link "lineout_0:out_1" "alsa_output.usb-BEHRINGER_UMC202HD_192k_12345678-00.stereo-fallback:playback_FR"
+```
+
 Voilá, you should hear some music!
 
+## Running Engine Core with docker compose
+
+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`
+
+```
+mixer.select 4 true
+```
-- 
GitLab