docs(M8.1): hand off the profile-aware TUI

Validation: git diff --cached --check
Gates: full workspace all-feature, default, no-default-feature, and isolated Pulse/midir matrices pass
Smoke: live PipeWire snapshot matched Qobuz into Music and Media group without writes
This commit is contained in:
Dandaedre 2026-10-15 01:17:51 +02:00
parent e57c8812bf
commit 25e61c2138
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
3 changed files with 78 additions and 8 deletions

View File

@ -9,9 +9,10 @@ Linux application volume and mute control from one or more USB MIDI surfaces.
This repository contains tested domain and configuration libraries, a PulseAudio
protocol worker compatible with `pipewire-pulse`, a local per-user server, and a
live terminal mixer. The domain layer supports matching, routing, balanced group
volume plans, and mute intent. Atomic TOML persistence and checkpointing are
implemented; profile aggregation, persistent MIDI lifecycle, and the
configuration editor remain on the ordered backlog:
volume plans, and mute intent. Atomic TOML persistence, checkpointing, and live
profile application/group aggregation are implemented; persistent MIDI
lifecycle, pickup/feedback, and the configuration editor remain on the ordered
backlog:
- [Architecture and library research](architecture.md)
- [Implementation tasks and acceptance tests](task.md)
@ -26,7 +27,7 @@ Start the server in one terminal:
```sh
cargo run --locked -p fader_master -- serve \
--config examples/profiles/desktop.toml --audio pulse
--config examples/profiles/arch-pipewire.toml --audio pulse
```
Then start the client in another:
@ -35,10 +36,10 @@ Then start the client in another:
cargo run --locked -p fader_master -- tui
```
Use Up/Down or J/K to select a live playback stream, Left/Right to change its
volume, M to toggle mute, and Q or Escape to quit. See the hands-on checklist for
the exact milestone scope and restoration steps. The current view lists raw
application streams; configured application/group aggregation follows in M8.1.
Use Up/Down or J/K to select a configured application or group, Left/Right to
change its volume, M to toggle mute, and Q or Escape to quit. Offline objects
remain visible, and aggregate rows show `MIXED` when member state differs. See
the hands-on checklist for the exact milestone scope and restoration steps.
# References

View File

@ -275,3 +275,63 @@ groups, pickup, MIDI status, and the editor remain later M8/M9 work.
- [x] Restore the applications' original volume and mute states.
- [x] Report any missing/mislabeled stream, wrong application being controlled,
visible error, layout corruption, or command that fails to converge.
# Profile-aware mixer TUI milestone (Arch Linux + PipeWire)
This checkpoint replaces raw playback-stream rows with stable configured
applications and groups. The supplied profile matches the Qobuz metadata
reported on this host and common Firefox/Chromium-family metadata. Startup is
still `adopt`: discovery must not change live audio.
## Start configured playback and server
- [ ] Start Qobuz playback and, if available, audio in Firefox, Chromium,
Chrome, Brave, or Librewolf. Record their current volume and mute values.
- [ ] In terminal 1 run:
```sh
cargo run --locked -p fader_master -- serve \
--config examples/profiles/arch-pipewire.toml --audio pulse
```
- [ ] Confirm startup does not change either application's volume or mute.
- [ ] Run `cargo run --locked -p fader_master -- status`. Confirm it reports
exactly three configured objects: `Music`, `Browser`, and `Media group`.
A stopped application must say `offline`; it must not vanish.
- [ ] Confirm `Music` is online while Qobuz plays. If a playing browser remains
offline, paste its earlier raw-stream metadata so its selector can be added.
## Exercise applications and the group
- [ ] In terminal 2 run `cargo run --locked -p fader_master -- tui` and confirm
the three rows are labeled as two applications and one group.
- [ ] Select `Music`, press `←` or `→` once, and confirm Qobuz changes while the
browser does not.
- [ ] Select `Browser`, press `m` twice, and confirm only browser audio mutes and
unmutes. Skip this item if no browser stream is matched.
- [ ] With both applications online, set their volumes to visibly different
values in the desktop mixer. Confirm `Media group` displays `MIXED` and its
meter represents the louder member.
- [ ] Select `Media group` and press `←` or `→` once. Confirm both applications
converge to the same displayed volume because this profile uses
`volume_mode = "absolute"`.
- [ ] Give the two applications different mute states externally. Confirm the
group displays `MIXED`; press `m` once to mute every member and again to
unmute every member without changing their gains.
- [ ] Stop Qobuz playback. Confirm `Music` remains visible as `OFFLINE`, the
group immediately reflects only its remaining browser member, and volume/mute
keys on the offline row show an error without affecting other audio.
- [ ] Restart Qobuz and confirm the existing `Music` row becomes live again.
## Layout, lifecycle, and report
- [ ] Resize the terminal both narrower/shorter and wider/taller. Confirm no
panic or corrupt terminal, and that moving selection keeps the selected row
visible.
- [ ] Quit and reopen the TUI while the server remains running. Confirm the
current group/application state is resynchronized on attach.
- [ ] Restore the original application volumes and mute states, then stop the
server with `Ctrl-C`.
- [ ] Report any unmatched application, wrong group member, unexpected startup
write, missing `MIXED`/`OFFLINE` indication, non-converging write, or layout
problem.

View File

@ -239,6 +239,15 @@ external-change refresh, stream churn, independent TUI exit/reconnect, and
terminal restoration against PipeWire 1.6.9. Terminal resize remains to be
checked alongside the next profile-aware TUI slice.
Profile-aware TUI verification on 2026-10-15: hardware-free tests cover stable
application/group rows, offline values, mixed gain/mute aggregation, group
write fan-out, pending state, stale-client resync, and small-terminal rendering.
A read-only live smoke run against PipeWire 1.6.9 matched the reported Qobuz
stream into `Music` and `Media group` while retaining `Browser` offline. All
workspace formatting, all-target/all-feature checks and tests, doctests, strict
Clippy, release build, default and no-default-feature tests, and isolated Pulse,
no-audio, midir, and no-MIDI feature checks pass on Rust 1.88.0.
## M9 — TUI configuration editor
Dependencies: M8, M2, M1.