Add option to disable automatic audio session deactivation (#881)

Calling `setActive(false)` could disrupt other audio in the app. I
believe it's relatively harmless to not call it. But in this PR we keep
the default to automatic deactivation and add doc about it.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added `isAutomaticDeactivationEnabled` option to control whether the
audio session is automatically deactivated when both playout and
recording are disabled. The audio session will remain active after calls
end when this option is disabled.

* **Documentation**
* Added documentation section explaining the new automatic audio session
deactivation control, including usage examples.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Błażej Pankowski <[email protected]>

Author: hiroshihorie

.changes/audio-session-deactivation-option

@@ -0,0 +1 @@
+patch type="changed" "Add option to disable automatic audio session deactivation"

Docs/audio.md

@@ -8,6 +8,20 @@ By default, the SDK automatically configures the `AVAudioSession`. However, this
 AudioManager.shared.audioSession.isAutomaticConfigurationEnabled = false
 ```
 
+## Disabling automatic `AVAudioSession` deactivation
+
+> **Note**: If you have already set `isAutomaticConfigurationEnabled = false`, you don't need to worry about this setting since the SDK won't touch the audio session at all.
+
+By default, the SDK deactivates the `AVAudioSession` when both playout and recording are disabled (e.g., after disconnecting from a room). This allows other apps' audio (like Music) to resume.
+
+However, if your app has its own audio features that could be disrupted by deactivating the audio session, you can disable automatic deactivation:
+
+```swift
+AudioManager.shared.audioSession.isAutomaticDeactivationEnabled = false
+```
+
+When set to `false`, the audio session remains active after the LiveKit call ends, preserving your app's audio state.
+
 ## Disabling Voice Processing
 
 Apple's voice processing is enabled by default, such as echo cancellation and auto-gain control.

Sources/LiveKit/Audio/AudioSessionEngineObserver.swift

@@ -18,8 +18,6 @@
 
 import AVFoundation
 
-internal import LiveKitWebRTC
-
 /// An ``AudioEngineObserver`` that configures the `AVAudioSession` based on the state of the audio engine.
 public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @unchecked Sendable {
     /// Controls automatic configuration of the `AVAudioSession` based on audio engine state.
@@ -35,6 +33,22 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
         set { _state.mutate { $0.isAutomaticConfigurationEnabled = newValue } }
     }
 
+    /// Controls whether the audio session is deactivated when the audio engine stops.
+    ///
+    /// - When `true`: The `AVAudioSession` is deactivated when both playout and recording are disabled
+    /// - When `false`: The `AVAudioSession` remains active when the audio engine stops
+    ///
+    /// > Note: This value is only used when `isAutomaticConfigurationEnabled` is `true`.
+    ///
+    /// > Tip: Set to `false` if your app has other audio features that could be disrupted
+    /// > by deactivating the audio session.
+    ///
+    /// Default value: `true`
+    public var isAutomaticDeactivationEnabled: Bool {
+        get { _state.isAutomaticDeactivationEnabled }
+        set { _state.mutate { $0.isAutomaticDeactivationEnabled = newValue } }
+    }
+
     /// Controls the speaker output preference for audio routing.
     ///
     /// - When `true`: The speaker output is preferred over the receiver output
@@ -52,6 +66,7 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
         var next: (any AudioEngineObserver)?
 
         var isAutomaticConfigurationEnabled: Bool = true
+        var isAutomaticDeactivationEnabled: Bool = true
         var isPlayoutEnabled: Bool = false
         var isRecordingEnabled: Bool = false
         var isSpeakerOutputPreferred: Bool = true
@@ -84,20 +99,18 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
     }
 
     @Sendable func configure(oldState: State, newState: State) {
-        let session = LKRTCAudioSession.sharedInstance()
-
-        session.lockForConfiguration()
-        defer {
-            session.unlockForConfiguration()
-            log("AudioSession activationCount: \(session.activationCount), webRTCSessionCount: \(session.webRTCSessionCount)")
-        }
+        let session = AVAudioSession.sharedInstance()
 
         if (!newState.isPlayoutEnabled && !newState.isRecordingEnabled) && (oldState.isPlayoutEnabled || oldState.isRecordingEnabled) {
-            do {
-                log("AudioSession deactivating...")
-                try session.setActive(false)
-            } catch {
-                log("AudioSession failed to deactivate with error: \(error)", .error)
+            if newState.isAutomaticDeactivationEnabled {
+                do {
+                    log("AudioSession deactivating...")
+                    try session.setActive(false, options: .notifyOthersOnDeactivation)
+                } catch {
+                    log("AudioSession failed to deactivate with error: \(error)", .error)
+                }
+            } else {
+                log("AudioSession deactivation skipped...")
             }
         } else if newState.isRecordingEnabled || newState.isPlayoutEnabled {
             // Configure and activate the session with the appropriate category
@@ -106,7 +119,7 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
 
             do {
                 log("AudioSession configuring category to: \(config.category)")
-                try session.setConfiguration(config.toRTCType())
+                try session.setCategory(config.category, mode: config.mode, options: config.categoryOptions)
             } catch {
                 log("AudioSession failed to configure with error: \(error)", .error)
             }