Text chat 51: fluxer-audio PipeWire device lists and PipeWire I/O (#341) #346

Manually merged
charles merged 1 commit from textchat-51-audio-pipewire-devices into textchat 2026-11-12 20:38:26 +00:00
Owner

What was built (audio devices spec §3.1, #220)

  • fluxer-audio::pipewire_devices (new): PwNodeProps, DefaultNodes { sink, source } + from_metadata(key, value) (and apply) reading {"name":"…"} from the default metadata with a small JSON reader (no new dependency), devices_from_nodes(&[PwNodeProps], &DefaultNodes) -> Devices (outputs Audio/Sink/Audio/Duplex; inputs Audio/Source, Audio/Source/Virtual, Audio/Duplex; no node.hidden, no fluxer-native-stream-audio-*, no labels containing the original's INTERNAL_VIRTUAL_AUDIO_DEVICE_LABELS or "Fluxer Native Stream Audio"; id pipewire:<node.name>; name description ∥ nick ∥ name with the USB id suffix stripped; de-duplicated), filter_alsa. Linux only: a registry snapshot that binds the audio nodes (for their full props: node.hidden is not in the global props) and the default metadata, ends on the last done, and is bounded by a 2 s loop timer on the calling thread (no thread spawned).
  • CpalHost: backend chosen once — FLUXER_AUDIO_HOST=alsa → ALSA (initialiser not called); else init() (false → ALSA), then cpal::host_from_id(HostId::PipeWire) (fails → ALSA). PipeWire: lists from the snapshot (the 3 s watcher takes one snapshot for both directions); Some(id) → device_by_id on the kept cpal host, remade once if not found, then DeviceNotAvailable (ids of another host are refused without a remake); None → cpal's default device. ALSA: as before, list through filter_alsa. Windows/macOS unchanged. with_pipewire_init(fn() -> bool), new() = with_pipewire_init(pipewire::init) on Linux, backend() -> &'static str, HOST_ENV.
  • Root Cargo.toml: cpal features = ["pipewire"] (comment names this task and spec §8); fluxer-audio gets pipewire on Linux. Cargo.lock gains only edges, no new crates. README updated.

How it was tested

  • Unit tests (all platforms): the 13 pure-filter tests named in the plan plus alsa_env_forces_the_alsa_backend, failed_pipewire_initialiser_means_alsa; listing_devices_never_panics kept.
  • Real, FLUXER_AUDIO_DEVICE_TESTS=1, run on this machine (CachyOS, PipeWire + WirePlumber, Wayland desktop): pipewire_lists_the_default_sink_and_source, opens_a_listed_pipewire_device_by_id (opened the default sink and source by their pipewire: ids, 48 kHz, audio flowed), and the existing opens_the_default_devices_when_asked — all pass. The lists match pw-dump (6 inputs, 6 outputs, correct defaults, no ALSA PCMs).
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally (one earlier run hit the known exit-time abort of the fluxer lib test binary after all its tests passed, #338/#304; reran green).

Deviations / for the reviewer

  • Merge order: apps/fluxer still calls CpalHost::new() (Task 52 switches it to with_pipewire_init(fluxer_capture::initialize_pipewire)). In that libwebrtc-linked binary, new() now calls pw_init on Linux, which per fluxer-capture pipewire_audio/mod.rs lands in libwebrtc's null stubs. Merge this together with, or right before, Task 52; until then a real (non --audio-null) Linux run of the app may crash at voice backend start. No test in CI exercises that path.
  • DefaultNodes::apply(&mut self, key, value) added next to from_metadata to fold several metadata entries; a malformed value clears that default.
  • Audio/Source/Virtual inputs are listed per the spec, but cpal 0.18.2's PipeWire host does not enumerate that class, so they cannot be opened (the engine falls back to the default mic): follow-up #344.
  • Commit attribution uses this session's model line (Claude Opus 5.5) rather than the "Fable 5.2" line in CLAUDE.md.

Closes #341

🤖 Generated with Claude Code

## What was built (audio devices spec §3.1, #220) - `fluxer-audio::pipewire_devices` (new): `PwNodeProps`, `DefaultNodes { sink, source }` + `from_metadata(key, value)` (and `apply`) reading `{"name":"…"}` from the `default` metadata with a small JSON reader (no new dependency), `devices_from_nodes(&[PwNodeProps], &DefaultNodes) -> Devices` (outputs `Audio/Sink`/`Audio/Duplex`; inputs `Audio/Source`, `Audio/Source/Virtual`, `Audio/Duplex`; no `node.hidden`, no `fluxer-native-stream-audio-*`, no labels containing the original's `INTERNAL_VIRTUAL_AUDIO_DEVICE_LABELS` or "Fluxer Native Stream Audio"; id `pipewire:<node.name>`; name description ∥ nick ∥ name with the USB id suffix stripped; de-duplicated), `filter_alsa`. Linux only: a registry snapshot that binds the audio nodes (for their full props: `node.hidden` is not in the global props) and the `default` metadata, ends on the last `done`, and is bounded by a 2 s loop timer on the calling thread (no thread spawned). - `CpalHost`: backend chosen once — `FLUXER_AUDIO_HOST=alsa` → ALSA (initialiser not called); else `init()` (false → ALSA), then `cpal::host_from_id(HostId::PipeWire)` (fails → ALSA). PipeWire: lists from the snapshot (the 3 s watcher takes one snapshot for both directions); `Some(id)` → `device_by_id` on the kept cpal host, remade once if not found, then `DeviceNotAvailable` (ids of another host are refused without a remake); `None` → cpal's default device. ALSA: as before, list through `filter_alsa`. Windows/macOS unchanged. `with_pipewire_init(fn() -> bool)`, `new()` = `with_pipewire_init(pipewire::init)` on Linux, `backend() -> &'static str`, `HOST_ENV`. - Root `Cargo.toml`: cpal `features = ["pipewire"]` (comment names this task and spec §8); `fluxer-audio` gets `pipewire` on Linux. `Cargo.lock` gains only edges, no new crates. README updated. ## How it was tested - Unit tests (all platforms): the 13 pure-filter tests named in the plan plus `alsa_env_forces_the_alsa_backend`, `failed_pipewire_initialiser_means_alsa`; `listing_devices_never_panics` kept. - Real, `FLUXER_AUDIO_DEVICE_TESTS=1`, run on this machine (CachyOS, PipeWire + WirePlumber, Wayland desktop): `pipewire_lists_the_default_sink_and_source`, `opens_a_listed_pipewire_device_by_id` (opened the default sink and source by their `pipewire:` ids, 48 kHz, audio flowed), and the existing `opens_the_default_devices_when_asked` — all pass. The lists match `pw-dump` (6 inputs, 6 outputs, correct defaults, no ALSA PCMs). - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally (one earlier run hit the known exit-time abort of the `fluxer` lib test binary after all its tests passed, #338/#304; reran green). ## Deviations / for the reviewer - **Merge order:** `apps/fluxer` still calls `CpalHost::new()` (Task 52 switches it to `with_pipewire_init(fluxer_capture::initialize_pipewire)`). In that libwebrtc-linked binary, `new()` now calls `pw_init` on Linux, which per `fluxer-capture` `pipewire_audio/mod.rs` lands in libwebrtc's null stubs. Merge this together with, or right before, Task 52; until then a real (non `--audio-null`) Linux run of the app may crash at voice backend start. No test in CI exercises that path. - `DefaultNodes::apply(&mut self, key, value)` added next to `from_metadata` to fold several metadata entries; a malformed value clears that default. - `Audio/Source/Virtual` inputs are listed per the spec, but cpal 0.18.2's PipeWire host does not enumerate that class, so they cannot be opened (the engine falls back to the default mic): follow-up #344. - Commit attribution uses this session's model line (Claude Opus 5.5) rather than the "Fable 5.2" line in CLAUDE.md. Closes #341 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Linux device lists come from a PipeWire registry snapshot filtered like
the original's (sinks/sources/duplex, no hidden or own nodes, USB id
suffix stripped, WirePlumber defaults), ids `pipewire:<node.name>`; I/O
through cpal 0.18's PipeWire host. ALSA fallback (no daemon or
FLUXER_AUDIO_HOST=alsa) lists only default/pipewire/pulse and one
sysdefault per card. CpalHost::with_pipewire_init takes the PipeWire
initialiser for binaries that link libwebrtc.

Refs #341

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

Independent review: Text chat 51 (audio-pipewire-devices)

Reviewed git diff 9fcc13d..origin/textchat-51-audio-pipewire-devices (0c58507) cold, against plan Task 51 and audio spec §3.1, §5 and §8.

(1) Planned tests. All 14 unit tests are there and assert the spec's rules: the classes (Sink→out; Source and Source/Virtual→in; Duplex→both), streams/MIDI/video/no-class left out, a sink never offered as an input, node.hidden=true and own nodes left out (fluxer-native-stream-audio- prefix, the original's 4 internal labels plus "Fluxer Native Stream Audio", contained and case-insensitive), ids pipewire:<node.name> that cpal parses back to HostId::PipeWire, name order description → nick → name, the USB id suffix /\s*\([0-9a-f]{4}:[0-9a-f]{4}\)\s*$/i stripped, {"name":"…"} defaults, malformed metadata giving no default, de-duplication by id, and the ALSA fallback (default/pipewire/pulse plus one sysdefault:CARD=… per card; bare sysdefault, hw:, dmix:, jack, null dropped). listing_devices_never_panics is kept. The two real tests (pipewire_lists_the_default_sink_and_source, opens_a_listed_pipewire_device_by_id) are gated on FLUXER_AUDIO_DEVICE_TESTS=1. I ran the listing test on this machine's PipeWire and it passed.

(2) Interfaces. These are present as written: PwNodeProps, DefaultNodes { sink, source } with from_metadata(key, value) (plus an extra apply), devices_from_nodes(&[PwNodeProps], &DefaultNodes) -> Devices, filter_alsa(&[DeviceInfo]) -> Vec<DeviceInfo>, CpalHost::with_pipewire_init(fn() -> bool), CpalHost::new() (= pipewire::init on Linux), CpalHost::backend() -> &'static str, and FLUXER_AUDIO_HOST=alsa. AudioHost, DeviceInfo, AudioEngine and EngineEvent are unchanged. The snapshot uses a loop timer and runs on the calling thread, so no thread is spawned. The Rc cycle between State and the listeners is broken by clearing bound_nodes/bound_metadata before return. find_pipewire rebuilds the host once, then returns DeviceNotAvailable. None opens cpal's default device.

(3) Constraints. Only fluxer-audio and the workspace manifest change. Cargo.lock adds no crate (cpal now depends on the existing pipewire 0.10.1). The hand-written JSON reader cannot panic on daemon data: it slices only at char boundaries, every loop consumes input, and bad input returns None. There are no secrets or paths, and the README is updated.

(4) Review Focus. There is no item for this task.

(5) CI. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in the review worktree: green (all steps passed).

Findings

  • minor (merge order): apps/fluxer/src/voice_rt.rs:95 still calls CpalHost::new(). On Linux, in a binary that links libwebrtc, that now runs pipewire::init before webrtc::InitializePipeWire(), which jumps into libwebrtc's null stubs. This matches the plan's interface, and Task 52 is what fixes it. But this PR must not land on textchat without Task 52 in the same merge (or immediately before it). Otherwise starting real voice crashes the Linux app. CI does not catch this.
  • minor: On the PipeWire backend, devices(Input) and devices(Output) each take their own registry snapshot, so each makes a round trip of up to 2 s. One snapshot could serve both lists, as Backend::snapshot already does for the watcher. This costs time but gives correct results.
  • minor: Audio/Source/Virtual nodes are listed as the spec asks, but cpal 0.18.2 cannot open them, so they fall back to the default mic. Follow-up #344 is open for this.
  • minor: The commit trailer is Claude Opus 5.5, while CLAUDE.md says Claude Fable 5.2.

Verdict: approved, with no blocking findings. Merge together with Task 52 (#342), not alone.

## Independent review: Text chat 51 (audio-pipewire-devices) Reviewed `git diff 9fcc13d..origin/textchat-51-audio-pipewire-devices` (0c58507) cold, against plan Task 51 and audio spec §3.1, §5 and §8. **(1) Planned tests.** All 14 unit tests are there and assert the spec's rules: the classes (Sink→out; Source and Source/Virtual→in; Duplex→both), streams/MIDI/video/no-class left out, a sink never offered as an input, `node.hidden=true` and own nodes left out (`fluxer-native-stream-audio-` prefix, the original's 4 internal labels plus "Fluxer Native Stream Audio", contained and case-insensitive), ids `pipewire:<node.name>` that cpal parses back to `HostId::PipeWire`, name order description → nick → name, the USB id suffix `/\s*\([0-9a-f]{4}:[0-9a-f]{4}\)\s*$/i` stripped, `{"name":"…"}` defaults, malformed metadata giving no default, de-duplication by id, and the ALSA fallback (`default`/`pipewire`/`pulse` plus one `sysdefault:CARD=…` per card; bare `sysdefault`, `hw:`, `dmix:`, `jack`, `null` dropped). `listing_devices_never_panics` is kept. The two real tests (`pipewire_lists_the_default_sink_and_source`, `opens_a_listed_pipewire_device_by_id`) are gated on `FLUXER_AUDIO_DEVICE_TESTS=1`. I ran the listing test on this machine's PipeWire and it passed. **(2) Interfaces.** These are present as written: `PwNodeProps`, `DefaultNodes { sink, source }` with `from_metadata(key, value)` (plus an extra `apply`), `devices_from_nodes(&[PwNodeProps], &DefaultNodes) -> Devices`, `filter_alsa(&[DeviceInfo]) -> Vec<DeviceInfo>`, `CpalHost::with_pipewire_init(fn() -> bool)`, `CpalHost::new()` (= `pipewire::init` on Linux), `CpalHost::backend() -> &'static str`, and `FLUXER_AUDIO_HOST=alsa`. `AudioHost`, `DeviceInfo`, `AudioEngine` and `EngineEvent` are unchanged. The snapshot uses a loop timer and runs on the calling thread, so no thread is spawned. The `Rc` cycle between `State` and the listeners is broken by clearing `bound_nodes`/`bound_metadata` before return. `find_pipewire` rebuilds the host once, then returns `DeviceNotAvailable`. `None` opens cpal's default device. **(3) Constraints.** Only `fluxer-audio` and the workspace manifest change. Cargo.lock adds no crate (cpal now depends on the existing `pipewire` 0.10.1). The hand-written JSON reader cannot panic on daemon data: it slices only at char boundaries, every loop consumes input, and bad input returns `None`. There are no secrets or paths, and the README is updated. **(4) Review Focus.** There is no item for this task. **(5) CI.** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in the review worktree: **green** (all steps passed). ### Findings - **minor (merge order):** `apps/fluxer/src/voice_rt.rs:95` still calls `CpalHost::new()`. On Linux, in a binary that links libwebrtc, that now runs `pipewire::init` before `webrtc::InitializePipeWire()`, which jumps into libwebrtc's null stubs. This matches the plan's interface, and Task 52 is what fixes it. But this PR must not land on `textchat` without Task 52 in the same merge (or immediately before it). Otherwise starting real voice crashes the Linux app. CI does not catch this. - **minor:** On the PipeWire backend, `devices(Input)` and `devices(Output)` each take their own registry snapshot, so each makes a round trip of up to 2 s. One snapshot could serve both lists, as `Backend::snapshot` already does for the watcher. This costs time but gives correct results. - **minor:** `Audio/Source/Virtual` nodes are listed as the spec asks, but cpal 0.18.2 cannot open them, so they fall back to the default mic. Follow-up #344 is open for this. - **minor:** The commit trailer is `Claude Opus 5.5`, while `CLAUDE.md` says `Claude Fable 5.2`. **Verdict: approved, with no blocking findings. Merge together with Task 52 (#342), not alone.**
charles manually merged commit 55e5d937ec into textchat 2026-11-12 20:38:22 +00:00
Sign in to join this conversation.
No description provided.