Added SDL_HINT_AUDIO_DUCK_OTHERS

Previously default audio on Apple platforms would duck other audio streams. This is unexpected, so by default we won't do that and you can use the hint SDL_HINT_AUDIO_DUCK_OTHERS to re-enable that behavior.

include/SDL3/SDL_hints.h

@@ -294,9 +294,9 @@ extern "C" {
  *
  * The variable can be set to the following values:
  *
+ * - "playback": Use the AVAudioSessionCategoryPlayback category. (default)
  * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be
- *   muted by the phone mute switch (default)
- * - "playback": Use the AVAudioSessionCategoryPlayback category.
+ *   muted by the phone mute switch.
  *
  * For more information, see Apple's documentation:
  * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
@@ -506,6 +506,22 @@ extern "C" {
  */
 #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER"
 
+/**
+ * Specify whether this audio stream should duck other audio.
+ *
+ * On Apple platforms, this hint controls whether other audio streams are ducked (reduced in volume) while your application is in the foreground.
+ *
+ * The variable can be set to the following values:
+ *
+ * - "0": Other audio will not be ducked. (default)
+ * - "1": Other audio will be ducked.
+ *
+ * This hint should be set before an audio device is opened.
+ *
+ * \since This hint is available since SDL 3.6.0.
+ */
+#define SDL_HINT_AUDIO_DUCK_OTHERS "SDL_AUDIO_DUCK_OTHERS"
+
 /**
  * A variable controlling the audio rate when using the dummy audio driver.
  *

src/audio/coreaudio/SDL_coreaudio.m

@@ -464,7 +464,9 @@ static bool UpdateAudioSession(SDL_AudioDevice *device, bool open, bool allow_pl
         }
         if (category == AVAudioSessionCategoryPlayback ||
             category == AVAudioSessionCategoryPlayAndRecord) {
-            options |= AVAudioSessionCategoryOptionDuckOthers;
+            if (SDL_GetHintBoolean(SDL_HINT_AUDIO_DUCK_OTHERS, false)) {
+                options |= AVAudioSessionCategoryOptionDuckOthers;
+            }
         }
 
         if (![session.category isEqualToString:category] || session.categoryOptions != options) {