Sound API 2

.changes/sound-api-2

@@ -0,0 +1 @@
+minor type="added" "SoundPlayer API for prepared audio clips with local playback and best-effort remote playback"

Sources/LiveKit/Audio/AudioSessionEngineObserver.swift

@@ -69,13 +69,15 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
 
         var isAutomaticConfigurationEnabled: Bool = true
         var isAutomaticDeactivationEnabled: Bool = true
-        var isPlayoutEnabled: Bool = false
-        var isRecordingEnabled: Bool = false
         var isSpeakerOutputPreferred: Bool = true
+
+        var sessionRequirements: [UUID: SessionRequirement] = [:]
     }
 
     let _state = StateSync(State())
 
+    private let sessionRequirementId = UUID()
+
     public var next: (any AudioEngineObserver)? {
         get { _state.next }
         set { _state.mutate { $0.next = newValue } }
@@ -85,14 +87,64 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
         _state.onDidMutate = { [weak self] new, old in
             guard let self,
                   new.isSpeakerOutputPreferred != old.isSpeakerOutputPreferred else { return }
-            _ = configureIfNeeded(oldState: old, newState: new)
+            do {
+                try configureIfNeeded(oldState: old, newState: new)
+            } catch {
+                log("Failed to configure audio session after speaker preference change: \(error)", .error)
+            }
+        }
+    }
+
+    /// Acquires an audio session requirement handle for external ownership.
+    ///
+    /// Use this to keep the audio session active from external components
+    /// (e.g., ``SoundPlayer``) that need playout or recording independently
+    /// of the WebRTC engine lifecycle.
+    ///
+    /// - Throws: ``LiveKitError`` if the audio session fails to configure or activate.
+    public func acquire(requirement: SessionRequirement) throws -> SessionRequirementHandle {
+        let id = UUID()
+        try set(requirement: requirement, for: id)
+        return SessionRequirementHandle(releaseImpl: { [weak self] in
+            guard let self else { return }
+            try removeRequirement(for: id)
+        })
+    }
+
+    private func set(requirement: SessionRequirement, for id: UUID) throws {
+        try updateRequirements {
+            if requirement == .none {
+                $0.removeValue(forKey: id)
+            } else {
+                $0[id] = requirement
+            }
+        }
+    }
+
+    fileprivate func removeRequirement(for id: UUID) throws {
+        try updateRequirements {
+            $0.removeValue(forKey: id)
+        }
+    }
+
+    private func updateRequirements(_ block: (inout [UUID: SessionRequirement]) -> Void) throws {
+        try _state.mutate {
+            let oldState = $0
+            block(&$0.sessionRequirements)
+            guard $0.sessionRequirements != oldState.sessionRequirements else { return }
+            do {
+                try configureIfNeeded(oldState: oldState, newState: $0)
+            } catch {
+                $0 = oldState
+                throw LiveKitError(.audioSession, message: "Failed to configure audio session")
+            }
         }
     }
 
     // MARK: - Audio Session Configuration
 
-    private func configureIfNeeded(oldState: State, newState: State) -> Int {
-        guard newState.isAutomaticConfigurationEnabled else { return 0 }
+    private func configureIfNeeded(oldState: State, newState: State) throws {
+        guard newState.isAutomaticConfigurationEnabled else { return }
 
         // Deprecated: `customConfigureAudioSessionFunc` overrides the default configuration.
         // This path does not support error propagation since the legacy func returns Void.
@@ -101,20 +153,17 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
             let oldLegacy = AudioManager.State(localTracksCount: oldState.isRecordingEnabled ? 1 : 0, remoteTracksCount: oldState.isPlayoutEnabled ? 1 : 0)
             let newLegacy = AudioManager.State(localTracksCount: newState.isRecordingEnabled ? 1 : 0, remoteTracksCount: newState.isPlayoutEnabled ? 1 : 0)
             legacyConfigFunc(newLegacy, oldLegacy)
-            return 0
+            return
         }
 
-        do {
-            try configureAudioSession(oldState: oldState, newState: newState)
-            return 0
-        } catch {
-            return kAudioEngineErrorFailedToConfigureAudioSession
-        }
+        try configureAudioSession(oldState: oldState, newState: newState)
     }
 
     @Sendable private func configureAudioSession(oldState: State, newState: State) throws {
         let session = AVAudioSession.sharedInstance()
 
+        log("configure isRecordingEnabled: \(newState.isRecordingEnabled), isPlayoutEnabled: \(newState.isPlayoutEnabled)")
+
         if (!newState.isPlayoutEnabled && !newState.isRecordingEnabled) && (oldState.isPlayoutEnabled || oldState.isRecordingEnabled) {
             if newState.isAutomaticDeactivationEnabled {
                 do {
@@ -166,38 +215,31 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
     // MARK: - AudioEngineObserver
 
     public func engineWillEnable(_ engine: AVAudioEngine, isPlayoutEnabled: Bool, isRecordingEnabled: Bool) -> Int {
-        let result: Int = _state.mutate {
-            let oldState = $0
-            $0.isPlayoutEnabled = isPlayoutEnabled
-            $0.isRecordingEnabled = isRecordingEnabled
-            let result = configureIfNeeded(oldState: oldState, newState: $0)
-            if result != 0 {
-                // Rollback state on failure so it stays consistent with WebRTC's rollback.
-                $0 = oldState
-            }
-            return result
+        let requirement = SessionRequirement(isPlayoutEnabled: isPlayoutEnabled, isRecordingEnabled: isRecordingEnabled)
+        do {
+            try set(requirement: requirement, for: sessionRequirementId)
+        } catch {
+            return kAudioEngineErrorFailedToConfigureAudioSession
         }
-        guard result == 0 else { return result }
         return _state.next?.engineWillEnable(engine, isPlayoutEnabled: isPlayoutEnabled, isRecordingEnabled: isRecordingEnabled) ?? 0
     }
 
     public func engineDidDisable(_ engine: AVAudioEngine, isPlayoutEnabled: Bool, isRecordingEnabled: Bool) -> Int {
         let nextResult = _state.next?.engineDidDisable(engine, isPlayoutEnabled: isPlayoutEnabled, isRecordingEnabled: isRecordingEnabled) ?? 0
 
-        let result: Int = _state.mutate {
-            let oldState = $0
-            $0.isPlayoutEnabled = isPlayoutEnabled
-            $0.isRecordingEnabled = isRecordingEnabled
-            let result = configureIfNeeded(oldState: oldState, newState: $0)
-            if result != 0 {
-                // Rollback state on failure so it stays consistent with WebRTC's rollback.
-                $0 = oldState
-            }
-            return result
+        let requirement = SessionRequirement(isPlayoutEnabled: isPlayoutEnabled, isRecordingEnabled: isRecordingEnabled)
+        do {
+            try set(requirement: requirement, for: sessionRequirementId)
+        } catch {
+            return kAudioEngineErrorFailedToConfigureAudioSession
         }
-        guard result == 0 else { return result }
         return nextResult
     }
 }
 
+extension AudioSessionEngineObserver.State {
+    var isPlayoutEnabled: Bool { sessionRequirements.values.contains(where: \.isPlayoutEnabled) }
+    var isRecordingEnabled: Bool { sessionRequirements.values.contains(where: \.isRecordingEnabled) }
+}
+
 #endif

Sources/LiveKit/Audio/Manager/AudioManager.swift

@@ -22,6 +22,81 @@
 
 internal import LiveKitWebRTC
 
+/// Represents an audio session requirement from a specific component.
+///
+/// Multiple components can independently register their requirements. On platforms that use
+/// `AVAudioSession`, the session stays active as long as any component requires playout or recording.
+public struct SessionRequirement: OptionSet, Sendable {
+    public let rawValue: UInt8
+
+    public static let playout = Self(rawValue: 1 << 0)
+    public static let recording = Self(rawValue: 1 << 1)
+
+    public static let none: Self = []
+    public static let playbackOnly: Self = [.playout]
+    public static let recordingOnly: Self = [.recording]
+    public static let playbackAndRecording: Self = [.playout, .recording]
+
+    public init(rawValue: UInt8) {
+        self.rawValue = rawValue
+    }
+
+    public init(isPlayoutEnabled: Bool = false, isRecordingEnabled: Bool = false) {
+        var rawValue: UInt8 = 0
+        if isPlayoutEnabled {
+            rawValue |= Self.playout.rawValue
+        }
+        if isRecordingEnabled {
+            rawValue |= Self.recording.rawValue
+        }
+        self.init(rawValue: rawValue)
+    }
+
+    public var isPlayoutEnabled: Bool {
+        contains(.playout)
+    }
+
+    public var isRecordingEnabled: Bool {
+        contains(.recording)
+    }
+}
+
+/// Opaque handle for an acquired audio session requirement.
+///
+/// Call ``release()`` when the requirement is no longer needed.
+/// If not released explicitly, the requirement is released automatically on deinit.
+public final class SessionRequirementHandle: @unchecked Sendable {
+    private struct State {
+        var releaseImpl: (@Sendable () throws -> Void)?
+    }
+
+    private let _state: StateSync<State>
+
+    init(releaseImpl: @escaping @Sendable () throws -> Void) {
+        _state = StateSync(State(releaseImpl: releaseImpl))
+    }
+
+    deinit {
+        try? releaseIfNeeded()
+    }
+
+    /// Releases the associated audio session requirement.
+    ///
+    /// Releasing the same handle multiple times is a no-op.
+    public func release() throws {
+        try releaseIfNeeded()
+    }
+
+    private func releaseIfNeeded() throws {
+        let releaseImpl = _state.mutate { state -> (@Sendable () throws -> Void)? in
+            let releaseImpl = state.releaseImpl
+            state.releaseImpl = nil
+            return releaseImpl
+        }
+        try releaseImpl?()
+    }
+}
+
 // Audio Session Configuration related
 public class AudioManager: Loggable {
     // MARK: - Public
@@ -103,10 +178,10 @@
         // Keep this var within State so it's protected by UnfairLock
         public var localTracksCount: Int = 0
         public var remoteTracksCount: Int = 0
         public var customConfigureFunc: ConfigureAudioSessionFunc?
         public var sessionConfiguration: AudioSessionConfiguration?
 
         public var trackState: TrackState {
             switch (localTracksCount > 0, remoteTracksCount > 0) {
             case (true, false): .localOnly
             case (false, true): .remoteOnly
@@ -375,6 +450,17 @@
         RTC.audioDeviceModule.isEngineRunning
     }
 
+    /// Acquires an audio session requirement for external ownership.
+    ///
+    /// On platforms without `AVAudioSession`, this returns a no-op handle.
+    public func acquireSessionRequirement(_ requirement: SessionRequirement) throws -> SessionRequirementHandle {
+        #if os(iOS) || os(visionOS) || os(tvOS)
+        try audioSession.acquire(requirement: requirement)
+        #else
+        SessionRequirementHandle(releaseImpl: {})
+        #endif
+    }
+
     /// The mute state of internal audio engine which uses Voice Processing I/O mute API ``AVAudioInputNode.isVoiceProcessingInputMuted``.
     /// Normally, you do not need to set this manually since it will be handled automatically.
     public var isMicrophoneMuted: Bool {