From 44aa2afe4255d1f760819e8cdae0d736581e3dc6 Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Wed, 27 Jan 2021 16:09:53 +0100
Subject: [PATCH] Improeved documentation for ALSA config. engine#72

---
 config/sample-development.engine-core.ini | 22 ++++++++++------------
 config/sample-docker.engine-core.ini      | 22 ++++++++++------------
 config/sample-production.engine-core.ini  | 22 ++++++++++------------
 3 files changed, 30 insertions(+), 36 deletions(-)

diff --git a/config/sample-development.engine-core.ini b/config/sample-development.engine-core.ini
index 6fa74c6..75e68eb 100644
--- a/config/sample-development.engine-core.ini
+++ b/config/sample-development.engine-core.ini
@@ -56,21 +56,19 @@ output_device_2=""
 output_device_3=""
 output_device_4=""
 
-# If you are using Alsa, you most probably have to tweak these values
-# out of the box you will hear alot of cracklings and artifacts
+# If you are using ALSA, you might need to tweak these values if you're hearing jitter, cracklings or other artifacts
 
-
-# alsa_buffer => int
-alsa_buffer="8192"
-#alsa_buffer="16384"
-# alsa_buffer_length => int
-alsa_buffer_length="25"
-# alsa_periods => int
+# Set to 0 to use the ALSA default.
+alsa_buffer="0"
+# Only used for buffered ALSA I/O, and affects latency. Probably not wanted for live audio. Defaults to "1"
+alsa_buffer_length="0"
+# # Set to 0 to use the ALSA default. Defaults to "0"
 alsa_periods="0"
-# frame_duration => double
-frame_duration=""
-# frame_size => int
+# Frame Size ("frame.audio.size"); Unclear if that's still required as it's not documented in Liquidsoap anymore.
 frame_size=""
+# Tentative frame duration in seconds, defaults to "0.04" (Float). This setting is used as a hint for the duration, 
+# when ‘frame_size’ is not provided. It's required for getting things in sync, but it's actually tricky to set correctly.
+frame_duration=""
 
 [stream]
 # defines enabled or not
diff --git a/config/sample-docker.engine-core.ini b/config/sample-docker.engine-core.ini
index 0667c5b..ebba40c 100644
--- a/config/sample-docker.engine-core.ini
+++ b/config/sample-docker.engine-core.ini
@@ -56,21 +56,19 @@ output_device_2=""
 output_device_3=""
 output_device_4=""
 
-# If you are using Alsa, you most probably have to tweak these values
-# out of the box you will hear alot of cracklings and artifacts
+# If you are using ALSA, you might need to tweak these values if you're hearing jitter, cracklings or other artifacts
 
-
-# alsa_buffer => int
-#alsa_buffer="8192"
-alsa_buffer="16384"
-# alsa_buffer_length => int
-alsa_buffer_length="25"
-# alsa_periods => int
+# Set to 0 to use the ALSA default.
+alsa_buffer="0"
+# Only used for buffered ALSA I/O, and affects latency. Probably not wanted for live audio. Defaults to "1"
+alsa_buffer_length="0"
+# # Set to 0 to use the ALSA default. Defaults to "0"
 alsa_periods="0"
-# frame_duration => double
-frame_duration=""
-# frame_size => int
+# Frame Size ("frame.audio.size"); Unclear if that's still required as it's not documented in Liquidsoap anymore.
 frame_size=""
+# Tentative frame duration in seconds, defaults to "0.04" (Float). This setting is used as a hint for the duration, 
+# when ‘frame_size’ is not provided. It's required for getting things in sync, but it's actually tricky to set correctly.
+frame_duration=""
 
 [stream]
 # defines enabled or not
diff --git a/config/sample-production.engine-core.ini b/config/sample-production.engine-core.ini
index dc168f0..75e68eb 100644
--- a/config/sample-production.engine-core.ini
+++ b/config/sample-production.engine-core.ini
@@ -56,21 +56,19 @@ output_device_2=""
 output_device_3=""
 output_device_4=""
 
-# If you are using Alsa, you most probably have to tweak these values
-# out of the box you will hear alot of cracklings and artifacts
+# If you are using ALSA, you might need to tweak these values if you're hearing jitter, cracklings or other artifacts
 
-
-# alsa_buffer => int
-#alsa_buffer="8192"
-alsa_buffer="16384"
-# alsa_buffer_length => int
-alsa_buffer_length="25"
-# alsa_periods => int
+# Set to 0 to use the ALSA default.
+alsa_buffer="0"
+# Only used for buffered ALSA I/O, and affects latency. Probably not wanted for live audio. Defaults to "1"
+alsa_buffer_length="0"
+# # Set to 0 to use the ALSA default. Defaults to "0"
 alsa_periods="0"
-# frame_duration => double
-frame_duration=""
-# frame_size => int
+# Frame Size ("frame.audio.size"); Unclear if that's still required as it's not documented in Liquidsoap anymore.
 frame_size=""
+# Tentative frame duration in seconds, defaults to "0.04" (Float). This setting is used as a hint for the duration, 
+# when ‘frame_size’ is not provided. It's required for getting things in sync, but it's actually tricky to set correctly.
+frame_duration=""
 
 [stream]
 # defines enabled or not
-- 
GitLab