Add audio output device/port selection for Android and iOS/macOS (#191)

* Add audio output device/port selection for Android and iOS/macOS

Adds the ability to control which audio output device or port is used
for playback on both Android and iOS/macOS platforms.

Android:
- New AudioOutputDevice enum mapping to AudioDeviceType values
- PreferredOutputDevice property on AudioPlayerOptions
- SetPreferredOutputDevice method with API 28+ support
- Extracted ConfigureAudioAttributes for reuse after player.Reset()
- Reapply audio attributes + preferred device after Reset in
  SetSpeedInternal and SetSource
- Fixed invalid Pause() call in Prepared state after speed change

iOS/macCatalyst:
- New AudioOutputPort enum (Default, Speaker) mapping to
  AVAudioSessionPortOverride values
- PreferredOutputPort property on AudioPlayerOptions
- SetPreferredOutputPort with session-wide override
- Early-return for Default to avoid undoing other players' overrides
- Static ref-counted Speaker override with lock for thread safety
- Proper cleanup on Dispose (only clears when last player releases)
- SetSource correctly manages override ownership across player recreation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address review findings: restore docs, fix iOS category, add sample

- Restore deleted Audio Focus & Interruption Handling documentation
- Fix iOS: auto-upgrade session to PlayAndRecord when speaker override
  is requested (required for OverrideOutputAudioPort to take effect)
- Fix Android: use existing audioManager field instead of new instance
- Remove misleading [SupportedOSPlatform] attribute from enum (runtime
  check in SetPreferredOutputDevice handles API level gracefully)
- Add 'Force Speaker Output' toggle to sample app MusicPlayerPage
- Update README.md with output device selection example
- Add Windows 'not supported' note and Mac Catalyst caveat in docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix audioManager init and sample app concurrency

- Initialize audioManager unconditionally in all 3 Android constructors
  so PreferredOutputDevice works even when ManageAudioFocus is false
- Add reentry guard to sample ReloadWithOutputDevice to prevent crash
  from rapid toggle of Force Speaker Output switch
- Properly unsubscribe PlaybackEnded before disposing old player
- Fix iOS docs: speaker override does not override wired/BT devices

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix XML docs: speaker override does not override wired/BT

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add Windows output device selection support

- Add AudioPlayerOptions.PreferredOutputDeviceName property (string)
- Enumerate audio render devices via DeviceInformation.FindAllAsync
- Match by partial name (case-insensitive), set MediaPlayer.AudioDevice
- Update docs, README, and sample app with Windows examples
- Cross-platform example now covers all three platforms

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix SetSource reapply and docs note for Windows

- Reapply PreferredOutputDeviceName after SetSource on Windows
- Fix docs note: options are customizable on all platforms now

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Gerald Versluis <gerald@verslu.is>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

README.md

@@ -69,6 +69,28 @@ Now that you know how to use the `AudioManager` class, please refer to the follo
 * [Stream audio](docs/audio-streamer.md)
 * [Audio listeners](docs/audio-listeners.md)
 
+### Output Device Selection
+
+You can control which audio output device is used for playback. For example, force audio through the device speaker even when Bluetooth is connected:
+
+```csharp
+var player = audioManager.CreatePlayer(
+    await FileSystem.OpenAppPackageFileAsync("ukelele.mp3"),
+    new AudioPlayerOptions
+    {
+#if ANDROID
+        PreferredOutputDevice = Plugin.Maui.Audio.AudioOutputDevice.Speaker
+#elif IOS || MACCATALYST
+        Category = AVFoundation.AVAudioSessionCategory.PlayAndRecord,
+        PreferredOutputPort = Plugin.Maui.Audio.AudioOutputPort.Speaker
+#elif WINDOWS
+        PreferredOutputDeviceName = "Speakers"
+#endif
+    });
+```
+
+For more details, see the [Audio playback documentation](docs/audio-player.md#controlling-audio-output-deviceport).
+
 ## Supported Audio Formats
 
 ### Audio Playback

docs/audio-player.md

@@ -26,7 +26,7 @@ public class AudioPlayerViewModel
 When calling `CreatePlayer` it is possible to provide an optional parameter of type `AudioPlayerOptions`, this parameter makes it possible to customize the playback settings at the platform level. 
 
 > [!NOTE]
-> Currently you can only customize options for iOS, macOS and Android.
+> Currently you can customize options for iOS, macOS, Android, and Windows.
 
 The following example shows how to configure your audio to blend in with existing audio being played on device on iOS and macOS:
 
@@ -123,6 +123,101 @@ When `HandleAudioInterruptions` is set to `false`, the player will not automatic
 > [!NOTE]
 > By default, both `ManageAudioFocus` (Android) and `HandleAudioInterruptions` (iOS/macOS) are enabled (`true`). Your app will properly interact with system audio and other apps out of the box. The audio focus management is handled transparently - you can still control playback manually using `Play()`, `Pause()`, and `Stop()` methods. For backward compatibility, playback will continue even if audio focus cannot be acquired, though this is rare.
 
+## Controlling Audio Output Device/Port
+
+You can control which audio output device or port is used for playback on all platforms.
+
+### Android - Output Device Selection
+
+On Android, you can specify which audio output device should be used for playback. This is useful when you want to ensure audio plays through a specific output, such as the device speaker, even when other outputs like Bluetooth are connected.
+
+```csharp
+audioManager.CreatePlayer(
+    await FileSystem.OpenAppPackageFileAsync("ukelele.mp3"),
+    new AudioPlayerOptions
+    {
+#if ANDROID
+        PreferredOutputDevice = Plugin.Maui.Audio.AudioOutputDevice.Speaker
+#endif
+    });
+```
+
+This feature requires Android API 28 (Android 9.0 Pie) or higher. On older versions, the setting will be ignored and the system default routing will be used.
+
+Available output device options include:
+- `AudioOutputDevice.Default` - Use system default routing
+- `AudioOutputDevice.Speaker` - Built-in device speaker (loudspeaker)
+- `AudioOutputDevice.Earpiece` - Built-in earpiece (typically used for phone calls)
+- `AudioOutputDevice.WiredHeadset` - Wired headset or headphones with microphone
+- `AudioOutputDevice.WiredHeadphones` - Wired headphones without microphone
+- `AudioOutputDevice.BluetoothA2dp` - Bluetooth device with A2DP profile (e.g., Bluetooth headphones, car audio)
+- `AudioOutputDevice.BluetoothSco` - Bluetooth SCO device (typically used for phone calls)
+- `AudioOutputDevice.UsbDevice` - USB audio device
+- `AudioOutputDevice.UsbAccessory` - USB accessory
+- `AudioOutputDevice.AuxLine` - Auxiliary line connection (e.g., 3.5mm aux cable)
+
+**Note:** The system treats this as a preference, not a guarantee. If the requested device is not available or connected, the system will fall back to its default routing behavior.
+
+### iOS/macOS - Output Port Override
+
+On iOS, you can override the audio output port to force audio to play through the built-in speaker instead of the earpiece when no external audio devices are connected. This is primarily useful for `PlayAndRecord` sessions where the default output is the earpiece.
+
+> [!IMPORTANT]
+> The speaker override requires the audio session category to be set to `PlayAndRecord`. If your session uses the default `Playback` category, the plugin will automatically upgrade to `PlayAndRecord` when a speaker override is requested. Note that speaker override does **not** override wired headphones or Bluetooth — when those are connected, audio will route to them regardless of this setting. On Mac Catalyst, speaker override has no effect since Macs do not distinguish between speaker and earpiece routing.
+
+```csharp
+audioManager.CreatePlayer(
+    await FileSystem.OpenAppPackageFileAsync("ukelele.mp3"),
+    new AudioPlayerOptions
+    {
+#if IOS || MACCATALYST
+        Category = AVFoundation.AVAudioSessionCategory.PlayAndRecord,
+        PreferredOutputPort = Plugin.Maui.Audio.AudioOutputPort.Speaker
+#endif
+    });
+```
+
+Available output port options include:
+- `AudioOutputPort.Default` - Use system default routing
+- `AudioOutputPort.Speaker` - Force output to built-in speaker
+
+**Note:** Unlike Android's per-player device selection, iOS uses a session-wide port override that affects all audio output on the device. The override remains in effect until explicitly changed back to `AudioOutputPort.Default` or all players using the override are disposed.
+
+### Windows - Output Device Selection
+
+On Windows, you can specify which audio output device should be used for playback by providing the device name (or a partial name match).
+
+```csharp
+audioManager.CreatePlayer(
+    await FileSystem.OpenAppPackageFileAsync("ukelele.mp3"),
+    new AudioPlayerOptions
+    {
+#if WINDOWS
+        PreferredOutputDeviceName = "Speakers"
+#endif
+    });
+```
+
+The first audio render device whose name contains the specified value (case-insensitive) will be selected. If the specified device is not found, the system default audio device will be used.
+
+### Cross-Platform Example
+
+```csharp
+var options = new AudioPlayerOptions
+{
+#if ANDROID
+    PreferredOutputDevice = Plugin.Maui.Audio.AudioOutputDevice.Speaker,
+#elif IOS || MACCATALYST
+    Category = AVFoundation.AVAudioSessionCategory.PlayAndRecord,
+    PreferredOutputPort = Plugin.Maui.Audio.AudioOutputPort.Speaker,
+#elif WINDOWS
+    PreferredOutputDeviceName = "Speakers",
+#endif
+};
+var player = audioManager.CreatePlayer(await FileSystem.OpenAppPackageFileAsync("ukelele.mp3"), options);
+player.Play(); // Audio plays through device speaker on all platforms
+```
+
 ## AudioPlayer API
 
 Once you have created an `AudioPlayer` you can interact with it in the following ways:

samples/Plugin.Maui.Audio.Sample/Pages/MusicPlayerPage.xaml

@@ -108,6 +108,11 @@
                 Maximum="{Binding MaximumSpeed}"
                 Value="{Binding UserSpeed}"
 				DragCompletedCommand="{Binding UpdateSpeedCommand}"/>
+
+			<HorizontalStackLayout HorizontalOptions="Center" Spacing="3">
+				<Label Text="Force Speaker Output:" VerticalOptions="Center" />
+				<Switch IsToggled="{Binding ForceSpeakerOutput}" VerticalOptions="Center" />
+			</HorizontalStackLayout>
 		</VerticalStackLayout>
     </ScrollView>
 

samples/Plugin.Maui.Audio.Sample/ViewModels/MusicPlayerPageViewModel.cs

@@ -188,6 +188,87 @@ public void UpdateSpeed()
 	public double MinimumSpeed => audioPlayer?.MinimumSpeed ?? 1;
 	public double MaximumSpeed => audioPlayer?.MaximumSpeed ?? 1;
 
+	bool forceSpeakerOutput;
+	public bool ForceSpeakerOutput
+	{
+		get => forceSpeakerOutput;
+		set
+		{
+			if (forceSpeakerOutput == value)
+			{
+				return;
+			}
+
+			forceSpeakerOutput = value;
+			NotifyPropertyChanged();
+			ReloadWithOutputDevice();
+		}
+	}
+
+	bool isReloadingOutputDevice;
+
+	async void ReloadWithOutputDevice()
+	{
+		if (musicItemViewModel is null || isReloadingOutputDevice)
+		{
+			return;
+		}
+
+		isReloadingOutputDevice = true;
+
+		try
+		{
+			var wasPlaying = audioPlayer?.IsPlaying ?? false;
+			var position = audioPlayer?.CurrentPosition ?? 0;
+
+			if (audioPlayer is not null)
+			{
+				audioPlayer.PlaybackEnded -= AudioPlayer_PlaybackEnded;
+				audioPlayer.Dispose();
+				audioPlayer = null;
+			}
+
+			var options = new AudioPlayerOptions();
+
+#if ANDROID
+			options.PreferredOutputDevice = forceSpeakerOutput
+				? AudioOutputDevice.Speaker
+				: AudioOutputDevice.Default;
+#elif IOS || MACCATALYST
+			if (forceSpeakerOutput)
+			{
+				options.Category = AVFoundation.AVAudioSessionCategory.PlayAndRecord;
+				options.PreferredOutputPort = AudioOutputPort.Speaker;
+			}
+#elif WINDOWS
+			options.PreferredOutputDeviceName = forceSpeakerOutput ? "Speakers" : null;
+#endif
+
+			audioPlayer = audioManager.CreatePlayer(
+				await FileSystem.OpenAppPackageFileAsync(musicItemViewModel.Filename),
+				options);
+			audioPlayer.PlaybackEnded += AudioPlayer_PlaybackEnded;
+
+			if (position > 0 && audioPlayer.CanSeek)
+			{
+				audioPlayer.Seek(position);
+			}
+
+			if (wasPlaying)
+			{
+				audioPlayer.Play();
+			}
+
+			NotifyPropertyChanged(nameof(HasAudioSource));
+			NotifyPropertyChanged(nameof(Duration));
+			NotifyPropertyChanged(nameof(IsPlaying));
+		}
+		finally
+		{
+			isReloadingOutputDevice = false;
+		}
+	}
+
 	public bool Loop
 	{
 		get => audioPlayer?.Loop ?? false;

src/Plugin.Maui.Audio/AudioPlayer/AudioOutputDevice.android.cs

@@ -0,0 +1,73 @@
+using Android.Media;
+
+namespace Plugin.Maui.Audio;
+
+/// <summary>
+/// Specifies the preferred audio output device type for Android.
+/// </summary>
+/// <remarks>
+/// This enum is used to specify which audio output device should be preferred for playback.
+/// Requires Android API 28 (Android 9.0 Pie) or higher for setting the preferred device.
+/// On older versions, this setting will be ignored and the system default routing will be used.
+/// </remarks>
+public enum AudioOutputDevice
+{
+	/// <summary>
+	/// Use the system default audio output device. No preferred device will be set.
+	/// </summary>
+	Default = 0,
+
+	/// <summary>
+	/// Route audio to the built-in device speaker (typically the loudspeaker).
+	/// Corresponds to <see cref="AudioDeviceType.BuiltinSpeaker"/>.
+	/// </summary>
+	Speaker = AudioDeviceType.BuiltinSpeaker,
+
+	/// <summary>
+	/// Route audio to the built-in earpiece (typically used for phone calls).
+	/// Corresponds to <see cref="AudioDeviceType.BuiltinEarpiece"/>.
+	/// </summary>
+	Earpiece = AudioDeviceType.BuiltinEarpiece,
+
+	/// <summary>
+	/// Route audio to a wired headset or headphones.
+	/// Corresponds to <see cref="AudioDeviceType.WiredHeadset"/>.
+	/// </summary>
+	WiredHeadset = AudioDeviceType.WiredHeadset,
+
+	/// <summary>
+	/// Route audio to a wired headphone device.
+	/// Corresponds to <see cref="AudioDeviceType.WiredHeadphones"/>.
+	/// </summary>
+	WiredHeadphones = AudioDeviceType.WiredHeadphones,
+
+	/// <summary>
+	/// Route audio to a Bluetooth device with A2DP profile (e.g., Bluetooth headphones, car audio).
+	/// Corresponds to <see cref="AudioDeviceType.BluetoothA2dp"/>.
+	/// </summary>
+	BluetoothA2dp = AudioDeviceType.BluetoothA2dp,
+
+	/// <summary>
+	/// Route audio to a Bluetooth SCO (Synchronous Connection Oriented) device (typically used for phone calls).
+	/// Corresponds to <see cref="AudioDeviceType.BluetoothSco"/>.
+	/// </summary>
+	BluetoothSco = AudioDeviceType.BluetoothSco,
+
+	/// <summary>
+	/// Route audio to an auxiliary line connection (e.g., 3.5mm aux cable).
+	/// Corresponds to <see cref="AudioDeviceType.AuxLine"/>.
+	/// </summary>
+	AuxLine = AudioDeviceType.AuxLine,
+
+	/// <summary>
+	/// Route audio to a USB audio device.
+	/// Corresponds to <see cref="AudioDeviceType.UsbDevice"/>.
+	/// </summary>
+	UsbDevice = AudioDeviceType.UsbDevice,
+
+	/// <summary>
+	/// Route audio to a USB accessory.
+	/// Corresponds to <see cref="AudioDeviceType.UsbAccessory"/>.
+	/// </summary>
+	UsbAccessory = AudioDeviceType.UsbAccessory,
+}

src/Plugin.Maui.Audio/AudioPlayer/AudioOutputPort.macios.cs

@@ -0,0 +1,27 @@
+using AVFoundation;
+
+namespace Plugin.Maui.Audio;
+
+/// <summary>
+/// Specifies the preferred audio output port override for iOS/macOS.
+/// </summary>
+/// <remarks>
+/// This enum controls audio routing on iOS/macOS platforms using AVAudioSession.
+/// Unlike Android's device-specific routing, iOS uses a session-wide port override that affects all audio.
+/// </remarks>
+public enum AudioOutputPort : ulong
+{
+	/// <summary>
+	/// Use the default audio routing behavior. The system will route audio based on connected devices.
+	/// Corresponds to <see cref="AVAudioSessionPortOverride.None"/>.
+	/// </summary>
+	Default = AVAudioSessionPortOverride.None,
+
+	/// <summary>
+	/// Force audio output to the built-in speaker, overriding the default earpiece routing.
+	/// This is primarily useful when using the PlayAndRecord category, where the default output is the earpiece.
+	/// Note: This does not override wired headphones or Bluetooth devices — when those are connected, audio routes to them regardless.
+	/// Corresponds to <see cref="AVAudioSessionPortOverride.Speaker"/>.
+	/// </summary>
+	Speaker = AVAudioSessionPortOverride.Speaker,
+}