feat: adding the audio ducking

Author: Mhp23

android/src/main/java/com/speech/SpeechModule.kt

@@ -4,7 +4,11 @@ import java.util.UUID
 import java.util.Locale
 import android.os.Build
 import android.os.Bundle
+import android.content.Context
 import android.speech.tts.Voice
+import android.media.AudioManager
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
 import android.annotation.SuppressLint
 import android.speech.tts.TextToSpeech
 import com.facebook.react.bridge.Promise
@@ -27,11 +31,11 @@ class SpeechModule(reactContext: ReactApplicationContext) :
   companion object {
     const val NAME = "Speech"
 
-    @SuppressLint("ConstantLocale")
     private val defaultOptions: Map<String, Any> = mapOf(
       "rate" to 0.5f,
       "pitch" to 1.0f,
       "volume" to 1.0f,
+      "ducking" to false,
       "language" to Locale.getDefault().toLanguageTag()
     )
   }
@@ -55,10 +59,59 @@ class SpeechModule(reactContext: ReactApplicationContext) :
   private var currentQueueIndex = -1
   private val speechQueue = mutableListOf<SpeechQueueItem>()
 
+  private val audioManager: AudioManager by lazy {
+    reactApplicationContext.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+  }
+  private var audioFocusChangeListener: AudioManager.OnAudioFocusChangeListener? = null
+  private var audioFocusRequest: AudioFocusRequest? = null
+  private var isDucking = false
+
   init {
     initializeTTS()
   }
 
+  private fun activateDuckingSession() {
+    if (!isDucking) return
+
+    audioFocusChangeListener = AudioManager.OnAudioFocusChangeListener { }
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      val audioAttributes = AudioAttributes.Builder()
+        .setUsage(AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY)
+        .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+        .build()
+      val focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)
+        .setAudioAttributes(audioAttributes)
+        .setOnAudioFocusChangeListener(audioFocusChangeListener!!)
+        .build()
+      audioFocusRequest = focusRequest
+      audioManager.requestAudioFocus(focusRequest)
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.requestAudioFocus(
+        audioFocusChangeListener,
+        AudioManager.STREAM_MUSIC,
+        AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK
+      )
+    }
+  }
+
+  private fun deactivateDuckingSession() {
+    if (!isDucking) return
+    audioFocusChangeListener ?: return
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      audioFocusRequest?.let { request ->
+        audioManager.abandonAudioFocusRequest(request)
+      }
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.abandonAudioFocus(audioFocusChangeListener)
+    }
+    audioFocusChangeListener = null
+    audioFocusRequest = null
+  }
+
   private fun processPendingOperations() {
     val operations = ArrayList(pendingOperations)
     pendingOperations.clear()
@@ -143,6 +196,7 @@ class SpeechModule(reactContext: ReactApplicationContext) :
             synchronized(queueLock) {
               speechQueue.find { it.utteranceId == utteranceId }?.let { item ->
                 item.status = SpeechStatus.COMPLETED
+                deactivateDuckingSession()
                 emitOnFinish(getEventData(utteranceId))
                 if (!isPaused) {
                   currentQueueIndex++
@@ -155,6 +209,7 @@ class SpeechModule(reactContext: ReactApplicationContext) :
             synchronized(queueLock) {
               speechQueue.find { it.utteranceId == utteranceId }?.let { item ->
                 item.status = SpeechStatus.ERROR
+                deactivateDuckingSession()
                 emitOnError(getEventData(utteranceId))
                 if (!isPaused) {
                   currentQueueIndex++
@@ -265,6 +320,9 @@ class SpeechModule(reactContext: ReactApplicationContext) :
   private fun getValidatedOptions(options: ReadableMap): Map<String, Any> {
     val validated = globalOptions.toMutableMap()
 
+    if (options.hasKey("ducking")) {
+      validated["ducking"] = options.getBoolean("ducking")
+    }
     if (options.hasKey("voice")) {
       options.getString("voice")?.let { validated["voice"] = it }
     }
@@ -368,6 +426,7 @@ class SpeechModule(reactContext: ReactApplicationContext) :
     ensureInitialized(promise) {
       if (synthesizer.isSpeaking || isPaused) {
         synthesizer.stop()
+        deactivateDuckingSession()
         synchronized(queueLock) {
           if (currentQueueIndex in speechQueue.indices) {
             val item = speechQueue[currentQueueIndex]
@@ -387,6 +446,7 @@ class SpeechModule(reactContext: ReactApplicationContext) :
       } else {
         isPaused = true
         synthesizer.stop()
+        deactivateDuckingSession()
         promise.resolve(true)
       }
     }
@@ -403,6 +463,7 @@ class SpeechModule(reactContext: ReactApplicationContext) :
         if (pausedItemIndex >= 0) {
           currentQueueIndex = pausedItemIndex
           isPaused = false
+          activateDuckingSession()
           processNextQueueItem()
           promise.resolve(true)
         } else {
@@ -419,6 +480,8 @@ class SpeechModule(reactContext: ReactApplicationContext) :
       return
     }
     ensureInitialized(promise) {
+      isDucking = globalOptions["ducking"] as? Boolean ?: false
+      activateDuckingSession()
       val utteranceId = getUniqueID()
       val queueItem = SpeechQueueItem(text = text, options = emptyMap(), utteranceId = utteranceId)
       synchronized(queueLock) {
@@ -438,8 +501,10 @@ class SpeechModule(reactContext: ReactApplicationContext) :
       return
     }
     ensureInitialized(promise) {
+      val validatedOptions = getValidatedOptions(options) 
+      isDucking = validatedOptions["ducking"] as? Boolean ?: false
+      activateDuckingSession()
       val utteranceId = getUniqueID()
-      val validatedOptions = getValidatedOptions(options)
       val queueItem = SpeechQueueItem(text = text, options = validatedOptions, utteranceId = utteranceId)
       synchronized(queueLock) {
         speechQueue.add(queueItem)

example/src/views/RootView.tsx

@@ -22,7 +22,7 @@ const RootView: React.FC = () => {
   >([]);
 
   React.useEffect(() => {
-    // Speech.initialize({silentMode: 'ignore'});
+    // Speech.initialize({silentMode: 'obey', ducking: true});
 
     const onSpeechEnd = () => {
       setIsStarted(false);

ios/Speech.mm

@@ -4,6 +4,7 @@
 
 @implementation Speech
 {
+  BOOL isDucking;
   NSDictionary *defaultOptions;
 }
 
@@ -19,25 +20,65 @@ - (instancetype)init {
   if (self) {
     _synthesizer = [[AVSpeechSynthesizer alloc] init];
     _synthesizer.delegate = self;
-    
+
     defaultOptions = @{
       @"pitch": @(1.0),
       @"volume": @(1.0),
+      @"ducking": @(NO),
       @"silentMode": @"obey",
       @"rate": @(AVSpeechUtteranceDefaultSpeechRate),
       @"language": [AVSpeechSynthesisVoice currentLanguageCode] ?: @"en-US"
     };
-    
     self.globalOptions = [defaultOptions copy];
   }
   return self;
 }
 
-- (void)configureSilentModeSession:(NSString *)silentMode {
+- (void)activateDuckingSession {
+  if (!isDucking) {
+    return;
+  }
+  NSError *error = nil;
+  AVAudioSession *session = [AVAudioSession sharedInstance];
+
+  [session setCategory:AVAudioSessionCategoryPlayback
+            mode:AVAudioSessionModeSpokenAudio
+            options:AVAudioSessionCategoryOptionDuckOthers
+                  error:&error];
+  if (error) {
+    NSLog(@"[Speech] Failed to set audio session configuration for ducking: %@", error.localizedDescription);
+    return;
+  }
+  [session setActive:YES error:&error];
+  if (error) {
+    NSLog(@"[Speech] Failed to activate audio session for ducking: %@", error.localizedDescription);
+  }
+}
+
+- (void)deactivateDuckingSession {
+  if (!isDucking) {
+    return;
+  }
   NSError *error = nil;
+  [[AVAudioSession sharedInstance] setActive:NO
+                                 withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation
+                                       error:&error];
+
+  if (error) {
+    NSLog(@"[Speech] AVAudioSession setActive (deactivate) error: %@", error.localizedDescription);
+  }
+}
 
+- (void)configureSilentModeSession:(NSString *)silentMode {
+  if (isDucking || [silentMode isEqualToString:@"obey"]) {
+    return;
+  }
+  NSError *error = nil;
   if ([silentMode isEqualToString:@"ignore"]) {
-    [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:&error];
+     [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback
+             mode:AVAudioSessionModeSpokenAudio
+             options:AVAudioSessionCategoryOptionInterruptSpokenAudioAndMixWithOthers
+                   error:&error];
   } else if ([silentMode isEqualToString:@"respect"]) {
     [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryAmbient error:&error];
   }
@@ -64,6 +105,9 @@ - (NSDictionary *)getVoiceItem:(AVSpeechSynthesisVoice *)voice {
 - (NSDictionary *)getValidatedOptions:(VoiceOptions &)options {
   NSMutableDictionary *validatedOptions = [self.globalOptions mutableCopy];
 
+  if (options.ducking()) {
+    validatedOptions[@"ducking"] = @(options.ducking().value());
+  }
   if (options.voice()) {
     validatedOptions[@"voice"] = options.voice();
   }
@@ -165,6 +209,7 @@ - (void)stop:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)rejec
 - (void)pause:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
   if (self.synthesizer.isSpeaking && !self.synthesizer.isPaused) {
     BOOL paused = [self.synthesizer pauseSpeakingAtBoundary:AVSpeechBoundaryImmediate];
+    [self deactivateDuckingSession];
     resolve(@(paused));
   } else {
     resolve(@(false));
@@ -173,6 +218,7 @@ - (void)pause:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reje
 
 - (void)resume:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
   if (self.synthesizer.isPaused) {
+    [self activateDuckingSession];
     BOOL resumed = [self.synthesizer continueSpeaking];
     resolve(@(resumed));
   } else {
@@ -192,13 +238,17 @@ - (void)speak:(NSString *)text
   AVSpeechUtterance *utterance;
 
   @try {
+    isDucking = [self.globalOptions[@"ducking"] boolValue];
+
+    [self activateDuckingSession];
     [self configureSilentModeSession:self.globalOptions[@"silentMode"]];
 
     utterance = [self getUtterance:text withOptions:self.globalOptions];
     [self.synthesizer speakUtterance:utterance];
     resolve(nil);
   }
   @catch (NSException *exception) {
+    [self deactivateDuckingSession];
     [self emitOnError:[self getEventData:utterance]];
     reject(@"speech_error", exception.reason, nil);
   }
@@ -218,13 +268,17 @@ - (void)speakWithOptions:(NSString *)text
 
   @try {
     NSDictionary *validatedOptions = [self getValidatedOptions:options];
+    isDucking = [validatedOptions[@"ducking"] boolValue];
+
+    [self activateDuckingSession];
     [self configureSilentModeSession:validatedOptions[@"silentMode"]];
 
     utterance = [self getUtterance:text withOptions:validatedOptions];
     [self.synthesizer speakUtterance:utterance];
     resolve(nil);
   }
   @catch (NSException *exception) {
+    [self deactivateDuckingSession];
     [self emitOnError:[self getEventData:utterance]];
     reject(@"speech_error", exception.reason, nil);
   }
@@ -246,6 +300,7 @@ - (void)speechSynthesizer:(AVSpeechSynthesizer *)synthesizer
 
 - (void)speechSynthesizer:(AVSpeechSynthesizer *)synthesizer
   didFinishSpeechUtterance:(AVSpeechUtterance *)utterance {
+  [self deactivateDuckingSession];
   [self emitOnFinish:[self getEventData:utterance]];
 }
 
@@ -261,6 +316,7 @@ - (void)speechSynthesizer:(AVSpeechSynthesizer *)synthesizer
 
 - (void)speechSynthesizer:(AVSpeechSynthesizer *)synthesizer
   didCancelSpeechUtterance:(AVSpeechUtterance *)utterance {
+  [self deactivateDuckingSession];
   [self emitOnStopped:[self getEventData:utterance]];
 }
 

src/NativeSpeech.ts

@@ -31,12 +31,19 @@ export interface VoiceProps {
 }
 export interface VoiceOptions {
   /**
-   * Determines how speech audio should behave with the iOS silent switch (ringer)
+   * If `true`, audio from other apps will be temporarily lowered (ducked) while speech is active.
+   * This is for critical announcements (e.g., navigation) and takes priority over `silentMode` on iOS.
+   * @default false
+   */
+  ducking?: boolean;
+  /**
+   * Determines how speech audio interacts with the device's silent (ringer) switch.
+   * This option is ignored if `ducking` is `true`.
    * @platform ios
    *
-   * - `obey`: (Default) The library does not change the app's audio session. Speech audio will follow the app's current audio configuration or the system default
-   * - `respect`: Speech audio will be silenced by the ringer switch. This is for non-critical speech
-   * - `ignore`: Speech audio will play even if the ringer switch is on silent. Use this for critical speech like navigation
+   * - `obey`: (Default) Does not change the app's audio session. Speech follows the system default.
+   * - `respect`: Speech will be silenced by the ringer switch. Use for non-critical audio.
+   * - `ignore`: Speech will play even if the ringer is off. Use for critical audio when ducking is not desired.
    */
   silentMode?: 'obey' | 'respect' | 'ignore';
   /** The language code to use (e.g., 'en', 'fr', 'en-US', 'fr-FR') */