fader_master/checklist.md

124 lines
5.6 KiB
Markdown

# fader_master hands-on checklist (Arch Linux + 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.
## Confirmed baseline
- [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:
```sh
cargo run --locked -p fader_master -- serve \
--config examples/profiles/arch-pipewire.toml --audio pulse
```
```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`.
## Pickup, routing, and output
- [ ] 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.
## Buffering and polling
- [ ] 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.
## Offline, disconnect, and recovery
- [ ] 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.
## Optional hardware coverage
- [ ] 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:
```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
```
## Report
- [ ] 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.