docs(M4): add the real-audio acceptance checklist

Document the hands-on discovery, confirmed volume/mute, external-change, churn, and daemon lifecycle checks for the functional Pulse fixture. Restrict the fixture to unity-or-lower writes and link the checklist from the README.

Validation: full locked workspace formatting, all-target/all-feature checks and tests, doctests, strict Clippy, release build, and no-default-feature checks/tests pass; real user-session audio remains checklist verification.
This commit is contained in:
Dandaedre 2026-10-14 19:42:06 +02:00
parent e7067e277f
commit bb12fb14b1
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
3 changed files with 66 additions and 1 deletions

View File

@ -17,6 +17,7 @@ editor remain planned in the following documents:
- [Project-agent instructions and test/commit workflow](AGENTS.md)
- [Build prerequisites and MSRV](docs/build.md)
- [CI coverage and badge lifecycle](docs/ci-coverage.md)
- [Hands-on functional checklist](checklist.md)
## Run the TUI

64
checklist.md Normal file
View File

@ -0,0 +1,64 @@
# Functional Pulse milestone checklist
This checklist validates the first real-audio milestone against your user audio
session. The fixture talks to PulseAudio or PipeWire's `pipewire-pulse` service
through libpulse; it does not parse or invoke `pactl`. It changes only the sink
input index you explicitly select and refuses amplification above unity.
## Preparation
- [ ] Install the native build dependency (`libpulse-dev` on Debian/Ubuntu,
`libpulse-devel` on Fedora/openSUSE, or the equivalent for your distribution).
- [ ] Confirm your user audio service is running: `pactl info` should report a
server rather than a connection error.
- [ ] 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`.
- [ ] If using PipeWire, confirm `pactl info` identifies the PulseAudio-compatible
server and note whether any native-only PipeWire playback nodes are absent.
## 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.
- [ ] Repeat the watch once after restarting your PulseAudio or pipewire-pulse
user service. 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 your distribution, audio server shown by `pactl info`, and any
unchecked or failed item, including the fixture's exact error text.
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.

View File

@ -21,7 +21,7 @@ fn main() -> Result<(), Box<dyn Error>> {
if !current.volume_writable {
return Err(invalid_input("selected sink input is not volume-writable"));
}
let channels = current.channels.scaled_to(gain, Gain::new(4.0)?)?;
let channels = current.channels.scaled_to(gain, Gain::UNITY)?;
print_stream(&client.set_volume(index, &channels)?);
}
"mute" => {