338 lines
17 KiB
Markdown
338 lines
17 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.
|
|
- [x] 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
|
|
|
|
- [x] Restore the application's original volume and mute state.
|
|
- [x] Run `cargo test --workspace --all-targets --all-features --locked` and
|
|
confirm it passes with your native libpulse installation.
|
|
- [x] Report the `Server Name` shown by `pactl info` and any unchecked or failed
|
|
item, including the fixture's exact error text. : PulseAudio (on PipeWire 1.6.9)
|
|
|
|
## 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`.
|
|
- [x] Confirm the output starts with `Ready`, contains one `SnapshotBegin` and
|
|
one `SnapshotEnd`, and reports the playing stream through copied
|
|
`StreamMetadata` and `Observed` events.
|
|
- [x] During the watch, change volume and mute in your desktop mixer and confirm
|
|
new `Observed` events contain the updated channel values and mute state.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
- [x] 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`.
|
|
- [x] Run
|
|
`cargo run --locked -p volume_lib --example pulse_fixture -- probe pulse`
|
|
and confirm the explicit selection succeeds with the same server identity.
|
|
- [x] 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.
|
|
- [x] Confirm none of these probe commands changes application volume or mute.
|
|
|
|
## Real-daemon integration fixture
|
|
|
|
- [x] Confirm `paplay` is installed with `command -v paplay` and pause any audio
|
|
you do not want visible in the diagnostic output.
|
|
- [x] 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
|
|
```
|
|
|
|
- [x] 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
|
|
```
|
|
|
|
- [x] Confirm the restart fixture observes a disconnect, reconnects with a new
|
|
backend epoch, completes a fresh snapshot, and that `pactl info` works again.
|
|
running 1 test
|
|
fixture snapshot event: SnapshotBegin(BackendEpoch(20))
|
|
fixture snapshot event: StreamMetadata { stream: StreamHandle { epoch: BackendEpoch(20), backend_id: 162, incarnation: 1 }, metadata: StreamMetadata { application_name: Some("PipeWire ALSA [qbz]"), application_id: None, process_binary: None, media_name: Some("ALSA Playback"), raw: {} }, volume_writable: true }
|
|
fixture snapshot event: Adapter(Observed { stream: StreamHandle { epoch: BackendEpoch(20), backend_id: 162, incarnation: 1 }, channels: ChannelGains([Gain(0.050650994655370596), Gain(0.050650994655370596)]), muted: Unmuted, operation: None })
|
|
fixture observed expected disconnect: PulseAudio context entered state Failed
|
|
fixture snapshot event: SnapshotBegin(BackendEpoch(21))
|
|
test pipewire_restart_disconnects_and_a_new_epoch_resnapshots ... ok
|
|
|
|
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 1.90s
|
|
|
|
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
|
|
|
|
- [x] Confirm the Arch ALSA userspace library is installed:
|
|
`sudo pacman -S --needed alsa-lib`.
|
|
- [X] Connect the controller and run
|
|
`cargo run --locked -p midi --example midi_monitor -- list`.
|
|
index=1 identity=PortIdentity { backend_id: "36:0", name: "APC MINI:APC MINI MIDI 1 36:0", usb: Some(UsbDeviceIdentity { vendor_id: "09e8", product_id: "0028", serial: Some("Ver00.10"), path: Some("pci-0000:0f:00.4-usb-0:1.4.4:1.0") }) }
|
|
- [x] Confirm the controller appears with an `index`, backend `id`, and readable
|
|
`name`. Ignore `Midi Through` unless that is intentionally the input under
|
|
test.
|
|
- [x] 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.
|
|
|
|
- [x] Run
|
|
`cargo run --locked -p midi --example midi_monitor -- watch INDEX 30`.
|
|
- [x] Move an absolute fader or knob. Confirm `ControlChange` lines show the
|
|
expected 1-based channel and values spanning some or all of `0..127`.
|
|
- [x] Press and release a note button. Confirm a nonzero note-on reports
|
|
`Press`, while note-off or note-on velocity zero reports `Release`.
|
|
- [x] 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.
|
|
- [x] If the controller sends MIDI clock or active sensing, confirm those
|
|
packets produce no lines and do not prevent supported controls from appearing.
|
|
- [x] Confirm the command exits normally without `Malformed`, callback
|
|
disconnection, or `queue overflowed` errors.
|
|
|
|
## Hardware-free verification
|
|
|
|
- [x] Run `cargo test --locked -p midi --all-targets --all-features`.
|
|
- [x] Run `cargo test --locked -p midi --all-targets --no-default-features`.
|
|
- [x] 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.
|
|
|
|
- [x] With one USB MIDI controller connected, run
|
|
`cargo run --locked -p midi --example midi_monitor -- list`.
|
|
- [x] Confirm its `PortIdentity` includes the ALSA `backend_id`, port `name`,
|
|
four-digit USB `vendor_id` and `product_id`, and a udev `path`.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
index=1 identity=PortIdentity { backend_id: "36:0", name: "APC MINI:APC MINI MIDI 1 36:0", usb: Some(UsbDeviceIdentity { vendor_id: "09e8", product_id: "0028", serial: Some("Ver00.10"), path: Some("pci-0000:0d:00.0-usb-0:2.3:1.0") }) }
|
|
|
|
# First live TUI milestone checklist (Arch Linux + PipeWire)
|
|
|
|
This is the first TUI that needs hands-on testing. It controls real application
|
|
streams through the persistent local server and `pipewire-pulse`. For this
|
|
slice, rows are raw playback streams; configured application aggregation,
|
|
groups, pickup, MIDI status, and the editor remain later M8/M9 work.
|
|
|
|
## Start the server
|
|
|
|
- [x] Start playback in at least two applications whose volume can safely be
|
|
changed, and record their original volume/mute states.
|
|
- [x] In terminal 1, run:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- serve \
|
|
--config examples/profiles/desktop.toml --audio pulse
|
|
```
|
|
|
|
- [x] Confirm it prints `serving profile=desktop backend=pulse` and remains
|
|
running without changing any application volume at startup.
|
|
- [x] Attempt the same command in another terminal and confirm it refuses to
|
|
start a second server.
|
|
- [x] Run `cargo run --locked -p fader_master -- status` and confirm it reports
|
|
`status=ready` plus the currently playing streams with sensible labels,
|
|
gains, mute state, and `writable=true`.
|
|
|
|
## Exercise the live mixer
|
|
|
|
- [x] In terminal 2, run `cargo run --locked -p fader_master -- tui`.
|
|
- [x] Confirm the header shows `pulse · ready`, and each playing application
|
|
appears as a separate row with its current volume and mute state.
|
|
- [ ] Resize the terminal smaller and larger. Confirm borders remain intact and
|
|
the selected row remains visible without a panic.
|
|
- [x] Use `↑`/`↓` or `k`/`j` to select different application streams.
|
|
- [x] On a disposable stream, use `←`/`→` to change volume. Confirm only that
|
|
selected application changes, channel balance is preserved, and the displayed
|
|
value converges to the desktop mixer's readback.
|
|
- [x] Press `m` twice. Confirm the selected application mutes and unmutes without
|
|
changing its volume.
|
|
- [x] Change volume and mute externally in the desktop mixer. Confirm the TUI
|
|
refreshes to the external values without emitting a compensating write.
|
|
- [x] Stop and restart one playback application. Confirm its row disappears and
|
|
a fresh row appears without crashing or reusing stale state.
|
|
- [x] Press `q` or `Esc`. Confirm the terminal is restored and terminal 1 keeps
|
|
serving; `cargo run --locked -p fader_master -- status` must still work.
|
|
|
|
## Finish and report
|
|
|
|
- [x] Stop terminal 1 with `Ctrl-C`, then start it once more. Confirm the stale
|
|
socket is recovered automatically and the new server reaches `ready`.
|
|
- [x] Restore the applications' original volume and mute states.
|
|
- [x] Report any missing/mislabeled stream, wrong application being controlled,
|
|
visible error, layout corruption, or command that fails to converge.
|
|
|
|
# Profile-aware mixer TUI milestone (Arch Linux + PipeWire)
|
|
|
|
This checkpoint replaces raw playback-stream rows with stable configured
|
|
applications and groups. The supplied profile matches the Qobuz metadata
|
|
reported on this host and common Firefox/Chromium-family metadata. Startup is
|
|
still `adopt`: discovery must not change live audio.
|
|
|
|
## Start configured playback and server
|
|
|
|
- [x] Start Qobuz playback and, if available, audio in Firefox, Chromium,
|
|
Chrome, Brave, or Librewolf. Record their current volume and mute values.
|
|
- [x] In terminal 1 run:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- serve \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
- [x] Confirm startup does not change either application's volume or mute.
|
|
- [x] Run `cargo run --locked -p fader_master -- status`. Confirm it reports
|
|
exactly three configured objects: `Music`, `Browser`, and `Media group`.
|
|
A stopped application must say `offline`; it must not vanish.
|
|
- [x] Confirm `Music` is online while Qobuz plays. If a playing browser remains
|
|
offline, paste its earlier raw-stream metadata so its selector can be added.
|
|
|
|
## Exercise applications and the group
|
|
|
|
- [x] In terminal 2 run `cargo run --locked -p fader_master -- tui` and confirm
|
|
the three rows are labeled as two applications and one group.
|
|
- [x] Select `Music`, press `←` or `→` once, and confirm Qobuz changes while the
|
|
browser does not.
|
|
- [x] Select `Browser`, press `m` twice, and confirm only browser audio mutes and
|
|
unmutes. Skip this item if no browser stream is matched.
|
|
- [x] With both applications online, set their volumes to visibly different
|
|
values in the desktop mixer. Confirm `Media group` displays `MIXED` and its
|
|
meter represents the louder member.
|
|
- [x] Select `Media group` and press `←` or `→` once. Confirm both applications
|
|
converge to the same displayed volume because this profile uses
|
|
`volume_mode = "absolute"`.
|
|
- [x] Give the two applications different mute states externally. Confirm the
|
|
group displays `MIXED`; press `m` once to mute every member and again to
|
|
unmute every member without changing their gains.
|
|
- [x] Stop Qobuz playback. Confirm `Music` remains visible as `OFFLINE`, the
|
|
group immediately reflects only its remaining browser member, and volume/mute
|
|
keys on the offline row show an error without affecting other audio.
|
|
- [x] Restart Qobuz and confirm the existing `Music` row becomes live again.
|
|
|
|
## Layout, lifecycle, and report
|
|
|
|
- [x] Resize the terminal both narrower/shorter and wider/taller. Confirm no
|
|
panic or corrupt terminal, and that moving selection keeps the selected row
|
|
visible.
|
|
- [x] Quit and reopen the TUI while the server remains running. Confirm the
|
|
current group/application state is resynchronized on attach.
|
|
- [x] Restore the original application volumes and mute states, then stop the
|
|
server with `Ctrl-C`.
|
|
- [x] Report any unmatched application, wrong group member, unexpected startup
|
|
write, missing `MIXED`/`OFFLINE` indication, non-converging write, or layout
|
|
problem.
|