From 63d2635719d0431802e2e1c933c23c3c1c2a2d5e Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Sun, 17 May 2026 08:47:36 -0700
Subject: [PATCH] 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 | 20 ++++++++++++++++++--
src/audio/coreaudio/SDL_coreaudio.m | 4 +++-
2 files changed, 21 insertions(+), 3 deletions(-)
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index 82f04e6d85602..160b89f89cfc1 100644
--- a/include/SDL3/SDL_hints.h
+++ b/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.
*
diff --git a/src/audio/coreaudio/SDL_coreaudio.m b/src/audio/coreaudio/SDL_coreaudio.m
index 5342d3d28d98f..5fb3cb74cb508 100644
--- a/src/audio/coreaudio/SDL_coreaudio.m
+++ b/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) {