From 661b0b105aafa05eeb244660aa1209f33a0de13e Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 04:33:32 +0200 Subject: [PATCH] docs: condense the M9 and M10 hardware checklist Validation: checklist commands and key bindings reviewed against the implemented CLI and TUI --- checklist.md | 179 +++++++++++++++++++++++---------------------------- 1 file changed, 79 insertions(+), 100 deletions(-) diff --git a/checklist.md b/checklist.md index 3598ab8..2f8c898 100644 --- a/checklist.md +++ b/checklist.md @@ -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.