Extend Local Audio Out provider with PulseAudio support

music_assistant/providers/local_audio/README.md

@@ -2,14 +2,17 @@
 
 ## Overview
 
-The Local Audio Out provider exposes locally attached soundcards (USB DACs, built-in speakers, HDMI audio, etc.) as players in Music Assistant. It leverages the Sendspin provider for synchronization and timing, registering each soundcard as an external Sendspin bridge client.
+The Local Audio Out provider exposes locally attached soundcards as players in Music Assistant. On Linux it enumerates PulseAudio sinks (USB DACs, built-in audio, HDMI, remap sinks, virtual sinks, etc.); on macOS it enumerates PortAudio/CoreAudio devices. It leverages the Sendspin provider for synchronization and timing, registering each device as an external Sendspin bridge client.
 
 ### Key Features
 
-- **Automatic Device Discovery**: Enumerates all audio output devices via PortAudio/sounddevice
+- **Automatic Device Discovery**: On Linux, enumerates all PulseAudio output sinks via `pactl --format=json` — returns native sample rate and format regardless of active stream state. On macOS, enumerates via PortAudio/sounddevice
+- **Native Format Negotiation** *(Linux)*: Each PA sink advertises its native sample rate and bit depth (16, 24, or 32-bit) so Music Assistant transcodes to the correct format — no unnecessary resampling
 - **Sendspin Integration**: Each device is registered as a Sendspin bridge client, enabling synchronized multi-room playback
-- **Software Volume Control**: Per-device volume and mute via PCM sample scaling
-- **Stable Player IDs**: Uses UUIDv5 from device name + host API index so players persist across restarts
+- **Hardware Volume Control**: PulseAudio sink volume on Linux, CoreAudio on macOS, with automatic fallback to software scaling
+- **Software Volume Control**: Per-device volume and mute via PCM sample scaling when hardware control is unavailable or disabled
+- **Stable Player IDs**: Uses UUIDv5 derived from device name + host API index so players persist across restarts
+- **Hardware Volume Ceiling** *(Linux)*: Configurable per-provider PA sink volume ceiling applied at startup
 
 ## Architecture
 
@@ -19,11 +22,12 @@ The Local Audio Out provider exposes locally attached soundcards (USB DACs, buil
 ┌──────────────────────────────────────────────────────────────┐
 │                    LocalAudioProvider                         │
 │  - Thin provider shell, delegates to bridge manager          │
+│  - Verifies libpulse-simple present on Linux at init         │
 └──────────────────────────────────────────────────────────────┘
                               │
                 ┌─────────────▼──────────────┐
                 │  LocalAudioBridgeManager   │
-                │  - Enumerates soundcards   │
+                │  - Enumerates devices      │
                 │  - Creates/stops bridges   │
                 └─────────────┬──────────────┘
                               │
@@ -35,44 +39,100 @@ The Local Audio Out provider exposes locally attached soundcards (USB DACs, buil
 │                     │              │                        │
 │ Sendspin Client ──► │              │ Sendspin Client ──►    │
 │ BridgePlayerRole    │              │ BridgePlayerRole       │
-│ sounddevice Output  │              │ sounddevice Output     │
+│ PA/sounddevice out  │              │ PA/sounddevice out     │
 └─────────────────────┘              └────────────────────────┘
 ```
 
 ### Audio Flow
 
+#### Linux (PulseAudio)
 ```
 Sendspin PushStream
        │
        ▼
 BridgePlayerRole.on_audio_chunk
        │
-       ▼ (volume/mute applied)
+       ▼ (software volume/mute applied, format conversion for 24-bit)
+asyncio.Queue
+       │
+       ▼
+PASimpleStream (libpulse-simple via ctypes)
+       │
+       ▼
+PulseAudio Sink
+       │
+       ▼
+Physical Audio Device
+```
+
+#### macOS (CoreAudio)
+```
+Sendspin PushStream
+       │
+       ▼
+BridgePlayerRole.on_audio_chunk
+       │
+       ▼ (software volume/mute applied)
 asyncio.Queue
        │
        ▼
 sounddevice.RawOutputStream (PortAudio)
        │
        ▼
-Physical Soundcard
+CoreAudio Device
 ```
 
+### Bit Depth Handling (Linux)
+
+| 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 |
+| File/Folder | Description |
+|-------------|-------------|
+| `__init__.py` | Provider entry point, setup, and config entries |
 | `provider.py` | `LocalAudioProvider` class |
-| `sendspin_bridge.py` | Bridge manager and per-device bridge implementation |
-| `constants.py` | Shared constants (UUID namespace, buffer size) |
+| `sendspin_bridge.py` | Bridge manager and per-device bridge (PA on Linux, sounddevice on macOS) |
+| `player.py` | `LocalAudioPlayer` — MA player model for each device |
+| `pa_simple.py` | ctypes wrapper around `libpulse-simple` for direct PCM output; sink enumeration via `pactl` *(Linux only)* |
+| `constants.py` | Shared constants (UUID namespace, buffer size, config keys) |
 | `manifest.json` | Provider metadata and dependencies |
+| `bin/pactl` | Bundled `pactl` binary for sink enumeration (fallback if `pulseaudio-utils` not installed) |
+| `bin/lib/` | Bundled `libpulsecommon` shared library required by the bundled `pactl` binary |
 
 ## Dependencies
 
 - **Sendspin provider** (`depends_on: sendspin`): Required for audio synchronization and player management
-- **sounddevice**: Python bindings for PortAudio, used for audio output
+- **libpulse-simple** *(Linux)*: PulseAudio simple client library accessed via ctypes for direct PCM streaming to sinks
+- **pactl** *(Linux)*: Used for sink enumeration via `--format=json`. Provided by `pulseaudio-utils` in the MA base image, with a bundled binary as fallback
+- **pulsectl** *(Linux)*: Python PulseAudio bindings used for hardware volume and mute control
+- **sounddevice** *(macOS)*: Python bindings for PortAudio, used for audio output and device enumeration
 - **numpy**: Used for PCM volume scaling
 
+## Configuration
+
+| Setting | Platform | Description |
+|---------|----------|-------------|
+| Volume control mode | All | `hardware` (OS-level), `software` (PCM scaling), or `disabled` |
+| Hardware volume ceiling | Linux only | Sets PA sink volume on startup to cap maximum output level (0–100, default 50) |
+
+## 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.
+
+## Notes
+
+- On Linux, 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.
+- On Linux, `pactl --format=json` is used for enumeration because it always reports the sink's native sample rate and format, unlike `pulsectl`/libpulse which reports the currently negotiated stream format when streams are active.
+- On Linux, hardware volume control uses `pulsectl` to set the PA sink volume directly. If `pulsectl` is unavailable the provider falls back to software volume automatically.
+- On macOS, hardware volume control uses CoreAudio. If that fails the provider falls back to software volume automatically.
+
 ## Related Documentation
 
 - [Sendspin Provider](../sendspin/README.md)

music_assistant/providers/local_audio/__init__.py

@@ -4,21 +4,14 @@
 
 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_models.enums import ProviderFeature
 
 from music_assistant.mass import MusicAssistant
 
-from .constants import (
-    CONF_VOLUME_CONTROL,
-    VOLUME_CONTROL_DISABLED,
-    VOLUME_CONTROL_HARDWARE,
-    VOLUME_CONTROL_SOFTWARE,
-)
 from .provider import LocalAudioProvider
 
 if TYPE_CHECKING:
-    from music_assistant_models.config_entries import ConfigValueType, ProviderConfig
+    from music_assistant_models.config_entries import ConfigEntry, ConfigValueType, ProviderConfig
     from music_assistant_models.provider import ProviderManifest
 
     from music_assistant.models import ProviderInstanceType
@@ -29,29 +22,13 @@
 
 
 async def get_config_entries(
-    mass: MusicAssistant,
-    instance_id: str | None = None,
-    action: str | None = None,
-    values: dict[str, ConfigValueType] | None = None,
+    mass: MusicAssistant,  # noqa: ARG001
+    instance_id: str | None = None,  # noqa: ARG001
+    action: str | None = None,  # noqa: ARG001
+    values: dict[str, ConfigValueType] | None = None,  # noqa: ARG001
 ) -> tuple[ConfigEntry, ...]:
     """Return Config entries to setup this provider."""
-    # ruff: noqa: ARG001
-    return (
-        ConfigEntry(
-            key=CONF_VOLUME_CONTROL,
-            type=ConfigEntryType.STRING,
-            label="Volume control mode",
-            options=[
-                ConfigValueOption(title="Hardware (preferred)", value=VOLUME_CONTROL_HARDWARE),
-                ConfigValueOption(title="Software", value=VOLUME_CONTROL_SOFTWARE),
-                ConfigValueOption(title="Disabled", value=VOLUME_CONTROL_DISABLED),
-            ],
-            default_value=VOLUME_CONTROL_HARDWARE,
-            description="Hardware uses OS/ALSA-level volume control. "
-            "Software applies volume scaling to PCM audio data. "
-            "Disabled passes audio at full volume.",
-        ),
-    )
+    return ()
 
 
 async def setup(

music_assistant/providers/local_audio/constants.py

@@ -4,13 +4,16 @@
 
 import uuid
 
-# UUID namespace for generating stable player IDs from device name + host API
-DEVICE_UUID_NAMESPACE = uuid.UUID("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
+# UUID namespace for generating stable player IDs from device name + host API.
+DEVICE_UUID_NAMESPACE = uuid.UUID("a7d68578-af81-4e3e-a8b8-df8f9d6d1f05")
 
-# Default buffer size in frames for the sounddevice output stream
-DEFAULT_BUFFER_FRAMES = 2048
+# Category for caching previous player state (volume/mute).
+# Bump the integer to invalidate old cached values when the format changes.
+CACHE_CATEGORY_PREV_STATE = 1
 
-CONF_VOLUME_CONTROL = "volume_control"
+# Volume control — software only
 VOLUME_CONTROL_SOFTWARE = "software"
-VOLUME_CONTROL_HARDWARE = "hardware"
-VOLUME_CONTROL_DISABLED = "disabled"
+
+# Defaults
+DEFAULT_PLAYER_VOLUME = 25  # initial volume for new players (percent)
+DEFAULT_BUFFER_FRAMES = 1024  # sounddevice blocksize (frames)

music_assistant/providers/local_audio/manifest.json

@@ -3,9 +3,9 @@
   "domain": "local_audio",
   "name": "Local Audio Out",
   "description": "Play audio through locally attached soundcards (USB DACs, built-in speakers, etc.).",
-  "codeowners": ["@music-assistant"],
+  "codeowners": ["@music-assistant", "@iVolt1"],
   "depends_on": "sendspin",
-  "requirements": ["sounddevice==0.5.5"],
+  "requirements": ["sounddevice==0.5.5", "pulsectl; sys_platform == 'linux'"],
   "documentation": "https://music-assistant.io/player-support/local-audio/",
   "builtin": true,
   "allow_disable": true,