feat: throttle the broadcast under thermal and Low Power pressure (#15)

Add a thermal + Low Power governor that sheds encoder, network, and camera load before iOS hard-throttles a long stream, reusing the existing adaptive path. ThermalPowerGovernor maps ProcessInfo state to a ceiling (bitrate scale + fps cap + facecam) that folds into the ABR's effectiveMaximum and frameInterval for both RTMP and SRT/WHIP; ScreenCaptureController observes thermal/power notifications, slows capture pacing, drops the facecam under heat, and exposes thermalNotice. Holds across Wi-Fi<->5G changes and SRT/WHIP connect. Adversarially reviewed; compile-verified on the simulator and device SDKs (on-device runtime validation still required).

Author: joeblau

Stream/ScreenCaptureController.swift

@@ -18,6 +18,9 @@ private let captureLog = Logger(subsystem: "com.joeblau.Stream", category: "scre
 final class ScreenCaptureController: NSObject {
     private(set) var isLive = false
     private(set) var errorMessage: String?
+    /// A user-facing note when the device's thermal/power state is forcing a
+    /// quality reduction, or nil when unrestricted. Read by the (future) stats HUD.
+    private(set) var thermalNotice: String?
 
     @ObservationIgnored private let picker = SCContentSharingPicker.shared
     @ObservationIgnored private var pendingSettings: StreamSettings?
@@ -27,6 +30,8 @@ final class ScreenCaptureController: NSObject {
     @ObservationIgnored private var publisherTask: Task<Void, Never>?
     @ObservationIgnored private var heartbeatTask: Task<Void, Never>?
     @ObservationIgnored private var micVolumeObserver: DarwinSignalObserver?
+    @ObservationIgnored private var lastAppliedCeiling: ThermalPowerCeiling?
+    @ObservationIgnored private var thermalApplyTask: Task<Void, Never>?
 
     override init() {
         super.init()
@@ -35,6 +40,21 @@ final class ScreenCaptureController: NSObject {
         micVolumeObserver = DarwinSignalObserver(name: BroadcastControl.micVolumeSignal) { [weak self] in
             Task { @MainActor [weak self] in self?.applyMicVolume() }
         }
+        let center = NotificationCenter.default
+        center.addObserver(self, selector: #selector(thermalOrPowerChanged),
+                           name: ProcessInfo.thermalStateDidChangeNotification, object: nil)
+        center.addObserver(self, selector: #selector(thermalOrPowerChanged),
+                           name: NSNotification.Name.NSProcessInfoPowerStateDidChange, object: nil)
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    /// Thermal-state and power-state notifications arrive on an arbitrary thread;
+    /// hop to the main actor to re-evaluate the governor.
+    @objc private nonisolated func thermalOrPowerChanged() {
+        Task { @MainActor [weak self] in self?.applyThermalCeiling() }
     }
 
     func presentPicker(settings: StreamSettings) {
@@ -137,6 +157,8 @@ final class ScreenCaptureController: NSObject {
             try await stream.startCapture()
             isLive = true
             publishState(true)
+            lastAppliedCeiling = nil
+            applyThermalCeiling()
             heartbeatTask = Task {
                 while !Task.isCancelled {
                     try? await Task.sleep(for: .seconds(3))
@@ -165,6 +187,9 @@ final class ScreenCaptureController: NSObject {
         heartbeatTask?.cancel()
         heartbeatTask = nil
         isLive = false
+        thermalNotice = nil
+        lastAppliedCeiling = nil
+        thermalApplyTask = nil
         output?.finish()
 
         if let stream, stream.isCapturing {
@@ -205,6 +230,34 @@ final class ScreenCaptureController: NSObject {
         Task { await publisher.setMicVolume(volume) }
     }
 
+    /// Recomputes the thermal/Low-Power ceiling and pushes it to the encoder (via
+    /// the adaptive controller) and the compositor. Reuses the existing throttle
+    /// path rather than adding a parallel one. No-op while not capturing.
+    private func applyThermalCeiling() {
+        guard let publisher, let output else { return }
+        let ceiling = ThermalPowerGovernor.current()
+        guard ceiling != lastAppliedCeiling else { return }
+        lastAppliedCeiling = ceiling
+        thermalNotice = ceiling.notice
+        output.applyThermalProfile(frameRateCap: ceiling.frameRateCap,
+                                   allowPiP: ceiling.allowPiP)
+        let scale = ceiling.bitRateScale
+        let cap = ceiling.frameRateCap
+        // Serialize applies in submission order so two notifications firing close
+        // together cannot land on the ABR actor out of order and leave a stale
+        // ceiling stored while thermalNotice reports otherwise.
+        let previous = thermalApplyTask
+        thermalApplyTask = Task {
+            await previous?.value
+            await publisher.setThermalCeiling(bitRateScale: scale, frameRateCap: cap)
+        }
+        if ceiling.notice != nil {
+            captureLog.notice("Thermal governor engaged: fpsCap=\(cap, privacy: .public) bitrateScale=\(scale, privacy: .public) lowPower=\(ProcessInfo.processInfo.isLowPowerModeEnabled, privacy: .public)")
+        } else {
+            captureLog.info("Thermal governor cleared; full quality restored")
+        }
+    }
+
     private func configurePreferredMicrophone(_ uid: String?) async {
         let session = AVAudioSession.sharedInstance()
         var activated = false
@@ -321,7 +374,7 @@ private final class ScreenCaptureOutput: NSObject, SCStreamOutput, SCStreamDeleg
     /// so the screen callback itself must throttle down to `settings.frameRate` —
     /// otherwise the encoder is flooded (irregular pacing + CPU/thermal spikes that
     /// stutter both video and audio). Touched only on the serial `sampleQueue`.
-    private let targetFrameInterval: CMTime
+    private var targetFrameInterval: CMTime
     private var nextVideoDeadline: CMTime = .invalid
 
     init(publisher: any Publisher,
@@ -422,6 +475,25 @@ private final class ScreenCaptureOutput: NSObject, SCStreamOutput, SCStreamDeleg
     func setMicVolume(_ volume: Double) {
         micLevelMeter.setGain(volume)
     }
+
+    /// Applies the device thermal/Low-Power profile to the capture side: paces the
+    /// screen callback to the capped frame rate (on the serial sample queue) and
+    /// stops the facecam under pressure so the camera + compositor stop burning
+    /// power. Re-arms the facecam when the device recovers. PiP toggling only
+    /// applies when the user has the facecam enabled.
+    func applyThermalProfile(frameRateCap: Int, allowPiP: Bool) {
+        sampleQueue.async { [weak self] in
+            guard let self else { return }
+            let fps = max(1, min(self.settings.frameRate, frameRateCap))
+            self.targetFrameInterval = CMTime(value: 1, timescale: CMTimeScale(fps))
+        }
+        guard settings.pipEnabled else { return }
+        if allowPiP {
+            facecam.start(with: settings)
+        } else {
+            facecam.stop()
+        }
+    }
 }
 
 /// Computes a throttled post-gain RMS level from ScreenCaptureKit microphone
@@ -533,6 +605,7 @@ private final class ScreenCaptureMicrophoneMeter: @unchecked Sendable {
 final class ScreenCaptureController {
     private(set) var isLive = false
     private(set) var errorMessage: String?
+    private(set) var thermalNotice: String?
 
     func presentPicker(settings: StreamSettings) {
         errorMessage = "Screen capture requires a physical iOS 27 device."

Stream/ThermalPowerGovernor.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+/// A throttle ceiling derived from the device's thermal and power state.
+///
+/// The broadcast has no environmental awareness on its own: a healthy-network
+/// stream encodes at full rate until iOS hard-throttles or terminates it. This
+/// ceiling is fed into the *existing* adaptive path — the network ABR still owns
+/// the final rate by taking the `min()` of the network and thermal ceilings — so
+/// a hot or battery-constrained device sheds encoder, network, and camera load
+/// before the OS does it for us.
+struct ThermalPowerCeiling: Equatable {
+    /// Fraction of the configured maximum video bitrate to allow (0...1).
+    var bitRateScale: Double
+    /// Hard frame-rate ceiling. `.max` means "no thermal cap".
+    var frameRateCap: Int
+    /// When false, the facecam is stopped to shed camera + compositor cost.
+    var allowPiP: Bool
+    /// User-facing reason, or nil when the device is unrestricted.
+    var notice: String?
+
+    static let unrestricted = ThermalPowerCeiling(
+        bitRateScale: 1.0, frameRateCap: .max, allowPiP: true, notice: nil
+    )
+}
+
+/// Maps `ProcessInfo` thermal + Low Power state to a `ThermalPowerCeiling`.
+enum ThermalPowerGovernor {
+    /// Pure policy: state in, ceiling out. Side-effect free so the mapping reads
+    /// clearly and can be reasoned about (and exercised) in isolation.
+    static func ceiling(thermalState: ProcessInfo.ThermalState,
+                        lowPowerMode: Bool) -> ThermalPowerCeiling {
+        switch thermalState {
+        case .critical:
+            // Shed aggressively — the OS is about to throttle or kill us anyway.
+            return ThermalPowerCeiling(bitRateScale: 0.35, frameRateCap: 10,
+                                       allowPiP: false,
+                                       notice: "Cooling down — quality reduced")
+        case .serious:
+            return ThermalPowerCeiling(bitRateScale: 0.6, frameRateCap: 24,
+                                       allowPiP: false,
+                                       notice: "Device warm — quality reduced")
+        case .fair, .nominal:
+            // Mild thermals are fine; only Low Power Mode pulls the rate back.
+            return lowPowerMode
+                ? ThermalPowerCeiling(bitRateScale: 0.75, frameRateCap: 30,
+                                      allowPiP: false,
+                                      notice: "Low Power Mode — quality reduced")
+                : .unrestricted
+        @unknown default:
+            return .unrestricted
+        }
+    }
+
+    /// The ceiling for the device's current thermal + power state.
+    static func current() -> ThermalPowerCeiling {
+        ceiling(thermalState: ProcessInfo.processInfo.thermalState,
+                lowPowerMode: ProcessInfo.processInfo.isLowPowerModeEnabled)
+    }
+}

StreamBroadcast/RTMPPublisher.swift

@@ -754,6 +754,12 @@ actor RTMPPublisher: Publisher {
         }
     }
 
+    func setThermalCeiling(bitRateScale: Double, frameRateCap: Int) async {
+        await networkController.setThermalCeiling(bitRateScale: bitRateScale,
+                                                  frameRateCap: frameRateCap,
+                                                  applyingTo: stream)
+    }
+
     /// Appends a (raw or composited) screen video buffer. Dropped until the output
     /// size is locked, so the encoder never starts at the wrong dimensions.
     func appendVideo(_ sb: CMSampleBuffer) async {
@@ -983,7 +989,17 @@ actor BroadcastAdaptiveBitRateController: StreamBitRateStrategy {
     private var currentInterface: NetworkPathSnapshot.Interface?
     private var lastGoodTarget: [NetworkPathSnapshot.Interface: Int] = [:]
 
-    private var effectiveMaximum: Int { min(mamimumVideoBitRate, pathCeiling) }
+    /// Thermal / Low-Power ceiling from `ThermalPowerGovernor`, composed with the
+    /// network path ceiling. `min()`'d into `effectiveMaximum` so the upward probe
+    /// never climbs past it, and folded into every frame-interval decision.
+    private var thermalBitRateScale: Double = 1.0
+    private var thermalFrameRateCap: Int = .max
+
+    private var effectiveMaximum: Int {
+        let thermalCeiling = Int(Double(mamimumVideoBitRate) * thermalBitRateScale)
+        return max(minimumVideoBitRate,
+                   min(min(mamimumVideoBitRate, pathCeiling), thermalCeiling))
+    }
 
     init(maximumBitRate: Int, frameRate: Int) {
         mamimumVideoBitRate = maximumBitRate
@@ -1103,7 +1119,10 @@ actor BroadcastAdaptiveBitRateController: StreamBitRateStrategy {
         }
         let raised = clamped > pathCeiling
         pathCeiling = clamped
-        targetBitRate = min(targetBitRate, pathCeiling)
+        // Clamp to effectiveMaximum (which folds in the thermal ceiling), not just
+        // pathCeiling: otherwise an interface change re-seeds targetBitRate from a
+        // full-rate last-good value and silently defeats an active thermal cap.
+        targetBitRate = min(targetBitRate, effectiveMaximum)
         if raised { healthySeconds = 0 }   // restart the upward probe cleanly
         await applyTarget(to: stream)      // apply NOW, not at the next 1 Hz event
     }
@@ -1118,13 +1137,62 @@ actor BroadcastAdaptiveBitRateController: StreamBitRateStrategy {
                              severe: Bool = false) async {
         var video = await stream.videoSettings
         video.bitRate = targetBitRate
+        video.frameInterval = frameInterval(severe: severe)
+        try? await stream.setVideoSettings(video)
+    }
+
+    /// The frame interval for the current congestion + thermal state. A larger
+    /// interval is a lower frame rate, so taking `max()` of the congestion and
+    /// thermal intervals always yields the more restrictive of the two.
+    private func frameInterval(severe: Bool) -> Double {
+        let congestionInterval: Double
         if severe {
-            video.frameInterval = VideoCodecSettings.frameInterval10
+            congestionInterval = VideoCodecSettings.frameInterval10
         } else if congestionActive, configuredFrameRate > 30 {
-            video.frameInterval = VideoCodecSettings.frameInterval30
+            congestionInterval = VideoCodecSettings.frameInterval30
         } else {
-            video.frameInterval = preferredFrameInterval
+            congestionInterval = preferredFrameInterval
         }
+        let cappedFrameRate = max(1, min(configuredFrameRate, thermalFrameRateCap))
+        let thermalInterval = max(0, (1.0 / Double(cappedFrameRate)) - 0.001)
+        return max(congestionInterval, thermalInterval)
+    }
+
+    /// Stores a thermal/Low-Power ceiling and clamps the current target to it.
+    /// Used when there is no stream to apply to yet (pre-connect); the value then
+    /// takes effect on the first adaptive event after connect.
+    func storeThermalCeiling(bitRateScale: Double, frameRateCap: Int) {
+        thermalBitRateScale = min(max(bitRateScale, 0.1), 1.0)
+        thermalFrameRateCap = max(1, frameRateCap)
+        // Only lower the target to fit a tightened ceiling. Leave healthySeconds
+        // alone: resetting it on every change would let brief thermal flapping
+        // across a boundary keep restarting the up-probe and starve recovery.
+        targetBitRate = min(targetBitRate, effectiveMaximum)
+    }
+
+    func currentFrameInterval() -> Double { frameInterval(severe: false) }
+
+    /// Applies the current (possibly thermally-clamped) target + frame interval to
+    /// a freshly-connected stream. SRT/WHIP emit no `.reset` event, so the
+    /// pre-connect store path relies on this to land the ceiling on the encoder.
+    func applyCurrentTarget(to stream: any StreamConvertible) async {
+        var video = await stream.videoSettings
+        video.bitRate = targetBitRate
+        video.frameInterval = frameInterval(severe: false)
+        try? await stream.setVideoSettings(video)
+    }
+
+    /// Applies a thermal/Low-Power ceiling to the encoder immediately, instead of
+    /// waiting for the next ~1 Hz adaptive event. Takes `any StreamConvertible` so
+    /// both the concrete RTMPStream and SessionPublisher's existential stream can
+    /// drive it.
+    func setThermalCeiling(bitRateScale: Double,
+                           frameRateCap: Int,
+                           applyingTo stream: any StreamConvertible) async {
+        storeThermalCeiling(bitRateScale: bitRateScale, frameRateCap: frameRateCap)
+        var video = await stream.videoSettings
+        video.bitRate = targetBitRate
+        video.frameInterval = frameInterval(severe: false)
         try? await stream.setVideoSettings(video)
     }
 

StreamBroadcast/SessionPublisher.swift

@@ -27,6 +27,9 @@ protocol Publisher: Actor {
     nonisolated func enqueueMic(_ sb: CMSampleBuffer)
     nonisolated func enqueueApp(_ sb: CMSampleBuffer)
     func setMicVolume(_ volume: Double) async
+    /// Applies a device thermal / Low-Power ceiling (bitrate scale + fps cap) to
+    /// the encoder, composed with the network ceiling by the adaptive controller.
+    func setThermalCeiling(bitRateScale: Double, frameRateCap: Int) async
 }
 
 /// Publishes over SRT or WHIP via HaishinKit's protocol-agnostic `StreamSession`
@@ -162,14 +165,19 @@ actor SessionPublisher: Publisher {
         // Re-apply the locked encoder size to the fresh stream (across reconnects).
         if let outputSize {
             try? await stream.setVideoSettings(
-                makeVideoSettings(await stream.videoSettings, size: outputSize)
+                await makeVideoSettings(await stream.videoSettings, size: outputSize)
             )
         }
 
         await mixer.addOutput(stream)
         self.session = session
         self.stream = stream
 
+        // Land any thermal ceiling stored before the stream existed. SRT/WHIP emit
+        // no `.reset` event, so no adaptive event would otherwise apply a hot-at-
+        // go-live ceiling to this fresh encoder until congestion or a state change.
+        await networkController.applyCurrentTarget(to: stream)
+
         try await session.connect { [weak self] in
             guard let self else { return }
             Task { await self.handleDisconnect() }
@@ -214,20 +222,36 @@ actor SessionPublisher: Publisher {
         outputSizeConfigured = true
         guard let stream else { return }
         do {
-            try await stream.setVideoSettings(makeVideoSettings(await stream.videoSettings, size: size))
+            try await stream.setVideoSettings(await makeVideoSettings(await stream.videoSettings, size: size))
         } catch {
             sessionLog.error("Video encoder configuration failed: \(String(describing: error), privacy: .public)")
         }
     }
 
-    private func makeVideoSettings(_ current: VideoCodecSettings, size: CGSize? = nil) -> VideoCodecSettings {
+    func setThermalCeiling(bitRateScale: Double, frameRateCap: Int) async {
+        // Apply immediately when connected; otherwise store the ceiling so the
+        // first adaptive event after connect (the `.reset`) picks it up.
+        if let stream {
+            await networkController.setThermalCeiling(bitRateScale: bitRateScale,
+                                                      frameRateCap: frameRateCap,
+                                                      applyingTo: stream)
+        } else {
+            await networkController.storeThermalCeiling(bitRateScale: bitRateScale,
+                                                        frameRateCap: frameRateCap)
+        }
+    }
+
+    private func makeVideoSettings(_ current: VideoCodecSettings, size: CGSize? = nil) async -> VideoCodecSettings {
         let frameRate = min(max(settings.frameRate, 1), 30)
         var v = current
         if let size { v.videoSize = size }
         v.scalingMode = .letterbox
-        v.bitRate = settings.videoBitrate
+        // Seed from the adaptive controller's current target + frame interval so a
+        // path or thermal ceiling learned before this (re)configuration is honored
+        // immediately, instead of starting the fresh encoder at the full rate.
+        v.bitRate = min(settings.videoBitrate, await networkController.currentTargetBitRate())
         v.expectedFrameRate = Double(frameRate)
-        v.frameInterval = max(0, (1.0 / Double(frameRate)) - 0.001)
+        v.frameInterval = await networkController.currentFrameInterval()
         v.maxKeyFrameIntervalDuration = 2
         v.bitRateMode = .average
         v.profileLevel = kVTProfileLevel_H264_Main_AutoLevel as String