Now initialize the project environment for development
After cloning the project perform following commands inside the project directory:
```bash
make init.dev
```
1. Create an initial configuration file based on an sample config: `cp config/sample.engine-core.ini config/engine-core.ini`
2. Create the folder structure `./audio/fallback/` in the project root and populate `fallback` with 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.
3. Execute `make run` to get the _Engine Core_ server running. Voilá, you should hear some music!
This command also creates a default configuration file `config/engine-core.ini`.
If the audio device desired for playback is set as `default`, the Engine now should be ready to play sound. If you are not hearing any sound set a working output device for `output_device_0` in `engine-core.ini` and carefully review the logs.
## Configuring Engine Core
> Important: 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 not running.
### Configure the audio interface
You can check the systems default audio hardware by executing `aplay -L` on the command line. If that's not the case you can set the default device in `/etc/asound.conf` or `~/asoundrc`. To check if PulseAudio is started, run `make audio.pa.status`. If this command returns an error, PulseAudio is deactivated.
By default only audio output is enabled using the systems default ALSA device.
## Audio Store
$`\textcolor{red}{\text{Ensure PulseAudio server is disabled}}`$
The aforementioned `audio` folder is the base for retrieving audio files. Engine Core is referencing three folders from this so-called _Audio Store_:
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 not running.
-**`audio/fallback/`**: A local folder for any emergency playback, also called _Station Fallback_. All audio files inside are played in a randomized order, if no actually scheduled music is played by the engine. The folder is being watched for changes. So you can add/remove audio on the fly. This fallback feature is enabled by default.
-**`audio/playlist/`**: Put a file `station-fallback-playlist.m3u` in here and it has the same effect as the fallback folder.
he playlist is being watched for changes. Set `fallback_type="playlist"` to enable this instead of the fallback folder.
-**`audio/source/`**: This is the location for audio files provided by [Tank](https://gitlab.servus.at/aura/tank). Usually any audio files which are part of the scheduled programme are read from here to perform broadcasts. If you are running all AURA components on a single machine you should be fine with just creating a symbolic link to the relevant Tank folder (`ln -s ../engine/audio ./audio`). But in some [distributed and redundant production scenario](https://docs.aura.radio/en/latest/administration/deployment-scenarios.html) you might think about more advanced options on how to sync your audio files between machines. You can find some ideas in the doc " [Setting up the Audio Store](https://docs.aura.radio/en/latest/administration/setup-audio-store.html)".
To check if PulseAudio is started, run `make audio.pa.status`. If this command returns an error,
PulseAudio is deactivated.
## Configuration
If you want to choose a different device, edit the configuration file and set a value for `output_device_0`.
By default only audio output is enabled using the systems default device. If you want to use another audio interface or enable live audio, check the [Audio Device Configuration](docs/audio-device-configuration.md) document.
It's also possible to set ALSA hardware device IDs like `hw:0,0`. Check the FAQ below on how to
retrieve available audio device IDs.
Also review the other settings in your `engine-core.ini` to fine-tune the heart of your engine. If you are experiencing issues also check out the [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md).
For better I/O performance it's recommended to create an ALSA PCM device named `pcm.aura_engine`.
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"`.
Following diagram shows existing channels and their routing.
Before you begin, ensure you have met the following requirements:
-[Docker](https://www.docker.com/)
- Audio interface which has good [ALSA](https://alsa-project.org/) support
## Configuring Engine Core
### Configure the audio interface
By default only audio output is enabled using the systems default ALSA device.
```{admonition} Ensure PulseAudio server is disabled
:class: warning
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 not running.
To check if PulseAudio is started, run `pactl list`. If this command returns an error, PulseAudio is deactivated.
```
If you want to choose a different device, edit the configuration file and set a value for `output_device_0`.
It's also possible to set ALSA hardware device IDs like `hw:0,0`. Check the FAQ below on how to retrieve available audio device IDs.
For better I/O performance it's recommended to create an ALSA PCM device named `pcm.aura_engine`. 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"`.
```
## Configure the audio source locations
Engine Core is requires different audio sources in order to perform the playout.
### Configure the location for fallback music
By default fallback audio is retrieved from the `fallback` folder. A local folder for any
emergency playback, also called _Station Fallback_.
```bash
audio/fallback/
```
All audio files inside are played in a randomized order, in situations where nothing is scheduled.
The folder is being watched for changes. So you can add/remove audio on the fly.
This fallback feature is enabled by default, but cann be turned off in via the configuration.
Instead of the fallback folder you can use a playlist in the `playlist` folder for fallback scenarios.
Its default file location is:
```bash
audio/playlist/station-fallback-playlist.m3u
```
Also this playlist is being watched for changes. You'll need to set the configuration option
`fallback_type="playlist"` to enable this instead of the fallback folder.
### Configure the audio source folder
This is the location for actually scheduled audio files. They are provided by Tank.
```bash
audio/source
```
If you are running all AURA services on a single instance you should be fine with just creating a
symbolic link to the relevant Tank folder (`ln -s ../engine/audio ./audio`). But in some
[distributed and redundant production scenario](https://docs.aura.radio/en/latest/administration/deployment-scenarios.html)
you might think about more advanced options on how to sync your audio files between machines.
You can find some ideas in the doc " [Setting up the Audio Store](https://docs.aura.radio/en/latest/administration/setup-audio-store.html)".
## Starting Engine Core
We recommend to run Engine Core as part of the [AURA Playout](https://docs.aura.radio/en/latest/administration/install-docker-compose.html#deploy-aura-playout) Docker Compose distribution.
But you could also [run Engine as a single Docker container](https://docs.aura.radio/en/latest/administration/install-docker.html) execute.
If you are a developer you might want to [run it natively](https://gitlab.servus.at/aura/engine-core).
## FAQ
### I am using the `default` audio device. How can I set another default device?
You can check the systems default audio hardware by executing `aplay -L` on the command line.
You can set the default device in `/etc/asound.conf` or `~/asoundrc`.
### How can I retrieve available ALSA audio devices
- To see only the physically available sound cards: `cat /proc/asound/cards`
- To see sound cards with all additional devices (e.g. HDMI): `aplay -l`
- To see devices configured by ALSA with additional plugins: `aplay -L`
- The default devices that should be used: `aplay -L | grep default`
### I have configured an audio device but still hear no sound (native installation)
To test if you device is able to output audio at all, independently from Engine Core, try executing `speaker-test`. Also checkout out the `-D` argument to test specific devices. If you system doesn't provide `speaker-test` you have to install or use your preferred way of testing also audio.
### I have configured an audio device but still hear no sound (Docker installation)
If you are running Engine Core using Docker, run the aforementioned `speaker-test` from within your docker container by perform following:
1. Bash into the container using `docker exec -it aura-engine-core bash`
2. Now run `speaker-test`. It that's working, you now know that your audio device is at least available from within Docker and you'll need to further check your Liquidsoap device configuration.
3. Next you can run `liquidsoap tests/test_alsa_default.liq`. This is a basic script which tries to play the supplied MP3 using the default ALSA device.
### I'm getting `clock.wallclock_alsa:2` Error when starting output lineout: Failure("Error while setting open_pcm: No such file or directory")!\*\*
Assure you have set the correct device ID. To do so read the paragraph above. Review the audio interface configuration settings and verify if the default settings `input_device_0` and `output_device_0` are valid device IDs.
In case your are _not_ running Engine Core within Docker, also check if your executing user (è.g. `engineuser`) belongs to the group `audio`.
### How to solve 'Error when starting output output_lineout_0: Failure("Error while setting open_pcm: Device or resource busy")!'?
You probably have set a wrong or occupied device ID. The device could be reserved by another software using the ALSA sound system. Or you might be accessing a device using ALSA which is already assigned to the Pulse Audio sound system. Here it could help to [remove the device from PulseAudio](https://jamielinux.com/blog/tell-pulseaudio-to-ignore-a-usb-device-using-udev/) before accessing it.
### How to avoid stutter, hangs, artifacts or in general glitchy sound?
This can have various reasons, but first of all it's good to check the `engine-core.log` file. Also check your CPU usage. Lastly review the settings of your audio device.
**Incorrect ALSA buffer settings**: If the ALSA settings provided by your system are not working cleanly the Engine Core settings provide to option to override parameters such as `alsa_buffer`. The correct settings are individual to the used soundcard but in general this is a tricky topic. In our case we had more success using PulseAudio or JACK instead. Recommendations are welcome.
**These problems occur while having Icecast streaming enabled**: Try to reduce the quality of the stream, especially when you are experiencing hangs on the stream. Check your Icecast connection. Is it up and running? Maybe there is some authentication issue or an [Icecast limitation for max clients](ttps://github.com/savonet/liquidsoap/issues/524).
**The hardware is hitting its limits**: Also check the relevant logs and the system utilization. Are there other processes using up the machines resources? You might even be hitting the performance limit of your hardware. Maybe using a realtime linux kernel could help too.
1.[Which Audio Interface or Soundcard is compatible with Engine Core?](#which-audio-interface-or-soundcard-is-compatible-with-engine-core)
2.[How can I find the audio output device IDs, required for settings in engine-core.ini?](#how-can-i-find-the-audio-output-device-ids-required-for-settings-in-engine-coreini)
3.[I have configured an audio device in my `engine-core.ini` but still hear no sound](#i-have-configured-an-audio-device-in-my-engine-coreini-but-still-hear-no-sound)
4.[I have configured an audio device in my `docker.engine-core.ini` but still hear no sound](#i-have-configured-an-audio-device-in-my-dockerengine-coreini-but-still-hear-no-sound)
5.[I'm getting [clock.wallclock_alsa:2] Error when starting output lineout: Failure("Error while setting open_pcm: No such file or directory")!\*\*](#im-getting-clockwallclock_alsa2-error-when-starting-output-lineout-failureerror-while-setting-open_pcm-no-such-file-or-directory)
6.[How to solve 'Error when starting output output_lineout_0: Failure("Error while setting open_pcm: Device or resource busy")!'?](#how-to-solve-error-when-starting-output-output_lineout_0-failureerror-while-setting-open_pcm-device-or-resource-busy)
7.[How to avoid stutter, hangs, artifacts or in general glitchy sound?](#how-to-avoid-stutter-hangs-artifacts-or-in-general-glitchy-sound)
8.[Are there any commands to directly control the playout-server for development, debugging or testing?](#are-there-any-commands-to-directly-control-the-playout-server-for-development-debugging-or-testing)
9.[Read More](#read-more)
<!-- /TOC -->
## Which Audio Interface or Soundcard is compatible with Engine Core?
Basically any audio device which is supported by Linux Debian/Ubuntu and has ALSA, JACK or Pulse Audio support.
## How can I find the audio output device IDs, required for settings in engine-core.ini?
- To see only the physically available sound cards: `cat /proc/asound/cards`
- To see sound cards with all additional devices (e.g. HDMI): `aplay -l`
- To see devices configured by ALSA with additional plugins: `aplay -L`
- The default devices that should be used: `aplay -L | grep default`
Check out the [Audio Device Configuration](docs/audio-device-configuration.md) page for more details on the input/output settings.
## I have configured an audio device in my `engine-core.ini` but still hear no sound
To test if you device is able to output audio at all, independently from Engine Core, try executing `speaker-test`. Also checkout out the `-D` argument to test specific devices. If you system doesn't provided `speaker-test` you have to install or use your preferred way of testing also audio.
## I have configured an audio device in my `docker.engine-core.ini` but still hear no sound
If you are running Engine Core using Docker, run the aforementioned `speaker-test` from within your docker container by perform following:
1. Start Engine Core in debug mode using `./run.sh docker:debug`
2. To login to your Docker container you can use the command `docker exec -it aura-engine-core bash`.
3. Now run `speaker-test`. It that's working, you now know that your audio device is at least available from within Docker and you'll need to further check your Liquidsoap device configuration.
4. Next you can run `liquidsoap tests/test_alsa_default.liq`. This is a basic script which tries to play the supplied MP3 using the default ALSA device.
## I'm getting [clock.wallclock_alsa:2] Error when starting output lineout: Failure("Error while setting open_pcm: No such file or directory")!\*\*
Assure you have set the correct device ID. To do so check the aforementioned question. Check the audio interface configuration section in `engine-core.ini`. Verify if the default settings `input_device_0` and `output_device_0` are valid device IDs.
In case your are _not_ running Engine Core within Docker, also check if your executing user (è.g. `engineuser`) belongs to the group `audio`.
## How to solve 'Error when starting output output_lineout_0: Failure("Error while setting open_pcm: Device or resource busy")!'?
You probably have set a wrong or occupied device ID. The device could be reserved by another software using the ALSA sound system. Or you might be accessing a device using ALSA which is already assigned to the Pulse Audio sound system. Here it could help to [remove the device from PulseAudio](https://jamielinux.com/blog/tell-pulseaudio-to-ignore-a-usb-device-using-udev/) before accessing it.
## How to avoid stutter, hangs, artifacts or in general glitchy sound?
This can have various reasons, but first of all it's good to check the `engine-core.log` logs. Also check your CPU usage. Lastly review the settings of your audio device.
**Incorrect ALSA buffer settings**: If the ALSA settings provided by your system are not working cleanly the `engine-core.ini` settings provide to option to override parameters such as `alsa_buffer`. The correct settings are individual to the used soundcard but in general this is a tricky topic. In our case we had more success using PulseAudio or JACK instead. Recommendations are welcome.
**These problems occur while having Icecast streaming enabled**: Try to reduce the quality of the stream, especially when you are experiencing hangs on the stream. Check your Icecast connection. Is it up and running? Maybe there is some authentication issue or an [Icecast limitation for max clients](ttps://github.com/savonet/liquidsoap/issues/524).
**The hardware is hitting its limits**: Also check the relevant logs and the system utilization. Are there other processes using up the machines resources? You might even be hitting the performance limit of your hardware. Maybe using a realtime linux kernel could help too.
## Are there any commands to directly control the playout-server for development, debugging or testing?
Connect to Liquidsoap via [Telnet](https://en.wikipedia.org/wiki/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.inputs`
Set the volume of mixer `input 0` to `100%`
`mixer.volume 0 100`
Push some audio file to the filesystem `in_queue_0`
