Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
2ffc3ae
feat(audio): add keep_default_sink option to capture without swapping…
mikefaille Oct 8, 2026
f9ac778
fix(linux): clear Sonar findings on audio sink lifecycle
mikefaille Oct 15, 2026
894bf46
fix(linux): log suppressed exception in audio server teardown
mikefaille Oct 15, 2026
77a5a78
fix(audio): capture host sink when keep-default has no configured sink
mikefaille Oct 17, 2026
2ec6d80
fix(web): cover shared keep_default_sink checkbox in UI tests
mikefaille Oct 17, 2026
f875ce4
feat(audio): support keep_default_sink on Windows and macOS
mikefaille Oct 17, 2026
edf6c3e
fix(audio): add default case to capture-routing channel switch
mikefaille Oct 17, 2026
efcd6e3
fix(web): share AudioVideo mount helper between UI tests
mikefaille Oct 17, 2026
627882c
feat(audio): unify keep-default capture with process loopback and cap…
mikefaille Nov 9, 2026
dcb684c
feat(audio): harden capture with session guard, params bundle, and he…
mikefaille Nov 9, 2026
29cb270
refactor(audio): modernize capture plumbing with C++23 idioms
mikefaille Nov 10, 2026
b4073e8
refactor(audio): address valid Sonar findings in capture path and tests
mikefaille Nov 10, 2026
5b334af
refactor(audio): use CTAD for live_count and report test guard restor…
mikefaille Nov 10, 2026
734e3ab
docs(audio): drop duplicated param docs from select_audio_capture_sin…
mikefaille Nov 10, 2026
34dacf5
style(tests): consolidate include groups in audio tests
mikefaille Nov 10, 2026
8cdf346
refactor(audio): centralize recorded capture-target state in audio_co…
mikefaille Nov 10, 2026
7a669d4
refactor(audio): share keep-default capture body and hook paired targ…
mikefaille Nov 11, 2026
4382c56
fix(audio): create microphone outside the capture-target lock
mikefaille Nov 16, 2026
e1250fd
fix(config): scope legacy external_audio migration to Windows with a …
mikefaille Nov 16, 2026
2f92bd3
fix(tests): drop blank line at EOF from trim surgery
mikefaille Nov 17, 2026
5721311
fix(windows/audio): drop stray brace left by trim surgery in micropho…
mikefaille Nov 17, 2026
06e5ec7
refactor(web): reorganize Audio/Video capture sections and clarify ca…
mikefaille Nov 17, 2026
cb29ce4
fix(web): gate saves on valid capture target, fix search reveal, hard…
mikefaille Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 62 additions & 17 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -821,7 +821,6 @@ consent prompt for directory ACLs, so the Web UI shows setup steps for correctin
<br>
Sunshine can only access microphones on macOS due to system limitations.
To stream system audio use
[Soundflower](https://github.com/mattingalls/Soundflower) or
[BlackHole](https://github.com/ExistentialAudio/BlackHole).
<br>
<br>
Expand All @@ -835,6 +834,18 @@ consent prompt for directory ACLs, so the Web UI shows setup steps for correctin
}
@attention{If you want to mute the host speakers, use
[virtual_sink](#virtual_sink) instead.}
@tip{On FreeBSD/Linux, Sunshine also provides its own null sinks (for example
`sink-sunshine-stereo`). Enter one here to capture a private mix you route
yourself; combined with [keep_default_sink](#keep_default_sink), the host
default output is left untouched.}
<br>
<br>
In the Web UI Audio Capture choices: a blank value with
[keep_default_sink](#keep_default_sink) disabled is <strong>Quiet streaming</strong>; a blank value
with it enabled is <strong>Play on this PC too</strong>; a named value is <strong>Custom device</strong>,
where <strong>I route apps myself</strong> enables [keep_default_sink](#keep_default_sink) and
<strong>Sunshine sets it as the default</strong> leaves it disabled so Sunshine sets the named
sink as the default while streaming and restores the previous default afterwards.
</td>
</tr>
<tr>
Expand Down Expand Up @@ -868,14 +879,24 @@ consent prompt for directory ACLs, so the Web UI shows setup steps for correctin
<td>Description</td>
<td colspan="2">
The audio device that's virtual, like Steam Streaming Speakers. This allows Sunshine to stream audio,
while muting the speakers.
while muting the speakers. It applies only to the <strong>Quiet streaming</strong> path
([keep_default_sink](#keep_default_sink) disabled; the Windows Web UI shows it only for Quiet
streaming) and is ignored for <strong>Play on this PC too</strong> and for <strong>Custom device</strong>
with <strong>I route apps myself</strong>. A named [audio_sink](#audio_sink) always wins over
this virtual sink, including when Moonlight host playback is off.
@tip{See [audio_sink](#audio_sink)!}
@tip{These are some options for virtual sound devices.
* Stream Streaming Speakers (Linux, macOS, Windows)
@tip{This option is Windows only. Some options for virtual sound devices on Windows:
* Steam Streaming Speakers
* Steam must be installed.
* Enable [install_steam_audio_drivers](#install_steam_audio_drivers)
or use Steam Remote Play at least once to install the drivers.
* [Virtual Audio Cable](https://vb-audio.com/Cable) (macOS, Windows)
* [Virtual Audio Cable](https://vb-audio.com/Cable)
<br>
<br>
On FreeBSD/Linux, leave this option unset and use <strong>Quiet streaming</strong> instead:
Sunshine captures its own null sinks (for example `sink-sunshine-stereo`) automatically.
On macOS, use <strong>Custom device</strong> with
[BlackHole](https://github.com/ExistentialAudio/BlackHole) and route the game to it yourself.
}
</td>
</tr>
Expand Down Expand Up @@ -939,23 +960,48 @@ consent prompt for directory ACLs, so the Web UI shows setup steps for correctin
</tr>
</table>

### external_audio
### keep_default_sink

<table>
<tr>
<td>Description</td>
<td colspan="2">
Enables capture-only operation when an external audio router manages application playback.
An explicit [audio_sink](#audio_sink) is required; use an endpoint ID when names are ambiguous.
Sunshine captures that endpoint directly without changing or restoring Windows default devices
or endpoint formats.
Capture the selected audio sink without changing the host default sink. When disabled, Sunshine sets
the selected (or virtual) sink as the host default sink while streaming on platforms that swap
defaults; macOS never changes the default output.
<br>
<br>
This replaces the Windows-only <code>external_audio</code> option. An existing
<code>external_audio = enabled</code> setting is migrated to <code>keep_default_sink = enabled</code>
on upgrade, unless <code>keep_default_sink</code> is also set. Unlike the old Windows mode, an
explicit [audio_sink](#audio_sink) is no longer required. Note that [virtual_sink](#virtual_sink)
only affects sink selection on the swap path; in keep-default mode the
capture target is the configured <code>audio_sink</code>, or the host sink when none is configured.
Moonlight's host-playback selection likewise only affects sink selection on the swap path,
except on macOS where it still controls the system tap mute behavior (muted tap versus tap plus
speakers) in keep-default mode.
<br>
<br>
In this mode, [virtual_sink](#virtual_sink), automatic Steam audio driver installation,
and Moonlight's host-playback toggle do not affect routing. Configure local playback and the audio
sent to the selected endpoint in your external mixer. If the endpoint is unavailable, audio capture
fails rather than falling back to another endpoint. Video streaming can continue without audio.
@note{This option is only supported on Windows. Other platforms retain their existing behavior.}
In the Web UI, the Audio Capture choices map to these keys as follows: <strong>Quiet streaming</strong>
leaves this option disabled and <code>audio_sink</code> blank, so the client hears the audio while the
host stays silent when Moonlight host playback is off; <strong>Play on this PC too</strong> enables this
option with <code>audio_sink</code> blank; <strong>Custom device</strong> sets <code>audio_sink</code>
to the named sink, device, or input and adds a routing-owner choice: <strong>I route apps
myself</strong> enables this option (Sunshine captures the named sink without changing the default),
while <strong>Sunshine sets it as the default</strong> leaves this option disabled (Sunshine sets the
named sink as the default while streaming and restores the previous default afterwards). On macOS, Quiet streaming is
disabled in the Web UI and neither Custom routing owner changes the default output; for silent or
separated capture, use Custom device with BlackHole and route the game to it yourself.
@note{Platform behavior:<br>
<strong>Windows:</strong> captures the target endpoint directly and is hands-off, so an external
router such as VoiceMeeter or GoXLR keeps owning endpoint defaults and formats; it also skips the
Steam driver install, the startup default-device reset, and default reinstallation.<br>
<strong>Linux:</strong> captures the configured sink's monitor, or the host sink's monitor when
none is configured, and adopts pre-existing null sinks instead of unloading them.<br>
<strong>FreeBSD:</strong> captures the configured sink's monitor, or the host sink's monitor when
none is configured, without changing the default sink.<br>
<strong>macOS:</strong> honors the option natively through a system tap or the selected input,
without touching the default output.}
</td>
</tr>
<tr>
Expand All @@ -967,8 +1013,7 @@ consent prompt for directory ACLs, so the Web UI shows setup steps for correctin
<tr>
<td>Example</td>
<td colspan="2">@code{}
external_audio = enabled
audio_sink = My Streaming Mix
keep_default_sink = enabled
@endcode</td>
</tr>
</table>
Expand Down
1 change: 0 additions & 1 deletion docs/getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -595,7 +595,6 @@ Sunshine supports native system audio capture on macOS 14.0 (Sonoma) and newer v
To use it, simply leave the **Audio Sink** setting blank.

If you prefer to manage your own loopback device, you can still use
[Soundflower](https://github.com/mattingalls/Soundflower) or
[BlackHole](https://github.com/ExistentialAudio/BlackHole)
and enter its device name in the [audio_sink](configuration.md#audio_sink) field.

Expand Down
159 changes: 127 additions & 32 deletions src/audio.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
*/
// standard includes
#include <array>
#include <mutex>
#include <thread>

// lib includes
Expand Down Expand Up @@ -33,6 +34,27 @@ namespace audio {
static void stop_audio_control(audio_ctx_t &);
static void apply_surround_params(opus_stream_config_t &stream, const stream_params_t &params);

/**
* @brief Serializes capture-target refresh, microphone creation, and target release across concurrent sessions.
*
* All capture() threads share one audio control. Each session's
* session_capture_target_t guard holds this mutex across the refresh
* and the exit clear, but never across microphone creation itself,
* which can wait on endpoint activation; holding the lock across it
* would stall every other session's teardown.
*
* Lock order: this outer mutex is always taken before the backend-internal
* `platf::audio_control_t::capture_state_mutex_`, acquired inside
* `set_capture_target()`/`microphone()`/`clear_capture_target()`. Backends
* never take this mutex, so the order cannot invert.
*
* @return Reference to the process-lifetime capture-target mutex.
*/
std::mutex &capture_target_mutex() {
static std::mutex mutex;
return mutex;
}

/**
* @brief Select the Opus stream configuration for a channel count and quality tier.
*
Expand Down Expand Up @@ -152,8 +174,68 @@ namespace audio {
}
}

/**
* @brief Select the capture sink for startup without touching the capture target.
*/
bool select_audio_capture_sink(platf::audio_control_t &control, const capture_routing_t &routing) {
if (routing.swap_at_startup) {
// The target is already the host sink when there is nothing to restore,
// so the swap is skipped entirely instead of reasserting the default.
if (routing.restore_at_teardown && control.set_sink(routing.target)) {
return false;
}
} else if (control.capture_sink(routing.target)) {
return false;
}
return true;
}

/**
* @brief Create a guard that owns no target until the first refresh.
*/
session_capture_target_t::session_capture_target_t(platf::audio_control_t &control, platf::audio_capture_intent_e intent, std::mutex &mutex):
control_ {&control},
intent_ {intent},
mutex_ {&mutex} {
}

/**
* @brief Destroy the guard, releasing the recorded target when one exists.
*/
session_capture_target_t::~session_capture_target_t() {
if (!recorded_) {
return;
}
std::lock_guard lock {*mutex_};
control_->clear_capture_target(intent_, 0);
}

/**
* @brief Refresh the endpoint capture target, then create the microphone for it.
*/
std::unique_ptr<platf::mic_t> session_capture_target_t::create_microphone(const platf::microphone_params_t &mic_params) {
// Refresh the endpoint target before every microphone creation. Only the
// refresh runs under the lock: microphone creation can wait on endpoint
// activation, and holding the lock across it would stall every other
// session's teardown. The refresh is recorded even when microphone
// creation fails so teardown still releases this session's target.
{
std::lock_guard lock {*mutex_};
control_->set_capture_target(intent_, 0);
recorded_ = true;
}
return control_->microphone(mic_params);
}

/**
* @brief Run the capture loop for this backend.
*
* Sessions share one audio control: sink selection runs through
* select_audio_capture_sink(), the restore flag is assigned directly from
* the resolved routing, and one session_capture_target_t guard owns the
* shared target for the session. Both microphone call sites (startup and
* reinitialization) are the same single guard call, and guard destruction
* releases the shared target only when a refresh ran.
*/
void capture(safe::mail_t mail, config_t config, stream::session_t *channel_data) {
auto shutdown_event = mail->event<bool>(mail::shutdown);
Expand Down Expand Up @@ -184,46 +266,52 @@ namespace audio {
return;
}

// Order of priority:
// 1. Virtual sink
// 2. Audio sink
// 3. Host
std::string *sink = &ref->sink.host;
if (!config::audio.sink.empty()) {
sink = &config::audio.sink;
}
const auto capture_intent = resolve_audio_capture_intent(config::audio.keep_default_sink, config::audio.sink);

// Prefer the virtual sink if host playback is disabled or there's no other sink
if (ref->sink.null && (!config.flags[config_t::HOST_AUDIO] || sink->empty())) {
auto &null = *ref->sink.null;
switch (stream.channelCount) {
case 2:
sink = &null.stereo;
break;
case 6:
sink = &null.surround51;
break;
case 8:
sink = &null.surround71;
break;
}
}
// One RAII owner for the session's shared capture target. Destruction
// releases exactly the last recorded target, or nothing when no refresh
// ran, so one session cannot wipe another session's recorded target.
session_capture_target_t capture_target {*control, capture_intent, capture_target_mutex()};

// Only the first to start a session may change the default sink
if (!ref->sink_flag->exchange(true, std::memory_order_acquire)) {
// If the selected sink is different than the current one, change sinks.
ref->restore_sink = ref->sink.host != *sink;
if (ref->restore_sink) {
if (control->set_sink(*sink)) {
return;
}
// One decision point for swap-vs-capture: the recorded restore flag keeps
// teardown symmetric with startup on every platform, including backends
// that never learned the keep-default behavior.
const auto routing = resolve_capture_routing(
config::audio.keep_default_sink,
control->supports_keep_default_sink(),
config.flags[config_t::HOST_AUDIO],
stream.channelCount,
ref->sink.host,
config::audio.sink,
ref->sink.null
);
ref->restore_sink = routing.restore_at_teardown;
BOOST_LOG(info) << "Audio capture mode ["sv << (routing.swap_at_startup ? "swap-and-restore"sv : "capture-keep-default"sv)
<< "], target ["sv << routing.target
<< "], restore_at_teardown ["sv << routing.restore_at_teardown
<< "], keep_default_sink requested ["sv << config::audio.keep_default_sink
<< "], keep_default_sink supported ["sv << control->supports_keep_default_sink()
<< "], capture intent ["sv << audio_capture_intent_name(capture_intent) << ']';
// If the selected sink cannot be selected, there is no audio to capture.
if (!select_audio_capture_sink(*control, routing)) {
return;
}
}

auto frame_size = config.packetDuration * stream.sampleRate / 1000;
bool host_audio = config.flags[config_t::HOST_AUDIO];
bool continuous_audio = config.flags[config_t::CONTINUOUS_AUDIO];
auto mic = control->microphone(stream.mapping, stream.channelCount, stream.sampleRate, frame_size, continuous_audio, host_audio);
const platf::microphone_params_t mic_params {
stream.mapping,
stream.channelCount,
static_cast<std::uint32_t>(stream.sampleRate),
static_cast<std::uint32_t>(frame_size),
continuous_audio,
host_audio
};
auto mic = capture_target.create_microphone(mic_params);
if (!mic) {
return;
}
Expand Down Expand Up @@ -260,7 +348,7 @@ namespace audio {
BOOST_LOG(info) << "Reinitializing audio capture"sv;
mic.reset();
do {
mic = control->microphone(stream.mapping, stream.channelCount, stream.sampleRate, frame_size, continuous_audio, host_audio);
mic = capture_target.create_microphone(mic_params);
if (!mic) {
BOOST_LOG(warning) << "Couldn't re-initialize audio input"sv;
}
Expand All @@ -284,6 +372,12 @@ namespace audio {
return false;
}

// Keep-default captures the configured sink, so probe that endpoint rather
// than the host default recorded at startup.
if (config::audio.keep_default_sink && !config::audio.sink.empty() && ctx.control->supports_keep_default_sink()) {
return ctx.control->is_sink_available(config::audio.sink);
}

const std::string &sink = ctx.sink.host.empty() ? config::audio.sink : ctx.sink.host;
if (sink.empty()) {
return false;
Expand Down Expand Up @@ -336,7 +430,8 @@ namespace audio {
}

void stop_audio_control(audio_ctx_t &ctx) {
// restore audio-sink if applicable
// restore audio-sink if applicable. Startup recorded whether it swapped;
// keep-default sessions never swap, so there is nothing to restore.
if (!ctx.restore_sink) {
return;
}
Expand Down
Loading