Add comments

Author: ipavlidakis

Sources/StreamVideo/CallKit/CallKitService.swift

@@ -104,6 +104,8 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
     private var callEndedNotificationCancellable: AnyCancellable?
     private var ringingTimerCancellable: AnyCancellable?
 
+    /// Debounces CallKit mute toggles that arrive in bursts when the app moves
+    /// between foreground and background states.
     private let muteActionSubject = PassthroughSubject<MuteRequest, Never>()
     private var muteActionCancellable: AnyCancellable?
     private let muteProcessingQueue = OperationQueue(maxConcurrentOperationCount: 1)
@@ -120,12 +122,9 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
             .compactMap { $0.object as? Call }
             .sink { [weak self] in self?.callEnded($0.cId, ringingTimedOut: false) }
 
-        /// - Important:
-        /// It used to debounce System's attempts to mute/unmute the call. It seems that the system
-        /// performs rapid mute/unmute attempts when the call is being joined or moving to foreground.
-        /// The observation below is in place to guard and normalise those attempts to avoid
-        /// - rapid speaker and mic toggles
-        /// - unnecessary attempts to mute/unmute the mic
+        /// - Important: CallKit can rapidly toggle the mute state while the app
+        /// moves between foreground and background. This observation smooths
+        /// those bursts so we do not end up thrashing the audio pipeline.
         muteActionCancellable = muteActionSubject
             .removeDuplicates()
             .filter { [weak self] _ in self?.applicationStateAdapter.state != .foreground }
@@ -787,6 +786,8 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
         }
     }
 
+    /// Normalises mute requests triggered by call settings so CallKit stays in
+    /// sync with the in-app toggle while avoiding redundant transactions.
     private func performCallSettingMuteRequest(
         _ muted: Bool,
         callUUID: UUID
@@ -808,6 +809,8 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
         }
     }
 
+    /// Applies the debounced mute request once CallKit and permissions agree
+    /// that the action is allowed.
     private func performMuteRequest(_ request: MuteRequest) {
         muteProcessingQueue.addTaskOperation { [weak self] in
             guard

Sources/StreamVideo/Models/CallSettings.swift

@@ -7,6 +7,8 @@ import Foundation
 
 /// Represents the settings for a call.
 public final class CallSettings: ObservableObject, Sendable, Equatable, CustomStringConvertible {
+    /// Canonical baseline settings used when we need a placeholder before the
+    /// backend sends the definitive values.
     public static let `default` = CallSettings()
 
     /// Whether the audio is on for the current user.

Sources/StreamVideo/Utils/AudioSession/AudioDeviceModule/AudioDeviceModule.swift

@@ -131,15 +131,12 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
     /// - Parameter source: The audio device module implementation to observe.
     init(
         _ source: any RTCAudioDeviceModuleControlling,
-        isPlaying: Bool = false,
-        isRecording: Bool = false,
-        isMicrophoneMuted: Bool = false,
         audioLevelsNodeAdapter: AudioEngineNodeAdapting = AudioEngineLevelNodeAdapter()
     ) {
         self.source = source
-        self.isPlayingSubject = .init(isPlaying)
-        self.isRecordingSubject = .init(isRecording)
-        self.isMicrophoneMutedSubject = .init(isMicrophoneMuted)
+        self.isPlayingSubject = .init(source.isPlaying)
+        self.isRecordingSubject = .init(source.isRecording)
+        self.isMicrophoneMutedSubject = .init(source.isMicrophoneMuted)
         self.isStereoPlayoutEnabledSubject = .init(source.isStereoPlayoutEnabled)
         self.isVoiceProcessingBypassedSubject = .init(source.isVoiceProcessingBypassed)
         self.isVoiceProcessingEnabledSubject = .init(source.isVoiceProcessingEnabled)
@@ -162,28 +159,6 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
 
         audioLevelsAdapter.subject = audioLevelSubject
         source.observer = self
-
-        source
-            .microphoneMutedPublisher()
-            .receive(on: dispatchQueue)
-            .sink { [weak self] in self?.isMicrophoneMutedSubject.send($0) }
-            .store(in: disposableBag)
-
-        source
-            .isVoiceProcessingBypassedPublisher()
-            .receive(on: dispatchQueue)
-            .sink { [weak self] in self?.isVoiceProcessingBypassedSubject.send($0) }
-            .store(in: disposableBag)
-        source
-            .isVoiceProcessingEnabledPublisher()
-            .receive(on: dispatchQueue)
-            .sink { [weak self] in self?.isVoiceProcessingEnabledSubject.send($0) }
-            .store(in: disposableBag)
-        source
-            .isVoiceProcessingAGCEnabledPublisher()
-            .receive(on: dispatchQueue)
-            .sink { [weak self] in self?.isVoiceProcessingAGCEnabledSubject.send($0) }
-            .store(in: disposableBag)
     }
 
     // MARK: - Recording
@@ -207,10 +182,13 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         (source as? RTCAudioDeviceModule)?.setRecordingAlwaysPreparedMode(true)
         source.prefersStereoPlayout = isPreferred
 
+        /// We store the mic state before we perform `InitAndStartRecording` so we can restore
+        /// the state at the end.
         let isMuted = isMicrophoneMuted
 
         _ = source.stopRecording()
         _ = source.initAndStartRecording()
+
         if isMuted {
             _ = source.setMicrophoneMuted(isMuted)
         }
@@ -519,40 +497,3 @@ extension AVAudioEngine {
         return "\(asbd.mChannelsPerFrame) ch @ \(asbd.mSampleRate) Hz"
     }
 }
-
-enum RetriableTask {
-    static func run(
-        iterations: Int,
-        operation: () throws -> Void
-    ) throws {
-        try execute(
-            currentIteration: 0,
-            iterations: iterations,
-            operation: operation
-        )
-    }
-
-    private static func execute(
-        currentIteration: Int,
-        iterations: Int,
-        operation: () throws -> Void
-    ) throws {
-        do {
-            return try operation()
-        } catch {
-            if currentIteration < iterations - 1 {
-                do {
-                    return try execute(
-                        currentIteration: currentIteration + 1,
-                        iterations: iterations,
-                        operation: operation
-                    )
-                } catch {
-                    throw error
-                }
-            } else {
-                throw error
-            }
-        }
-    }
-}

Sources/StreamVideo/Utils/AudioSession/AudioDeviceModule/RTCAudioDeviceModuleControlling.swift

@@ -6,9 +6,11 @@ import Combine
 import StreamWebRTC
 
 /// Abstraction over `RTCAudioDeviceModule` so tests can provide fakes while
-/// production code keeps using the WebRTC implementation.
+/// production code continues to rely on the WebRTC-backed implementation.
 protocol RTCAudioDeviceModuleControlling: AnyObject {
     var observer: RTCAudioDeviceModuleDelegate? { get set }
+    var isPlaying: Bool { get }
+    var isRecording: Bool { get }
     var isMicrophoneMuted: Bool { get }
     var isStereoPlayoutEnabled: Bool { get }
     var isVoiceProcessingBypassed: Bool { get }
@@ -24,15 +26,11 @@ protocol RTCAudioDeviceModuleControlling: AnyObject {
     func setMicrophoneMuted(_ isMuted: Bool) -> Int
     func stopRecording() -> Int
     func refreshStereoPlayoutState()
-
-    /// Publisher that emits whenever the microphone mute state changes.
-    func microphoneMutedPublisher() -> AnyPublisher<Bool, Never>
-    func isVoiceProcessingBypassedPublisher() -> AnyPublisher<Bool, Never>
-    func isVoiceProcessingEnabledPublisher() -> AnyPublisher<Bool, Never>
-    func isVoiceProcessingAGCEnabledPublisher() -> AnyPublisher<Bool, Never>
 }
 
 extension RTCAudioDeviceModule: RTCAudioDeviceModuleControlling {
+    /// Convenience wrapper that mirrors the old `initPlayout` and
+    /// `startPlayout` sequence so the caller can request playout in one call.
     func initAndStartPlayout() -> Int {
         let result = initPlayout()
         if result == 0 {
@@ -41,24 +39,4 @@ extension RTCAudioDeviceModule: RTCAudioDeviceModuleControlling {
             return result
         }
     }
-    
-    func microphoneMutedPublisher() -> AnyPublisher<Bool, Never> {
-        publisher(for: \.isMicrophoneMuted)
-            .eraseToAnyPublisher()
-    }
-
-    func isVoiceProcessingBypassedPublisher() -> AnyPublisher<Bool, Never> {
-        publisher(for: \.isVoiceProcessingBypassed)
-            .eraseToAnyPublisher()
-    }
-
-    func isVoiceProcessingEnabledPublisher() -> AnyPublisher<Bool, Never> {
-        publisher(for: \.isVoiceProcessingEnabled)
-            .eraseToAnyPublisher()
-    }
-
-    func isVoiceProcessingAGCEnabledPublisher() -> AnyPublisher<Bool, Never> {
-        publisher(for: \.isVoiceProcessingAGCEnabled)
-            .eraseToAnyPublisher()
-    }
 }

Sources/StreamVideo/Utils/AudioSession/AudioRecorder/Namespace/Middleware/StreamCallAudioRecorder+AVAudioRecorderMiddleware.swift

@@ -22,6 +22,8 @@ extension StreamCallAudioRecorder.Namespace {
     /// ensure thread safety when accessing the recorder instance.
     final class AVAudioRecorderMiddleware: Middleware<StreamCallAudioRecorder.Namespace>, @unchecked Sendable {
 
+        /// Tracks which metering backend is active so we can flip between
+        /// `AVAudioRecorder` and the audio device module seamlessly.
         enum Mode: Equatable {
             case invalid
             case audioRecorder(AVAudioRecorder)
@@ -39,6 +41,8 @@ extension StreamCallAudioRecorder.Namespace {
 
         /// Subscription for publishing meter updates at refresh rate.
         private var updateMetersCancellable: AnyCancellable?
+        /// Listens for ADM availability and pivots the metering source on the
+        /// fly when stereo playout is enabled.
         private var audioDeviceModuleCancellable: AnyCancellable?
 
         init(audioRecorder: AVAudioRecorder? = nil) {

Sources/StreamVideo/Utils/AudioSession/AudioRecorder/Namespace/Middleware/StreamCallAudioRecorder+CategoryMiddleware.swift

@@ -33,6 +33,8 @@ extension StreamCallAudioRecorder.Namespace {
 
             // Monitor for category changes that are incompatible with recording
             cancellable = audioStore
+                // Observe the derived configuration so system-driven category
+                // changes also stop the local recorder.
                 .publisher(\.audioSessionConfiguration.category)
                 .filter { $0 != .playAndRecord && $0 != .record }
                 .sink { [weak self] _ in

Sources/StreamVideo/Utils/AudioSession/CallAudioSession.swift

@@ -12,6 +12,8 @@ final class CallAudioSession: @unchecked Sendable {
 
     @Injected(\.audioStore) private var audioStore
 
+    /// Bundles the reactive inputs we need to evaluate whenever call
+    /// capabilities or settings change, keeping log context attached.
     private struct Input {
         var callSettings: CallSettings
         var ownCapabilities: Set<OwnCapability>
@@ -50,6 +52,8 @@ final class CallAudioSession: @unchecked Sendable {
     private let disposableBag = DisposableBag()
     private let processingQueue = OperationQueue(maxConcurrentOperationCount: 1)
 
+    /// Serialises policy evaluations so the AVAudioSession only receives one
+    /// configuration at a time even when upstream publishers fire in bursts.
     private let processingPipeline = PassthroughSubject<Input, Never>()
 
     private var lastAppliedConfiguration: AudioSessionConfiguration?
@@ -91,6 +95,8 @@ final class CallAudioSession: @unchecked Sendable {
         self.delegate = delegate
         self.statsAdapter = statsAdapter
 
+        // Expose the policy's stereo preference so the audio device module can
+        // reconfigure itself before WebRTC starts playout.
         audioStore.dispatch(.stereo(.setPlayoutPreferred(policy is LivestreamAudioSessionPolicy)))
         audioStore.dispatch(.webRTCAudioSession(.setAudioEnabled(true)))
 
@@ -162,6 +168,8 @@ final class CallAudioSession: @unchecked Sendable {
         )
     }
 
+    /// Wires call setting and capability updates into the processing queue so
+    /// downstream work always executes serially.
     private func configureCallSettingsAndCapabilitiesObservation(
         callSettingsPublisher: AnyPublisher<CallSettings, Never>,
         ownCapabilitiesPublisher: AnyPublisher<Set<OwnCapability>, Never>
@@ -184,6 +192,8 @@ final class CallAudioSession: @unchecked Sendable {
             .store(in: disposableBag)
     }
 
+    /// Reapplies the last known category options when the system clears them,
+    /// which happens after some CallKit activations.
     private func configureCallOptionsObservation() {
         audioStore
             .publisher(\.audioSessionConfiguration.options)
@@ -195,6 +205,8 @@ final class CallAudioSession: @unchecked Sendable {
             .store(in: disposableBag)
     }
 
+    /// Keeps the delegate informed of hardware flips while also re-evaluating
+    /// the policy when we detect a reconfiguration-worthy route change.
     private func configureCurrentRouteObservation() {
         audioStore
             .publisher(\.currentRoute)
@@ -246,6 +258,8 @@ final class CallAudioSession: @unchecked Sendable {
         )
     }
 
+    /// Breaks the configuration into store actions so reducers update the
+    /// audio session and our own bookkeeping in a single dispatch.
     private func applyConfiguration(
         _ configuration: AudioSessionConfiguration,
         callSettings: CallSettings,

Sources/StreamVideo/Utils/AudioSession/Extensions/AVAudioSession.CategoryOptions+Convenience.swift

@@ -23,6 +23,8 @@ extension AVAudioSession.CategoryOptions {
     static let playback: AVAudioSession.CategoryOptions = []
 
     #if !canImport(AVFoundation, _version: 2360.61.4.11)
+    /// Older SDKs only expose ``allowBluetooth`` so we map the HFP alias to it
+    /// to avoid peppering the codebase with availability checks.
     public static let allowBluetoothHFP = Self.allowBluetooth
     #endif
 }

Sources/StreamVideo/Utils/AudioSession/Extensions/AVAudioSession.RouteChangeReason+Convenience.swift

@@ -7,9 +7,8 @@ import Foundation
 
 extension AVAudioSession.RouteChangeReason {
 
-    /// Taken from https://chromium.googlesource.com/external/webrtc/+/34911ad55c4c4c549fe60e1b4cc127420b15666b/webrtc/modules/audio_device/ios/audio_device_ios.mm#557
-    /// in the routeChange logic. Useful to ignore route changes that don't really matter for our
-    /// webrtc sessions.
+    /// Mirrors the filtering logic used by WebRTC so we ignore redundant
+    /// callbacks such as `categoryChange` that would otherwise spam the store.
     var isValidRouteChange: Bool {
         switch self {
         case .categoryChange, .routeConfigurationChange:
@@ -19,7 +18,8 @@ extension AVAudioSession.RouteChangeReason {
         }
     }
 
-    /// https://github.com/TheWidlarzGroup/react-native-video/blob/fbb260e9164194a55d2b26404aea000e924e2f04/ios/Video/AudioSessionManager.swift#L357
+    /// Flags reasons that represent real hardware transitions so we can rebuild
+    /// the audio graph when necessary.
     var requiresReconfiguration: Bool {
         switch self {
         case .categoryChange, .override, .wakeFromSleep, .newDeviceAvailable, .oldDeviceUnavailable:

Sources/StreamVideo/Utils/AudioSession/Extensions/AVAudioSessionMode+Convenience.swift

@@ -12,6 +12,8 @@ extension AVAudioSession.Mode {
         rawValue
     }
 
+    /// Indicates whether the mode keeps stereo playout active or if WebRTC
+    /// should fall back to mono because of voice-processing constraints.
     var supportsStereoPlayout: Bool {
         switch self {
         case .videoChat, .voiceChat, .gameChat: