Address feedback and fix documentation tests

Author: ipavlidakis

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

@@ -11,6 +11,15 @@ import StreamWebRTC
 /// audio pipeline can stay in sync with application logic.
 final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable, @unchecked Sendable {
 
+    enum Constant {
+        // WebRTC interfaces are returning integer result codes. We use this typed/named
+        // constant to define the Success of an operation.
+        static let successResult = 0
+
+        // The down limit of audio pipeline in DB that is considered silence.
+        static let silenceDB: Float = -160
+    }
+
     /// Events emitted as the underlying audio engine changes state.
     enum Event: Equatable {
         case speechActivityStarted
@@ -35,7 +44,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
     var isMicrophoneMuted: Bool { isMicrophoneMutedSubject.value }
     var isMicrophoneMutedPublisher: AnyPublisher<Bool, Never> { isMicrophoneMutedSubject.eraseToAnyPublisher() }
 
-    private let audioLevelSubject = CurrentValueSubject<Float, Never>(-160) // default to silence
+    private let audioLevelSubject = CurrentValueSubject<Float, Never>(Constant.silenceDB) // default to silence
     var audioLevel: Float { audioLevelSubject.value }
     var audioLevelPublisher: AnyPublisher<Float, Never> { audioLevelSubject.eraseToAnyPublisher() }
 
@@ -159,7 +168,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         didCreateEngine engine: AVAudioEngine
     ) -> Int {
         subject.send(.didCreateAudioEngine(engine))
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -171,7 +180,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         subject.send(.willEnableAudioEngine(engine))
         isPlayingSubject.send(isPlayoutEnabled)
         isRecordingSubject.send(isRecordingEnabled)
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -183,7 +192,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         subject.send(.willStartAudioEngine(engine))
         isPlayingSubject.send(isPlayoutEnabled)
         isRecordingSubject.send(isRecordingEnabled)
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -196,7 +205,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         audioLevelsAdapter.uninstall(on: 0)
         isPlayingSubject.send(isPlayoutEnabled)
         isRecordingSubject.send(isRecordingEnabled)
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -209,7 +218,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         audioLevelsAdapter.uninstall(on: 0)
         isPlayingSubject.send(isPlayoutEnabled)
         isRecordingSubject.send(isRecordingEnabled)
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -218,7 +227,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
     ) -> Int {
         subject.send(.willReleaseAudioEngine(engine))
         audioLevelsAdapter.uninstall(on: 0)
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -235,7 +244,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
             bus: 0,
             bufferSize: 1024
         )
-        return 0
+        return Constant.successResult
     }
 
     func audioDeviceModule(
@@ -246,13 +255,13 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
         format: AVAudioFormat,
         context: [AnyHashable: Any]
     ) -> Int {
-        0
+        Constant.successResult
     }
 
     func audioDeviceModuleDidUpdateDevices(
         _ audioDeviceModule: RTCAudioDeviceModule
     ) {
-        // TODO:
+        /* No-op */
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -281,7 +290,7 @@ final class AudioDeviceModule: NSObject, RTCAudioDeviceModuleDelegate, Encodable
     ) throws {
         let result = operation()
 
-        guard result != 0 else {
+        guard result != Constant.successResult else {
             return
         }
 

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

@@ -72,19 +72,47 @@ final class AudioEngineLevelNodeAdapter: AudioEngineNodeAdapting {
     /// Processes the PCM buffer produced by the tap and computes a clamped RMS
     /// value which is forwarded to the publisher.
     private func processInputBuffer(_ buffer: AVAudioPCMBuffer) {
+        // Safely unwrap the `subject` (used to publish updates) and the
+        // `floatChannelData` (pointer to the interleaved or non-interleaved
+        // channel samples in memory). If either is missing, exit early since
+        // processing cannot continue.
         guard
             let subject,
             let channelData = buffer.floatChannelData
         else { return }
 
+        // Obtain the total number of frames in the buffer as a vDSP-compatible
+        // length type (`vDSP_Length`). This represents how many samples exist
+        // per channel in the current audio buffer.
         let frameCount = vDSP_Length(buffer.frameLength)
 
+        // Declare a variable to store the computed RMS (root-mean-square)
+        // amplitude value for the buffer. It will represent the signal's
+        // average power in linear scale (not decibels yet).
         var rms: Float = 0
+
+        // Use Apple's Accelerate framework to efficiently compute the RMS
+        // (root mean square) of the float samples in the first channel.
+        // - Parameters:
+        //   - channelData[0]: Pointer to the first channel’s samples.
+        //   - 1: Stride between consecutive elements (every sample).
+        //   - &rms: Output variable to store the computed RMS.
+        //   - frameCount: Number of samples to process.
         vDSP_rmsqv(channelData[0], 1, &rms, frameCount)
 
+        // Convert the linear RMS value to decibels using the formula
+        // 20 * log10(rms). To avoid a log of zero (which is undefined),
+        // use `max(rms, Float.ulpOfOne)` to ensure a minimal positive value.
         let rmsDB = 20 * log10(max(rms, Float.ulpOfOne))
+
+        // Clamp the computed decibel value to a reasonable audio level range
+        // between -160 dB (silence) and 0 dB (maximum). This prevents extreme
+        // or invalid values that may occur due to noise or computation errors.
         let clampedRMS = max(-160.0, min(0.0, Float(rmsDB)))
 
+        // Publish the clamped decibel value to the CurrentValueSubject so that
+        // subscribers (e.g., UI level meters or analytics systems) receive the
+        // updated level reading.
         subject.send(clampedRMS)
     }
 }