Add --alsa-mixer: hardware volume through an ALSA mixer control

CMakeLists.txt

@@ -488,6 +488,7 @@ if(SENDSPIN_CLI_BUILD_TESTS)
     include(GoogleTest)
 
     add_executable(sendspin-cli-tests
+        tests/alsa_mixer_test.cpp
         tests/audio_source_test.cpp
         tests/cli_test.cpp
         tests/config_file_test.cpp

README.md

@@ -105,6 +105,8 @@ sendspin-cli -n den --input default
 | `--input <device>` | Audio to stream to the server: a microphone or line-in, e.g. `default`, `hw:1,0`, `pulse`, `pipewire:<node>` or `portaudio`, or `coreaudio` on macOS; or `loopback` for what this host plays (on macOS without the player's own playback, on Linux with it). `-l` lists them. Off unless given. See [Stream a microphone or line-in](https://github.com/Sendspin/sendspin-cpp-cli/wiki/Advanced-Usage#stream-a-microphone-or-line-in) and [Stream what this host plays](https://github.com/Sendspin/sendspin-cpp-cli/wiki/Advanced-Usage#stream-what-this-host-plays). |
 | `--allow-unpaired` | Let a server play without pairing with this player first. Off by default. |
 | `--fixed-volume` | Play at full volume, unmuted, and let the server set neither — for a line-out into an amplifier whose level is set there. |
+| `--alsa-mixer <card:control>` | Drive an ALSA hardware mixer for volume and mute instead of scaling the stream in software, e.g. `0:Master`, mapped over the control's dB range on the curve `--alsa-mixer-curve` selects. The level the mixer is at when the player starts is what it reports and keeps until a server sends its own, and a change made outside the player (alsamixer, `amixer`, a hardware knob) is reported to the server. Volume 0 silences the stream even when the control's floor is not silent. ALSA outputs only; a mixer that cannot be opened or set falls back to software gain. Contradicts `--fixed-volume`. |
+| `--alsa-mixer-curve <spec\|cubic>` | How volume maps onto the mixer's dB range. `spec` (default) is the perceived-loudness curve; `cubic` is the steeper one whose inverse is alsamixer's slider position, so the two track each other. Needs `--alsa-mixer`. |
 | `--release-device` | Close the output device when a stream ends and reopen it when the next one starts, so other players can take turns on an exclusive device such as an ALSA `hw:` DAC. Off by default: between streams another app can take the device, and the next stream is then discarded. ALSA and PortAudio only. |
 | `--pairing-code <8 digits>` | A fixed code a server can pair with, confirmed with `sendspin-cli pair confirm`. Without it the player shows a fresh 6-digit code per attempt. |
 | `-s, --server <host[:port]>` | Connect out to a server rather than waiting to be discovered, or `mdns:[<name>]` to discover one over mDNS. Turns off the mDNS advertisement. |

docs/wiki/Configuration.md

@@ -64,6 +64,8 @@ already does that.
 | `output-delay` | `--output-delay` | latency this endpoint's hardware adds after the audio port, 0–5000. `static-delay` / `--static-delay` is still accepted as the old name | `0` |
 | `allow-unpaired` | `--allow-unpaired` | `true`/`false` — let a server that has not paired with this player play on it | `false` |
 | `fixed-volume` | `--fixed-volume` | `true`/`false` — play at full volume, unmuted, and offer the server neither volume nor mute, for an output whose level is set elsewhere (a line-out into an amplifier). A remembered volume is kept but ignored, and returns once the key is dropped | `false` |
+| `alsa-mixer` | `--alsa-mixer` | `<card>:<control>` — drive this ALSA hardware mixer for volume and mute instead of scaling the stream in software, e.g. `0:Master`. The value is mapped over the control's dB range on the curve `alsa-mixer-curve` selects, and the level the mixer is at when the player starts is what it reports and keeps until a server sends its own. A change made outside the player (alsamixer, `amixer`, a hardware knob) is reported to the server, and volume 0 silences the stream even when the control's floor is not silent. ALSA outputs only; a mixer that cannot be opened or set falls back to software gain. Contradicts `fixed-volume` | none |
+| `alsa-mixer-curve` | `--alsa-mixer-curve` | `spec` or `cubic` — how volume maps onto the mixer's dB range. `spec` (default) is the perceived-loudness curve, amplitude `(v/100)^1.5`; `cubic` is the steeper curve Snapcast uses, whose inverse `100*10^(dB/60)` is alsamixer's slider position, so the two track each other. Needs `alsa-mixer` | `spec` |
 | `release-device` | `--release-device` | `true`/`false` — close the output device at each stream end and reopen it at the next stream start, for an exclusive device such as an ALSA `hw:` DAC shared with other players (Squeezelite, AirPlay, Spotify). The trade-off: another app can take the device between streams, and the next stream is then discarded; each stream also pays a fresh open. ALSA and PortAudio only; other backends ignore it | `false` |
 | `pairing-code` | `--pairing-code` | exactly 8 digits — a static code a server can pair with, confirmed each time with `sendspin-cli pair confirm`; replaces the 6-digit code the player otherwise shows. See [Pairing a Player](Pairing-a-Player#3-static-code) | none |
 | `no-mdns` | `--no-mdns` | `true`/`false` — do not advertise `_sendspin._tcp` | `false` |

docs/wiki/Controlling-the-Player.md

@@ -113,6 +113,10 @@ above `output:` says so, and appears whenever a server is connected.
   reads `100 (fixed; the server cannot set it)`: the output plays at full gain, unmuted, the
   server is offered neither volume nor mute, and a volume remembered from an earlier run is
   kept but ignored until the flag is dropped. `vol` and `mute` still address the group.
+  With `--alsa-mixer` it starts at the level the hardware control was already at, marked
+  `(read from the hardware mixer at startup)`, until the server sends a volume of its own. A
+  later change made outside the player — in alsamixer, `amixer`, or by a hardware knob — is
+  picked up and reported, so a controller keeps showing the real level.
 - **`state` and `stream` are different facts.** `state` is the *group's* transport state.
   `stream` is whether audio is arriving at *this* endpoint — a player dropped from the group
   loses it while the group plays on. A `stream: receiving` line with **no format after the

packaging/sendspin-cli.conf.example

@@ -46,6 +46,14 @@
 # set elsewhere, such as a line-out into an amplifier. A remembered volume returns once dropped.
 #fixed-volume = true
 
+# Drive an ALSA hardware mixer for volume and mute instead of scaling the stream in software,
+# as card:control, e.g. 0:Master. The value is mapped over the control's dB range on the spec's
+# curve, and the level the mixer is at when the player starts is what it reports and keeps until
+# a server sends its own. A change made outside the player (alsamixer, amixer, a hardware knob)
+# is reported to the server, and volume 0 silences the stream. ALSA outputs only; a mixer that
+# cannot be opened or set falls back to software gain. Contradicts fixed-volume.
+#alsa-mixer = 0:Master
+
 # A static pairing code: exactly 8 digits, chosen at random for this player. Every attempt
 # with it waits for 'sendspin-cli pair confirm'. Unset, the player shows a fresh 6-digit code.
 #pairing-code = 48151623