aplay: implement adaptive resampler

Author: borine

.github/spellcheck-wordlist.txt

@@ -256,6 +256,7 @@ SIGIO
 SIGPIPE
 SIGSEGV
 SIGTERM
+SINC
 SL
 SNR
 spandsp

configure.ac

@@ -319,6 +319,14 @@ AC_ARG_ENABLE([aplay],
 	[AS_HELP_STRING([--disable-aplay], [disable building of bluealsa-aplay tool])])
 AM_CONDITIONAL([ENABLE_APLAY], [test "x$enable_aplay" != "xno"])
 
+AC_ARG_ENABLE([aplay-resampler],
+	AS_HELP_STRING([--enable-aplay-resampler], [enable resampler in bluealsa-aplay]))
+AM_CONDITIONAL([ENABLE_APLAY_RESAMPLER], [test "x$enable_aplay_resampler" = "xyes"])
+AM_COND_IF([ENABLE_APLAY_RESAMPLER], [
+	PKG_CHECK_MODULES([SAMPLERATE], [samplerate >= 0.2.2])
+	AC_DEFINE([ENABLE_APLAY_RESAMPLER], [1], [Define to 1 if aplay resampler is enabled.])
+])
+
 AC_ARG_ENABLE([rfcomm],
 	[AS_HELP_STRING([--enable-rfcomm], [enable building of bluealsa-rfcomm tool])])
 AM_CONDITIONAL([ENABLE_RFCOMM], [test "x$enable_rfcomm" = "xyes"])

doc/bluealsa-aplay.1.rst

@@ -6,7 +6,7 @@ bluealsa-aplay
 a simple BlueALSA player
 ------------------------
 
-:Date: August 2024
+:Date: January 2025
 :Manual section: 1
 :Manual group: General Commands Manual
 :Version: $VERSION$
@@ -76,10 +76,12 @@ OPTIONS
     Select ALSA playback PCM device to use for audio output.
     The default is ``default``.
 
-    Internally, **bluealsa-aplay** does not perform any audio transformations
+    Internally, **bluealsa-aplay** is able to perform sample rate conversion
+    if it was built with libsamplerate support (see the option
+    **--resampler=**), but does not perform any other audio transformations
     nor streams mixing. If multiple Bluetooth devices are connected it simply
     opens a new connection to the ALSA PCM device for each stream. Selected
-    hardware parameters like sample rate and number of channels are
+    hardware parameters like sample format and number of channels are
     taken from the audio profile of a particular Bluetooth connection. Note,
     that each connection can have a different setup.
 
@@ -187,6 +189,38 @@ OPTIONS
     Note: Only one of A2DP or SCO can be used. If both are specified, the
     last one given will be selected.
 
+--resampler=METHOD
+    Use libsamplerate to convert the stream from the Bluetooth sample rate to
+    the ALSA PCM sample rate. This option is only available if
+    **bluealsa-aplay** was built with libsamplerate support. The resampler uses
+    adaptive resampling to compensate for timer drift between the Bluetooth
+    timer and the ALSA device timer. Resampling can be CPU intensive and
+    therefore by default this option is not enabled. *METHOD* specifies which
+    libsamplerate converter to use, and may be one of 6 values:
+
+    - **best** - use the SRC_SINC_BEST_QUALITY converter; generates the highest
+      quality output but also has very high CPU usage.
+
+    - **medium** - use the SRC_SINC_MEDIUM_QUALITY converter; generates high
+      quality output and has moderately high CPU usage.
+
+    - **fastest** - use the SRC_SINC_FASTEST converter; generates good quality
+      output with lower CPU usage than the other SINC based converters. Often
+      this converter is the best compromise for Bluetooth audio.
+
+    - **zero-hold** - use the SRC_ZERO_ORDER_HOLD converter; the audio quality
+      is relatively poor compared to the SINC converters, but CPU usage is very
+      low so may be better suited to very low power embedded processors.
+
+    - **linear** - use the SRC_LINEAR converter; the lowest quality converter
+      of libsamplerate. Output quality is similar to the ALSA rate plugin's own
+      internal linear converter, but this option also performs adaptive
+      resampling which is not possible with the ALSA rate plugin.
+
+    - **none** - do not perform any resampling; the ALSA PCM device is then
+      responsible for rate conversion, and no timer drift adjustment is made.
+      This is the default when no resampler is specified.
+
 --single-audio
     Allow only one Bluetooth device to play audio at a time.
     If multiple devices are connected, only the first to start will play, the
@@ -236,10 +270,10 @@ The ALSA **dmix** plugin will ignore the period and buffer times selected by
 the application (because it has to allow connections from multiple
 applications). Instead it will choose its own values, which can lead to
 rounding errors in the period size calculation when used with the ALSA **rate**
-plugin. To avoid this, it is recommended to explicitly define the hardware
-period size and buffer size for **dmix** in your ALSA configuration. For
-example, suppose we want a period time of 50000 µs and a buffer holding 4
-periods with an Intel 'PCH' card:
+plugin (but not when using the *--resampler=* option). To avoid this, it is
+recommended to explicitly define the hardware period size and buffer size for
+**dmix** in your ALSA configuration. For example, suppose we want a period time
+of 50000 µs and a buffer holding 4 periods with an Intel 'PCH' card:
 
 ::
 
@@ -308,7 +342,7 @@ element will be used as a hardware volume control knob.
 COPYRIGHT
 =========
 
-Copyright (c) 2016-2024 Arkadiusz Bokowy.
+Copyright (c) 2016-2025 Arkadiusz Bokowy.
 
 The bluez-alsa project is licensed under the terms of the MIT license.
 

misc/bash-completion/bluealsad

@@ -265,7 +265,7 @@ _bluealsa_aplay() {
 			__ltrim_colon_completions "$cur"
 			return
 			;;
-		--loglevel|--volume)
+		--loglevel|--resampler|--volume)
 			readarray -t list < <(_bluealsa_enum_values "$1" "$prev")
 			readarray -t COMPREPLY < <(compgen -W "${list[*]}" -- "$cur")
 			return

test/test-utils-aplay.c

@@ -276,7 +276,7 @@ CK_START_TEST(test_play_dbus_signals) {
 				NULL), -1);
 	spawn_terminate(&sp_ba_aplay, 1500);
 
-	char output[8192] = "";
+	char output[16384] = "";
 	ck_assert_int_gt(spawn_read(&sp_ba_aplay, NULL, 0, output, sizeof(output)), 0);
 
 #if ENABLE_HFP_CODEC_SELECTION && DEBUG

utils/aplay/Makefile.am

@@ -19,17 +19,24 @@ bluealsa_aplay_SOURCES = \
 	delay-report.c \
 	aplay.c
 
+if ENABLE_APLAY_RESAMPLER
+bluealsa_aplay_SOURCES += \
+	resampler.c
+endif
+
 bluealsa_aplay_CFLAGS = \
 	-I$(top_srcdir)/src \
 	@ALSA_CFLAGS@ \
 	@BLUEZ_CFLAGS@ \
 	@DBUS1_CFLAGS@ \
-	@LIBUNWIND_CFLAGS@
+	@LIBUNWIND_CFLAGS@ \
+	@SAMPLERATE_CFLAGS@
 
 bluealsa_aplay_LDADD = \
 	@ALSA_LIBS@ \
 	@BLUEZ_LIBS@ \
 	@DBUS1_LIBS@ \
-	@LIBUNWIND_LIBS@
+	@LIBUNWIND_LIBS@ \
+	@SAMPLERATE_LIBS@
 
 endif

utils/aplay/alsa-pcm.c

@@ -10,16 +10,20 @@
 
 #include "alsa-pcm.h"
 
+#include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
 #include "shared/log.h"
 
-static int alsa_pcm_set_hw_params(snd_pcm_t *pcm, snd_pcm_format_t format, int channels,
-		int rate, unsigned int *buffer_time, unsigned int *period_time, char **msg) {
+static int alsa_pcm_set_hw_params(snd_pcm_t *pcm, snd_pcm_format_t format_1,
+		snd_pcm_format_t format_2, snd_pcm_format_t *selected_format,
+		int channels, unsigned int *rate, bool exact_rate,
+		unsigned int *buffer_time, unsigned int *period_time, char **msg) {
 
 	const snd_pcm_access_t access = SND_PCM_ACCESS_RW_INTERLEAVED;
+	snd_pcm_format_t format = SND_PCM_FORMAT_UNKNOWN;
 	snd_pcm_hw_params_t *params;
 	char buf[256];
 	int dir;
@@ -37,18 +41,36 @@ static int alsa_pcm_set_hw_params(snd_pcm_t *pcm, snd_pcm_format_t format, int c
 		goto fail;
 	}
 
-	if ((err = snd_pcm_hw_params_set_format(pcm, params, format)) != 0) {
-		snprintf(buf, sizeof(buf), "Set format: %s: %s", snd_strerror(err), snd_pcm_format_name(format));
+	/* Prefer format_1 if supported by the device. */
+	if ((err = snd_pcm_hw_params_set_format(pcm, params, format_1)) == 0)
+		format = format_1;
+	/* Otherwise try format 2 */
+	else if (format_2 != SND_PCM_FORMAT_UNKNOWN) {
+		if ((err = snd_pcm_hw_params_set_format(pcm, params, format_2)) == 0)
+			format = format_2;
+		else {
+			snprintf(buf, sizeof(buf), "Set format: %s: %s and %s", snd_strerror(err), snd_pcm_format_name(format_1), snd_pcm_format_name(format_2));
+			goto fail;
+		}
+	}
+	else {
+		snprintf(buf, sizeof(buf), "Set format: %s: %s", snd_strerror(err), snd_pcm_format_name(format_1));
 		goto fail;
 	}
+	*selected_format = format;
 
 	if ((err = snd_pcm_hw_params_set_channels(pcm, params, channels)) != 0) {
 		snprintf(buf, sizeof(buf), "Set channels: %s: %d", snd_strerror(err), channels);
 		goto fail;
 	}
 
-	if ((err = snd_pcm_hw_params_set_rate(pcm, params, rate, 0)) != 0) {
-		snprintf(buf, sizeof(buf), "Set sample rate: %s: %d", snd_strerror(err), rate);
+	dir = 0;
+	if (exact_rate)
+		err = snd_pcm_hw_params_set_rate(pcm, params, *rate, dir);
+	else
+		err = snd_pcm_hw_params_set_rate_near(pcm, params, rate, &dir);
+	if (err != 0) {
+		snprintf(buf, sizeof(buf), "Set sample rate: %s: %u", snd_strerror(err), *rate);
 		goto fail;
 	}
 
@@ -72,43 +94,36 @@ static int alsa_pcm_set_hw_params(snd_pcm_t *pcm, snd_pcm_format_t format, int c
 	return 0;
 
 fail:
+	*selected_format = format;
 	if (msg != NULL)
 		*msg = strdup(buf);
 	return err;
 }
 
-static int alsa_pcm_set_sw_params(struct alsa_pcm *pcm, snd_pcm_uframes_t buffer_size,
-		snd_pcm_uframes_t period_size, char **msg) {
+static int alsa_pcm_set_sw_params(snd_pcm_t *pcm,
+		snd_pcm_uframes_t start_threshold, char **msg) {
 
-	snd_pcm_t *snd_pcm = pcm->handle;
 	snd_pcm_sw_params_t *params;
 	char buf[256];
 	int err;
 
 	snd_pcm_sw_params_alloca(&params);
 
-	if ((err = snd_pcm_sw_params_current(snd_pcm, params)) != 0) {
-		snprintf(buf, sizeof(buf), "Get current params: %s", snd_strerror(err));
+	if ((err = snd_pcm_sw_params_current(pcm, params)) != 0) {
+		snprintf(buf, sizeof(buf), "Get current sw params: %s", snd_strerror(err));
 		goto fail;
 	}
 
-	/* Start the transfer when three periods have been written (or when the
-	 * buffer is full if it holds less than three periods. */
-	snd_pcm_uframes_t threshold = period_size * 3;
-	if (threshold > buffer_size)
-		threshold = buffer_size;
-	if ((err = snd_pcm_sw_params_set_start_threshold(snd_pcm, params, threshold)) != 0) {
-		snprintf(buf, sizeof(buf), "Set start threshold: %s: %lu", snd_strerror(err), threshold);
+	if ((err = snd_pcm_sw_params_set_start_threshold(pcm, params, start_threshold)) != 0) {
+		snprintf(buf, sizeof(buf), "Set start threshold: %s: %lu", snd_strerror(err), start_threshold);
 		goto fail;
 	}
 
-	if ((err = snd_pcm_sw_params(snd_pcm, params)) != 0) {
-		snprintf(buf, sizeof(buf), "%s", snd_strerror(err));
+	if ((err = snd_pcm_sw_params(pcm, params)) != 0) {
+		snprintf(buf, sizeof(buf), "Set sw params: %s", snd_strerror(err));
 		goto fail;
 	}
 
-	pcm->start_threshold = threshold;
-
 	return 0;
 
 fail:
@@ -123,18 +138,19 @@ void alsa_pcm_init(struct alsa_pcm *pcm) {
 }
 
 int alsa_pcm_open(
-		struct alsa_pcm *pcm,
-		const char *name,
-		snd_pcm_format_t format,
-		int channels,
-		unsigned int rate,
-		unsigned int buffer_time,
-		unsigned int period_time,
-		int flags,
-		char **msg) {
+		struct alsa_pcm *pcm, const char *name,
+		snd_pcm_format_t format_1, snd_pcm_format_t format_2,
+		int channels, unsigned int rate,
+		unsigned int buffer_time, unsigned int period_time,
+		int flags, char **msg) {
 
 	char *tmp = NULL;
 	char buf[256];
+	unsigned int actual_buffer_time = buffer_time;
+	unsigned int actual_period_time = period_time;
+	snd_pcm_format_t actual_format = SND_PCM_FORMAT_UNKNOWN;
+	unsigned int actual_rate = rate;
+	const bool exact_rate = !(flags & SND_PCM_NO_AUTO_RESAMPLE);
 	int err;
 
 	assert (pcm->handle == NULL);
@@ -144,21 +160,28 @@ int alsa_pcm_open(
 		goto fail;
 	}
 
-	unsigned int actual_buffer_time = buffer_time;
-	unsigned int actual_period_time = period_time;
-	if ((err = alsa_pcm_set_hw_params(pcm->handle, format, channels, rate,
+	pcm->format = actual_format;
+	if ((err = alsa_pcm_set_hw_params(pcm->handle, format_1, format_2,
+				&actual_format, channels, &actual_rate, exact_rate,
 				&actual_buffer_time, &actual_period_time, &tmp)) != 0) {
 		snprintf(buf, sizeof(buf), "Set HW params: %s", tmp);
 		goto fail;
 	}
+	pcm->format = actual_format;
 
 	snd_pcm_uframes_t buffer_size, period_size;
 	if ((err = snd_pcm_get_params(pcm->handle, &buffer_size, &period_size)) != 0) {
 		snprintf(buf, sizeof(buf), "Get params: %s", snd_strerror(err));
 		goto fail;
 	}
 
-	if ((err = alsa_pcm_set_sw_params(pcm, buffer_size, period_size, &tmp)) != 0) {
+	/* Start the transfer when three requested periods have been written (or
+	 * when the buffer is full if it holds less than three requested periods. */
+	snd_pcm_uframes_t start_threshold = (period_time * 3 / 1000) * (rate / 1000);
+	if (start_threshold > buffer_size)
+		start_threshold = buffer_size;
+
+	if ((err = alsa_pcm_set_sw_params(pcm->handle, start_threshold, &tmp)) != 0) {
 		snprintf(buf, sizeof(buf), "Set SW params: %s", tmp);
 		goto fail;
 	}
@@ -168,15 +191,15 @@ int alsa_pcm_open(
 		goto fail;
 	}
 
-	pcm->format = format;
 	pcm->channels = channels;
-	pcm->sample_size = snd_pcm_format_size(format, 1);
-	pcm->frame_size = snd_pcm_format_size(format, channels);
-	pcm->rate = rate;
+	pcm->sample_size = snd_pcm_format_size(actual_format, 1);
+	pcm->frame_size = snd_pcm_format_size(actual_format, channels);
+	pcm->rate = actual_rate;
 	pcm->buffer_time = actual_buffer_time;
 	pcm->period_time = actual_period_time;
 	pcm->buffer_frames = buffer_size;
 	pcm->period_frames = period_size;
+	pcm->start_threshold = start_threshold;
 	pcm->delay = 0;
 
 	/* Maintain buffer fill level above 1 period plus 2ms to allow for
@@ -205,7 +228,7 @@ int alsa_pcm_write(struct alsa_pcm *pcm, ffb_t *buffer, bool drain, bool verbose
 	pcm->underrun = false;
 	if ((ret = snd_pcm_avail_delay(pcm->handle, &avail, &delay)) < 0) {
 		if (ret == -EPIPE) {
-			debug("ALSA playback PCM underrun");
+			warn("ALSA playback PCM underrun");
 			pcm->underrun = true;
 			snd_pcm_prepare(pcm->handle);
 			avail = pcm->buffer_frames;
@@ -221,7 +244,7 @@ int alsa_pcm_write(struct alsa_pcm *pcm, ffb_t *buffer, bool drain, bool verbose
 	snd_pcm_sframes_t written_frames = 0;
 
 	/* If not draining, write only as many frames as possible without blocking.
-	 * If necessary insert silemce frames to prevent underrun. */
+	 * If necessary insert silence frames to prevent underrun. */
 	if (!drain) {
 		if (frames > avail)
 			frames = avail;
@@ -234,7 +257,10 @@ int alsa_pcm_write(struct alsa_pcm *pcm, ffb_t *buffer, bool drain, bool verbose
 				info("Underrun imminent: inserting %zu silence frames", padding / pcm->channels);
 			snd_pcm_format_set_silence(pcm->format, buffer->tail, padding);
 			ffb_seek(buffer, padding);
-			frames += padding;
+			frames = ffb_len_out(buffer) / pcm->channels;
+			/* Flag an underrun to indicate that we have caused a discontinuity
+			 * in the input stream. */
+			pcm->underrun = true;
 		}
 	}
 
@@ -245,7 +271,7 @@ int alsa_pcm_write(struct alsa_pcm *pcm, ffb_t *buffer, bool drain, bool verbose
 			case EINTR:
 				continue;
 			case EPIPE:
-				debug("ALSA playback PCM underrun");
+				warn("ALSA playback PCM underrun");
 				pcm->underrun = true;
 				snd_pcm_prepare(pcm->handle);
 				continue;