618 lines
31 KiB
Markdown
618 lines
31 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.
|
|
|
|
# APC MINI lifecycle and mapping checkpoint
|
|
|
|
This checkpoint originally verified server-owned MIDI discovery and hotplug
|
|
recovery before routing was enabled. The later live-routing checkpoint now
|
|
supersedes its control-movement expectation.
|
|
|
|
## Connection and hotplug
|
|
|
|
- [x] Connect the APC MINI and start the server with the Arch profile:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- serve \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
- [x] In another terminal run `cargo run --locked -p fader_master -- status`.
|
|
Confirm it contains `device=apc-mini`, `status=connected`, a backend ID such
|
|
as `36:0`, and `error=None`.
|
|
- [ ] Move only unassigned APC controls and confirm the server stays running and
|
|
application volume or mute does not change. The six assigned controls are
|
|
listed in the live-routing checkpoint below and are expected to change audio.
|
|
- [ ] Unplug the APC MINI, wait two seconds, and run `status` again. Confirm the
|
|
device remains listed as `status=missing` while audio objects remain usable.
|
|
- [ ] Reconnect it, optionally through another USB socket, wait two seconds, and
|
|
confirm it returns to `status=connected`. A changed ALSA backend ID is valid;
|
|
the serial-first assignment must still resolve it.
|
|
|
|
## Record controls for the pickup-safe routing slice
|
|
|
|
- [x] Stop the server, run
|
|
`cargo run --locked -p midi --example midi_monitor -- list`, and note the APC
|
|
index.
|
|
- [x] Run `cargo run --locked -p midi --example midi_monitor -- watch INDEX 30`
|
|
and move the physical fader you want assigned to `Media group`. Record its
|
|
`ControlChange` channel and number plus the endpoint values it reports.
|
|
- [x] During another watch, press and release the button you want assigned to
|
|
group mute. Record whether it is `Note` or `ControlChange`, its channel and
|
|
number, and the press/release values.
|
|
- [x] Report those two mappings and any connection, hotplug, or unexpected audio
|
|
behavior. They will be added to the profile before MIDI-to-audio routing is
|
|
enabled.
|
|
|
|
# APC MINI live routing and pickup checkpoint
|
|
|
|
This checkpoint covers physical MIDI control of applications, their Media
|
|
group, and the actual default PipeWire/Pulse output. The Arch profile uses MIDI
|
|
channel 1 and the following assignments:
|
|
|
|
| Target | Volume fader | Mute button |
|
|
| --- | ---: | ---: |
|
|
| Music / Qobuz | CC 48 | Note 64 |
|
|
| Browser | CC 49 | Note 65 |
|
|
| Media group | CC 50 | Note 66 |
|
|
| Default output / Master | CC 56 | Note 98 |
|
|
|
|
The non-motorized faders use pickup. They must not change audio until their
|
|
physical position reaches or crosses the current live volume.
|
|
|
|
## Prepare and connect
|
|
|
|
- [x] Start Qobuz and browser playback. Set both volumes above 30%, unmute them,
|
|
and note their starting values.
|
|
- [x] Before starting the server, place faders 48, 49, and 56 at the bottom.
|
|
- [x] Start the server:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- serve \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
- [x] In another terminal start
|
|
`cargo run --locked -p fader_master -- tui`. Confirm Music, Browser, and Media
|
|
are online and the APC MINI is `connected`.
|
|
- [ ] Stop the server used for the earlier checks and restart it from the new
|
|
build. The IPC protocol changed for the output object, so an old server must
|
|
not remain attached to `/run/user/1000/fader_master/control.sock`.
|
|
- [ ] Confirm the restarted TUI has a fourth `Master [output]` row whose detail
|
|
names the current default output, such as the Scarlett Solo. Before moving
|
|
CC 50 or CC 56, place both physical faders at the bottom.
|
|
- [ ] Confirm server startup itself did not change any volume or mute state.
|
|
|
|
## Verify startup pickup and target isolation
|
|
|
|
- [ ] Move fader 48 slightly near the bottom. Confirm Music does not jump down.
|
|
Raise it slowly through Music's displayed starting volume; once crossed,
|
|
confirm Music follows the fader and Browser does not change.
|
|
- [ ] Repeat with fader 49. Confirm only Browser responds after its pickup point
|
|
is crossed.
|
|
- [ ] With Music and Browser at visibly different levels, move fader 50 slightly
|
|
near the bottom. Confirm neither application jumps. Cross the displayed Media
|
|
level and confirm both applications then follow the group fader and converge
|
|
to the same volume.
|
|
- [ ] Move an unassigned fader and press an unassigned button. Confirm neither
|
|
changes Music, Browser, or Media.
|
|
|
|
## Verify mute buttons
|
|
|
|
- [ ] Press and release button 64 once. Confirm Music toggles mute exactly once
|
|
and Browser is unchanged; press it again to restore Music.
|
|
- [ ] Repeat with button 65 and confirm only Browser toggles.
|
|
- [ ] Press button 66 once and confirm every online Media member is muted. Press
|
|
it again and confirm every member is unmuted without changing their gains.
|
|
|
|
## Verify the real output master
|
|
|
|
- [ ] Note the `Master` row's starting volume and the corresponding default
|
|
output value in the desktop mixer.
|
|
- [ ] Move fader 56 slightly near the bottom. Confirm the output volume does not
|
|
jump. Raise it through the displayed Master value; after crossing, confirm the
|
|
default output follows the fader while the Music and Browser application-row
|
|
gains remain unchanged.
|
|
- [ ] Press button 98 once. Confirm the default output mutes exactly once while
|
|
the application mute states remain unchanged. Press it again to restore the
|
|
output.
|
|
- [ ] After CC 56 is tracking, change the default output to a clearly different
|
|
volume in the desktop mixer. Move CC 56 without crossing that new value and
|
|
confirm it does not snap back; cross it and confirm tracking resumes.
|
|
- [ ] If another output is available, change the desktop's default output.
|
|
Confirm the Master row changes its device detail and adopts the new output's
|
|
live volume without modifying either output. Then verify CC 56 requires pickup
|
|
against the new output before it sends a write.
|
|
|
|
## Verify pickup rearming and hotplug
|
|
|
|
- [ ] After fader 48 is tracking, change Music to a clearly different volume in
|
|
the desktop mixer. Move fader 48 without crossing the new value and confirm it
|
|
does not snap Music back. Cross the new value and confirm tracking resumes.
|
|
- [ ] Unplug the APC MINI and wait two seconds. Confirm the server and TUI stay
|
|
alive, audio remains controllable from the TUI, and `status` reports the
|
|
device as `missing`.
|
|
- [ ] Reconnect the APC MINI, wait two seconds, and confirm it returns to
|
|
`connected`, even if its ALSA backend ID changes.
|
|
- [ ] Move a mapped fader without crossing its current live value and confirm no
|
|
volume jump occurs. Cross the live value and confirm control resumes.
|
|
- [ ] Restore the starting volume and mute states, stop the server, and report
|
|
any wrong target, duplicate button toggle, startup/reconnect/default-output
|
|
jump, or server error. Pickup state is not displayed explicitly in the TUI
|
|
yet, so judge this checkpoint by the observed audio values and behavior.
|
|
|
|
# Buffered interaction and synchronization checkpoint
|
|
|
|
This checkpoint exercises the new bounded command path. Volume motion may be
|
|
coalesced while an older audio request is in flight, but the final requested
|
|
value must always be applied. Mute presses are edges and must never be
|
|
coalesced. The TUI now updates its local view immediately while socket requests
|
|
run on a background thread.
|
|
|
|
## Restart on the new build
|
|
|
|
- [ ] Stop any server and TUI started from an older build.
|
|
- [ ] Start playback in Qobuz and a browser, then run:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- serve \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
- [ ] In another terminal run
|
|
`cargo run --locked -p fader_master -- tui` and confirm Music, Browser, Media,
|
|
and Master reach stable live values without a startup volume change.
|
|
|
|
## TUI responsiveness and local updates
|
|
|
|
- [ ] Select Music and hold `→` long enough to generate a burst of changes.
|
|
Confirm the displayed value responds immediately, shows pending work when
|
|
applicable, and the TUI continues to accept navigation and redraw normally.
|
|
- [ ] While volume work is pending, resize the terminal and move the selection
|
|
with `j`/`k`. Confirm neither input nor drawing freezes behind an audio or
|
|
socket round trip.
|
|
- [ ] Release the key and confirm Music settles at the final displayed value in
|
|
the desktop mixer within about one second; it must not walk through a long
|
|
backlog of every intermediate value.
|
|
- [ ] Repeat a short burst on Master. Confirm the default output converges while
|
|
the Music and Browser application gains remain unchanged.
|
|
|
|
## MIDI bursts and ordered buttons
|
|
|
|
- [ ] First cross the pickup point for CC 48, then sweep it rapidly back and
|
|
forth for several seconds. Stop at a distinct position and confirm Music
|
|
converges to that final position without freezing the server or TUI.
|
|
- [ ] Repeat with CC 56 and confirm only the default output Master converges.
|
|
- [ ] Move CC 48 and CC 49 in quick alternation. Confirm Music and Browser each
|
|
settle at their own final fader position; coalescing one target must not lose
|
|
the other target's update.
|
|
- [ ] Press button 64 twice quickly. Confirm Music returns to its original mute
|
|
state after exactly two toggles; no press may be lost or duplicated.
|
|
- [ ] Repeat the rapid double press with Master button 98 and confirm the output
|
|
returns to its original mute state without changing application mute states.
|
|
|
|
## Confirm synchronization and lifecycle
|
|
|
|
- [ ] Change Music volume externally in the desktop mixer while the controls
|
|
are idle. Confirm the TUI adopts the external value within roughly 250 ms and
|
|
does not write the old local value back.
|
|
- [ ] After that external change, move CC 48 without crossing the new value and
|
|
confirm pickup prevents a snap-back. Cross it, stop moving, and confirm the
|
|
final physical position wins and the pending indication clears.
|
|
- [ ] Quit the TUI immediately after a volume key press. Confirm it restores the
|
|
terminal cleanly, the server stays alive, and reopening the TUI shows the
|
|
confirmed final state.
|
|
- [ ] Run `cargo run --locked -p fader_master -- status` and confirm the server
|
|
still reports `status=ready` with the same final values.
|
|
- [ ] Report any persistent pending marker, missed/duplicate mute, value that
|
|
rebounds after settling, final value that takes more than about one second,
|
|
`buffered audio dispatch lane overflowed` error, or server/TUI freeze.
|
|
|
|
# Built-in TUI theme checkpoint
|
|
|
|
The server may remain running for these presentation-only checks. Close an old
|
|
TUI first so the client is rebuilt with the new theme support.
|
|
|
|
- [ ] Run
|
|
`cargo run --locked -p fader_master -- tui --theme dracula` and confirm the
|
|
header says `Dracula` and the background, borders, selection, and meters use
|
|
the purple/cyan palette.
|
|
- [ ] Press `t` repeatedly and confirm the header cycles through Nord, Gruvbox
|
|
Dark, Catppuccin Mocha, Solarized Dark, Default, and back to Dracula without
|
|
flicker, layout corruption, or lost selection.
|
|
- [ ] Confirm normal text, dim borders, the selected row, meter fill, and muted
|
|
warning color remain readable in every theme used by your terminal emulator.
|
|
- [ ] While on a non-default theme, navigate rows, change one disposable volume,
|
|
and toggle mute twice. Confirm theme switching is presentation-only and does
|
|
not interrupt control or synchronization.
|
|
- [ ] Quit and run `cargo run --locked -p fader_master -- tui`. Confirm Default
|
|
is selected when no `--theme` argument is supplied.
|
|
- [ ] Optionally launch each explicit name: `default`, `dracula`, `nord`,
|
|
`gruvbox-dark`, `catppuccin-mocha`, and `solarized-dark`. Report any palette
|
|
with poor contrast and include the terminal emulator plus its color settings.
|
|
|
|
# Disconnected server and offline target checkpoint
|
|
|
|
This checkpoint verifies that expected lifecycle failures remain visible but do
|
|
not terminate either side. Use the Arch PipeWire profile and leave the browser
|
|
closed initially so its configured application target is offline.
|
|
|
|
## Start the TUI before the server
|
|
|
|
- [ ] Stop every running `fader_master serve` process and confirm
|
|
`/run/user/1000/fader_master/control.sock` is absent.
|
|
- [ ] Run `cargo run --locked -p fader_master -- tui`. Confirm the TUI opens
|
|
instead of returning to the shell, shows `local IPC · waiting for server`, and
|
|
displays the missing-socket error inside the terminal.
|
|
- [ ] Leave that TUI open. In another terminal start:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- serve \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
- [ ] Confirm the existing TUI connects and populates its rows within roughly
|
|
one second without being restarted. Browser should remain present as
|
|
`offline`; Music, Media, and Master should reflect their actual live state.
|
|
|
|
## Exercise an offline mapped application
|
|
|
|
- [ ] While Browser is offline, move its CC 49 fader repeatedly and press its
|
|
Note 65 mute button several times. Confirm the server stays running and does
|
|
not print `mixer object Application "browser" is offline` as a fatal error.
|
|
- [ ] Confirm Music (CC 48 / Note 64) and Master (CC 56 / Note 98) remain
|
|
controllable. Run `cargo run --locked -p fader_master -- status` and confirm
|
|
it still reports the server state.
|
|
- [ ] Start browser playback. Confirm Browser becomes online automatically and
|
|
adopts its live volume without replaying any movement or mute press made while
|
|
it was offline.
|
|
- [ ] Move CC 49 without crossing the live Browser volume and confirm pickup
|
|
prevents a jump. Cross the live value and confirm Browser control begins.
|
|
|
|
## Lose and restore the server
|
|
|
|
- [ ] With the TUI still open, stop the server. Confirm the TUI stays open,
|
|
remains responsive to navigation, resizing, and theme changes, retains its
|
|
last confirmed rows, and shows the connection error inside the terminal.
|
|
- [ ] Restart the same server command. Confirm the TUI reconnects within roughly
|
|
one second and replaces the retained values with a fresh server snapshot.
|
|
- [ ] Confirm no queued volume or mute operation from the disconnected interval
|
|
is applied after reconnection, then perform one fresh control change and
|
|
verify it synchronizes normally.
|
|
- [ ] Report any process exit, terminal corruption, stale write after reconnect,
|
|
row loss, repeated error spam, or reconnection taking longer than one second.
|