audio: a fresh AAudio sink module for the daemon, built from upstream PulseAudio 13 headers

Blocking-write design: the IO thread pulls one burst at a time from the sink and hands it to a
blocking AAudio output stream, whose buffer paces the thread; latency comes from the stream's
playback timestamp; with adaptive=1 the buffer grows a burst per underrun up to a cap. Same
module arguments as before, so the daemon's config line is unchanged. build.sh compiles it with
the NDK against the app's own libpulse* and a small config.h; a workflow checks it on every push.
This commit is contained in:
The412Banner committed 2026-09-23 09:12:15 -04:00
1 parent c232274157
commit 32178e6e4a
5 files changed
+561

No files matched your search

+31
View File
@@ -0,0 +1,31 @@
name: Build AAudio sink module
# A quick check of tools/aaudio-sink on its own; the APK build compiles the same module into the
# audio bundle. Runs on pushes that touch the module.
on:
push:
paths:
- 'tools/aaudio-sink/**'
- '.github/workflows/build-aaudio-sink.yml'
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-24.04
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- name: PulseAudio 13.0 source
run: |
set -euo pipefail
curl -fsSL -o pa.tar.gz https://github.com/pulseaudio/pulseaudio/archive/refs/tags/v13.0.tar.gz
mkdir -p pa13 && tar -xzf pa.tar.gz -C pa13 --strip-components=1
- name: Build
run: |
set -euo pipefail
export NDK="${ANDROID_NDK_LATEST_HOME:-${ANDROID_NDK_HOME:-$ANDROID_NDK_ROOT}}"
tools/aaudio-sink/build.sh "$PWD/pa13" "$PWD/module-aaudio-sink.so"
- uses: actions/upload-artifact@v4
with:
name: module-aaudio-sink
path: module-aaudio-sink.so
+38
View File
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
# Compiles module-aaudio-sink.so against the upstream PulseAudio 13.0 headers and the daemon's own
# libraries the app ships (app/src/main/jniLibs/arm64-v8a), with the Android NDK.
# NDK=<ndk root> tools/aaudio-sink/build.sh <pulseaudio-13.0 source dir> <output .so>
set -euo pipefail
PA_SRC=$1
OUT=$2
: "${NDK:?set NDK to the Android NDK root}"
API=26
HERE=$(cd "$(dirname "$0")" && pwd)
REPO=$(cd "$HERE/../.." && pwd)
LIBS="$REPO/app/src/main/jniLibs/arm64-v8a"
TOOLCHAIN="$NDK/toolchains/llvm/prebuilt/linux-x86_64/bin"
CC="$TOOLCHAIN/aarch64-linux-android${API}-clang"
test -x "$CC"
test -f "$PA_SRC/src/pulse/version.h.in"
INC=$(mktemp -d)
mkdir -p "$INC/pulse"
sed -e 's/@PA_MAJOR@/13/g' -e 's/@PA_MINOR@/0/g' -e 's/@PA_API_VERSION@/12/g' -e 's/@PA_PROTOCOL_VERSION@/33/g' \
"$PA_SRC/src/pulse/version.h.in" > "$INC/pulse/version.h"
cp "$HERE/config.h" "$HERE/ltdl.h" "$INC/"
"$CC" -O2 -shared -fPIC -Wall -Wno-unused-parameter -DHAVE_CONFIG_H \
-I"$INC" -I"$PA_SRC/src" \
-o "$OUT" "$HERE/module-aaudio-sink.c" \
-L"$LIBS" -l:libpulsecore-13.0.so -l:libpulsecommon-13.0.so -l:libpulse.so -laaudio
"$TOOLCHAIN/llvm-strip" --strip-unneeded "$OUT"
# What the daemon looks for, and nothing linked that a device would not have.
for sym in pa__init pa__done pa__get_author pa__get_description pa__get_usage pa__get_version pa__load_once; do
"$TOOLCHAIN/llvm-nm" -D --defined-only "$OUT" | grep -q " $sym$" || { echo "ERROR: $OUT does not export $sym"; exit 1; }
done
NEEDED=$("$TOOLCHAIN/llvm-readelf" -d "$OUT" | sed -n 's/.*NEEDED.*\[\(.*\)\]/\1/p' | tr '\n' ' ')
echo "NEEDED: $NEEDED"
for lib in $NEEDED; do
case $lib in libpulsecore-13.0.so|libpulsecommon-13.0.so|libpulse.so|libaaudio.so|libc.so|libm.so|libdl.so) ;;
*) echo "ERROR: unexpected dependency $lib"; exit 1 ;;
esac
done
ls -l "$OUT"
+15
View File
@@ -0,0 +1,15 @@
/* The handful of build-time facts PulseAudio 13's headers read, for compiling one module against
* the upstream source tree without running its configure. The daemon and libraries the app ships
* were built for the same target (Android arm64, bionic), so these match them. */
#ifndef STEAMDECK_PA_CONFIG_H
#define STEAMDECK_PA_CONFIG_H
#define PACKAGE "pulseaudio"
#define PACKAGE_NAME "pulseaudio"
#define PACKAGE_VERSION "13.0"
#define HAVE_ATOMIC_BUILTINS 1
#define HAVE_ATOMIC_BUILTINS_MEMORY_MODEL 1
#define HAVE_CLOCK_GETTIME 1
#define HAVE_FAST_64BIT_OPERATIONS 1
#define HAVE_SYS_RESOURCE_H 1
#define HAVE_MEMFD 1
#endif
+6
View File
@@ -0,0 +1,6 @@
/* pulsecore/module.h keeps a libltdl handle in pa_module; the module never touches it, so the
* handle type is all that is needed here. */
#ifndef STEAMDECK_LTDL_STUB_H
#define STEAMDECK_LTDL_STUB_H
typedef void *lt_dlhandle;
#endif
+471
View File
@@ -0,0 +1,471 @@
/*
* module-aaudio-sink: a PulseAudio 13 sink on Android's AAudio, for the SteamDeck app.
*
* The daemon's IO thread pulls rendered audio from the sink one burst at a time and hands it to
* a blocking AAudio output stream; the stream's own buffer paces the thread, and the latency the
* sink reports comes from the stream's playback timestamp. With adaptive=1 the buffer grows by a
* burst after each underrun, up to a cap, so a device that cannot keep a small buffer fed settles
* on one it can.
*
* Module arguments keep the names the app has always passed (performance_mode, adaptive, volume,
* buffer_frames, max_buffer_frames) so the daemon's config line did not have to change.
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
#include <errno.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <aaudio/AAudio.h>
#include <pulse/rtclock.h>
#include <pulse/timeval.h>
#include <pulse/util.h>
#include <pulse/xmalloc.h>
#include <pulsecore/core-util.h>
#include <pulsecore/log.h>
#include <pulsecore/macro.h>
#include <pulsecore/modargs.h>
#include <pulsecore/module.h>
#include <pulsecore/rtpoll.h>
#include <pulsecore/sink.h>
#include <pulsecore/thread-mq.h>
#include <pulsecore/thread.h>
PA_MODULE_AUTHOR("The412Banner");
PA_MODULE_DESCRIPTION("Android AAudio output");
PA_MODULE_VERSION(PACKAGE_VERSION);
PA_MODULE_LOAD_ONCE(false);
PA_MODULE_USAGE(
"sink_name=<name for the sink> "
"sink_properties=<properties for the sink> "
"format=<sample format> "
"rate=<sample rate> "
"channels=<number of channels> "
"channel_map=<channel map> "
"volume=<initial volume, linear, 1.0 = full> "
"performance_mode=<0 none, 1 low latency, 2 power saving> "
"adaptive=<grow the buffer after underruns: 0 or 1> "
"buffer_frames=<initial buffer size in frames, 0 = two bursts> "
"max_buffer_frames=<largest the buffer may grow to, 0 = the stream's capacity>");
#define DEFAULT_SINK_NAME "aaudio_output"
/* A write that blocks longer than this has lost the device underneath it. */
#define WRITE_TIMEOUT_NS (500LL * 1000 * 1000)
/* Underruns are polled every so many writes, not every write. */
#define XRUN_CHECK_EVERY 16
#define FALLBACK_BURST_FRAMES 192
static const char* const valid_modargs[] = {
"sink_name",
"sink_properties",
"format",
"rate",
"channels",
"channel_map",
"volume",
"performance_mode",
"adaptive",
"buffer_frames",
"max_buffer_frames",
NULL
};
struct userdata {
pa_core *core;
pa_module *module;
pa_sink *sink;
pa_thread *thread;
pa_thread_mq thread_mq;
pa_rtpoll *rtpoll;
pa_sample_spec ss;
size_t frame_size;
size_t chunk_bytes;
aaudio_performance_mode_t performance_mode;
AAudioStream *stream;
bool started;
int32_t burst_frames;
int32_t buffer_frames;
int32_t max_buffer_frames;
int32_t requested_buffer_frames;
bool adaptive;
int32_t xruns_seen;
unsigned writes_since_xrun_check;
};
static pa_usec_t frames_to_usec(const struct userdata *u, int64_t frames) {
return (pa_usec_t) (frames * (int64_t) PA_USEC_PER_SEC / (int64_t) u->ss.rate);
}
static void close_stream(struct userdata *u) {
if (!u->stream)
return;
if (u->started)
AAudioStream_requestStop(u->stream);
AAudioStream_close(u->stream);
u->stream = NULL;
u->started = false;
}
static void apply_buffer_size(struct userdata *u, int32_t frames) {
int32_t got;
if (frames < u->burst_frames)
frames = u->burst_frames;
if (u->max_buffer_frames > 0 && frames > u->max_buffer_frames)
frames = u->max_buffer_frames;
got = AAudioStream_setBufferSizeInFrames(u->stream, frames);
u->buffer_frames = got > 0 ? got : AAudioStream_getBufferSizeInFrames(u->stream);
}
/* Opens the stream for u->ss; on return u->ss holds what the device actually gave. */
static int open_stream(struct userdata *u) {
AAudioStreamBuilder *builder = NULL;
aaudio_result_t r;
int32_t capacity;
if ((r = AAudio_createStreamBuilder(&builder)) != AAUDIO_OK) {
pa_log("AAudio_createStreamBuilder: %s", AAudio_convertResultToText(r));
return -1;
}
AAudioStreamBuilder_setDirection(builder, AAUDIO_DIRECTION_OUTPUT);
AAudioStreamBuilder_setSharingMode(builder, AAUDIO_SHARING_MODE_SHARED);
AAudioStreamBuilder_setPerformanceMode(builder, u->performance_mode);
AAudioStreamBuilder_setFormat(builder, u->ss.format == PA_SAMPLE_FLOAT32NE ? AAUDIO_FORMAT_PCM_FLOAT : AAUDIO_FORMAT_PCM_I16);
AAudioStreamBuilder_setSampleRate(builder, (int32_t) u->ss.rate);
AAudioStreamBuilder_setChannelCount(builder, (int32_t) u->ss.channels);
r = AAudioStreamBuilder_openStream(builder, &u->stream);
AAudioStreamBuilder_delete(builder);
if (r != AAUDIO_OK) {
pa_log("AAudioStreamBuilder_openStream: %s", AAudio_convertResultToText(r));
u->stream = NULL;
return -1;
}
u->ss.rate = (uint32_t) AAudioStream_getSampleRate(u->stream);
u->ss.channels = (uint8_t) AAudioStream_getChannelCount(u->stream);
u->ss.format = AAudioStream_getFormat(u->stream) == AAUDIO_FORMAT_PCM_FLOAT ? PA_SAMPLE_FLOAT32NE : PA_SAMPLE_S16NE;
u->frame_size = pa_frame_size(&u->ss);
u->burst_frames = AAudioStream_getFramesPerBurst(u->stream);
if (u->burst_frames <= 0)
u->burst_frames = FALLBACK_BURST_FRAMES;
u->chunk_bytes = (size_t) u->burst_frames * u->frame_size;
capacity = AAudioStream_getBufferCapacityInFrames(u->stream);
if (u->max_buffer_frames <= 0 || (capacity > 0 && u->max_buffer_frames > capacity))
u->max_buffer_frames = capacity;
apply_buffer_size(u, u->requested_buffer_frames > 0 ? u->requested_buffer_frames : 2 * u->burst_frames);
u->xruns_seen = AAudioStream_getXRunCount(u->stream);
pa_log_info("stream open: %u Hz, %u ch, %s, burst %d frames, buffer %d of %d frames, performance mode %d",
u->ss.rate, u->ss.channels, pa_sample_format_to_string(u->ss.format),
u->burst_frames, u->buffer_frames, u->max_buffer_frames, (int) u->performance_mode);
return 0;
}
static int start_stream(struct userdata *u) {
aaudio_result_t r;
if (u->started)
return 0;
if ((r = AAudioStream_requestStart(u->stream)) != AAUDIO_OK) {
pa_log("AAudioStream_requestStart: %s", AAudio_convertResultToText(r));
return -1;
}
u->started = true;
return 0;
}
static void stop_stream(struct userdata *u) {
if (!u->started)
return;
AAudioStream_requestStop(u->stream);
u->started = false;
}
/* How much audio the device still holds: frames written less frames it reports played. */
static pa_usec_t stream_latency(struct userdata *u) {
int64_t position = 0, when_ns = 0;
if (u->stream && u->started && AAudioStream_getTimestamp(u->stream, CLOCK_MONOTONIC, &position, &when_ns) == AAUDIO_OK) {
struct timespec now;
int64_t now_ns, played, pending;
clock_gettime(CLOCK_MONOTONIC, &now);
now_ns = (int64_t) now.tv_sec * 1000000000LL + now.tv_nsec;
played = position + (now_ns - when_ns) * (int64_t) u->ss.rate / 1000000000LL;
pending = AAudioStream_getFramesWritten(u->stream) - played;
if (pending < 0)
pending = 0;
return frames_to_usec(u, pending);
}
return frames_to_usec(u, u->buffer_frames);
}
static void check_underruns(struct userdata *u) {
int32_t xruns;
if (++u->writes_since_xrun_check < XRUN_CHECK_EVERY)
return;
u->writes_since_xrun_check = 0;
xruns = AAudioStream_getXRunCount(u->stream);
if (xruns <= u->xruns_seen)
return;
u->xruns_seen = xruns;
if (!u->adaptive || u->buffer_frames >= u->max_buffer_frames)
return;
apply_buffer_size(u, u->buffer_frames + u->burst_frames);
pa_sink_set_fixed_latency_within_thread(u->sink, frames_to_usec(u, u->buffer_frames));
pa_log_info("underrun %d: buffer now %d frames", xruns, u->buffer_frames);
}
/* One burst from the sink into the device. Returns <0 when the stream is gone for good. */
static int write_one_burst(struct userdata *u) {
pa_memchunk chunk;
const void *data;
aaudio_result_t written;
pa_sink_render_full(u->sink, u->chunk_bytes, &chunk);
data = pa_memblock_acquire_chunk(&chunk);
written = AAudioStream_write(u->stream, data, (int32_t) (chunk.length / u->frame_size), WRITE_TIMEOUT_NS);
pa_memblock_release(chunk.memblock);
pa_memblock_unref(chunk.memblock);
if (written >= 0) {
check_underruns(u);
return 0;
}
/* The device went away (headphones, a route change). Reopen once with the same settings; if
* the new stream differs in rate or format there is nothing sane to do but give up. */
pa_log_warn("AAudioStream_write: %s; reopening the stream", AAudio_convertResultToText(written));
{
pa_sample_spec before = u->ss;
close_stream(u);
if (open_stream(u) < 0)
return -1;
if (!pa_sample_spec_equal(&before, &u->ss)) {
pa_log("the reopened stream changed format; unloading");
return -1;
}
if (start_stream(u) < 0)
return -1;
}
return 0;
}
static int sink_process_msg(pa_msgobject *o, int code, void *data, int64_t offset, pa_memchunk *chunk) {
struct userdata *u = PA_SINK(o)->userdata;
switch (code) {
case PA_SINK_MESSAGE_GET_LATENCY:
*((pa_usec_t*) data) = stream_latency(u);
return 0;
}
return pa_sink_process_msg(o, code, data, offset, chunk);
}
/* Runs in the IO thread: an opened sink means a running stream and a busy loop; a suspended
* one means a stopped stream and a thread asleep until a message arrives. */
static int sink_set_state_in_io_thread_cb(pa_sink *s, pa_sink_state_t new_state, pa_suspend_cause_t new_suspend_cause) {
struct userdata *u = s->userdata;
if (PA_SINK_IS_OPENED(new_state)) {
if (start_stream(u) < 0)
return -1;
pa_rtpoll_set_timer_relative(u->rtpoll, 0);
} else if (new_state == PA_SINK_SUSPENDED) {
stop_stream(u);
pa_rtpoll_set_timer_disabled(u->rtpoll);
}
return 0;
}
static void thread_func(void *userdata) {
struct userdata *u = userdata;
pa_log_debug("IO thread starting");
pa_thread_mq_install(&u->thread_mq);
for (;;) {
int ret;
if (PA_SINK_IS_OPENED(u->sink->thread_info.state) && u->started) {
if (write_one_burst(u) < 0)
goto fail;
}
/* With the timer at zero this only drains the message queue; with it disabled (the sink
* suspended) it blocks until something arrives. */
if ((ret = pa_rtpoll_run(u->rtpoll)) < 0)
goto fail;
if (ret == 0)
goto finish;
}
fail:
pa_asyncmsgq_post(u->thread_mq.outq, PA_MSGOBJECT(u->core), PA_CORE_MESSAGE_UNLOAD_MODULE, u->module, 0, NULL, NULL);
pa_asyncmsgq_wait_for(u->thread_mq.inq, PA_MESSAGE_SHUTDOWN);
finish:
pa_log_debug("IO thread shutting down");
}
int pa__init(pa_module *m) {
struct userdata *u = NULL;
pa_modargs *ma = NULL;
pa_sink_new_data data;
pa_sample_spec ss;
pa_channel_map map;
pa_cvolume volume;
uint32_t performance_mode = 1, buffer_frames = 0, max_buffer_frames = 0;
double linear_volume = 1.0;
bool adaptive = true;
pa_assert(m);
if (!(ma = pa_modargs_new(m->argument, valid_modargs))) {
pa_log("Failed to parse module arguments.");
goto fail;
}
ss = m->core->default_sample_spec;
map = m->core->default_channel_map;
if (pa_modargs_get_sample_spec_and_channel_map(ma, &ss, &map, PA_CHANNEL_MAP_DEFAULT) < 0) {
pa_log("Invalid sample format specification or channel map");
goto fail;
}
/* AAudio speaks 16-bit or float; anything else is rendered as 16-bit. */
if (ss.format != PA_SAMPLE_FLOAT32NE)
ss.format = PA_SAMPLE_S16NE;
if (pa_modargs_get_value_u32(ma, "performance_mode", &performance_mode) < 0 || performance_mode > 2) {
pa_log("performance_mode must be 0, 1 or 2");
goto fail;
}
if (pa_modargs_get_value_boolean(ma, "adaptive", &adaptive) < 0) {
pa_log("adaptive must be 0 or 1");
goto fail;
}
if (pa_modargs_get_value_u32(ma, "buffer_frames", &buffer_frames) < 0 ||
pa_modargs_get_value_u32(ma, "max_buffer_frames", &max_buffer_frames) < 0) {
pa_log("buffer_frames and max_buffer_frames must be whole numbers");
goto fail;
}
if (pa_modargs_get_value_double(ma, "volume", &linear_volume) < 0 || linear_volume < 0.0 || linear_volume > 10.0) {
pa_log("volume must be a linear factor between 0 and 10");
goto fail;
}
m->userdata = u = pa_xnew0(struct userdata, 1);
u->core = m->core;
u->module = m;
u->ss = ss;
u->performance_mode = performance_mode == 0 ? AAUDIO_PERFORMANCE_MODE_NONE
: performance_mode == 2 ? AAUDIO_PERFORMANCE_MODE_POWER_SAVING
: AAUDIO_PERFORMANCE_MODE_LOW_LATENCY;
u->adaptive = adaptive;
u->requested_buffer_frames = (int32_t) buffer_frames;
u->max_buffer_frames = (int32_t) max_buffer_frames;
u->rtpoll = pa_rtpoll_new();
if (pa_thread_mq_init(&u->thread_mq, m->core->mainloop, u->rtpoll) < 0) {
pa_log("pa_thread_mq_init() failed.");
goto fail;
}
if (open_stream(u) < 0)
goto fail;
if (u->ss.channels != ss.channels)
pa_channel_map_init_auto(&map, u->ss.channels, PA_CHANNEL_MAP_DEFAULT);
pa_sink_new_data_init(&data);
data.driver = __FILE__;
data.module = m;
pa_sink_new_data_set_name(&data, pa_modargs_get_value(ma, "sink_name", DEFAULT_SINK_NAME));
pa_sink_new_data_set_sample_spec(&data, &u->ss);
pa_sink_new_data_set_channel_map(&data, &map);
pa_cvolume_set(&volume, u->ss.channels, pa_sw_volume_from_linear(linear_volume));
pa_sink_new_data_set_volume(&data, &volume);
pa_proplist_sets(data.proplist, PA_PROP_DEVICE_STRING, "aaudio");
pa_proplist_sets(data.proplist, PA_PROP_DEVICE_DESCRIPTION, "Android audio output");
pa_proplist_sets(data.proplist, PA_PROP_DEVICE_CLASS, "sound");
pa_proplist_sets(data.proplist, PA_PROP_DEVICE_API, "aaudio");
if (pa_modargs_get_proplist(ma, "sink_properties", data.proplist, PA_UPDATE_REPLACE) < 0) {
pa_log("Invalid properties");
pa_sink_new_data_done(&data);
goto fail;
}
u->sink = pa_sink_new(m->core, &data, PA_SINK_HARDWARE | PA_SINK_LATENCY);
pa_sink_new_data_done(&data);
if (!u->sink) {
pa_log("Failed to create sink.");
goto fail;
}
u->sink->parent.process_msg = sink_process_msg;
u->sink->set_state_in_io_thread = sink_set_state_in_io_thread_cb;
u->sink->userdata = u;
pa_sink_set_asyncmsgq(u->sink, u->thread_mq.inq);
pa_sink_set_rtpoll(u->sink, u->rtpoll);
pa_sink_set_max_request(u->sink, u->chunk_bytes);
pa_sink_set_fixed_latency(u->sink, frames_to_usec(u, u->buffer_frames));
if (!(u->thread = pa_thread_new("aaudio-sink", thread_func, u))) {
pa_log("Failed to create thread.");
goto fail;
}
pa_sink_put(u->sink);
pa_modargs_free(ma);
return 0;
fail:
if (ma)
pa_modargs_free(ma);
pa__done(m);
return -1;
}
int pa__get_n_used(pa_module *m) {
struct userdata *u;
pa_assert(m);
pa_assert_se(u = m->userdata);
return pa_sink_linked_by(u->sink);
}
void pa__done(pa_module *m) {
struct userdata *u;
pa_assert(m);
if (!(u = m->userdata))
return;
if (u->sink)
pa_sink_unlink(u->sink);
if (u->thread) {
pa_asyncmsgq_send(u->thread_mq.inq, NULL, PA_MESSAGE_SHUTDOWN, NULL, 0, NULL);
pa_thread_free(u->thread);
}
pa_thread_mq_done(&u->thread_mq);
if (u->sink)
pa_sink_unref(u->sink);
close_stream(u);
if (u->rtpoll)
pa_rtpoll_free(u->rtpoll);
pa_xfree(u);
}