feat: default wasapi-virtual-default-devices -> windows-legacy

Author: philpax

Cargo.toml

@@ -10,7 +10,7 @@ edition = "2021"
 rust-version = "1.77"
 
 [features]
-default = ["wasapi-virtual-default-devices"]
+default = []
 
 # ASIO backend for Windows
 # Provides low-latency audio I/O by bypassing the Windows audio stack
@@ -21,14 +21,18 @@ asio = [
     "dep:num-traits",
 ]
 
-
-# Enable virtual default devices for WASAPI. When enabled:
-# - Audio automatically reroutes when the default device changes
-# - Streams survive device changes (e.g., plugging in headphones)
-# - Requires Windows 8 or later
+# Legacy Windows audio device activation mode. When enabled:
+# - Uses IMMDevice::Activate instead of ActivateAudioInterfaceAsync
+# - Audio does NOT automatically reroute when the default device changes
+# - Streams will break when the default device changes (e.g., plugging in headphones)
+#
+# By default (without this feature), CPAL uses virtual default devices that:
+# - Automatically reroute audio when the default device changes
+# - Allow streams to survive device changes
+# - Require Windows 8 or later
 #
-# Disable this feature if supporting Windows 7 or earlier.
-wasapi-virtual-default-devices = []
+# Enable this feature only if supporting Windows 7 or earlier.
+windows-legacy = []
 
 # JACK Audio Connection Kit backend
 # Provides low-latency connections between applications and audio hardware

src/host/wasapi/device.rs

@@ -305,7 +305,7 @@ unsafe fn format_from_waveformatex_ptr(
     Some(format)
 }
 
-#[cfg(feature = "wasapi-virtual-default-devices")]
+#[cfg(not(feature = "windows-legacy"))]
 unsafe fn activate_audio_interface_sync(
     deviceinterfacepath: windows::core::PWSTR,
 ) -> windows::core::Result<Audio::IAudioClient> {
@@ -587,13 +587,14 @@ impl Device {
             return Ok(lock);
         }
 
-        // When using virtual default devices, we use `ActivateAudioInterfaceAsync` to get
-        // an `IAudioClient` for the default output or input device. When retrieved this way,
-        // streams will be automatically rerouted if the default device is changed.
+        // By default, we use `ActivateAudioInterfaceAsync` to get an `IAudioClient` for
+        // virtual default devices. When retrieved this way, streams will be automatically
+        // rerouted if the default device is changed.
         //
-        // Otherwise, we use `Activate` to get an `IAudioClient` for the current device.
+        // When the `windows-legacy` feature is enabled, we use `Activate` to get an
+        // `IAudioClient` for the current device, which does not support automatic rerouting.
 
-        #[cfg(feature = "wasapi-virtual-default-devices")]
+        #[cfg(not(feature = "windows-legacy"))]
         let audio_client: Audio::IAudioClient = unsafe {
             match &self.device {
                 DeviceHandle::DefaultOutput => {
@@ -614,7 +615,7 @@ impl Device {
             }
         };
 
-        #[cfg(not(feature = "wasapi-virtual-default-devices"))]
+        #[cfg(feature = "windows-legacy")]
         let audio_client = unsafe {
             self.immdevice()
                 .ok_or(windows::core::Error::new(