docs: condense the M9 and M10 hardware checklist
Rust CI fader_master failed CI.
MadGobblins/fader_master/pipeline/head There was a failure building this commit Details

Validation: checklist commands and key bindings reviewed against the implemented CLI and TUI
This commit is contained in:
Dandaedre 2026-10-15 04:33:32 +02:00
parent 184cec90c7
commit 661b0b105a
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
1 changed files with 79 additions and 100 deletions

View File

@ -1,123 +1,102 @@
# fader_master hands-on checklist (Arch Linux + PipeWire)
# fader_master hands-on checklist (Arch + PipeWire)
This is the condensed hardware checklist. Automated Rust gates cover schema,
routing, buffering, IPC, failure paths, and rendering; this file keeps only
environment-specific behavior that benefits from your real PipeWire session,
APC MINI, applications, and terminal.
Automated tests cover validation, buffering, IPC, rollback, rendering, and
atomic persistence. This checklist is only for behavior requiring your real
PipeWire session, APC MINI, applications, and terminal.
## Confirmed baseline
## Setup
- [x] PipeWire Pulse compatibility is available as
`PulseAudio (on PipeWire 1.6.9)` through Arch's `libpulse` package.
- [x] Pulse discovery, confirmed volume/mute writes, external notifications,
stream churn, worker ownership, and reconnect epochs work against the real
daemon.
- [x] Qobuz matches Music and Waterfox matches Browser; Media is their absolute
sync group.
- [x] The default Scarlett Solo output appears as Master without changing audio
during startup.
- [x] APC MINI identity is stable through USB serial `Ver00.10` with VID:PID
`09e8:0028`; its physical path may change between USB sockets.
- [x] Application/group mute controls, local TUI responsiveness, terminal
resize, all built-in themes, and offline Browser input are functional.
- [x] Starting the server does not restore or overwrite live volume by default.
## Current profile and controls
Use [examples/profiles/arch-pipewire.toml](examples/profiles/arch-pipewire.toml).
The shared server/Pulse polling interval is configured under `[runtime]` and
accepts `poll_interval_ms = 1..100` (`10` by default).
| Target | Volume | Mute |
| --- | ---: | ---: |
| Music / Qobuz | CC 48 | Note 64 |
| Browser | CC 49 | Note 65 |
| Media sync group | CC 50 | Note 66 |
| Default output / Master | CC 56 | Note 98 |
Start or restart both processes from the current build after an IPC/profile
change:
Use a disposable profile directory so editor Save does not modify tracked
examples:
```sh
work=/tmp/fader-master-check
mkdir -p "$work"
cp examples/profiles/{arch-pipewire,desktop}.toml "$work/"
cargo run --locked -p fader_master -- serve \
--config examples/profiles/arch-pipewire.toml --audio pulse
--config "$work/arch-pipewire.toml" --audio pulse
```
In another terminal:
```sh
cargo run --locked -p fader_master -- tui
```
- [ ] Confirm startup prints `backend=pulse poll=10ms`, the TUI shows Music,
Browser, Media, and Master, and the APC MINI status includes its backend ID.
- [ ] Confirm mapped online rows initially show `pickup: waiting`; after crossing
the live value they show `pickup: tracking`.
Known mappings: Music `CC48/Note64`, Browser `CC49/Note65`, Media sync
`CC50/Note66`, and Master `CC56/Note98`. The profile polling interval is 10 ms
and accepts 1–100 ms.
## Pickup, routing, and output
## Mixer smoke test
- [ ] From below the live values, cross CC 48 and CC 49 slowly. Confirm there is
no initial jump and only the corresponding application follows each fader.
- [ ] With Music and Browser at different values, cross CC 50. Confirm both Media
members converge to the same absolute value.
- [ ] Cross CC 56. Confirm Master follows while application-row gains stay
unchanged; Note 98 must mute only the output.
- [ ] Change Music and Master externally. Confirm their rows return to
`pickup: waiting`, movement cannot snap either value back before crossing,
and `pickup: tracking` returns after crossing.
- [ ] Move unassigned controls. Confirm no configured target changes and the
server remains alive.
- [ ] If another output is available, change the desktop default. Confirm Master
adopts it without writing either output and requires pickup against the new
live value.
- [ ] TUI shows Music, Browser, Media, Master, and the APC backend ID; startup
does not change any live volume or mute.
- [ ] CC48/49 control only their applications; CC50 sets both Media members to
one absolute value; CC56/Note98 affect only the default output.
- [ ] Pickup starts `waiting`, becomes `tracking` only after crossing the live
value, and returns to `waiting` after an external volume change.
- [ ] A rapid fader sweep stays responsive and converges to its last position;
rapid double mute presses preserve both edges.
- [ ] With Browser offline, its controls are nonfatal and are not replayed when
Browser starts.
## Buffering and polling
## Config tab and MIDI learn
- [ ] Sweep CC 48 rapidly for several seconds and stop distinctly. Confirm the
UI/audio follow smoothly enough for use and converge to the final position
within about one second without replaying a long intermediate backlog.
- [ ] Repeat with CC 56, then move CC 48 and CC 49 in quick alternation. Confirm
each target converges independently.
- [ ] Double-press Notes 64 and 98 rapidly. Confirm both targets return to their
original mute state with no lost or duplicate edge.
- [ ] Compare `poll_interval_ms` values `10`, `5`, and `2`, restarting the server
each time. Record responsiveness, CPU impact, and the lowest useful value.
- [ ] Hold a TUI volume key while navigating/resizing. Confirm drawing remains
responsive and the final displayed value becomes the confirmed audio value.
Press `Tab` (or `2`) for Config. Inputs use `|` separators:
## Offline, disconnect, and recovery
- `A`: `id|label|field|exact/regex|pattern`
- `G`: `id|label|member1,member2`
- `F`: `id|application/group/output|target|yes/no`
- `D`: `application/group/fader|id`
- `L`: `surface|fader|volume/toggle_mute`; `C` cancels learn
- `P` applies the draft live; `S` saves it
- [ ] Start the TUI with no server/socket. Confirm it stays open with an internal
missing-socket diagnostic, then connects automatically when the server starts.
- [ ] While Browser is offline, move CC 49 and press Note 65 repeatedly. Confirm
no fatal server error; start Browser and confirm offline actions are not
replayed.
- [ ] Stop the server while the TUI is open. Confirm it retains its last rows,
remains responsive, shows the error internally, and resynchronizes after a
server restart without replaying disconnected actions.
- [ ] Unplug the APC MINI. Confirm the server/TUI remain alive and show
`missing — connect device`; reconnect it and confirm the backend ID/status and
pickup behavior recover.
- [ ] Run `cargo run --locked -p fader_master -- status` after the stress checks
and confirm `status=ready` with the expected final values.
- [ ] With `F`, add `browser-test|application|browser|yes`; with `G`, add
`test-group|Test group|browser,music`. Invalid IDs, regexes, or members show
an error without changing the draft revision.
- [ ] Press `Esc` during an input and confirm nothing changes. Try deleting a
referenced application and confirm it is rejected.
- [ ] Learn an unused APC control for `browser-test`, confirm the old mapped
controls still route normally during learn, and confirm `C` restores normal
routing without an assignment.
- [ ] Apply with `P`: the Config header's live revision catches the draft
revision, no audio jumps, and the new fader works after pickup.
- [ ] Save with `S`, restart from `/tmp/fader-master-check/arch-pipewire.toml`,
and confirm the edit and any existing TOML comments remain.
- [ ] Conflict check: make another draft edit, modify the disposable TOML in an
editor, then press `S`. Confirm the external file is untouched and the TUI
keeps an unsaved draft with a visible conflict.
## Optional hardware coverage
## Profile switching and recovery
- [ ] If two identical controllers are available, confirm distinct serial/path
identities where possible.
- [ ] For identical serial-less controllers, swap USB sockets and confirm they
remain explicitly ambiguous instead of being assigned by enumeration order.
- [ ] Only when interrupting desktop audio is acceptable, rerun the PipeWire
restart fixture:
Both disposable profiles are siblings, so while the server is running:
```sh
FADER_MASTER_RESTART_PIPEWIRE=1 \
cargo test --locked -p volume_lib --test pulse_daemon --all-features \
pipewire_restart_disconnects_and_a_new_epoch_resnapshots -- \
--ignored --exact --nocapture
```
```sh
cargo run --locked -p fader_master -- profile switch desktop
cargo run --locked -p fader_master -- profile switch arch-pipewire
```
## Report
- [ ] Each successful switch changes the profile shown in Config, preserves
observed live audio without a write, and requires pickup again.
- [ ] A missing/invalid profile reports an error and leaves the old profile
active. A switch attempted during pending fader work returns an actionable
retry error instead of crossing generations.
- [ ] Stop the server while TUI remains open: rows stay visible, the error is
internal to the TUI, and restart reconnects without replaying input.
- [ ] Unplug/replug APC MINI: server/TUI stay alive, status changes to
`missing — connect device`, and reconnection rearms pickup.
- [ ] Start TUI before the server and confirm it recovers automatically when the
socket appears.
- [ ] Restore disposable application/output volume and mute values.
- [ ] Report any jump before pickup, wrong target, rough movement at each polling
interval, stale value, missed/duplicate mute, persistent pending marker,
reconnect exceeding one second, terminal corruption, or process exit.
## Polling and report
- [ ] Compare `poll_interval_ms = 10`, `5`, and `2` (restart between values).
Record responsiveness, CPU impact, and the lowest useful value.
- [ ] Run `cargo run --locked -p fader_master -- status`; confirm `status=ready`
and expected final values.
- [ ] Report any pre-pickup jump, wrong target, rough sweep, stale/pending value,
lost mute edge, failed apply/save diagnostic, reconnect over one second,
terminal corruption, or process exit.
Explicit `profile switch --restore` is automated but remains optional for manual
testing until the MIDI output-feedback milestone is implemented.