fader_master/checklist.md

103 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# fader_master hands-on checklist (Arch + PipeWire)
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.
## Setup
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 "$work/arch-pipewire.toml" --audio pulse
```
In another terminal:
```sh
cargo run --locked -p fader_master -- tui
```
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.
## Mixer smoke test
- [ ] 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.
## Config tab and MIDI learn
Press `Tab` (or `2`) for Config. Inputs use `|` separators:
- `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
- [ ] 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.
## Profile switching and recovery
Both disposable profiles are siblings, so while the server is running:
```sh
cargo run --locked -p fader_master -- profile switch desktop
cargo run --locked -p fader_master -- profile switch arch-pipewire
```
- [ ] 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.
## 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.