fader_master/checklist.md

4.3 KiB
Raw Blame History

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:

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:

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:

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.