1.[Disabe an existing Pulse Audio Server](#disabe-an-existing-pulse-audio-server)
2.[Setting the output device using a device ID](#setting-the-output-device-using-a-device-id)
3.[Setting the input device](#setting-the-input-device)
1.[(A) Buffered audio](#a-buffered-audio)
2.[(B) Unbuffered audio](#b-unbuffered-audio)
2.[Pulse Audio](#pulse-audio)
3.[JACK](#jack)
<!-- /TOC -->
Following three audio drivers & servers are supported by *Engine Core*:
Following three audio drivers & servers are supported by _Engine Core_:
1. ALSA: Recommended for native hardware access. Only one input and output per channel pair is available.
2. PulseAudio: This provides the most simple setup, but is not recommended for live audio input due to latencies.
...
...
@@ -32,7 +30,8 @@ Out of the box Engine Core is configured to use ALSA `default` output. The input
When using your audio device with ALSA you are pretty close to the actual hardware. It can be relatively hard to find some good settings though.
**Documentation:** While the [*Official ALSA*](https://www.alsa-project.org/wiki/Documentation) documentation is not an easy read, there is a superb [*ALSA, exposed!*](https://rendaw.gitlab.io/blog/2125f09a85f2.html#alsa-exposed) documentation available too.
**Documentation:** While the [_Official ALSA_](https://www.alsa-project.org/wiki/Documentation) documentation is not an easy read, there is a superb [_ALSA, exposed!_](https://rendaw.gitlab.io/blog/2125f09a85f2.html#alsa-exposed) documentation available too.
### Disabe an existing Pulse Audio Server
Before starting, you need to ensure not having a Pulse Audio server running on your system. On Linux distributions like Ubuntu, PulseAudio is pre-installed and it can be tricky turning it off.
...
...
@@ -43,7 +42,7 @@ Having PulseAudio running in the background while thinking running native ALSA c
First stop PulseAudio from restarting automatically
```conf
````conf
nano ~/.pulse/client.conf
(autospawn = no)
```conf
...
...
@@ -51,7 +50,7 @@ nano ~/.pulse/client.conf
```bash
systemctl --userstoppulseaudio.socket
systemctl --userstoppulseaudio.service
```
````
You might even think about uninstalling PulseAudio altogether, as there are scenarios where the driver gets restarted upon ALSA device requests. Yes, even with having the PulseAudio service disabled and `autospawn = no` set in your PulseAudio configuration.
- Modern distributions configure the ALSA devices with *dmix*, so that several devices can use the sound card at the same time. This can lead to unintentional audio being played independently of engine-core, e.g. if a desktop is running on the same computer.
- Modern distributions configure the ALSA devices with _dmix_, so that several devices can use the sound card at the same time. This can lead to unintentional audio being played independently of engine-core, e.g. if a desktop is running on the same computer.
- The default configuration might have higher latencies than would be possible. However, the latency of the default devices is like using PulseAudio and quite sufficient.
This can be avoided by directly addressing the hardware and setting the parameters buffer size and periods in `engine-ini`. However, this requires a deep understanding of ALSA and experimentally finding the right parameters, so it is not recommended. A good starting point is to set only the parameter for the buffer size. Liquidsoap will adjust the remaining parameters automatically:
This can be avoided by directly addressing the hardware and setting the parameters buffer size and frame size in `engine-ini`. However, this requires a deep understanding of ALSA and experimentally finding the right parameters, so it is not recommended. A good starting point is to set only the parameter for the buffer size. Liquidsoap will adjust the remaining parameters automatically:
```ini
output_device_0="hw:2"
alsa_buffer="8192"
alsa_buffer="7056"
```
> #TODO Check if we should remove the alsa buffer recommendation here? According to my experience the frame-size is enough, as it also sets the buffer indirectly.
Next you need to connect some external audio to the analog inputs of your audio interface. Double check if there is enough amplitude to avoid unnecessary searches for an error. Now you can try starting the engine with `run.sh`. Do you hear some sound? It might work, but probably you hear some audio glitches and see plenty buffer underruns in the logs. That's because you need to specific the proper frame-size, individual to you soundcard and ALSA driver.
Next you need to decide if you want:
-**(A) Buffered audio**: There's some latency involved, but it is relatively easy to configure.
...
...
@@ -170,33 +168,34 @@ Buffered audio is relatively easy to configure, but introduce some latency. By t
First check if buffered audio is enabled. But it's the default anyway.
```ini
alsa_use_buffer="true"
alsa_buffered_input="true"
alsa_buffered_output="true"
```
In that case you might need to tweak following settings, where the defaults are a good start. Maybe you are lucky and it works out of the box? :-)
```ini
alsa_buffer="8192"
alsa_buffer="7056"
alsa_buffer_length="10"
alsa_frame_size="2048"
frame_audio_size="1764"
```
If you don't experience any buffer underruns in the logs you can try to decrease the buffer size to for example `4096` or `2048`.
If you don't experience any buffer underruns in the logs you can try to decrease the buffer size to for example `3528` or `1764`.
In case you get plenty of buffer unterruns then try to increase the buffer size and possibly the frame size to twice the given value.
#### (B) Unbuffered audio
When enabling unbuffered audio you can access the (almost ;) real-time capabilities of ALSA.
When enabling unbuffered audio you can access the (almost) real-time capabilities of ALSA.
```ini
alsa_use_buffer="false"
alsa_buffered_input="false"
```
In that case you need to tweak at least following setting, but it's one with some huge impact.
```ini
alsa_frame_size="2048"
frame_audio_size="1764"
```
**Detecting the correct frame-size**
...
...
@@ -209,23 +208,23 @@ Now perform following steps to find the correct frame-size:
1. Run the script with the initial `frame.audio.size` of zero: `engine-core/tests$ liquidsoap -v test_alsa_framesize.liq`
2. This causes plenty buffer underruns.
3. Liquidsoap reports the "correct" frame-size of e.g. 1881 in the logs: `[analog_input:3] Could not set buffer size to 'frame.size' (1764 samples), got 1881.`.
4. Now adapt the `frame.audio.size` in the script to `1881`.
3. Liquidsoap reports the "correct" frame-size of e.g. 1764 in the logs: `[analog_input:3] Could not set buffer size to 'frame.size' (1764 samples), got 1881.`.
4. Now adapt the `frame.audio.size` in the script to `1764`.
5. This may have caused buffer underruns too
6. Now try to set the frame size to a multiple of "1881". For example frame size to 2 x 1881 = 3762. Run the script again.
7. Liquidsoap logs another mismatch in the logs: `[analog_input:3] Could not set buffer size to 'frame.size' (3762 samples), got 3763.`
8. Now the value is only off by 1. This might be because of a resolution problem. So now try to set the frame size to 3762 + 1 = 3763
6. Now try to set the frame size to a multiple of "1764". For example frame size to 2 x 1764 = 3528. Run the script again.
7. Liquidsoap logs another mismatch in the logs: `[analog_input:3] Could not set buffer size to 'frame.size' (3528 samples), got 3529.`
8. Now the value is only off by 1. This might be because of a resolution problem. So now try to set the frame size to 3528 + 1 = 3529
9. Run the script again. Now the logs don't report an error like "Could not not set buffer size" anymore.
10. Watch the logs for a while. If there are still some buffer underruns try a higher number. Try another multiple by setting frame size to 2 x 3763 = 7526.
10. Watch the logs for a while. If there are still some buffer underruns try a higher number. Try another multiple by setting frame size to 2 x 3528 = 7056.
11. Run the script again. If there are no buffer underruns anymore and you hear clean sound without any glitches you have found an optimal value. Also watchout for any "Could not set buffer size" logs, they should be gone too.
The total steps needed and resulting values might be different based on your system and audio interface.
After you have found your own personal frame-size, use the value for the `alsa_frame_size` in the `engine-core.ini` config. Then start the engine and double-check the logs there.
After you have found your own personal frame-size, use the value for the `frame_audio_size` in the `engine-core.ini` config. Then start the engine and double-check the logs there.
## Pulse Audio
> *More testing and documentation on PulseAudio usage to be provided at a later stage. Feedback and tips are welcome.*
> _More testing and documentation on PulseAudio usage to be provided at a later stage. Feedback and tips are welcome._
A system which is already configured for PulseAudio needs no further configuration. The `default` ALSA device is emulated automatically using a PulseAudio ALSA plugin. The signal flow looks like following:
...
...
@@ -235,12 +234,10 @@ Obviously this is the reason for increased latencies. This should not be an issu
**Documentation:** Find more information in the [*PulseAudio*](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/) documentation.
**Documentation:** Find more information in the [_PulseAudio_](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/) documentation.
## JACK
> *Supported, but not yet tested. Documentation will be updated as soon we have more information on the actual usage. We are happy for contributions on configuration and best practices.*
> _Supported, but not yet tested. Documentation will be updated as soon we have more information on the actual usage. We are happy for contributions on configuration and best practices._
**Documentation:** Find more information in the [*JACK Audio Connection Kit*](https://jackaudio.org/) documentation.
**Documentation:** Find more information in the [_JACK Audio Connection Kit_](https://jackaudio.org/) documentation.
