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.
