Skip to content

feat(windows/audio): capture launched process tree with WASAPI loopback - #6124

Draft
mikefaille wants to merge 32 commits into
SunshineStream:masterfrom
mikefaille:feat/windows-process-tree-capture
Draft

mikefaille wants to merge 32 commits into
SunshineStream:masterfrom
mikefaille:feat/windows-process-tree-capture

Conversation

@mikefaille

@mikefaille mikefaille commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Description

Context

Stacked on B (#6123) per scope agreement.

Problem

On Windows with host playback ("Play on this PC too"), capture comes from the shared endpoint, so everything audible on the PC — notification sounds, other apps — goes into the stream.

Solution

Capture the launched application's process tree with WASAPI process loopback instead, so the stream carries the game only, with creation-time identity validation so a reused PID can never capture the wrong app.

  • Wire the launched-application process identity from proc through audio::capture into the Windows backend.
  • Add should_capture_process_tree() gating (host-and-client intent + backend support + known PID, silence-first, pinned sink wins), the capture_process_identity_provider plumbing through session_capture_target_t::create_microphone() with post-creation re-check and one retry, stream.cpp provider wiring from proc::app_process_identity_provider, and the Windows loopback/identity/activation/validation/seams plus the full process-aware microphone(). Includes audio_tests.h seams, the Windows audio tests, ProviderIdentity unit coverage, and the WASAPI process-loopback sentence in configuration.md.

Screenshot

N/A (no UI changes).

Issues Fixed or Closed

Roadmap Issues

None.

Stack

Testing

C-only gates, observed on Linux (Release, tray OFF, ccache):

  • cmake -B cmake-build-c -DPython3_EXECUTABLE=$PWD/.venv/bin/python -DSUNSHINE_ENABLE_TRAY=OFF -DCMAKE_BUILD_TYPE=Release: configure done.
  • cmake --build cmake-build-c --target test_sunshine -j12: built.
  • ./cmake-build-c/tests/test_sunshine (full): 1144 ran, 1135 passed, 9 skipped (CUDA/tray/HID/nvenc environmental, same set as B), 0 failed, exit 0. Includes new AudioCaptureProcessTreeTest, ProviderIdentityIsRecordedBeforeMicrophone, ProviderIdentityReachesBackendVerbatim, RetargetDuringCreationDiscardsAndRetries, and SessionGuardReleasesRealBaseRecord (7/7 in targeted filter).
  • uv run --locked lb-update-clang-format: stable on second run, no new changes, exit 0.
  • git diff --check: clean, exit 0.
  • cmake --build cmake-build-c --target docs: exit 0, 1123 HTML pages.
  • Scope checks: zero diff vs B-tip on process.*, common.h, nvhttp.cpp, test_process.cpp, web UI, getting_started.md, and macOS/Linux platform code; configuration.md carries only the WASAPI sentence (+4/-1).
  • Review fixes (48ae5e3f, on merged B-tip c1b1c98e): one-lock docs corrected; concurrency oracle asserts paired identity; new collect_reports_failure_combinations, real_activation_paths_cover_success_failure_and_timeout (real entry point via injected fake API), and microphone_returns_loopback_for_valid_target seams + tests; macro-gate SKIP markers; portable ProviderIdentityChangeIsPickedUpOnReinitialization and ConcurrentRefreshAndTeardownStayBalanced tests (3x stable).
  • Re-run after fixes: full suite 1152 ran, 1143 passed, 9 skipped, 0 failed; format + diff-check clean; doxygen warning-free on new symbols. MinGW probes pass for the new COM fakes and the activation-function alias against real SDK headers.
  • Dedup follow-up (tip 91cd1281): shares the 17-line loopback probe setup across the 8 microphone tests via make_current_process_probe() (baseline + per-test field overrides). Rebuilt + full suite: 1155 ran, 1146 passed, 9 skipped (same environmental set), 0 failed, exit 0. MinGW -fsyntax-only probe passes for the real helper text and probe struct against real SDK headers. Format + git diff --check clean.
  • Not run here: Windows TUs (src/platform/windows/audio.cpp, audio_tests.h, windows/test_audio.cpp) do not compile on Linux; covered by Windows CI.

Type of Change

  • feat: New feature (non-breaking change which adds functionality)
  • fix: Bug fix (non-breaking change which fixes an issue)
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit
  • BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

  • Code follows the style guidelines of this project
  • Code has been self-reviewed
  • Code has been commented, particularly in hard-to-understand areas
  • Code docstring/documentation-blocks for new or existing methods/components have been added or updated
  • Tests have been added or updated for new or modified functionality, including regression tests for bug fixes

AI Usage

See our AI usage policy.

  • AI tools were used while preparing this PR

This pull request was generated by Muse Code powered by Meta Muse Spark

… host default

Adds the keep_default_sink config key controlling whether audio capture swaps the host default sink.

- Config: new keep_default_sink key (default disabled) with validation.
- Policy: when enabled, capture keeps the host default sink untouched; teardown restores only state this session changed.
- UI: AudioVideo tab toggle plus locale strings.
- Docs: configuration.md documents the new key.
- Tests: config, audio, and linux audio unit coverage.
Rename shadowed module field (S1669), extract adopt_sink/ensure_sink
helpers from the duplicated sink setup blocks (S3776), shrink the
oversized enumeration lambda (S1188), and guard destructor teardown
against throwing unloads (S1048). Behavior unchanged.
Give the destructor's catch-all a log statement so the intentionally
suppressed unload path is not an empty handler (S2486). Teardown
stays non-throwing.
Route the capture-only path at the configured sink, or the saved host sink
when nothing is configured, instead of the virtual sink. Without a swap,
applications stay on the host default, so capturing the virtual sink's
monitor yields silence when host playback is muted.

Extract the startup selection plus swap-vs-capture policy into the pure
resolve_capture_routing() helper so the empty/configured sink by HOST_AUDIO
matrix is covered by unit tests, and pin the historical virtual-sink
selection on the swap path.
Include the new shared checkbox in the Windows control-list assertion and
add round-trip coverage rendering it on Windows, Linux, and macOS.
Share the keep-default routing contract across backends. Windows records
the capture target for direct WASAPI capture and guards the default
reassertion callback, the startup default-device reset, and the Steam
driver install behind hands-off-mode predicates, composing with the
existing external_audio behavior. macOS reports support natively since
tap/input capture never touches the default output. Document the
per-platform behavior.
Satisfies Sonar cpp:S3562 on the new code. Behavior unchanged: layouts
other than stereo/5.1/7.1 keep the previously selected sink.
Extract the duplicated mountAudioVideo helper into audioVideoMount.js so
the keep_default_sink suite and the external_audio suite use one copy.
Clears the Sonar new-code duplication gate.
…ap-owned activation blob

Unify keep-default capture under one shared key with a thread-safe
session guard, a microphone params bundle, and WASAPI process loopback
using a heap-owned activation blob plus PID revalidation.
Behavior-preserving modernization of the audio capture path: string_view for read-only string parameters, using-enum with exhaustive switches, constexpr/noexcept/nodiscard on pure predicates and intent helpers, const-correct virtual-sink helpers, explicit wstring materialization at the UTF-8 boundary, a params-bundle using-declaration for the Linux backend, and documented no-op capture-target defaults. No behavior change.
Production: extract the find_device_id endpoint probe, rename shadowed error locals, std::format for sink names, dropped redundant lambda return types, CTAD atomics, using-enum in the concurrency seam, and the macOS params-bundle using-declaration. Tests: noexcept guard destructor with deleted copies, three params-bundle using-declarations, string_view call_index, std::array mapping. Behavior-preserving throughout.
…et clear

Hoist the identical keep-default capture_sink bodies into a protected base helper so both backends record through one path, and reset Windows creation-time identity via an on_capture_target_cleared() hook fired under the same lock hold as the shared record reset.
…ne()

The d3dc65f surgery dropped the process-loopback if-block but kept its
closing brace after 'auto mic', which would close microphone() early and
break the Windows build (unseen on Linux where this TU is excluded).
Harden proc_t launch/cleanup: snapshot app state and claim termination
atomically with a lifecycle generation, serialize app_process_id/identity
reads with the lifecycle mutex, lock getters and reaper, and gate complete
execute/running/terminate transitions with proc_transition_mutex so an
overlapping web close/stream cleanup cannot run the old snapshot's undo or
display revert after the successor's preparation.

Carry the shared capture-target record (identity struct, record, snapshot
helpers, mutex, conditional clear, hook) in platf::audio_control_t with a
mechanical audio.cpp call-site update, plus lifecycle and BaseRecord
regression coverage including a latch-controlled overlap test and the P2
test-guard correction for the identity-producer test.
@mikefaille

Copy link
Copy Markdown
Contributor Author

This pull request was generated by Muse Code powered by Meta Muse Spark

Pollers (stream loop, nvhttp launch/resume/cancel/serverinfo) no longer
block on the transition gate: running() classifies state under the
lifecycle mutex only, reports mid-launch as busy (fail closed), and
takes the transition gate with try_to_lock only when an exited app
needs cleanup. On contention the last-known app id is reported and the
transition owner performs the cleanup.

The POSIX blanket reaper runs only when the gate is idle and after the
root checks, so it can neither steal prep/undo wait statuses nor lose
the root exit code (Boost keeps still_active after an external reap,
which would break auto_detach detection).

finish_termination() still runs under the transition hold, preserving
the undo/display-revert-before-successor-prep ordering.

Also corrects the lifecycle/audio lock-order docs (the two mutexes are
never nested in either direction), documents the identity-type home in
platf/common.h, and rewords the POSIX zero-marker comment as a
fail-closed contract instead of a backend prediction.
Adds gated overlap tests proving running() answers promptly during
execute()/terminate()/owned-cleanup (each fails on the blocking
implementation), a poller hammer across natural exit and racing
terminate, a terminate-during-launch drain test, and an OS-death
cleanup test with successor relaunch.

Hardens the PID oracle (kill liveness + /proc cmdline identity +
sample count) and the provider test (Windows exact-match marker vs an
independent OS query, placebo {0,0} branch).
Drive the real activation entry point in tests via an injectable API seam
with success/failure/timeout phases; assert paired identity in the
concurrency oracle; cover collect() failure combinations and the
end-to-end loopback success path; correct the one-lock docs; add
mutable-provider and teardown-concurrency tests.
The six gated lifecycle tests each hand-rolled the same $\sim0-line setup
(scratch dir, marker scripts, app contexts, process manager, guards), which
SonarCloud flags as 148 duplicated lines on PR SunshineStream#6123.

Replace the six setups with gated_launch_t: one config list per test selects
markers, gating, and commands, while the fixture owns the directory, scripts,
apps, target, background-launch thread, deadline poll, and gate release. The
Overlapping test additionally drops its bespoke tmp dir, script writer, and
read/wait loops in favor of the existing gate helpers. Test bodies keep only
their orchestration and assertions; all markers and gate behavior are unchanged.

The hook audio control fake now derives from the recording fake instead of
duplicating its 50 lines, keeping its two intentional differences documented.
Eight microphone tests repeated the same 17-line probe setup (live PID and
creation marker plus the baseline probe literal), flagged as 34 duplicated
lines on PR SunshineStream#6124.

Add make_current_process_probe() for the shared baseline; each test keeps its
environment asserts and overrides only the fields its case varies (intent,
configured sink, keep_default, stale marker). The PID-0 endpoint test keeps
its distinct literal.
@mikefaille mikefaille closed this Nov 17, 2026
@mikefaille mikefaille reopened this Nov 17, 2026
@sonarqubecloud

Copy link
Copy Markdown

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[windows/audio] Process-tree capture + identity handoff (follow-up to #5935)

1 participant