213 lines
10 KiB
Markdown
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.
|