fader_master/checklist.md

19 KiB

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

  • 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.)
  • Run pactl info and confirm Server Name contains PulseAudio (on PipeWire ...) rather than reporting a connection error.
  • 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.
  • Start continuous playback in a disposable application or browser tab.
  • Record that application's current volume and mute state so you can restore them after testing.

Discovery and metadata

  • Run cargo run --locked -p volume_lib --example pulse_fixture -- list.
  • Confirm the playing application appears with a numeric index, useful application/binary metadata, one or more channel gains, mute state, and writable=true.
  • 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.

  • Run cargo run --locked -p volume_lib --example pulse_fixture -- volume INDEX 0.35.
  • Confirm the application audibly changes and the command prints a readback whose loudest channel is approximately 0.35.
  • If the stream has unequal left/right gains, confirm their balance remains unequal in the same proportion after the change.
  • Run cargo run --locked -p volume_lib --example pulse_fixture -- mute INDEX on and confirm audio is muted without changing its channel gains.
  • 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

  • In one terminal run cargo run --locked -p volume_lib --example pulse_fixture -- watch 30.
  • During those 30 seconds, change the application's volume and mute state in your desktop mixer; confirm each change produces an updated fixture line.
  • 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. : 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.
  • 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:

    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:

    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. 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.

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. 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") }) }
  • 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. 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

  • Start playback in at least two applications whose volume can safely be changed, and record their original volume/mute states.

  • In terminal 1, run:

    cargo run --locked -p fader_master -- serve \
      --config examples/profiles/desktop.toml --audio pulse
    
  • Confirm it prints serving profile=desktop backend=pulse and remains running without changing any application volume at startup.

  • Attempt the same command in another terminal and confirm it refuses to start a second server.

  • 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

  • In terminal 2, run cargo run --locked -p fader_master -- tui.
  • 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.
  • Use ↑/↓ or k/j to select different application streams.
  • 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.
  • Press m twice. Confirm the selected application mutes and unmutes without changing its volume.
  • Change volume and mute externally in the desktop mixer. Confirm the TUI refreshes to the external values without emitting a compensating write.
  • Stop and restart one playback application. Confirm its row disappears and a fresh row appears without crashing or reusing stale state.
  • 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

  • Stop terminal 1 with Ctrl-C, then start it once more. Confirm the stale socket is recovered automatically and the new server reaches ready.
  • Restore the applications' original volume and mute states.
  • 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

  • Start Qobuz playback and, if available, audio in Firefox, Chromium, Chrome, Brave, or Librewolf. Record their current volume and mute values.

  • In terminal 1 run:

    cargo run --locked -p fader_master -- serve \
      --config examples/profiles/arch-pipewire.toml --audio pulse
    
  • Confirm startup does not change either application's volume or mute.

  • 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.

  • 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

  • In terminal 2 run cargo run --locked -p fader_master -- tui and confirm the three rows are labeled as two applications and one group.
  • Select Music, press ← or → once, and confirm Qobuz changes while the browser does not.
  • Select Browser, press m twice, and confirm only browser audio mutes and unmutes. Skip this item if no browser stream is matched.
  • 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.
  • Select Media group and press ← or → once. Confirm both applications converge to the same displayed volume because this profile uses volume_mode = "absolute".
  • 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.
  • 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.
  • Restart Qobuz and confirm the existing Music row becomes live again.

Layout, lifecycle, and report

  • Resize the terminal both narrower/shorter and wider/taller. Confirm no panic or corrupt terminal, and that moving selection keeps the selected row visible.
  • Quit and reopen the TUI while the server remains running. Confirm the current group/application state is resynchronized on attach.
  • Restore the original application volumes and mute states, then stop the server with Ctrl-C.
  • 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 verifies server-owned MIDI discovery and hotplug recovery. MIDI messages are deliberately not routed to audio yet, so moving controls must not change application volume during this test.

Connection and hotplug

  • Connect the APC MINI and start the server with the Arch profile:

    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 -- status. Confirm it contains device=apc-mini, status=connected, a backend ID such as 36:0, and error=None.

  • Move several APC controls and confirm the server stays running and no application volume or mute changes. Routing is intentionally inactive here.

  • 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

  • Stop the server, run cargo run --locked -p midi --example midi_monitor -- list, and note the APC index.
  • 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.
  • 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.
  • 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.