fader_master/checklist.md

213 lines
10 KiB
Markdown

# Functional Pulse milestone checklist (Arch Linux + PipeWire)
This checklist validates the first real-audio milestone against your Arch user
audio session. The fixture uses Arch's `libpulse` client library to talk to
PipeWire's `pipewire-pulse` compatibility service; it does not install or run the
standalone PulseAudio server, and it does not parse or invoke `pactl`. It changes
only the sink-input index you explicitly select and refuses amplification above
unity.
## Preparation
- [x] Install or confirm the Arch packages used by this milestone:
`sudo pacman -S --needed base-devel pkgconf libpulse pipewire-audio pipewire-pulse wireplumber`.
(`libpulse` is the Arch package name; there is no separate `libpulse-dev`.)
- [x] Run `pactl info` and confirm `Server Name` contains
`PulseAudio (on PipeWire ...)` rather than reporting a connection error.
- [x] If that check fails, inspect the user units with
`systemctl --user status pipewire pipewire-pulse wireplumber --no-pager`.
PipeWire normally starts them through user socket activation, so do not enable
or start the standalone `pulseaudio` service.
- [x] Start continuous playback in a disposable application or browser tab.
- [x] Record that application's current volume and mute state so you can restore
them after testing.
## Discovery and metadata
- [x] Run `cargo run --locked -p volume_lib --example pulse_fixture -- list`.
- [x] Confirm the playing application appears with a numeric `index`, useful
application/binary metadata, one or more channel gains, mute state, and
`writable=true`.
- [x] Note whether any native-only PipeWire playback nodes are absent. This
milestone intentionally sees the streams exposed through `pipewire-pulse`;
direct native-PipeWire discovery belongs to the later native adapter milestone.
## Confirmed volume and mute control
Replace `INDEX` below with the selected sink-input index.
- [x] Run `cargo run --locked -p volume_lib --example pulse_fixture -- volume INDEX 0.35`.
- [x] Confirm the application audibly changes and the command prints a readback
whose loudest channel is approximately `0.35`.
- [x] If the stream has unequal left/right gains, confirm their balance remains
unequal in the same proportion after the change.
- [x] Run `cargo run --locked -p volume_lib --example pulse_fixture -- mute INDEX on`
and confirm audio is muted without changing its channel gains.
- [x] Run `cargo run --locked -p volume_lib --example pulse_fixture -- mute INDEX off`
and confirm audio returns at the prior gain.
## External changes and lifecycle
- [x] In one terminal run
`cargo run --locked -p volume_lib --example pulse_fixture -- watch 30`.
- [x] During those 30 seconds, change the application's volume and mute state in
your desktop mixer; confirm each change produces an updated fixture line.
- [x] Stop and restart playback; confirm the watcher reports removal and then a
newly discovered sink input without crashing.
- [ ] When interrupting audio is acceptable, run
`systemctl --user restart pipewire pipewire-pulse wireplumber`, then repeat the
watch. A clean connection error is acceptable for this bounded fixture; record
it so reconnect behavior can be verified in the full worker integration.
## Restore and report
- [ ] Restore the application's original volume and mute state.
- [ ] Run `cargo test --workspace --all-targets --all-features --locked` and
confirm it passes with your native libpulse installation.
- [ ] Report the `Server Name` shown by `pactl info` and any unchecked or failed
item, including the fixture's exact error text.
## Owned Pulse worker milestone
These checks exercise the new bounded worker path rather than the direct client
used by the earlier commands.
- [ ] Start playback, then run
`cargo run --locked -p volume_lib --example pulse_fixture -- worker-watch 30`.
- [ ] Confirm the output starts with `Ready`, contains one `SnapshotBegin` and
one `SnapshotEnd`, and reports the playing stream through copied
`StreamMetadata` and `Observed` events.
- [ ] During the watch, change volume and mute in your desktop mixer and confirm
new `Observed` events contain the updated channel values and mute state.
- [ ] Stop and restart playback during another watch. Confirm `StreamRemoved` is
followed by a newly observed handle; if PipeWire reuses the numeric backend
ID, its `incarnation` must differ.
- [ ] Confirm the command exits normally without `Disconnected`, event-lane
overflow, or an owner-thread panic.
## Adapter selection milestone
These probes are read-only and do not alter the saved profile or live volumes.
- [ ] Run
`cargo run --locked -p volume_lib --example pulse_fixture -- probe auto`.
Confirm it prints `selected=pulse`, reports
`PulseAudio (on PipeWire ...)`, and lists application-stream, volume, mute,
and subscription capabilities as `true`.
- [ ] Run
`cargo run --locked -p volume_lib --example pulse_fixture -- probe pulse`
and confirm the explicit selection succeeds with the same server identity.
- [ ] Run
`cargo run --locked -p volume_lib --example pulse_fixture -- probe pipewire`.
This must fail with an actionable `not built`/`pipewire` feature diagnostic;
it must not silently select `pulse` after the manual request fails.
- [ ] Confirm none of these probe commands changes application volume or mute.
## Real-daemon integration fixture
- [ ] Confirm `paplay` is installed with `command -v paplay` and pause any audio
you do not want visible in the diagnostic output.
- [ ] Run the non-disruptive isolated-stream fixture:
```sh
cargo test --locked -p volume_lib --test pulse_daemon --all-features \
real_stream_commands_external_edits_and_churn_converge -- \
--ignored --exact --nocapture
```
- [ ] Confirm it passes after showing the uniquely named
`fader-master-fixture-*` stream converge through worker volume/mute commands,
external changes, removal, and replacement. Other streams may be listed but
must not be changed.
- [ ] Only when interrupting all desktop audio is acceptable, run:
```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
```
- [ ] Confirm the restart fixture observes a disconnect, reconnects with a new
backend epoch, completes a fresh snapshot, and that `pactl info` works again.
The fixture design and standalone-PulseAudio CI instructions are documented in
[`docs/pulse-daemon-fixture.md`](docs/pulse-daemon-fixture.md).
The main TUI is still explicitly backed by demo state at this milestone. Passing
this checklist validates the real Pulse control boundary that will feed the
server and live multi-application/group TUI; it does not yet validate MIDI or
the final TUI-to-server path.
# MIDI decode and input milestone checklist (Arch Linux)
This section validates M5.1 against a real controller. It only reads MIDI input;
it does not change application audio, send MIDI output, or save an assignment.
Persistent device matching, hotplug recovery, and MIDI feedback are later
milestones.
## MIDI preparation and discovery
- [ ] Confirm the Arch ALSA userspace library is installed:
`sudo pacman -S --needed alsa-lib`.
- [ ] Connect the controller and run
`cargo run --locked -p midi --example midi_monitor -- list`.
- [ ] Confirm the controller appears with an `index`, backend `id`, and readable
`name`. Ignore `Midi Through` unless that is intentionally the input under
test.
- [ ] Record the controller model/firmware and its reported `id` and `name` for
the M5.2 identity spike.
## Decode a real controller
Replace `INDEX` with the controller index from the list command.
- [ ] Run
`cargo run --locked -p midi --example midi_monitor -- watch INDEX 30`.
- [ ] Move an absolute fader or knob. Confirm `ControlChange` lines show the
expected 1-based channel and values spanning some or all of `0..127`.
- [ ] Press and release a note button. Confirm a nonzero note-on reports
`Press`, while note-off or note-on velocity zero reports `Release`.
- [ ] If the controller has a CC button, press and release it and confirm its
values move between nonzero and zero. CC button edge interpretation is tested
in the router even though the raw monitor intentionally displays CC values.
- [ ] If the controller sends MIDI clock or active sensing, confirm those
packets produce no lines and do not prevent supported controls from appearing.
- [ ] Confirm the command exits normally without `Malformed`, callback
disconnection, or `queue overflowed` errors.
## Hardware-free verification
- [ ] Run `cargo test --locked -p midi --all-targets --all-features`.
- [ ] Run `cargo test --locked -p midi --all-targets --no-default-features`.
- [ ] Confirm both pass. The second command proves decoding and binding remain
testable without an ALSA device or daemon.
## MIDI identity spike
These checks close M5.2. They do not save an assignment or test hotplug
reconnection yet.
- [ ] With one USB MIDI controller connected, run
`cargo run --locked -p midi --example midi_monitor -- list`.
- [ ] Confirm its `PortIdentity` includes the ALSA `backend_id`, port `name`,
four-digit USB `vendor_id` and `product_id`, and a udev `path`.
- [ ] If the device has a serial number, confirm `serial` is `Some(...)` and
record it. If it reports `None`, record that explicitly; this is valid device
metadata, not a probe failure.
- [ ] Disconnect and reconnect the controller to another USB socket. Record
which of the ALSA backend ID, udev path, and serial changed. A real serial
should remain stable while the physical path is expected to change.
- [ ] If two identical controllers are available, connect both and confirm they
have distinct serials or paths even when their port names and VID/PID match.
- [ ] If the identical controllers have no serials, swap their USB sockets and
confirm they cannot be identified independently of the sockets. This is the
intentional manual-assignment case: the server must show ambiguity rather
than choosing whichever ALSA port was enumerated first.
- [ ] Run `cargo test --locked -p midi --test identity --all-features` and
confirm the serial, path, ambiguity, and explicit-selection policy tests pass.
Report the controller model/firmware plus the complete `PortIdentity` lines.
Do not redact USB serials unless you prefer not to store them in the project
test record; a redacted but clearly stable/absent result is sufficient.