Add UX optionality settings (#42)

[thomaseleff]

Summary

Implements all 4 workstreams of the UX-optionality plan for issue #42.

WS1 — feature-flag foundation

• Adds the feature-flag catalog pattern (audera/ui/features.py): Feature/Option dataclasses, a FEATURES registry, and get_feature/default_selections/selected/flag_enabled helpers.
• Adds Settings.features: dict[str, str] persistence field; the existing DAL round-trips it with zero code changes, and old settings.json files without the key still load fine (defaults to {}).
• Adds ADR 004 documenting the design decisions (catalog as source of truth, FF_* option-value constants, 2-3 options with first-as-default, user-selected + DAL-persisted flags, Settings stores raw selections only).
• Documents the pattern in audera/ui/AGENTS.md.

WS2 — Settings tab: Features button groups

• Replaces the PlexAmp/Snapserver host text inputs and manual Save button in the Settings tab with one auto-saving ui.toggle button group per registered audera.ui.features entry (Player Selection, Volume).
• Selecting an option persists immediately via the DAL (no Save click) and refreshes the Players tab.
• Host fields remain on the Settings model (still needed to construct clients) but are now sourced from env vars only, no longer editable from the UI.
• _load_settings() switches from exists-then-get to settings_dal.get_or_create(...) seeded with features.default_selections(), so ~/.audera/settings.json exists with resolved default flags from the very first dashboard load — a decision explicitly deferred from WS1 that WS3/WS4's players-tab branching depends on.

WS3 — Players tab: Player Selection experience

• The Players tab now reads the player_selection flag (features.flag_enabled(...)) once per render and branches each Snapcast client card accordingly.
• mute (default, unchanged): full card — name, settings button, volume slider, and a Mute checkbox that disables the slider when checked.
• disabled (new): an enable/disable ui.switch appears left of the name, derived from client.muted. Toggling it calls set_client_volume(id, 100, muted=not enabled) and refreshes the tab. Muted clients collapse to a minimized single-line header (switch + name + settings button, no volume row); unmuted clients show the full card minus the now-redundant Mute checkbox.
• "Disabled" is deliberately derived from Snapcast's live client.muted state rather than a new persisted field — an accepted trade-off per issue Add UX optionality settings #42 (a client muted via dragging the volume slider to 0 in the mute experience will also show as "disabled" after switching experiences).
• The settings-gear button stays visible even on minimized cards — it's the only path to rename/latency/loudness/Snapcast-reset for that client.

WS4 — Players tab: Volume experience (percent vs. dB)

• Wires the previously inert volume feature flag into the Players tab's volume control, which now reads features.flag_enabled(..., VOLUME_KEY, FF_VOLUME_PERC_OR_DB) per render.
• Both modes gain a leading volume_up icon and a live trailing value label bound to the slider.
• percent (default, mostly unchanged): today's 0-100 slider, now with the icon/label pair (NN%).
• db (new): the same percent (0-100) slider as percent mode — only the trailing label changes, showing percent_to_db(value) as -N.N dB. Keeping one shared percent scale means the handle sits at the same physical spot when toggling between modes (a dB-scaled slider would move the handle, since dB is logarithmic in the percent domain).
• DSPConfig.volume (percent) remains the single canonical persisted value regardless of UI mode, and both modes drive CamillaDSP through set_percent_volume before calling dsp_dal.update(...) and Snapcast's set_client_volume.

dB experience fixes (follow-up)

Testing WS4 on a re-provisioned streamer surfaced three defects, all now fixed:

• dB slider position mismatch (root fix). The dB experience originally used a dB-scaled slider (min=MIN_DB, max=MAX_DB), so the handle jumped when toggling modes — the same volume sits at percent/100 of the track in percent mode but at (db-MIN_DB)/(MAX_DB-MIN_DB) in dB mode. Fixed by making the slider always percent-scaled and only relabeling in dB mode (see WS4 above), so the handle position is identical across modes. Seeds are integer-percent aligned so the periodic refresh doesn't fire a phantom update:model-value and re-snap the handle. (db_to_percent still returns a precise float and DSPConfig.volume is a float — no rename, no migration, 25 parses to 25.0 — so get_percent_volume stays exact; the slider path no longer depends on it.)
• Auto-mute on refresh. The persist path muted whenever percent == 0, and the old db_to_percent truncated anything below ~-40.5 dB to 0, so a normal mid-range dB edit could silently persist 0 → Snapcast mute, noticed only when the 10s refresh re-read Snapcast state. Mute is now anchored to the slider floor (percent <= 0, shown as MIN_DB in dB mode), never on lossy zero-rounding — and since the slider is percent-scaled, only the far-left 0% mutes.
• dB range. MIN_DB is -50.0 and MAX_DB is 0.0, matching CamillaGUI's default slider range (volume_range=50 / volume_max=0); attenuation-only, no gain above 0 dB.
• Preamp attenuation Gain filter (loudness headroom). As an artifact of the volume/headroom work, apply_loudness now inserts an audera_preamp_attenuation Gain filter at -10.0 dB (-_LOUDNESS_LOW_BOOST) before the audera_loudness Loudness filter, on both channels, so the two together never exceed 0 dB of headroom (clip protection against the Loudness filter's worst-case +10 dB low_boost). remove_loudness strips both the loudness and preamp filters (and their pipeline steps). Verified on-device: enabling loudness yields preamp_gain=-10.0 dB with 2 loudness + 2 preamp steps; disabling removes all four.

UI polish & conventions (follow-up)

Two Players-tab nit-picks plus a readability convention, surfaced while wrapping up:

• dB slider length no longer shifts. The dB value label had no fixed width, so the percent-scaled slider (grow) elongated/shortened as the label text changed digit count (e.g. -9.0 dB ↔ -10.0 dB), visibly nudging the handle. The label now has a fixed width + right-align (text-right w-16), which comfortably fits the widest string in either mode (-50.0 dB, 100%), so the slider length — and handle position — stays constant.
• Disabled players read as disabled. In the disabled experience, a disabled (muted) client now grays out its name (text-gray-400) and disables its settings-gear button, reinforcing the "disabled" intent. The gear stays in the DOM (still the only path to its settings), just non-interactive.
• Flag-resolution locals named after their FF_* constant. Call sites that resolve a flag into a local boolean now name that variable identically to the constant (FF_DISABLED_VS_MUTE = flag_enabled(...), FF_VOLUME_PERC_OR_DB = flag_enabled(...)), so every flag-gated UI branch is instantly recognizable and greppable by FF_. Recorded as decision 7 in ADR 004, and a new Architecture decisions section in AGENTS.md points agents at docs/adrs/ so the convention is discoverable.

HDMI audio-device provisioning fixes + bundled configs into code (follow-up)

PR #46 added --audio-device hdmi provisioning support; two of the settings it applied were wrong for real HDMI sinks. Fixing the first cleanly meant parameterizing the config-emitting CLI, so to avoid a split architecture (one config rendered from code, the rest read from data files) all bundled configs are now rendered from code.

• CamillaDSP playback format is now a CLI flag (--playback-format), defaulting to S32LE, and provisioning passes S16LE for HDMI. Many HDMI sinks (TVs, AVRs) reject 32-bit PCM and respond with silence/dropouts. audera {player,streamer} conf camilladsp.yml --playback-format {S16LE,S32LE} (added to both conf subparsers in audera/cli/audera.py, threaded through commands.py) selects the format; os/dietpi/{player,streamer}/automation/setup.sh passes S16LE when --audio-device hdmi is set, via a new camilladsp_playback_format helper in os/dietpi/lib/config.sh, and S32LE otherwise. This loses no quality — the pipeline's effective ceiling is already 16-bit/48 kHz (ADR 002), so the 32-bit playback path is lossless zero-padding. The capture format stays S32LE regardless, to match Snapclient's 32-bit loopback output.
• dtoverlay=vc4-kms-v3d → vc4-fkms-v3d in the hdmi) branch of configure_audio_device() (os/dietpi/lib/config.sh). Full KMS ignores the legacy hdmi_* config.txt settings the same branch writes; firmware-KMS honors them, which headless HDMI audio needs. The hdmi_*, dtparam=audio=on, and vc4.force_hotplug=3 lines are unchanged.
• All bundled configs moved from audera/conf/ data files into audera/cli/conf.py render functions (render_camilladsp, render_snapserver, render_asound) — a single source of truth. commands.py dispatches by filename to the render functions instead of reading files via importlib.resources. The embedded content is reproduced byte-for-byte verbatim: each render was generated programmatically from the originals' read_text() output and diffed against git HEAD (CRLF-normalized to match read_text() behavior) — the snapserver, asound, and both (byte-identical) camilladsp originals all match, and the S16LE variant changes only the single playback-format line.
• Deleted the audera/conf/ directory (player/camilladsp.yml, streamer/{asound.conf,camilladsp.yml,snapserver.conf}); nothing else reads them and hatchling ships audera regardless.
• Tests & fixtures migrated. tests/conftest.py's snapserver_container fixture now writes conf.render_snapserver() to a tmp_path_factory file and mounts that (also validating the render against a real snapserver). tests/cli/test_commands.py drops the importlib.resources mocking in favor of asserting real render output, including parameterized camilladsp cases: default → playback + capture both S32LE; S16LE → playback S16LE, capture still S32LE, HDMI STABILITY comment preserved.
• Docs. ADR 003 gains a "HDMI playback uses S16LE" subsection; ADRs 001/002/003 update their audera/conf/* path references to the audera/cli/conf.py render functions; docs/dev/CLI.md documents the --playback-format flag; docs/dev/PROVISION.md extends the -a, --audio-device row (hdmi uses vc4-fkms-v3d and S16LE).
• A scoped [tool.ruff.lint.per-file-ignores] entry exempts audera/cli/conf.py from E501/W291/W293, since the embedded config content must preserve long lines and trailing/blank-line whitespace verbatim.

Test plan

• uv run ruff check --fix — clean
• uv run ruff format — clean
• uv run ty check — clean
• uv run pytest tests/ui/test_streamer.py -v — 27 passed
• uv run pytest tests/clients/test_camilladsp.py::test_percent_to_db tests/clients/test_camilladsp.py::test_db_to_percent -v — 2 passed (pure math, no Docker)
• uv run pytest tests/dal/ tests/models/test_dsp.py -v — 63 passed, no regressions
• uv run pytest tests/cli/test_commands.py -v — rewritten + new render cases pass (no Docker)
• Byte-equivalence: each audera/cli/conf.py render diffed against git HEAD:audera/conf/* (CRLF-normalized) — empty diff for snapserver, asound, and both camilladsp originals

Manual end-to-end on the streamer (percent drag, dB round-trip across mode switches, mid-range dB edit stays unmuted through the 10s refresh, far-left floor mutes/unmutes) still to be exercised on-device. HDMI-specific manual verification (config.txt shows dtoverlay=vc4-fkms-v3d; /etc/camilladsp/config.yml shows format: S16LE under playback: / S32LE under capture: after provisioning with --audio-device hdmi) still to be exercised on-device.

🤖 Generated with Claude Code