Add Pulse Audio Out player provider

Dockerfile

@@ -62,8 +62,6 @@ ENV PATH="$VIRTUAL_ENV/bin:$PATH"
 # copy the already built /app dir
 COPY --from=builder /app /app
 
-# the /app contents have correct permissions but for some reason /app itself does not.
-# so apply again, but ONLY to the dir (otherwise we increase the size)
 RUN chmod 777 /app
 
 # Set some labels

Dockerfile.base

@@ -126,6 +126,16 @@ RUN PYAV_VERSION=$(python -c "import json; reqs=json.load(open('/tmp/sendspin_ma
 
 ##################################################################################################
 
+# Small builder to install pulseaudio-utils and extract binaries/libs
+FROM debian:bookworm AS pa-builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    pulseaudio-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Ensure the files we need exist (pactl, pacmd and pulse libs)
+# They will be copied into the final base image.
+
 FROM python:3.13-slim-bookworm
 
 # Enable non-free and contrib repositories for codec libraries
@@ -197,6 +207,7 @@ RUN set -x \
         # AirPlay receiver dependencies (shairport-sync)
         libconfig9 \
         libpopt0 \
+        pulseaudio-utils \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
@@ -224,6 +235,14 @@ COPY --from=ffmpeg-builder /usr/local/lib/libpostproc.so* /usr/local/lib/
 # Copy pre-built PyAV wheel for use by downstream images
 COPY --from=pyav-builder /wheels/ /usr/local/share/pyav-wheels/
 
+# Copy pulseaudio binaries and libs from pa-builder
+COPY --from=pa-builder /usr/bin/pactl /usr/bin/pactl
+COPY --from=pa-builder /usr/bin/pacmd /usr/bin/pacmd
+# PulseAudio libraries location on Debian x86_64; copy the whole pulse dir to be safe
+COPY --from=pa-builder /usr/lib/x86_64-linux-gnu/pulse /usr/lib/x86_64-linux-gnu/pulse
+# Some systems place libs directly under /usr/lib; include these patterns if needed:
+COPY --from=pa-builder /usr/lib/x86_64-linux-gnu/libpulse* /usr/lib/x86_64-linux-gnu/ || true
+
 # Update shared library cache and verify FFmpeg
 RUN ldconfig && ffmpeg -version && ffprobe -version
 

music_assistant/providers/pulse_audio/README.md

@@ -0,0 +1,101 @@
+# Pulse Audio Out Provider
+
+## Overview
+
+The Pulse Audio Out provider exposes PulseAudio sinks (USB DACs, built-in audio, HDMI, remap sinks, etc.) as players in Music Assistant. It leverages the Sendspin provider for synchronization and timing, registering each sink as an external Sendspin bridge client.
+
+### Key Features
+
+- **Automatic Sink Discovery**: Enumerates all PulseAudio output sinks via `pactl`, including virtual sinks such as remap and combined sinks
+- **Native Format Negotiation**: Each sink advertises its native sample rate and bit depth (16, 24, or 32-bit) so Music Assistant transcodes to the correct format per sink — no unnecessary resampling
+- **Sendspin Integration**: Each sink is registered as a Sendspin bridge client, enabling synchronized multi-room playback
+- **Software Volume Control**: Per-sink volume and mute via PCM sample scaling
+- **Stable Player IDs**: Uses UUIDv5 derived from the PulseAudio sink name so players persist across restarts
+- **Hardware Volume Ceiling**: Configurable per-provider PA sink volume ceiling applied at startup
+
+## Architecture
+
+### Component Overview
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                  LocalPulseAudioProvider                      │
+│  - Thin provider shell, delegates to bridge manager          │
+└──────────────────────────────────────────────────────────────┘
+                              │
+             ┌────────────────▼────────────────┐
+             │  LocalPulseAudioBridgeManager   │
+             │  - Enumerates PA sinks via pactl│
+             │  - Creates/stops bridges        │
+             └────────────────┬────────────────┘
+                              │
+          ┌───────────────────┼───────────────────┐
+          │                                       │
+┌─────────▼──────────┐              ┌─────────────▼──────────┐
+│ SendspinPulseAudio  │              │ SendspinPulseAudio     │
+│ Bridge (Sink A)     │              │ Bridge (Sink B)        │
+│                     │              │                        │
+│ Sendspin Client ──► │              │ Sendspin Client ──►    │
+│ BridgePlayerRole    │              │ BridgePlayerRole       │
+│ pa_simple output    │              │ pa_simple output       │
+└─────────────────────┘              └────────────────────────┘
+```
+
+### Audio Flow
+
+```
+Sendspin PushStream
+       │
+       ▼
+BridgePlayerRole.on_audio_chunk
+       │
+       ▼ (software volume/mute applied, format conversion for 24-bit)
+asyncio.Queue
+       │
+       ▼
+PASimpleStream (libpulse-simple via ctypes)
+       │
+       ▼
+PulseAudio Sink
+       │
+       ▼
+Physical Audio Device
+```
+
+### Bit Depth Handling
+
+| Sink Format | MA Delivery     | PA Stream Format   | Conversion                          |
+|-------------|-----------------|---------------------|-------------------------------------|
+| `s16le`     | 16-bit PCM      | `PA_SAMPLE_S16LE`  | None                                |
+| `s24le`     | 32-bit container (left-justified) | `PA_SAMPLE_S24LE` | Unpack int32, repack to 3-byte LE  |
+| `s32le`     | 32-bit PCM      | `PA_SAMPLE_S32LE`  | None                                |
+
+### File Structure
+
+| File | Description |
+|------|-------------|
+| `__init__.py` | Provider entry point, setup, and config |
+| `provider.py` | `LocalPulseAudioProvider` class |
+| `sendspin_bridge.py` | Bridge manager and per-sink bridge implementation |
+| `player.py` | `LocalPulseAudioPlayer` — MA player model for each sink |
+| `pa_simple.py` | Minimal ctypes wrapper around `libpulse-simple` for direct PCM output |
+| `helpers.py` | `find_pactl()` and `pactl_env()` utilities |
+| `constants.py` | Shared constants (UUID namespace, config keys) |
+| `manifest.json` | Provider metadata and dependencies |
+
+## Dependencies
+
+- **Sendspin provider** (`depends_on: sendspin`): Required for audio synchronization and player management
+- **libpulse / libpulse-simple**: PulseAudio client libraries (must be present on the host); accessed via ctypes — no Python PulseAudio bindings required
+- **pactl**: Used at startup for sink enumeration (`pulseaudio-utils` package on Debian/Ubuntu, `pulseaudio` on Alpine)
+- **numpy**: Used for PCM volume scaling
+
+## Notes
+
+- The bundled `pactl` binary (if present) is `amd64` only. On other architectures the system `pactl` must be available in `PATH` or `PULSE_SERVER` must be set.
+- Multi-channel sinks (5.1, 7.1) are supported — the bridge opens a stereo stream and PulseAudio handles channel remapping automatically.
+- Virtual sinks created by `module-remap-sink` (stereo pairs split from multi-channel cards) are fully supported and are the recommended way to expose individual speaker pairs as independent MA players.
+
+## Related Documentation
+
+- [Sendspin Provider](../sendspin/README.md)

music_assistant/providers/pulse_audio/__init__.py

@@ -0,0 +1,60 @@
+"""Local PulseAudio Out player provider for Music Assistant."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from music_assistant_models.config_entries import ConfigEntry, ConfigValueOption
+from music_assistant_models.enums import ConfigEntryType, ProviderFeature
+
+from music_assistant.mass import MusicAssistant
+
+from .constants import (
+    CONF_HARDWARE_VOLUME_CEILING,
+    CONF_VOLUME_CONTROL,
+    DEFAULT_HARDWARE_VOLUME_CEILING,
+    VOLUME_CONTROL_DISABLED,
+    VOLUME_CONTROL_HARDWARE,
+    VOLUME_CONTROL_SOFTWARE,
+)
+from .provider import LocalPulseAudioProvider
+
+if TYPE_CHECKING:
+    from music_assistant_models.config_entries import ConfigValueType, ProviderConfig
+    from music_assistant_models.provider import ProviderManifest
+    from music_assistant.models import ProviderInstanceType
+
+SUPPORTED_FEATURES = {
+    ProviderFeature.SYNC_PLAYERS,
+}
+
+
+async def get_config_entries(
+    mass: MusicAssistant,
+    instance_id: str | None = None,
+    action: str | None = None,
+    values: dict[str, ConfigValueType] | None = None,
+) -> tuple[ConfigEntry, ...]:
+    """Return Config entries to setup this provider."""
+    # ruff: noqa: ARG001
+    return (
+        ConfigEntry(
+            key=CONF_HARDWARE_VOLUME_CEILING,
+            type=ConfigEntryType.INTEGER,
+            label="Hardware volume ceiling",
+            description=(
+                "Sets the PulseAudio sink volume to this level on every startup. "
+                "This attenuates the maximum output level of the hardware. "
+                "Day-to-day volume control uses software scaling within this ceiling. "
+                "Range: 0-100. Default: 50."
+            ),
+            default_value=DEFAULT_HARDWARE_VOLUME_CEILING,
+            required=False,
+        ),
+    )
+
+
+async def setup(
+    mass: MusicAssistant, manifest: ProviderManifest, config: ProviderConfig
+) -> ProviderInstanceType:
+    """Initialize provider(instance) with given configuration."""
+    return LocalPulseAudioProvider(mass, manifest, config, SUPPORTED_FEATURES)

music_assistant/providers/pulse_audio/constants.py

@@ -0,0 +1,14 @@
+"""Constants for Local PulseAudio Out provider."""
+from __future__ import annotations
+
+import uuid
+
+DEVICE_UUID_NAMESPACE = uuid.UUID("b2c3d4e5-f6a7-8901-bcde-f12345678901")
+
+CONF_VOLUME_CONTROL = "volume_control"
+VOLUME_CONTROL_SOFTWARE = "software"
+VOLUME_CONTROL_HARDWARE = "hardware"
+VOLUME_CONTROL_DISABLED = "disabled"
+
+CONF_HARDWARE_VOLUME_CEILING = "hardware_volume_ceiling"
+DEFAULT_HARDWARE_VOLUME_CEILING = 50

music_assistant/providers/pulse_audio/helpers.py

@@ -0,0 +1,43 @@
+"""Shared helpers for Local PulseAudio Out provider."""
+from __future__ import annotations
+
+import os
+import shutil
+
+from .pa_simple import PULSE_SERVER
+
+
+def find_pactl() -> str:
+    """Find the pactl binary, preferring the bundled version."""
+    bundled = os.path.join(os.path.dirname(__file__), "bin", "pactl")
+    if os.path.isfile(bundled):
+        if not os.access(bundled, os.X_OK):
+            # Fix permissions if the wheel lost the execute bit
+            try:
+                os.chmod(bundled, 0o777)
+            except OSError:
+                pass
+        if os.access(bundled, os.X_OK):
+            return bundled
+    if path := shutil.which("pactl"):
+        return path
+    for candidate in ("/usr/bin/pactl", "/usr/local/bin/pactl", "/bin/pactl"):
+        if os.path.isfile(candidate):
+            return candidate
+    raise FileNotFoundError(
+        "pactl not found — bundled binary missing and pulseaudio-utils not installed"
+    )
+
+def pactl_env() -> dict[str, str]:
+    """Build environment dict for pactl subprocess calls.
+
+    Sets LD_LIBRARY_PATH to include the bundled lib directory so that
+    libpulsecommon is found, and sets PULSE_SERVER to the detected socket.
+    """
+    lib_dir = os.path.join(os.path.dirname(__file__), "lib")
+    existing_ld = os.environ.get("LD_LIBRARY_PATH", "")
+    ld_path = f"{lib_dir}:{existing_ld}" if existing_ld else lib_dir
+    env = {**os.environ, "LD_LIBRARY_PATH": ld_path}
+    if PULSE_SERVER:
+        env["PULSE_SERVER"] = PULSE_SERVER
+    return env

music_assistant/providers/pulse_audio/manifest.json

@@ -0,0 +1,12 @@
+{
+  "type": "player",
+  "domain": "pulse_audio",
+  "name": "Pulse Audio Out",
+  "description": "Play audio through locally attached pulse audio outputs.",
+  "codeowners": ["@music-assistant"],
+  "depends_on": "sendspin",
+  "documentation": "https://music-assistant.io/player-support/pulse-audio/",
+  "builtin": true,
+  "allow_disable": true,
+  "stage": "alpha"
+}