feat(cli): publish desktop audio exclusion

README.md

@@ -21,7 +21,8 @@ Working:
 - VAAPI H.264 encode in GStreamer (RDNA3 confirmed; other VAAPI-capable
   GPUs should work), with a software x264 fallback via `--no-hwencode`
 - Audio capture of the default sink's monitor, with optional per-app
-  routing (`--app <name>`)
+  routing (`--app <name>`) and a guarded whole-desktop mode for parent
+  integrations (`--audio-mode=desktop-excluding`)
 - `--repair` cleanup of orphaned PipeWire state left by a crashed host
 - `--doctor` environment diagnostic (capture/encode deps, VA-API H.264,
   viewer player, relay reachability) — see [Diagnostics](#diagnostics)
@@ -316,12 +317,34 @@ matches a built-in overrides that built-in.
 ## Audio
 
 By default pixelpass captures the default sink's monitor — the viewer
-hears whatever the host hears. `--app <name>` narrows that to a single
-application: pixelpass creates a per-PID null-sink and uses libpipewire to
-reroute matching `Stream/Output/Audio` nodes (by `application.name`) into
-it, so the viewer hears just that app instead of the whole desktop. In the
-interactive menu you can pick the app from a list of what's currently
-playing.
+hears whatever the host hears. This is also available explicitly as
+`--audio-mode=desktop-shared`.
+
+`--app <name>` narrows capture to a single application: pixelpass creates a
+per-PID null-sink and uses libpipewire to reroute matching
+`Stream/Output/Audio` nodes (by `application.name`) into it, so the viewer
+hears just that app instead of the whole desktop. In the interactive menu
+you can pick the app from a list of what's currently playing.
+
+Parent integrations can select guarded whole-desktop capture with
+`--audio-mode=desktop-excluding`. This copies eligible playback streams into
+a connection-owned capture sink while excluding PeerSpeak-tagged playback,
+the exact configured echo-canceller, unsafe ancestry, and unsupported stream
+formats. The mode requires an explicit AEC state so a missing integration
+argument cannot silently mean "no AEC":
+
+```sh
+pixelpass --host --audio-mode=desktop-excluding --aec=off
+pixelpass --host --audio-mode=desktop-excluding --aec=pulse-module:536870919
+```
+
+Integrations should use `pixelpass --capabilities`, not scrape `--help`. Its
+versioned response advertises strict per-app audio and desktop exclusion as
+independent capabilities:
+
+```json
+{"schema_version":1,"capabilities":{"strict_app_audio":true,"desktop_audio_exclusion":true}}
+```
 
 Microphone capture is intentionally out of scope — pixelpass is a
 screen-share tool meant to be paired with a dedicated voice app (Mumble,
@@ -407,9 +430,10 @@ each take precedence over the chosen preset's value for that field.
   either one breaks playback (the first kills the demuxer, the second
   kills the H.264 decoder). pixelpass warns at player-launch time if
   either plugin isn't on disk. mpv doesn't share these dependencies.
-- **Audio echo** if the host plays the stream through speakers and
-  captures system audio — expected, the mic / monitor picks up the
-  playback. Headphones bypass it.
+- **Audio echo in `desktop-shared` mode** if the host plays the stream through
+  speakers while capturing system audio. The guarded `desktop-excluding`
+  mode requires a cooperating parent integration to tag its playback and
+  supply the active AEC identity.
 - **Late joiners see ~2 s of garbage** before the next keyframe lets
   their decoder lock. Expected behavior, not a bug.
 - **VAAPI driver must be package-tracked**, not an orphaned `.so` on