Extend Local Audio Out provider with PulseAudio support by iVolt1 · Pull Request #3724 · music-assistant/server

iVolt1 · 2026-04-17T21:44:17Z

Extend Local Audio Out provider with PulseAudio support

Note to reviewers: This PR supersedes #3683 which proposed a separate pulse_audio provider. Based on feedback from that review, this PR instead extends the existing local_audio provider to support PulseAudio on Linux. Key changes addressing the review comments:

pulseaudio-utils added to Dockerfile.base: Added as a standard apt dependency alongside existing runtime packages — a single line addition rather than a separate build stage

Bundled pactl binary: Still included in the provider bin/ directory to facilitate testing with the MA DEV SERVER app, which does not build from the modified Dockerfile.base. This will be removed in a follow-up PR once validated against MA Nightly

PulseAudio output via libpulse-simple: As suggested, pa_simple.py uses libpulse-simple directly via ctypes rather than PortAudio, avoiding the PortAudio/PulseAudio build-from-source issue entirely

AI assistance disclosure: Claude was substantially involved in the development of this provider

Summary

Extends the existing local_audio player provider to support PulseAudio on Linux, while preserving the existing PortAudio/CoreAudio path on macOS. Each PulseAudio sink is registered as an external Sendspin bridge client, enabling synchronized multi-room playback alongside existing Sendspin players. Audio is written directly to PulseAudio via a minimal libpulse-simple ctypes wrapper. The separate pulse_audio provider is superseded by this change and removed.

Motivation

The existing local_audio provider uses PortAudio/sounddevice which cannot enumerate PulseAudio virtual sinks such as module-remap-sink stereo pairs. On Linux, PulseAudio sits on top of ALSA and owns the hardware devices, so PortAudio can only see physical ALSA devices — not virtual sinks. This change targets PulseAudio directly on Linux via pactl and libpulse-simple, correctly discovering and playing to all sinks including remap sinks, combined sinks, S/PDIF, and HDMI outputs, while preserving full macOS functionality.

Changes

Modified — `music_assistant/providers/local_audio/`

File	Description
init.py	Added hardware volume ceiling config entry (Linux only); updated volume control mode description
provider.py	Added libpulse-simple presence check on Linux at init
player.py	Added pa_sink_name and is_remap params; Linux uses software volume mode with hardware ceiling set once at startup; apply_hardware_ceiling sets physical ALSA sinks to ceiling value and remap sinks to 100%; pulsectl helpers for volume and mute
sendspin_bridge.py	Unified Linux (PASimpleStream) and Darwin (sounddevice) audio output paths; native format negotiation per sink; initial_volume=25 on bridge registration; apply_hardware_ceiling call per player
pa_simple.py	New file — ctypes wrapper around libpulse-simple for direct PCM playback; enumerate_pa_sinks via pactl --format=json
constants.py	Added CONF_HARDWARE_VOLUME_CEILING, DEFAULT_HARDWARE_VOLUME_CEILING
manifest.json	Added pulsectl; sys_platform == 'linux' to requirements
README.md	Updated for unified Linux/macOS provider
bin/pactl	Bundled pactl binary (fallback if pulseaudio-utils not installed)
bin/lib/libpulsecommon-16.1.so	Bundled library required by bundled pactl binary

Dependencies

libpulse-simple.so.0 (Linux): Must be present on the host — standard PulseAudio installation
pactl (Linux): Required for sink enumeration — provided by pulseaudio-utils in Dockerfile.base, with bundled binary as fallback
pulsectl (Linux): Python PulseAudio bindings for volume and mute control — installed via provider manifest requirements
numpy: Used for PCM volume scaling (already a MA dependency)
Sendspin provider (depends_on: sendspin)

Expanding Outputs with Stereo Pair Remap Sinks

Multi-channel sound cards (5.1, 7.1 surround) expose a single multi-channel PulseAudio sink by default. To use each channel pair as an independent MA player, PulseAudio module-remap-sink can split a multi-channel sink into individual stereo sinks — one per channel pair (front, rear, side, center/LFE). The Local Audio Out provider discovers and registers all remap sinks automatically alongside physical sinks, so no additional configuration is needed in MA once the remap sinks exist.

For Home Assistant OS users, the companion addon Pulse Audio Stereo Pairs automates this setup. It runs as a lightweight HA addon that creates the remap sinks on startup and reacts to audio device hot-plug and unplug events, removing the need to configure remap sinks manually via pactl. Once both the addon and this provider are running, each channel pair of every multi-channel card appears as a separate player in Music Assistant.

# Extend Local Audio Out provider with PulseAudio support

The fix wraps stream.close() in asyncio.shield() so cancellation of the parent task can't interrupt the executor call. The suppress(Exception) wrapper is still there as a safety net.

iVolt1 · 2026-04-29T16:44:13Z

If this is a known issue and/or you can reproduce it, I will/can open a separate PR for sendspin_bridge once yours lands.

EDIT: context: I have a DAC at the other end of the usb out of my laptop that remains 'on' needlessly

In HA's hassio_audio environment module-suspend-on-idle isn't loaded so DACs stay powered once played to regardless of stream state. Maybe your pipewire-pulse loads the module.

The asyncio.shield fix is included in my PR so feel free to test it.

vingerha · 2026-04-29T16:55:32Z

I will verify tomorrow. With me it was partially the local host config of the usb .... but when corked processes stayed open it never shut down too, only with a restart of pipewire (after playing ended) or a shutdown of MA it went down after x seconds. Thanks for the effort so far, as said back tomorrow :)

vingerha · 2026-04-30T08:01:14Z

update: the fix is not working for me, the processes remain active even after they stopped playing minutes ago and (with me) this prevents to suspend the usb, which then continues to provide 5v to the dac and that stays on.
The sendspin_bridge 'fix' (call it a draft version) that I worked on terminates the corked/no processes after a few seconds.

 pactl list sink-inputs | grep -E "Sink Input #|Corked:"
Sink Input #68
        Corked: no
Sink Input #82
        Corked: no
Sink Input #88
        Corked: no

iVolt1 · 2026-05-01T12:56:00Z

update: the fix is not working for me, the processes remain active even after they stopped playing minutes ago and (with me) this prevents to suspend the usb, which then continues to provide 5v to the dac and that stays on. The sendspin_bridge 'fix' (call it a draft version) that I worked on terminates the corked/no processes after a few seconds.

The MA hassio_audio pulse audio plugin does not include suspend_on_idle so that is likely why devices are not going to Idle or Suspend. It may depend on your linux distribution whether that is included or not.

iVolt1 · 2026-05-01T13:02:28Z

@marcelveldt, @MarvinSchenkel Is there anything else besides the Security Check holding back this PR from being merged to dev? I would really like to see it move forward since it is how I play audio here every day and it seems really solid. Also local audio is a much requested feature for whole house audio using line outputs with multiple DACS or 5.1/7.1 stereo pairs so I think many users will be happy to see this implemented. Thanks, iVolt1.

vingerha · 2026-05-01T15:24:01Z

update: the fix is not working for me, the processes remain active even after they stopped playing minutes ago and (with me) this prevents to suspend the usb, which then continues to provide 5v to the dac and that stays on. The sendspin_bridge 'fix' (call it a draft version) that I worked on terminates the corked/no processes after a few seconds.

The MA hassio_audio pulse audio plugin does not include suspend_on_idle so that is likely why devices are not going to Idle or Suspend. It may depend on your linux distribution whether that is included or not.

Nope...it is the processes that stay open, see my screenshot above, as soon as I reset pw (i.e. processes gone) or close MA container (ditto), USB goes down in seconds and after that also my dac suspends. Pipe/pulse is not proprely closing processes so some code needed to push to do so . Alsa devices no problem

vingerha · 2026-05-01T15:27:26Z

@marcelveldt, @MarvinSchenkel Is there anything else besides the Security Check holding back this PR from being merged to dev? I would really like to see it move forward since it is how I play audio here every day and it seems really solid. Also local audio is a much requested feature for whole house audio using line outputs with multiple DACS or 5.1/7.1 stereo pairs so I think many users will be happy to see this implemented. Thanks, iVolt1.

Ditto, I would like to see this go live too so next steps can be planned.
Wrt to hdmi....on intel there remains an issue playing above 48k, this seems to be a intel<>pw issue (not related to this PR)

Copilot

Pull request overview

Extends the built-in Local Audio Out player provider to add Linux PulseAudio sink discovery/output, while updating Sendspin bridge format handling so bridge players can advertise per-device PCM formats.

Changes:

Add Linux PulseAudio sink enumeration/playback plumbing in local_audio, including a new pa_simple.py helper and bridge/player changes.
Update Sendspin bridge format selection so bridge players can expose sink-specific sample rate/bit depth.
Add Linux-only pulsectl dependency and refresh Local Audio docs/metadata.

Note: the supplied diff did not include the Dockerfile.base or bundled binary/library changes mentioned in the PR description, so those parts could not be reviewed here.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
requirements_all.txt	Adds Linux-only `pulsectl` to aggregate requirements.
music_assistant/providers/sendspin/playback.py	Uses bridge-declared output format for member format selection.
music_assistant/providers/sendspin/bridge_role.py	Parameterizes bridge audio requirements and exposes the configured format.
music_assistant/providers/local_audio/sendspin_bridge.py	Reworks the bridge for Linux PulseAudio output and per-device format advertising.
music_assistant/providers/local_audio/README.md	Updates provider documentation for Linux PulseAudio and macOS behavior.
music_assistant/providers/local_audio/provider.py	Adds a Linux `libpulse-simple` availability check at init.
music_assistant/providers/local_audio/player.py	Changes player volume/mute persistence and PulseAudio sink volume handling.
music_assistant/providers/local_audio/pa_simple.py	Adds ctypes-based PulseAudio streaming and sink enumeration helpers.
music_assistant/providers/local_audio/manifest.json	Adds Linux-only `pulsectl` requirement and updates codeowners.
music_assistant/providers/local_audio/constants.py	Updates local audio defaults, cache constants, and UUID namespace.
music_assistant/providers/local_audio/init.py	Removes provider config entries and keeps basic provider setup exports.

Bit depth parser replaced with explicit format lookup dict — handles s24-32le correctly as 32-bit instead of producing 2432 pactl discovery now prefers system binary first, bundled binary is the fallback

restore_state() now called before register_or_update() so correct volume/mute values are in the initial PLAYER_ADDED event display_name from device.get("description", device_name) used for MA player display, while stable PA sink name is used for UUID generation

removed bin/pactl and bin/lib/ from the file structure table, updated pactl dependency to say "requires pulseaudio-utils", updated the notes bullet to match.

iVolt1 added 30 commits April 14, 2026 11:13

Allow per player sample_rate, bit depth, and channels.

2856d7c

Allow per player sample_rate, bit depth, and channels.

ce8c173

Merge branch 'music-assistant:dev' into MA_pulse_audio

4706fde

Merge branch 'music-assistant:dev' into MA_pulse_audio

5b1fc3a

Add pulsectl to requirement.

66e2bd3

Merge branch 'music-assistant:dev' into MA_pulse_audio

c72c0f5

Merge branch 'music-assistant:dev' into MA_pulse_audio

9bd9915

Update requirements add "pulsectl; sys_platform == 'linux'"

ba6590b

Add pulse audio output

6a86b97

Add pulse audio output

7309c7b

pa operations

a5b74ba

Update sendspin_bridge.py for pulse audio

a2ebfd5

Update player.py for pulse audio

e21f5f6

Changes fro pulse audio

b561b65

Changes for pulse audio

9706612

Changes for pulse audio

e1c6ba7

Update for adding pulse audio

00b900f

Add def _get_pulse_server() -> str:

09fcf26

Replace PULSE_SERVER references.

ead112b

Merge branch 'music-assistant:dev' into MA_pulse_audio

99051ea

Fix enumerate_pa_sinks()

bf782bd

Fix enumerate_pa_sinks()

dd95b27

Update for hardware volume cap

4ec8de4

Changes for hardware volume cap.

62ccd4d

Fix volume cap

8e1a7a9

debug code sample rate and bit dpeth.

0167e36

Remove ctypes from sample rate bit dpeth determination.

7013b19

Merge branch 'music-assistant:dev' into MA_pulse_audio

8844368

Merge branch 'music-assistant:dev' into MA_pulse_audio

538b390

Add pulseaudio-utils in order to get pactl

b8a3d93

Fix usb device staying powered on

17dfa3f

The fix wraps stream.close() in asyncio.shield() so cancellation of the parent task can't interrupt the executor call. The suppress(Exception) wrapper is still there as a safety net.

iVolt1 added 4 commits April 29, 2026 12:38

Lint/ruff

c157a65

Update sendspin_bridge.py

a996836

lint/ruff

9198338

Lint/ruff

82dd700

iVolt1 added 2 commits April 30, 2026 06:40

Merge branch 'music-assistant:dev' into MA_pulse_audio

f4893ab

Merge branch 'music-assistant:dev' into MA_pulse_audio

1999f82

Merge branch 'music-assistant:dev' into MA_pulse_audio

c4ada94

MarvinSchenkel requested a review from Copilot May 4, 2026 07:23

Copilot started reviewing on behalf of MarvinSchenkel May 4, 2026 07:23 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

iVolt1 added 12 commits May 4, 2026 20:29

Merge branch 'music-assistant:dev' into MA_pulse_audio

c79fa69

Merge branch 'music-assistant:dev' into MA_pulse_audio

9b67b98

Merge branch 'music-assistant:dev' into MA_pulse_audio

ef3036f

CoPilot suggested fixes

0512ae8

Bit depth parser replaced with explicit format lookup dict — handles s24-32le correctly as 32-bit instead of producing 2432 pactl discovery now prefers system binary first, bundled binary is the fallback

CoPilot suggested fixes

3b3d9ad

restore_state() now called before register_or_update() so correct volume/mute values are in the initial PLAYER_ADDED event display_name from device.get("description", device_name) used for MA player display, while stable PA sink name is used for UUID generation

Update README.md

035b33e

Update constants.py

eb30000

Merge branch 'music-assistant:dev' into MA_pulse_audio

c96885c

Merge branch 'music-assistant:dev' into MA_pulse_audio

192e57a

Update pa_simple.py

30e6e46

removed bin/pactl and bin/lib/

01a46ca

removed bin/pactl and bin/lib/ from the file structure table, updated pactl dependency to say "requires pulseaudio-utils", updated the notes bullet to match.

Comment on sounddevice

c4e9bd1

Uh oh!

Conversation

iVolt1 commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Extend Local Audio Out provider with PulseAudio support

Summary

Motivation

Changes

Modified — music_assistant/providers/local_audio/

Dependencies

Expanding Outputs with Stereo Pair Remap Sinks

Uh oh!

iVolt1 commented Apr 29, 2026

Uh oh!

vingerha commented Apr 29, 2026

Uh oh!

vingerha commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iVolt1 commented May 1, 2026

Uh oh!

iVolt1 commented May 1, 2026

Uh oh!

vingerha commented May 1, 2026

Uh oh!

vingerha commented May 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

iVolt1 commented Apr 17, 2026 •

edited

Loading

Modified — `music_assistant/providers/local_audio/`

vingerha commented Apr 30, 2026 •

edited

Loading