import Foundation import WebRTC /// Every number that shapes the picture, in one place. enum Tuning { // MARK: What a viewer gets when it doesn't say static let defaultMaxWidth = 1920 /// The stream down the host's socket. static let defaultFps = 30 /// The video track: the full rate while it is being carried, the reduced one while it is not /// (`FrameRate`, and its numbers below). A viewer that names a rate gets that one and no other. static let fullFps = 60 static let reducedFps = 30 static let fpsRange = 1...120 /// High refresh is opt-in and bounded by both displays, not just a sender preference. static func fullRate(viewer: Int, display: Int) -> Int { let maximum = min(viewer, display) return maximum >= 120 ? 120 : maximum >= 60 ? 60 : max(1, min(30, maximum)) } /// No picture is asked to be narrower than this, in pixels. static let narrowestPicture = 160 // MARK: libwebrtc /// Read once, when the factory is made (`RTCInitFieldTrialDictionary`). /// /// ForceSendPlayoutDelay: the sender writes min 0 / max 0 into the playout-delay header /// extension, which tells the receiver to show each frame as soon as it is decoded instead of /// holding it in the jitter buffer for smoothness (rtp_sender_video.cc, M154). It is the only /// way to say so to a receiver without `jitterBufferTarget` (Safari, WKWebView). static let fieldTrials: [String: String] = [ "WebRTC-ForceSendPlayoutDelay": "min_ms:0,max_ms:0", // M154 needs both: one exposes the send codec, the other creates the FEC-FR SSRC and // permits the sender. A receiver which drops flexfec-03 keeps the usual NACK/RTX path. "WebRTC-FlexFEC-03-Advertised": "Enabled", "WebRTC-FlexFEC-03": "Enabled", ] /// When the network or the encoder can't keep up, the picture gets smaller, not jerkier: a /// screen that is being controlled has to follow the hand. (libwebrtc's own choice for screen /// content is the opposite, maintain-resolution, which drops to a few frames a second.) static let degradation = RTCDegradationPreference.maintainFramerate /// The widest picture a viewer may ask for (`rtc.open`'s `maxWidth`): a 5K display's whole /// width at 60 frames is more than the encoder and a phone's decoder carry. static let widestPicture = 3840 /// 8 Mbit/s for a 1920-wide picture at 30 frames, half as much again at 60. Above that the /// ceiling grows with the square root of the pixels, not in proportion: the more pixels a /// screen has, the more of them are the same as their neighbours. The bandwidth estimate /// decides what is actually sent; this is the ceiling. static func maxBitrate(width: Int, height: Int, fps: Int) -> Int { let pixels = Double(width * height) / Double(1920 * 1080) let frameFactor = fps > 60 ? 1.5 * Double(fps) / 60 : fps > 30 ? 1.5 : 1 let rate = 8_000_000 * (pixels > 1 ? pixels.squareRoot() : pixels) * frameFactor return Int(min(max(rate, 2_000_000), 30_000_000)) } /// Where the bandwidth estimate starts. libwebrtc's default (300 kbit/s) makes the first /// seconds of a screen unreadable; a home network carries this from the first frame. static let startBitrate = 2_000_000 /// The most a picture sent through a TURN relay uses, in kbit/s, where the host doesn't say: someone pays /// for every byte a relay carries, and a phone shows a screen well at this. static let relayKbps = 3000 // MARK: The floor under the estimate on the local network (`LanFloor`) /// What the estimate is held to while the video stays on the local network: enough for crisp /// text at 1080p, a small part of what any working Wi-Fi carries. static let lanFloor = 8_000_000 /// Seconds of round trips looked at. The floor is set when the lowest of them is under /// `lanFloorRttMs` and lifted when even the lowest is over `lanFloorLiftRttMs`: a radio that /// holds packets for a moment raises some round trips, a queue that stays raises all of them. static let lanFloorWindow = 4 static let lanFloorRttMs = 20.0 static let lanFloorLiftRttMs = 40.0 /// Loss the floor is set under, and lifted over. static let lanFloorLoss = 0.01 static let lanFloorLiftLoss = 0.05 /// Average sender queueing the floor is set under, and lifted over: a floor the network can't /// take shows here first, before the round trip or loss do. static let lanFloorSendDelayMs = 10.0 static let lanFloorLiftSendDelayMs = 50.0 /// Seconds after the floor is set during which sender queueing alone does not lift it. Raising /// the estimate to the floor is itself what fills the pacer: the encoder answers the new rate /// with larger frames, and the queue they make reads as congestion the floor caused. Measured /// on two Macs over the local network, that burst showed as 84 ms and 141 ms of queueing and /// lifted the floor within 9–27 s of it being set. Round trip and loss still lift it at once: /// those say the path itself is full, not that the pacer has a moment's work in hand. static let lanFloorSettle = 5 /// Seconds running the sender must queue before that lifts the floor. On a watched Mac's log /// a third of all lifts (26 of 78) were one second of queueing, 54–263 ms, within seconds of /// the floor being set: one large frame at the pacer's rate, not a network refusing the rate. /// The floor went, the estimate fell, and the next large frames waited far longer. The same /// count as `frameRateDownAfter`: a queue that lasts this long costs the frame rate anyway. static let lanFloorLiftSendDelaySeconds = 3 /// Calm seconds before a lifted floor comes back, and lifts after which it never does. static let lanFloorRecalm = 30 static let lanFloorMaxLifts = 2 /// DSCP marking and the pacer's order, where a network honours it. static let networkPriority = RTCPriority.high // MARK: Making the first connection (`ScreenSession.scheduleRestart`) /// If no path has connected this many seconds after an offer, ICE is restarted and the offer /// re-sent: a stalled first gathering often clears on a fresh one. Kept well under the viewer's /// own 25 s patience so both restarts are tried before it gives up to the socket fallback. static let iceRestartAfter: TimeInterval = 8 /// How many times to restart before leaving it to the viewer's fallback. static let iceRestartLimit = 2 // MARK: The video track's frame rate (`FrameRate`), judged once a second while connected /// At the start, and after a change of rate, nothing is concluded for this many seconds: the /// estimate, the encoder and libwebrtc's own adapting are still finding the new rate's level. static let frameRateSettle = 4 /// The full rate is not being carried when one of these has gone on for this many seconds /// running. Shorter, and a moment's dip in the estimate would cost the rate; longer, and the /// viewer reads a blurred screen for no reason. static let frameRateDownAfter = 3 /// The picture sent has been made smaller when it has less than this share of the captured /// picture's pixels. libwebrtc's first step leaves 4/9 of them (1920 wide becomes 1280); an /// encoder that crops a row to align the picture leaves all but a thousandth. static let frameRateShrunk = 0.9 /// Frames are not making it out when the screen gives at least this share of the rate (so the /// rate is being asked for at all) and less than this share of what it gives is encoded. static let frameRateBusy = 0.8 static let frameRateCarried = 0.75 /// A sustained queue is pressure, even before libwebrtc reduces resolution or drops frames. /// These are adaptation thresholds, not a guarantee that individual packets meet a deadline. /// Separate down/up thresholds prevent small queue fluctuations from changing the rate. static let frameRateQueueSlowMs = 50.0 static let frameRateQueueCalmMs = 10.0 /// Probe the next rate after the current picture and send queue stay healthy this long. /// Failed probes double the wait up to the maximum; a low bitrate estimate alone is harmless. static let frameRateCalm = 10 static let frameRateCalmMax = 160 static let frameRateHeld = 30 /// For its first second the full rate may send this share of what the reduced rate was /// sending, and never less than this many bits a second (`ScreenSession.change`): twice the /// frames on half the bits are the bits there were. static let frameRateEase = 0.5 static let frameRateEaseFloor = 1_000_000 // MARK: The sender's queue (`SendQueue`, `VideoCompressor.KeyPlan`) /// libwebrtc's pacer sends at this multiple of the rate it gives the encoder (M154: /// `kDefaultPaceMultiplier`). static let pacerFactor = 2.5 /// A key frame may take this long to leave at the pacer's rate: a fifth of a second of the /// encoder's rate. Left to itself the low-latency encoder made a 1080p page's key frame 470 KB /// at 8 Mbit/s and 370–390 KB at 2 Mbit/s (a second and a half of that rate), then dropped the /// frames after it to pay for it. Held to a budget, a key frame comes coarser and the frames /// after it sharpen the picture. A change of scene that is not a key frame can't be held this /// way: the low-latency rate control ignores `DataRateLimits`, and those frames are for /// `SendQueue` to make room after. static let keyFrameSendSeconds = 0.08 static func keyFrameBudget(bitrate: Int) -> Int { max(1024, Int(Double(bitrate) * pacerFactor * keyFrameSendSeconds / 8)) } /// With more than this reckoned to be waiting to be sent, a picture is not encoded. The same /// 50 ms that, standing for seconds, costs the frame rate and the floor. static let sendQueueAdmitMs = 50.0 /// The pacer is not reckoned slower than this rate allows, whatever the encoder is told. static let sendQueueLowestRate = 300_000 /// Both are on unless said otherwise, by flag or by a default /// (`defaults write com.bd.linkshell.host screenKeyBudget -bool NO`, `screenQueueAdmission`): /// to compare the picture with and without them on a real network. static let keyBudget = !Launch.has("--no-key-budget") && UserDefaults.standard.object(forKey: "screenKeyBudget") as? Bool != false static let queueAdmission = !Launch.has("--no-queue-admission") && UserDefaults.standard.object(forKey: "screenQueueAdmission") as? Bool != false // MARK: Capture /// Surfaces ScreenCaptureKit may have out at once: one being encoded, one kept for repeating, /// and room for the next ones. static let captureQueueDepth = 5 /// Raw pictures admitted to VideoToolbox before its callbacks return. More lets a busy /// encoder build a queue of stale screen contents; fewer can starve its hardware pipeline. static let encoderPendingFrames = 2 /// The capture is asked for a little more than the frame rate. Asked for exactly 60, /// ScreenCaptureKit delivered 55 a second from a 120 Hz display and 57.5 from a 144 Hz one /// (28.8 for 30); asked for 66 it delivers 62, and libwebrtc drops the two too many. static let captureRateSlack = 1.1 /// ScreenCaptureKit is silent while the screen is still, and libwebrtc only answers a request /// for a key frame (or sharpens a picture it sent coarse) when a frame comes in. So the last /// picture is sent again: quickly for a moment after the screen stops changing, then slowly. static let settleRepeatInterval = 0.1 static let settleWindow = 1.0 static let idleRepeatInterval = 0.5 // MARK: Pointer, input and numbers /// How often the pointer's place is looked at, and said when it changed. static let cursorRate = 60.0 /// How often the pointer's picture is looked at: a change of shape a fifth of a second late /// is not noticed, and reading the picture is the dearer of the two. static let shapeRate = 5.0 /// The longest message a viewer may send on a data channel: 4000 characters of text, with /// room for the way JSON writes them. static let maxEventBytes = 64_000 /// `--stats-interval ` exists only to test whether reading the statistics itself /// disturbs the picture; the frame-rate and floor decisions assume one-second samples. static let statsInterval = Launch.value(after: "--stats-interval").flatMap(Double.init).map { min(max($0, 0.25), 10) } ?? 1.0 // MARK: The stream down the host's socket /// A key frame is never asked for more often than this, in seconds, nor a stream slower than /// this, in bits a second: below them there is no picture to speak of. static let streamShortestGop = 0.2 static let streamLowestBitrate = 50_000 /// The part of a second's bits a key frame may take: 0.4 leaves the larger part to the frames /// that follow it. Of a still screen the key frame is all there is to send, and it may take 0.8. static let streamKeyShare = 0.4 static let streamStillKeyShare = 0.8 /// A picture the rate left coarse is sent again, a frame at a time, until its quantizer is /// this fine (text is crisp from about here) or this many seconds have gone by. static let streamFineQuantizer = 24 static let streamRefineWindow = 1.5 /// A frame goes when its time has come to within this (nanoseconds): a timer is never exact. static let streamPaceTolerance: Int64 = 1_000_000 /// How soon to look again when the host or the encoder had no room (nanoseconds). static let streamRetryInterval: Int64 = 5_000_000 /// With this many seconds of the stream written and not yet read by the host, no more frames /// are made: they would only be late. The socket's own buffer comes on top of it, and is kept /// small for that reason: what is in it can't be taken back. static let streamPipeSeconds = 0.5 static let streamSocketBuffer = 64 * 1024 }