feat: Implement low-load battery-saver WebRTC profile for device harness

- Added support for a low-load battery-saver WebRTC profile when the environment variable
  `LIVEKIT_NATIVE_DEVICE_HARNESS_BATTERY_SAVER_WEBRTC` is set.
- Configured camera capture options to 320x180 at 10fps, with a single H.264 layer and a
  publisher bitrate of 250 kbps.
- Updated diagnostics and reconnect logic to accommodate the new profile.
- Enhanced the `DeviceHarnessViewModel` to manage soak automation and diagnostics
  effectively.
- Modified `LocalVideoPublishPlan` and related classes to handle the new H.264 bitrate
  configuration.
- Updated tests to validate the new power policy and its effects on video publishing.
- Revised documentation to reflect changes in the harness behavior and configuration.

Author: MarlonJD

Examples/DeviceHarness/DeviceHarnessViewModel.swift

@@ -29,6 +29,7 @@ final class DeviceHarnessViewModel: ObservableObject {
     private var didOpenPublisherHarnessDataChannel = false
     private var lastDataPublishFailure = ""
     private var lastAudioRouteDiagnosticAt = Date.distantPast
+    private var isSoakAutomationRunning = false
     private static let voiceIsolationRecommendationKey =
         "LiveKitNativeDeviceHarness.didSuggestAppleVoiceIsolation"
 
@@ -250,8 +251,11 @@ final class DeviceHarnessViewModel: ObservableObject {
     }
 
     @discardableResult
-    func refreshDiagnostics(reason: String) async -> RoomMediaDiagnostics? {
-        guard let diagnostics = await currentDiagnostics() else {
+    func refreshDiagnostics(
+        reason: String,
+        includeDataChannels: Bool = true
+    ) async -> RoomMediaDiagnostics? {
+        guard let diagnostics = await currentDiagnostics(includeDataChannels: includeDataChannels) else {
             diagnosticsText = "No active room for diagnostics."
             return nil
         }
@@ -347,14 +351,16 @@ final class DeviceHarnessViewModel: ObservableObject {
         }
     }
 
-    private func currentDiagnostics() async -> RoomMediaDiagnostics? {
+    private func currentDiagnostics(includeDataChannels: Bool = true) async -> RoomMediaDiagnostics? {
         guard let room else {
             return nil
         }
 
-        var diagnostics = await room.mediaDiagnostics()
+        var diagnostics = await room.mediaDiagnostics(includeDataChannels: includeDataChannels)
         if let subscriberRoom {
-            let subscriberDiagnostics = await subscriberRoom.mediaDiagnostics()
+            let subscriberDiagnostics = await subscriberRoom.mediaDiagnostics(
+                includeDataChannels: includeDataChannels
+            )
             diagnostics = Self.combinedDiagnostics(
                 publisherDiagnostics: diagnostics,
                 subscriberDiagnostics: subscriberDiagnostics
@@ -459,6 +465,11 @@ final class DeviceHarnessViewModel: ObservableObject {
         }
 
         var policy = WebRTCPowerPolicy.batterySaver
+        policy.cameraCaptureOptions = CameraCaptureOptions(width: 320, height: 180, framesPerSecond: 10)
+        policy.h264Bitrate = 250_000
+        policy.adaptiveStream = false
+        policy.subscriberAllowPause = false
+        policy.applySubscriberAdaptiveTrackSettings = false
         policy.decodeSubscriberVideo = true
         return .custom(policy)
     }
@@ -523,10 +534,17 @@ final class DeviceHarnessViewModel: ObservableObject {
         status = "Observed \(name)."
         if name == "audio-route-change" {
             let now = Date()
-            guard now.timeIntervalSince(lastAudioRouteDiagnosticAt) >= 5 else {
+            let minimumInterval: TimeInterval = isSoakAutomationRunning ? 30 : 5
+            guard now.timeIntervalSince(lastAudioRouteDiagnosticAt) >= minimumInterval else {
                 return
             }
             lastAudioRouteDiagnosticAt = now
+            if isSoakAutomationRunning {
+                if let detail {
+                    emitHarnessLog(detail)
+                }
+                return
+            }
         }
         if let detail {
             emitHarnessLog(detail)
@@ -742,10 +760,13 @@ final class DeviceHarnessViewModel: ObservableObject {
         var didObserveMediaContinuity = false
         var lastMediaContinuityCounters: (renderedFrames: Int, audioBuffers: Int)?
 
+        isSoakAutomationRunning = true
+        defer { isSoakAutomationRunning = false }
+
         emitHarnessLog(
             "soak_started: duration_minutes=\(clampedDurationMinutes) diagnostic_interval_seconds=\(intervalSeconds) reconnect_after_seconds=\(reconnectAtSeconds)"
         )
-        await refreshDiagnostics(reason: "soak-start")
+        await refreshDiagnostics(reason: "soak-start", includeDataChannels: false)
 
         while Int(Date().timeIntervalSince(start)) < totalSeconds {
             let elapsedSeconds = Int(Date().timeIntervalSince(start))
@@ -754,7 +775,10 @@ final class DeviceHarnessViewModel: ObservableObject {
                 reconnectReason = "scheduled"
             }
 
-            let diagnostics = await refreshDiagnostics(reason: "media-continuity")
+            let diagnostics = await refreshDiagnostics(
+                reason: "media-continuity",
+                includeDataChannels: false
+            )
             let canAttemptHealthReconnect = lastReconnectElapsedSeconds.map {
                 elapsedSeconds - $0 >= reconnectCooldownSeconds
             } ?? true
@@ -787,16 +811,18 @@ final class DeviceHarnessViewModel: ObservableObject {
                 reconnectAttemptCount += 1
                 let attempt = reconnectAttemptCount
                 emitHarnessLog("soak_reconnect: started reason=\(reconnectReason) attempt=\(attempt) elapsed_seconds=\(elapsedSeconds)")
-                await disconnect()
-                await connectAndPublish()
+                let recovered = await reconnectForSoak(
+                    reason: reconnectReason,
+                    attempt: attempt
+                )
                 lastReconnectElapsedSeconds = Int(Date().timeIntervalSince(start))
-                if isConnected {
+                if recovered {
                     reconnectCount += 1
                 }
                 didObserveMediaContinuity = false
                 lastMediaContinuityCounters = nil
-                emitHarnessLog("soak_reconnect: \(isConnected ? "completed" : "failed") reason=\(reconnectReason) attempt=\(attempt) elapsed_seconds=\(Int(Date().timeIntervalSince(start)))")
-                await refreshDiagnostics(reason: "reconnect-recovery")
+                emitHarnessLog("soak_reconnect: \(recovered ? "completed" : "failed") reason=\(reconnectReason) attempt=\(attempt) elapsed_seconds=\(Int(Date().timeIntervalSince(start)))")
+                await refreshDiagnostics(reason: "reconnect-recovery", includeDataChannels: false)
             }
 
             let remainingSeconds = max(1, totalSeconds - Int(Date().timeIntervalSince(start)))
@@ -806,7 +832,28 @@ final class DeviceHarnessViewModel: ObservableObject {
 
         emitHarnessLog("duration_minutes: \(clampedDurationMinutes)")
         emitHarnessLog("soak_completed: duration_minutes=\(clampedDurationMinutes) reconnect_observed=\(reconnectCount > 0) reconnect_count=\(reconnectCount) reconnect_attempts=\(reconnectAttemptCount)")
-        await refreshDiagnostics(reason: "soak-complete")
+        var completionReady = soakCompletionDiagnosticsReady(
+            await refreshDiagnostics(reason: "soak-complete", includeDataChannels: false)
+        )
+        if !completionReady {
+            for attempt in 1...3 {
+                emitHarnessLog("soak_complete_recovery: reconnecting attempt=\(attempt)")
+                _ = await reconnectForSoak(
+                    reason: "soak-complete",
+                    attempt: attempt
+                )
+                try? await Task.sleep(nanoseconds: 5_000_000_000)
+                completionReady = soakCompletionDiagnosticsReady(
+                    await refreshDiagnostics(reason: "soak-complete", includeDataChannels: false)
+                )
+                if completionReady {
+                    break
+                }
+            }
+            if !completionReady {
+                emitHarnessLog("soak_complete_recovery: failed")
+            }
+        }
     }
 
     private func shouldRecoverDuringSoak(diagnostics: RoomMediaDiagnostics) -> Bool {
@@ -824,6 +871,101 @@ final class DeviceHarnessViewModel: ObservableObject {
         return false
     }
 
+    private func reconnectForSoak(reason: String, attempt: Int) async -> Bool {
+        for retry in 1...3 {
+            disconnectCurrentRoomsInBackground()
+            try? await Task.sleep(nanoseconds: UInt64(retry) * 2_000_000_000)
+            let connected = await connectAndPublishForSoak(timeoutSeconds: 45)
+            if connected {
+                return true
+            }
+            if retry < 3 {
+                emitHarnessLog("soak_reconnect_retry: reason=\(reason) attempt=\(attempt) retry=\(retry)")
+            }
+        }
+
+        return false
+    }
+
+    private func connectAndPublishForSoak(timeoutSeconds: UInt64) async -> Bool {
+        await connectAndPublish(disconnectFirst: false)
+        guard isConnected else {
+            return false
+        }
+
+        let deadline = Date().addingTimeInterval(TimeInterval(timeoutSeconds))
+        while Date() < deadline {
+            if let diagnostics = await currentDiagnostics(includeDataChannels: false),
+               soakReconnectDiagnosticsReady(diagnostics)
+            {
+                return true
+            }
+            try? await Task.sleep(nanoseconds: 1_000_000_000)
+        }
+
+        emitHarnessLog("soak_reconnect_timeout: seconds=\(timeoutSeconds)")
+        disconnectCurrentRoomsInBackground()
+        return false
+    }
+
+    private func soakReconnectDiagnosticsReady(_ diagnostics: RoomMediaDiagnostics) -> Bool {
+        if !soakMediaPathConnected(diagnostics) {
+            return false
+        }
+        if diagnostics.counters.publisherAudioSenderCount < 1 ||
+            diagnostics.counters.publisherVideoSenderCount < 1
+        {
+            return false
+        }
+        if diagnostics.counters.subscriberRenderedVideoFrameCount < 1 ||
+            diagnostics.counters.subscriberAudioPlayoutScheduledBufferCount < 1
+        {
+            return false
+        }
+
+        return true
+    }
+
+    private func soakMediaPathConnected(_ diagnostics: RoomMediaDiagnostics) -> Bool {
+        if diagnostics.connectionState != .connected {
+            return false
+        }
+        if diagnostics.publisher.dtlsSRTPState != .connected {
+            return false
+        }
+        if !subscriberToken.isEmpty,
+           diagnostics.subscriber.dtlsSRTPState != .connected
+        {
+            return false
+        }
+
+        return true
+    }
+
+    private func soakCompletionDiagnosticsReady(_ diagnostics: RoomMediaDiagnostics?) -> Bool {
+        guard let diagnostics else {
+            return false
+        }
+
+        let counters = diagnostics.counters
+        let renderedFrames = max(
+            counters.subscriberRenderedVideoFrameCount,
+            videoView.renderedFrameCount
+        )
+
+        if !soakMediaPathConnected(diagnostics) {
+            return false
+        }
+        if counters.publisherAudioSenderCount < 1 || counters.publisherVideoSenderCount < 1 {
+            return false
+        }
+        if renderedFrames < 1 || counters.subscriberAudioPlayoutScheduledBufferCount < 1 {
+            return false
+        }
+
+        return true
+    }
+
     private func emitHarnessLog(_ text: String) {
         print(text)
     }

Examples/DeviceHarness/README.md

@@ -36,6 +36,10 @@ The harness intentionally keeps the app small:
 - Runs long soak loops when `LIVEKIT_NATIVE_DEVICE_HARNESS_SOAK_MINUTES` is set,
   including periodic media-continuity snapshots and a scripted reconnect
   recovery marker.
+- Uses a permanent low-load battery-saver soak profile when
+  `LIVEKIT_NATIVE_DEVICE_HARNESS_BATTERY_SAVER_WEBRTC=1` is set: 320x180@10fps,
+  a single H.264 layer, 250 kbps publisher bitrate, subscriber decode/playout
+  enabled, and adaptive subscriber pause disabled.
 
 The production workflow can use `scripts/run_device_validation_on_device.sh` to
 build the app, install it on physical hardware, launch it with console capture,

README.md

@@ -389,7 +389,8 @@ WebRTC power presets are opt-in through `RoomOptions.webRTCPowerMode`; leaving
 the mode nil preserves existing SDK behavior. `.batterySaver` starts camera
 helpers at 640x360@15, disables camera simulcast, uses 24 kbps Opus with DTX,
 requests low subscriber video, and can be paired with automatic Low Power Mode
-and thermal adaptation:
+and thermal adaptation. Custom policies can also cap the H.264 publisher
+bitrate for low-resolution runs:
 
 ```swift
 let room = Room(
@@ -409,6 +410,7 @@ subscriber power tradeoffs:
 let customPolicy = WebRTCPowerPolicy(
     cameraCaptureOptions: CameraCaptureOptions(width: 960, height: 540, framesPerSecond: 24),
     cameraSimulcast: false,
+    h264Bitrate: 500_000,
     opusBitrate: 28_000,
     initialSubscribedVideoQuality: .medium,
     decodeSubscriberVideo: false

Sources/LiveKitNative/Core/LocalPublishPlan.swift

@@ -22,10 +22,12 @@ struct LocalVideoPublishPlan: Equatable, Sendable {
     var ssrc: UInt32
     var payloadType: UInt8
     var nativeCameraSource: NativeCameraVideoSource?
+    var h264Bitrate: UInt32?
 
     init(
         track: LocalVideoTrack,
         options: TrackPublishOptions = .init(),
+        powerPolicy: WebRTCPowerPolicy? = nil,
         ssrc: UInt32 = GeneratedSSRC.make(),
         payloadType: UInt8 = 102
     ) {
@@ -41,6 +43,7 @@ struct LocalVideoPublishPlan: Equatable, Sendable {
         self.ssrc = ssrc
         self.payloadType = payloadType
         self.nativeCameraSource = track.nativeCameraSource
+        self.h264Bitrate = powerPolicy?.h264Bitrate
     }
 
     static func == (lhs: LocalVideoPublishPlan, rhs: LocalVideoPublishPlan) -> Bool {
@@ -53,7 +56,8 @@ struct LocalVideoPublishPlan: Equatable, Sendable {
             lhs.simulcast == rhs.simulcast &&
             lhs.codec == rhs.codec &&
             lhs.ssrc == rhs.ssrc &&
-            lhs.payloadType == rhs.payloadType
+            lhs.payloadType == rhs.payloadType &&
+            lhs.h264Bitrate == rhs.h264Bitrate
     }
 
     var videoEncodingLayers: [LocalVideoEncodingLayer] {
@@ -115,7 +119,11 @@ struct LocalVideoPublishPlan: Equatable, Sendable {
     }
 
     private var recommendedBitrate: Int {
-        switch max(width, height) {
+        if let h264Bitrate {
+            return max(1, Int(h264Bitrate))
+        }
+
+        return switch max(width, height) {
         case 0..<721:
             1_500_000
         case 721..<1_081:

Sources/LiveKitNative/Core/Participant.swift

@@ -223,7 +223,11 @@ public final class LocalParticipant: Participant, @unchecked Sendable {
     }
 
     public func publish(videoTrack: LocalVideoTrack, options: TrackPublishOptions = .init()) async throws -> LocalTrackPublication {
-        let plan = LocalVideoPublishPlan(track: videoTrack, options: options)
+        let plan = LocalVideoPublishPlan(
+            track: videoTrack,
+            options: options,
+            powerPolicy: currentWebRTCPowerPolicy()
+        )
         let publishedTrack = if let commandHandler = currentCommandHandler() {
             try await commandHandler.publishVideo(plan)
         } else {

Sources/LiveKitNative/Core/Room.swift

@@ -586,15 +586,26 @@ public final class Room: @unchecked Sendable {
         snapshots.connectionState
     }
 
-    public func mediaDiagnostics() async -> RoomMediaDiagnostics {
+    public func mediaDiagnostics(includeDataChannels: Bool = true) async -> RoomMediaDiagnostics {
         let publisherStartup = publisherMediaStartupLock.withLock {
             (result: publisherMediaStartupResult, error: publisherMediaStartupError)
         }
         let subscriberStartup = subscriberMediaStartupLock.withLock {
             (result: subscriberMediaStartupResult, error: subscriberMediaStartupError)
         }
-        let publisherDataChannelState = await publisherDataChannelObserverState()
-        let subscriberDataChannelState = await subscriberDataChannelObserverState()
+        let publisherDataChannelState: RoomDataChannelObserverState
+        let subscriberDataChannelState: RoomDataChannelObserverState
+        if includeDataChannels {
+            publisherDataChannelState = await publisherDataChannelObserverState()
+            subscriberDataChannelState = await subscriberDataChannelObserverState()
+        } else {
+            publisherDataChannelState = Self.skippedDataChannelObserverState(
+                installed: publisherDataChannel != nil
+            )
+            subscriberDataChannelState = Self.skippedDataChannelObserverState(
+                installed: subscriberDataChannel != nil
+            )
+        }
         let publisherRTPState = publisherRTPSenderLock.withLock {
             (
                 audioSenderCount: publisherAudioRTPSendersBySID.count,
@@ -666,6 +677,15 @@ public final class Room: @unchecked Sendable {
         )
     }
 
+    private static func skippedDataChannelObserverState(installed: Bool) -> RoomDataChannelObserverState {
+        RoomDataChannelObserverState(
+            installed: installed,
+            reliableOpen: false,
+            lossyOpen: false,
+            pendingPlanCount: 0
+        )
+    }
+
     public var mediaSectionsRequirement: MediaSectionsRequirementInfo? {
         snapshots.mediaSectionsRequirement
     }