@desklink/host 0.2.0 → 0.3.0

package/engine/src/session.rs

@@ -8,16 +8,18 @@
 use crate::capture::{self, Capture};
 use crate::clipboard;
 use crate::convert::{fit, I420};
-use crate::encoder::Encoder;
+use crate::encoder::{Encoder, VideoEncoder};
 use crate::input::{Button, HeldState, InputDevices};
 use crate::keymap::{self, Layout};
-use crate::peer::{h264_profile_level_id, PeerEvent, TransportOptions, VideoCodec, VideoPeer};
+use crate::peer::{
+    h264_profile_level_id, PathReport, PeerEvent, TransportOptions, VideoCodec, VideoPeer,
+};
 use crate::portal::{self, SelectedSource};
 use crate::protocol::{
     ControlMessage, ControlReply, EncodedCodec, Permission, PointerPhase, SourceRequest,
 };
 use crate::x11::X11Desktop;
-use anyhow::Result;
+use anyhow::{Context, Result};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Condvar, Mutex};
 use std::time::{Duration, Instant};
@@ -51,14 +53,41 @@ pub struct Metrics {
     pub dropped_frames: u64,
     pub encoded_frames: u64,
     pub encoded_bytes: u64,
-    /// Key frames sent: the first, and one per receiver request.
+    /// Key frames sent: the first, one per receiver request, and one each time
+    /// motion starts or stops being coded at half size.
     pub key_frames: u64,
     /// Refinement passes: a still desktop re-coded once, sharp.
     pub refined_frames: u64,
+    /// Motion frames coded at half size because full size could not keep up.
+    pub halved_frames: u64,
+    /// Fresh captures coded at the pace of change: a motion pass on a frame
+    /// the encoder had not coded yet — the population `queue_micros` is over.
+    pub motion_frames: u64,
     /// Time spent in the encoder, in microseconds, over every encoded frame.
     pub encode_micros: u64,
+    /// Time spent grabbing and converting a frame on the capture thread, in
+    /// microseconds, over every frame forwarded to the encoder. On X11 this
+    /// is `GetImage` plus the downscale to I420; unchanged polls are hashed,
+    /// recognised, and never forwarded, so their grab cost stays out; the lab
+    /// harness reads it as the grab cost L1 owns.
+    pub capture_micros: u64,
+    /// Time spent hashing a captured frame and working out its damage on the
+    /// capture thread, in microseconds, over every forwarded frame; the hash
+    /// branch runs only when `local_frames` is on.
+    pub convert_micros: u64,
+    /// Time a freshly captured frame waited between the capture handoff and
+    /// the start of its encode, in microseconds, over motion frames.
+    pub queue_micros: u64,
+    /// Time spent packetizing a frame and handing it to the transport, in
+    /// microseconds, over every sent frame.
+    pub send_micros: u64,
     /// The current rate target, after any loss back-off.
     pub target_kbps: u32,
+    /// The codec frames go out in, `vp9` or `h264`, and what codes them
+    /// (`libvpx`, `nvenc`, `vaapi`, `openh264`, `videotoolbox`); empty for an
+    /// encoded source, whose consumer is the encoder.
+    pub codec: &'static str,
+    pub encoder: &'static str,
     pub input_applied: u64,
     pub input_rejected: u64,
     /// Access units the consumer fed to an encoded source.
@@ -185,6 +214,7 @@ fn select_x11(
     let desktop = Arc::new(Mutex::new(X11Desktop::connect(display)?));
     let (width, height) = {
         let desktop = lock(&desktop);
+        eprintln!("x11 capture path: {}", desktop.capture_path());
         desktop.screen_size()
     };
     let source = SelectedSource {
@@ -207,26 +237,75 @@ fn select_x11(
             .spawn(move || {
                 let interval = frame_interval(max_fps);
                 let mut sequence = 0u64;
-                // An X server has no damage signal here, so an unchanged screen
-                // is recognised by its pixels: handing it on would keep the
-                // encoder busy and a still desktop would never be refined.
+                let mut last_sent: Option<Instant> = None;
+                // Without XDamage there is no change signal, so an unchanged
+                // screen is recognised by its pixels exactly as before.
+                let hashed = !lock(&desktop).damage_armed();
                 let mut last_hash = None;
+                // The first frame is always grabbed; afterwards Damage wakes
+                // the loop, so a still screen costs no grab, no conversion
+                // and no hash. The fps cap stays a minimum spacing.
+                let mut first = true;
                 while !stop.load(Ordering::SeqCst) {
+                    if !first {
+                        let changed = lock(&desktop).take_damage();
+                        if !changed {
+                            std::thread::sleep(interval);
+                            continue;
+                        }
+                        if let Some(sent) = last_sent {
+                            let elapsed = sent.elapsed();
+                            if elapsed < interval {
+                                std::thread::sleep(interval - elapsed);
+                            }
+                        }
+                    }
                     let started = Instant::now();
+                    let grabbed = Instant::now();
                     let frame = {
                         let mut desktop = lock(&desktop);
                         desktop.capture_with_pixels(max_width, max_height)
                     };
+                    let grab_micros = grabbed.elapsed().as_micros() as u64;
                     match frame {
                         Ok((frame, raw)) => {
-                            use std::hash::{Hash, Hasher};
-                            let mut hasher = std::collections::hash_map::DefaultHasher::new();
-                            raw.hash(&mut hasher);
-                            let hash = hasher.finish();
-                            if last_hash != Some(hash) {
-                                last_hash = Some(hash);
-                                sink(frame, sequence, raw);
+                            let changed = if hashed {
+                                use std::hash::{Hash, Hasher};
+                                let mut hasher = std::collections::hash_map::DefaultHasher::new();
+                                raw.hash(&mut hasher);
+                                let hash = hasher.finish();
+                                if last_hash == Some(hash) {
+                                    false
+                                } else {
+                                    last_hash = Some(hash);
+                                    true
+                                }
+                            } else {
+                                true
+                            };
+                            if changed {
+                                // Handing an unchanged frame on would keep the
+                                // encoder busy and a still desktop would never
+                                // be refined.
+                                if let Ok(mut m) = captured.lock() {
+                                    m.capture_micros += grab_micros;
+                                }
+                                let (w, h) = (frame.width, frame.height);
+                                let (screen_w, screen_h) = (width as usize, height as usize);
+                                sink(frame, sequence, &mut || {
+                                    crate::convert::to_bgrx(
+                                        &raw,
+                                        screen_w,
+                                        screen_h,
+                                        screen_w * 4,
+                                        crate::convert::PixelFormat::Bgrx,
+                                        w,
+                                        h,
+                                    )
+                                });
                                 sequence += 1;
+                                last_sent = Some(started);
+                                first = false;
                             }
                         }
                         Err(error) => {
@@ -239,11 +318,21 @@ fn select_x11(
                                 on_stop(format!("X11 capture stopped: {error}"));
                                 break;
                             }
+                            if !hashed {
+                                let elapsed = started.elapsed();
+                                if elapsed < interval {
+                                    std::thread::sleep(interval - elapsed);
+                                }
+                            }
                         }
                     }
-                    let elapsed = started.elapsed();
-                    if elapsed < interval {
-                        std::thread::sleep(interval - elapsed);
+                    // With Damage the fps cap paced the grab above; without
+                    // it the loop keeps its old trailing sleep.
+                    if hashed {
+                        let elapsed = started.elapsed();
+                        if elapsed < interval {
+                            std::thread::sleep(interval - elapsed);
+                        }
                     }
                 }
             })
@@ -506,6 +595,9 @@ pub struct OpenRequest {
     /// Offer a passive ICE-TCP candidate on the loopback, for a forwarded client.
     pub loopback_tcp: bool,
     pub agent_indicator: bool,
+    /// Keep the latest frame and its tile hashes for `session.frame` and
+    /// `session.frame.changed`; off, a frame is converted once, for the encoder.
+    pub local_frames: bool,
 }
 
 /// Events a session raises for its consumer.
@@ -546,8 +638,13 @@ pub enum SessionEvent {
     CaptureStopped {
         reason: String,
     },
+    /// The session ended on the engine's side. `code` says whether a new
+    /// session may recover it: `transport` is the path to the consumer's peer
+    /// lost, which a fresh `session.open` can heal; `lease` and `error` are
+    /// the session's authority ending or a fault, which it cannot.
     Revoked {
         reason: String,
+        code: &'static str,
     },
 }
 
@@ -579,7 +676,7 @@ struct Inner {
     /// offer has to name the profile the stream's own SPS declares.
     peer: Mutex<Option<Arc<VideoPeer>>>,
     /// Absent for an encoded source: the consumer is the encoder.
-    encoder: Mutex<Option<Encoder>>,
+    encoder: Mutex<Option<VideoEncoder>>,
     input: Mutex<Option<InputTarget>>,
     indicator: Mutex<Option<crate::indicator::Indicator>>,
     capture: Mutex<Option<FrameSource>>,
@@ -595,6 +692,8 @@ struct Inner {
     events: tokio_mpsc::UnboundedSender<Notice>,
     /// Present only for an encoded source.
     encoded: Mutex<Option<Encoded>>,
+    /// `OpenRequest::local_frames`: whether `latest` is kept at all.
+    local_frames: bool,
 }
 
 /// A source whose video arrives already encoded.
@@ -675,7 +774,7 @@ pub fn capabilities() -> serde_json::Value {
             "cursor": "embedded",
             "audio": false,
         },
-        "encode": { "codecs": ["vp9"], "hardware": false },
+        "encode": encode_capabilities(),
         "input": {
             "mechanism": "inputtino/uinput",
             "pointer": input,
@@ -733,7 +832,7 @@ pub fn capabilities() -> serde_json::Value {
                 "remedy": format!("Allow {} in System Settings › Privacy & Security › Screen & System Audio Recording, then reconnect.", crate::mac::tcc_responsible_app_name())
             }) }
         },
-        "encode": { "codecs": ["vp9"], "hardware": false },
+        "encode": encode_capabilities(),
         "input": {
             "mechanism": "quartz-cgevent",
             "pointer": input,
@@ -750,6 +849,24 @@ pub fn capabilities() -> serde_json::Value {
     })
 }
 
+/// `capabilities.encode`: VP9 always, H.264 when an encoder for it starts
+/// here now. `hardware` describes VP9, the default.
+fn encode_capabilities() -> serde_json::Value {
+    let h264 = crate::h264::probe();
+    let mut codecs = vec!["vp9"];
+    if h264.is_some() {
+        codecs.push("h264");
+    }
+    serde_json::json!({
+        "codecs": codecs,
+        "hardware": false,
+        "h264": {
+            "encoder": h264.map(|info| info.encoder),
+            "hardware": h264.is_some_and(|info| info.hardware),
+        },
+    })
+}
+
 impl Session {
     pub async fn open(
         request: OpenRequest,
@@ -832,9 +949,18 @@ impl Session {
         let capture_status = Arc::new(on_capture_status);
         let frame_events = events.clone();
         let frame_session_id = id.clone();
-        let sink = Box::new(move |frame: I420, _seq: u64, raw: Vec<u8>| {
-            let hashes = tile_hashes(&raw, frame.width, frame.height);
-            if let Ok(mut held) = observed.lock() {
+        let local_frames = request.local_frames;
+        let sink = Box::new(move |frame: I420, _seq: u64, pixels: capture::Pixels| {
+            // The frame's RTP time: when capture handed it over, not when it
+            // was coded, so the receiver never sees encode jitter as cadence.
+            // ponytail: stamped after the backend's grab and conversion; a
+            // grab-start instant from each backend needs a FrameSink change.
+            let captured_at = Instant::now();
+            let raw = if local_frames { pixels() } else { None };
+            let hashes = raw
+                .as_ref()
+                .map(|raw| tile_hashes(raw, frame.width, frame.height));
+            if let (Some(raw), Some(hashes), Ok(mut held)) = (raw, hashes, observed.lock()) {
                 let unchanged =
                     held.as_ref()
                         .is_some_and(|(_, _, width, height, _, current, _)| {
@@ -865,10 +991,11 @@ impl Session {
             }
             if let Ok(mut m) = captured.lock() {
                 m.captured_frames += 1;
+                m.convert_micros += captured_at.elapsed().as_micros() as u64;
             }
             // An encoder that is behind gets the newest frame, not a queue: a
             // desktop stream is live, and the last state is the one that counts.
-            if frame_tx.put(frame) {
+            if frame_tx.put(frame, captured_at) {
                 if let Ok(mut m) = captured.lock() {
                     m.dropped_frames += 1;
                 }
@@ -1046,6 +1173,16 @@ impl Session {
             SessionError::new("input", format!("no keyboard layout: {error:#}"))
         })?;
 
+        // H.264 is offered beside VP9 only when an encoder for it starts on
+        // this machine; the answer then decides which one is coded.
+        let codec = if !crate::h264::fits(width, height) {
+            VideoCodec::Vp9
+        } else {
+            match tokio::task::spawn_blocking(crate::h264::prepare).await {
+                Ok(Some(_)) => VideoCodec::Vp9OrH264,
+                _ => VideoCodec::Vp9,
+            }
+        };
         let (peer_events_tx, peer_events_rx) = tokio_mpsc::unbounded_channel::<PeerEvent>();
         let (peer, offer) = VideoPeer::offer(
             TransportOptions {
@@ -1056,7 +1193,7 @@ impl Session {
                 pace_bps: (bitrate_kbps as f64 * 3_000.0).max(20_000_000.0),
             },
             peer_events_tx,
-            VideoCodec::Vp9,
+            codec,
         )
         .await
         .map_err(|error| SessionError::new("transport", format!("{error:#}")))?;
@@ -1081,7 +1218,7 @@ impl Session {
             capture_error,
             frame_changes,
             peer: Mutex::new(Some(peer.clone())),
-            encoder: Mutex::new(Some(encoder)),
+            encoder: Mutex::new(Some(VideoEncoder::Vp9(encoder))),
             input: Mutex::new(input),
             indicator: Mutex::new(indicator),
             capture: Mutex::new(Some(capture)),
@@ -1092,6 +1229,7 @@ impl Session {
             pipeline: pipeline.clone(),
             events: events.clone(),
             encoded: Mutex::new(None),
+            local_frames: request.local_frames,
         });
 
         inner.notify(SessionEvent::Description {
@@ -1189,6 +1327,7 @@ impl Session {
                 peer_events,
                 feed,
             })),
+            local_frames: false,
         });
         inner.notify(SessionEvent::State {
             capture: "consented",
@@ -1266,6 +1405,7 @@ impl Session {
                 "this session forwards an encoded stream and keeps no frame",
             ));
         }
+        self.keeps_frames()?;
         let mut changes = self.inner.frame_changes.clone();
         let deadline = tokio::time::Instant::now() + Duration::from_millis(timeout_ms.min(120_000));
         loop {
@@ -1302,6 +1442,16 @@ impl Session {
         }
     }
 
+    fn keeps_frames(&self) -> std::result::Result<(), SessionError> {
+        if self.inner.local_frames {
+            return Ok(());
+        }
+        Err(SessionError::new(
+            "operation",
+            "this session was opened with local_frames off and keeps no frame",
+        ))
+    }
+
     /// Write only the requested lossless frame bytes; JSON carries metadata, never pixels.
     pub fn frame(
         &self,
@@ -1321,6 +1471,7 @@ impl Session {
                 "this session forwards an encoded stream and keeps no frame",
             ));
         }
+        self.keeps_frames()?;
         if let Some(reason) = lock(&self.inner.capture_error).clone() {
             return Err(SessionError::new("stream-stopped", reason));
         }
@@ -1449,7 +1600,7 @@ impl Session {
     }
 
     pub async fn close(&self, reason: &str) {
-        self.inner.close(reason).await;
+        self.inner.close(reason, "closed").await;
     }
 }
 
@@ -1464,13 +1615,18 @@ impl Inner {
 
     /// Stop everything and release whatever input this session held. Idempotent,
     /// and the one teardown both an explicit close and a lease expiry take.
-    async fn close(&self, reason: &str) {
+    async fn close(&self, reason: &str, code: &str) {
         if self.closed.swap(true, Ordering::SeqCst) {
             return;
         }
         self.control_open.store(false, Ordering::SeqCst);
         self.pipeline.store(false, Ordering::SeqCst);
         drop(lock(&self.encoded).take());
+        // The encoder goes now, not with the last handle: a hardware session
+        // still open when the process exits can hang the driver's exit
+        // handlers, and `shutdown` exits right after this. The encode thread
+        // finds it gone and stops.
+        drop(lock(&self.encoder).take());
         if let Ok(mut indicator) = self.indicator.lock() {
             indicator.take();
         }
@@ -1485,8 +1641,8 @@ impl Inner {
         if let Some(peer) = self.peer.lock().ok().and_then(|peer| peer.clone()) {
             let _ = peer
                 .send_control(
-                    &serde_json::to_string(&ControlReply::Revoked { reason }).unwrap_or_else(
-                        |_| String::from(r#"{"kind":"revoked","reason":"closed"}"#),
+                    &serde_json::to_string(&ControlReply::Revoked { reason, code }).unwrap_or_else(
+                        |_| String::from(r#"{"kind":"revoked","reason":"closed","code":"closed"}"#),
                     ),
                 )
                 .await;
@@ -1937,11 +2093,13 @@ fn frame_interval(max_fps: u32) -> Duration {
     Duration::from_secs_f64(1.0 / max_fps.max(1) as f64)
 }
 
-/// The newest captured frame, handed from the capture thread to the encoder. A
-/// newer frame replaces one the encoder has not taken, so however far behind
-/// it falls, what it codes next is the desktop as it is now.
+/// The newest captured frame and when it was captured, handed from the capture
+/// thread to the encoder. A newer frame replaces one the encoder has not taken,
+/// so however far behind it falls, what it codes next is the desktop as it is
+/// now. The instant travels with the picture so the pipeline can report how
+/// long a coded frame waited for its encode.
 struct FrameSlot {
-    frame: Mutex<(Option<I420>, bool)>,
+    frame: Mutex<(Option<(I420, Instant)>, bool)>,
     ready: Condvar,
 }
 
@@ -1958,13 +2116,13 @@ fn latest_frame() -> (FrameSender, FrameReceiver) {
 
 impl FrameSender {
     /// Hand over a frame; true when it replaced one the encoder never took.
-    fn put(&self, frame: I420) -> bool {
+    fn put(&self, frame: I420, captured: Instant) -> bool {
         let mut held = self
             .0
             .frame
             .lock()
             .unwrap_or_else(|poisoned| poisoned.into_inner());
-        let replaced = held.0.replace(frame).is_some();
+        let replaced = held.0.replace((frame, captured)).is_some();
         self.0.ready.notify_one();
         replaced
     }
@@ -1984,12 +2142,22 @@ impl Drop for FrameSender {
 }
 
 enum Taken {
-    Frame(I420),
+    Frame(I420, Instant),
     Timeout,
     Ended,
 }
 
 impl FrameReceiver {
+    /// Whether a frame is waiting to be taken.
+    fn waiting(&self) -> bool {
+        self.0
+            .frame
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+            .0
+            .is_some()
+    }
+
     fn take(&self, wait: Duration) -> Taken {
         let held = self
             .0
@@ -2002,7 +2170,7 @@ impl FrameReceiver {
             .wait_timeout_while(held, wait, |(frame, ended)| frame.is_none() && !*ended)
             .unwrap_or_else(|poisoned| poisoned.into_inner());
         match held.0.take() {
-            Some(frame) => Taken::Frame(frame),
+            Some((frame, captured)) => Taken::Frame(frame, captured),
             None if held.1 => Taken::Ended,
             None => Taken::Timeout,
         }
@@ -2028,12 +2196,32 @@ fn auto_bitrate(width: usize, height: usize) -> u32 {
     (1500 + (width * height * 18 / 10_000) as u32).min(25_000)
 }
 
-/// Loss-based rate target: back off quickly when the far end reports loss,
-/// creep back when it reports none, never above what the session asked for.
+/// Queueing delay that means the link carries more than it drains: well under
+/// the latency budget, well over the noise of a busy host's scheduling.
+const QUEUE_HIGH: Duration = Duration::from_millis(25);
+/// Below this the path has room again and the target may creep back up.
+const QUEUE_LOW: Duration = Duration::from_millis(10);
+/// How often queueing delay may back the target off: long enough for the last
+/// back-off to reach the far end and show in its feedback, short enough that a
+/// queue is drained in a few steps rather than a few seconds.
+const DELAY_BACKOFF_EVERY: Duration = Duration::from_millis(300);
+
+/// The rate target: back off when the far end reports a standing queue or
+/// loss, creep back when it reports neither, never above what the session
+/// asked for.
+///
+/// Delay leads. A link with a deep buffer (most Wi-Fi and cellular ones) never
+/// loses a packet it can queue, so loss alone lets queueing delay grow to
+/// seconds before anything reacts. A standing queue backs the target off to
+/// 85% of what the path delivered, which drains it; never more than halving
+/// per step, so a stream that was idle and sent little is not taken for a
+/// slow link. Receivers without transport-wide feedback leave it loss-only.
 struct RateControl {
     ceiling: u32,
     target: u32,
     last_change: Option<Instant>,
+    /// The last queueing delay reported, while the path reports one.
+    queue: Option<Duration>,
 }
 
 impl RateControl {
@@ -2042,26 +2230,40 @@ impl RateControl {
             ceiling,
             target: ceiling,
             last_change: None,
+            queue: None,
         }
     }
 
-    /// The new target when these reports move it, at most once a second.
-    fn update(&mut self, reports: &[u8], now: Instant) -> Option<u32> {
-        let worst = *reports.iter().max()?;
-        if self
-            .last_change
-            .is_some_and(|at| now.duration_since(at) < Duration::from_secs(1))
-        {
-            return None;
+    /// The new target when these loss reports (RFC 3550 fractions, /256) or
+    /// this path report move it: down on a standing queue at most every
+    /// `DELAY_BACKOFF_EVERY`, otherwise at most once a second.
+    fn update(&mut self, reports: &[u8], path: Option<PathReport>, now: Instant) -> Option<u32> {
+        if let Some(path) = path {
+            self.queue = Some(path.queue_delay);
         }
-        let loss = worst as f64 / 256.0;
+        let since = self.last_change.map(|at| now.duration_since(at));
+        let waited = |gap: Duration| since.is_none_or(|since| since >= gap);
         let floor = (self.ceiling / 8).max(500);
-        let next = if loss > 0.10 {
-            ((self.target as f64 * 0.7) as u32).max(floor)
-        } else if loss < 0.02 {
-            ((self.target as f64 * 1.08) as u32 + 64).min(self.ceiling)
+        let next = if let Some(path) = path.filter(|path| path.queue_delay > QUEUE_HIGH) {
+            if !waited(DELAY_BACKOFF_EVERY) {
+                return None;
+            }
+            let delivered = path.delivered_kbps.clamp(self.target / 2, self.target);
+            ((delivered as f64 * 0.85) as u32).max(floor)
         } else {
-            self.target
+            let worst = *reports.iter().max()?;
+            if !waited(Duration::from_secs(1)) {
+                return None;
+            }
+            let loss = worst as f64 / 256.0;
+            let roomy = self.queue.is_none_or(|queue| queue < QUEUE_LOW);
+            if loss > 0.10 {
+                ((self.target as f64 * 0.7) as u32).max(floor)
+            } else if loss < 0.02 && roomy {
+                ((self.target as f64 * 1.08) as u32 + 64).min(self.ceiling)
+            } else {
+                self.target
+            }
         };
         if next == self.target {
             return None;
@@ -2072,9 +2274,127 @@ impl RateControl {
     }
 }
 
+/// How far the stream may run ahead of its rate target before the next frame
+/// waits: one large frame (a key frame, a refinement) goes at once, but the
+/// frames behind it hold until the link has had time to carry it, instead of
+/// queueing behind it. The frame that goes then is the newest one.
+const FRAME_BURST: Duration = Duration::from_millis(60);
+
+/// How much faster than the target the budget drains. A rate-controlled
+/// encoder averages its target but overshoots it frame to frame; drained at
+/// the target itself, that ordinary overshoot would add up and hold frames on
+/// a link with room to spare. The rate control, not this, keeps the average
+/// under what the path carries.
+const BUDGET_HEADROOM: f64 = 1.25;
+
+/// What has been sent beyond the rate target, draining a little faster than
+/// it: a leaky bucket that bounds a burst to `FRAME_BURST` plus one frame.
+#[derive(Default)]
+struct SendBudget {
+    bits: f64,
+    at: Option<Instant>,
+}
+
+impl SendBudget {
+    /// The drain rate, in bits per second.
+    fn rate(kbps: u32) -> f64 {
+        kbps.max(1) as f64 * 1000.0 * BUDGET_HEADROOM
+    }
+
+    fn drained(&self, now: Instant, kbps: u32) -> f64 {
+        let elapsed = self
+            .at
+            .map_or(0.0, |at| now.saturating_duration_since(at).as_secs_f64());
+        (self.bits - elapsed * Self::rate(kbps)).max(0.0)
+    }
+
+    /// How long until a frame may go; zero when it may go now.
+    fn wait(&self, now: Instant, kbps: u32) -> Duration {
+        let rate = Self::rate(kbps);
+        let over = self.drained(now, kbps) - FRAME_BURST.as_secs_f64() * rate;
+        Duration::from_secs_f64((over / rate).max(0.0))
+    }
+
+    fn sent(&mut self, now: Instant, bytes: usize, kbps: u32) {
+        self.bits = self.drained(now, kbps) + bytes as f64 * 8.0;
+        self.at = Some(now);
+    }
+}
+
+/// Whether motion is coded at half size. A full-size frame is slow when it
+/// took longer to code than a frame interval and the source already had a
+/// newer frame waiting: the encoder, not the source, set the pace. Content that
+/// arrives slower than the frame cap (30 fps into a 60 fps session) is never
+/// slow however long a frame takes, as long as it is done before the next one.
+/// Several slow frames that each change much of the picture (a packet over a
+/// quarter of the per-frame rate budget) mean full size cannot reach the frame
+/// rate, so the rest of the motion is coded at half size, until it stops (the
+/// refinement pass is always full size) or a run of frames that are both small
+/// and not slow shows full size would keep up again. Packet size or coding time
+/// alone never returns it to full size, so heavy motion does not flap between
+/// sizes; each change costs a key frame. Both directions need a run of frames
+/// rather than one, so a slow key frame or a busy moment on the host does not
+/// flip it, and typing never halves.
+#[derive(Default)]
+struct MotionSize {
+    half: bool,
+    run: u32,
+}
+
+impl MotionSize {
+    const SLOW_RUN: u32 = 5;
+    const SMALL_RUN: u32 = 30;
+
+    /// Account for a motion frame coded at the current size in `took`; `large`
+    /// when its packet was over a quarter of the per-frame rate budget, `behind`
+    /// when a newer frame was already waiting once it was coded.
+    fn coded(&mut self, took: Duration, large: bool, behind: bool, interval: Duration) {
+        let slow = took > interval && behind;
+        let (counts, needed) = if self.half {
+            (!large && !slow, Self::SMALL_RUN)
+        } else {
+            (large && slow, Self::SLOW_RUN)
+        };
+        self.run = if counts { self.run + 1 } else { 0 };
+        if self.run >= needed {
+            self.half = !self.half;
+            self.run = 0;
+        }
+    }
+}
+
+/// The rate cap as a deadline rather than a minimum gap. `due` is where the
+/// next frame falls on the `max_fps` cadence the stream has kept so far, and a
+/// frame may go up to one interval before it, so a late frame's lost time is
+/// made up by the next. A capture clock that jitters around the cap is then
+/// coded the moment each frame arrives, instead of beating against a second
+/// clock that delays a frame or lets the next one supersede it; the sustained
+/// rate still never exceeds the cap, and no window holds more than one frame
+/// over it.
+struct Cadence {
+    interval: Duration,
+    due: Instant,
+}
+
+impl Cadence {
+    fn new(interval: Duration, now: Instant) -> Self {
+        Self { interval, due: now }
+    }
+
+    /// How long until a frame may go; zero when it may go now.
+    fn wait(&self, now: Instant) -> Duration {
+        self.due.saturating_duration_since(now + self.interval)
+    }
+
+    fn sent(&mut self, now: Instant) {
+        self.due = self.due.max(now) + self.interval;
+    }
+}
+
 enum Pass {
     Motion {
         keyframe: bool,
+        half: bool,
     },
     Refine,
     /// The same picture again, so a still stream never looks stalled.
@@ -2107,8 +2427,11 @@ fn spawn_pipeline(
             let mut rate = RateControl::new(bitrate_kbps);
             if let Ok(mut m) = inner.metrics.lock() {
                 m.target_kbps = bitrate_kbps;
+                (m.codec, m.encoder) = ("vp9", "libvpx");
             }
-            let mut latest: Option<I420> = None;
+            // Whether motion may be coded at half size: VP9's alone.
+            let mut halves = true;
+            let mut latest: Option<(I420, Instant)> = None;
             // `pending`: the latest frame has not been coded. `refined`: it has
             // had its refinement pass, or there is nothing to refine.
             let mut pending = false;
@@ -2116,11 +2439,15 @@ fn spawn_pipeline(
             let mut keyframe = true;
             let mut still_since = Instant::now();
             let mut last_sent: Option<Instant> = None;
+            let mut size = MotionSize::default();
+            let mut cadence = Cadence::new(interval, Instant::now());
+            let mut budget = SendBudget::default();
+            // What the last frame was stamped with: the RTP clock never runs
+            // backwards, even for a re-coded picture.
+            let mut last_stamp: Option<Instant> = None;
             loop {
                 let now = Instant::now();
-                let slot = last_sent.map_or(Duration::ZERO, |at| {
-                    interval.saturating_sub(now.duration_since(at))
-                });
+                let slot = cadence.wait(now).max(budget.wait(now, rate.target));
                 let connected = peer.is_connected();
                 let wait = if !connected {
                     // Nothing sent before the transport connects arrives; the
@@ -2140,13 +2467,13 @@ fn spawn_pipeline(
                         .clamp(Duration::from_millis(10), Duration::from_millis(100))
                 };
                 match frame_rx.take(wait) {
-                    Taken::Frame(frame) => {
+                    Taken::Frame(frame, captured) => {
                         if pending {
                             if let Ok(mut m) = inner.metrics.lock() {
                                 m.dropped_frames += 1;
                             }
                         }
-                        latest = Some(frame);
+                        latest = Some((frame, captured));
                         pending = true;
                         refined = false;
                         still_since = Instant::now();
@@ -2161,7 +2488,8 @@ fn spawn_pipeline(
                     keyframe = true;
                 }
                 let reports = peer.take_loss_reports();
-                if let Some(kbps) = rate.update(&reports, Instant::now()) {
+                let path = peer.take_path_report();
+                if let Some(kbps) = rate.update(&reports, path, Instant::now()) {
                     let applied = inner.encoder.lock().map(|mut encoder| {
                         encoder
                             .as_mut()
@@ -2174,18 +2502,45 @@ fn spawn_pipeline(
                         }
                     }
                 }
-                let Some(frame) = latest.as_ref() else {
+                let Some((frame, captured)) = latest.as_ref() else {
                     continue;
                 };
                 if !connected {
                     continue;
                 }
                 let now = Instant::now();
-                if last_sent.is_some_and(|at| now.duration_since(at) < interval) {
+                if !cadence.wait(now).is_zero() || !budget.wait(now, rate.target).is_zero() {
                     continue;
                 }
+                if halves && peer.sends_h264() {
+                    // The answer asked for H.264: nothing has been sent yet,
+                    // since frames wait for the transport, which waits for it.
+                    match start_h264(&inner, rate.target, max_fps) {
+                        Ok(()) => {
+                            halves = false;
+                            size = MotionSize::default();
+                            keyframe = true;
+                        }
+                        Err(error) => {
+                            eprintln!("{error:#}");
+                            let reason = String::from("no H.264 encoder could start");
+                            inner.notify(SessionEvent::Revoked {
+                                reason: reason.clone(),
+                                code: "error",
+                            });
+                            let target = inner.clone();
+                            handle.spawn(async move {
+                                target.close(&reason, "error").await;
+                            });
+                            break;
+                        }
+                    }
+                }
                 let pass = if pending || keyframe {
-                    Pass::Motion { keyframe }
+                    Pass::Motion {
+                        keyframe,
+                        half: size.half && halves,
+                    }
                 } else if !refined && now.duration_since(still_since) >= REFINE_AFTER {
                     Pass::Refine
                 } else if refined
@@ -2206,9 +2561,9 @@ fn spawn_pipeline(
                         break;
                     };
                     match pass {
-                        Pass::Motion { keyframe } => encoder.encode(frame, keyframe),
+                        Pass::Motion { keyframe, half } => encoder.encode(frame, keyframe, half),
                         Pass::Refine => encoder.refine(frame),
-                        Pass::Keepalive => encoder.encode(frame, false),
+                        Pass::Keepalive => encoder.encode(frame, false, false),
                     }
                 };
                 let packet = match packet {
@@ -2226,22 +2581,29 @@ fn spawn_pipeline(
                         let reason = String::from("the encoder rejected a frame");
                         inner.notify(SessionEvent::Revoked {
                             reason: reason.clone(),
+                            code: "error",
                         });
                         let target = inner.clone();
                         handle.spawn(async move {
-                            target.close(&reason).await;
+                            target.close(&reason, "error").await;
                         });
                         break;
                     }
                 };
+                let took = started.elapsed();
                 if let Ok(mut m) = inner.metrics.lock() {
                     m.encoded_frames += 1;
                     m.encoded_bytes += packet.data.len() as u64;
-                    m.encode_micros += started.elapsed().as_micros() as u64;
+                    m.encode_micros += took.as_micros() as u64;
+                    m.key_frames += packet.keyframe as u64;
+                    if matches!(pass, Pass::Motion { .. }) && pending {
+                        m.queue_micros += started.duration_since(*captured).as_micros() as u64;
+                        m.motion_frames += 1;
+                    }
                     match pass {
-                        Pass::Motion { keyframe: true } => m.key_frames += 1,
+                        Pass::Motion { half: true, .. } => m.halved_frames += 1,
                         Pass::Refine => m.refined_frames += 1,
-                        Pass::Motion { keyframe: false } | Pass::Keepalive => {}
+                        Pass::Motion { half: false, .. } | Pass::Keepalive => {}
                     }
                 }
                 match pass {
@@ -2250,13 +2612,34 @@ fn spawn_pipeline(
                         keyframe = false;
                         refined = false;
                         still_since = now;
+                        let budget = rate.target as u64 * 1000 / 8 / max_fps.max(1) as u64;
+                        let large = packet.data.len() as u64 * 4 > budget;
+                        if halves {
+                            size.coded(took, large, frame_rx.waiting(), interval);
+                        }
+                    }
+                    Pass::Refine => {
+                        refined = true;
+                        size = MotionSize::default();
                     }
-                    Pass::Refine => refined = true,
                     Pass::Keepalive => {}
                 }
                 last_sent = Some(now);
+                cadence.sent(now);
+                budget.sent(now, packet.data.len(), rate.target);
+                // A new picture carries the moment it was captured, so the
+                // receiver paces playout by the desktop's clock rather than by
+                // encode time; a re-coded one (refinement, keepalive) is new
+                // content now.
+                let stamp = match pass {
+                    Pass::Motion { .. } => *captured,
+                    Pass::Refine | Pass::Keepalive => now,
+                };
+                let stamp = last_stamp.map_or(stamp, |at| stamp.max(at + Duration::from_millis(1)));
+                last_stamp = Some(stamp);
+                let sending = Instant::now();
                 if let Err(error) =
-                    handle.block_on(peer.send_frame(&packet.data, packet.keyframe, now))
+                    handle.block_on(peer.send_frame(&packet.data, packet.keyframe, stamp))
                 {
                     // The transport is gone. End the session rather than leave
                     // the desktop captured behind a picture that stopped.
@@ -2264,18 +2647,41 @@ fn spawn_pipeline(
                     let reason = String::from("the connection to the phone was lost");
                     inner.notify(SessionEvent::Revoked {
                         reason: reason.clone(),
+                        code: "transport",
                     });
                     let target = inner.clone();
                     handle.spawn(async move {
-                        target.close(&reason).await;
+                        target.close(&reason, "transport").await;
                     });
                     break;
                 }
+                if let Ok(mut m) = inner.metrics.lock() {
+                    m.send_micros += sending.elapsed().as_micros() as u64;
+                }
             }
         })
         .ok();
 }
 
+/// Replace the session's VP9 encoder with an H.264 one of the same size and
+/// rate target, on the encode thread that will drive it.
+fn start_h264(inner: &Arc<Inner>, bitrate_kbps: u32, fps: u32) -> Result<()> {
+    let mut held = lock(&inner.encoder);
+    let (width, height) = held
+        .as_ref()
+        .map(VideoEncoder::size)
+        .context("the session has no encoder")?;
+    let (backend, info) = crate::h264::open(width, height, bitrate_kbps, fps)?;
+    *held = Some(VideoEncoder::H264 {
+        backend,
+        size: (width, height),
+    });
+    if let Ok(mut m) = inner.metrics.lock() {
+        (m.codec, m.encoder) = ("h264", info.encoder);
+    }
+    Ok(())
+}
+
 /// Packetize what a consumer feeds an encoded source, building the peer on the
 /// first access unit that carries an SPS.
 ///
@@ -2338,6 +2744,7 @@ fn spawn_encoded(inner: &Arc<Inner>, mut feed: tokio_mpsc::Receiver<FedAccessUni
                         revoke(
                             &inner,
                             format!("the transport refused the encoded stream: {error:#}"),
+                            "error",
                         )
                         .await;
                         return;
@@ -2362,7 +2769,12 @@ fn spawn_encoded(inner: &Arc<Inner>, mut feed: tokio_mpsc::Receiver<FedAccessUni
                 }
                 Err(error) => {
                     eprintln!("the video track refused a fed access unit: {error:#}");
-                    revoke(&inner, String::from("the connection to the phone was lost")).await;
+                    revoke(
+                        &inner,
+                        String::from("the connection to the phone was lost"),
+                        "transport",
+                    )
+                    .await;
                     return;
                 }
             }
@@ -2376,11 +2788,12 @@ fn current_peer(inner: &Arc<Inner>) -> Option<Arc<VideoPeer>> {
 
 /// End the session with a reason the consumer can show, exactly as the encode
 /// pipeline does when its transport goes away.
-async fn revoke(inner: &Arc<Inner>, reason: String) {
+async fn revoke(inner: &Arc<Inner>, reason: String, code: &'static str) {
     inner.notify(SessionEvent::Revoked {
         reason: reason.clone(),
+        code,
     });
-    inner.close(&reason).await;
+    inner.close(&reason, code).await;
 }
 
 fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiver<PeerEvent>) {
@@ -2428,8 +2841,9 @@ fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiv
                         let reason = String::from("the connection to the phone was lost");
                         inner.notify(SessionEvent::Revoked {
                             reason: reason.clone(),
+                            code: "transport",
                         });
-                        inner.close(&reason).await;
+                        inner.close(&reason, "transport").await;
                         continue;
                     }
                     inner.notify(SessionEvent::State {
@@ -2487,10 +2901,11 @@ fn spawn_lease(inner: &Arc<Inner>, ttl: Duration) {
         let reason = String::from("the session lease expired");
         inner.notify(SessionEvent::Revoked {
             reason: reason.clone(),
+            code: "lease",
         });
         // An expiry ends the session exactly as an explicit close does; the
         // notification above is not a substitute for stopping the desktop.
-        inner.close(&reason).await;
+        inner.close(&reason, "lease").await;
     });
 }
 
@@ -2575,10 +2990,11 @@ mod tests {
                 peer_events,
                 feed,
             })),
+            local_frames: false,
         });
         spawn_peer_events(&inner, peer_events_rx);
         spawn_encoded(&inner, feed_rx);
-        inner.close("test").await;
+        inner.close("test", "closed").await;
         for _ in 0..100 {
             if Arc::strong_count(&inner) == 1 {
                 break;
@@ -2600,6 +3016,41 @@ mod tests {
         );
     }
 
+    #[test]
+    fn frames_that_jitter_around_the_cap_go_at_once_and_a_flood_stays_capped() {
+        let interval = Duration::from_millis(20);
+        let start = Instant::now();
+        let mut cadence = Cadence::new(interval, start);
+        // Captured at the cap, each a few ms early or late: none waits, so
+        // none is delayed or superseded by the next.
+        for (n, jitter) in [0i64, -6, 5, -8, 7, -3, 0, -9, 9, -5].iter().enumerate() {
+            let at = start + interval * n as u32 + Duration::from_millis(9);
+            let at = if *jitter < 0 {
+                at - Duration::from_millis(jitter.unsigned_abs())
+            } else {
+                at + Duration::from_millis(*jitter as u64)
+            };
+            assert_eq!(cadence.wait(at), Duration::ZERO, "frame {n} waited");
+            cadence.sent(at);
+        }
+
+        // A source far above the cap: one second of 1 ms frames sends at most
+        // one frame over the cap.
+        let start = start + Duration::from_secs(10);
+        let mut cadence = Cadence::new(interval, start);
+        let sent = (0..1000)
+            .map(|ms| start + Duration::from_millis(ms))
+            .filter(|&at| {
+                let go = cadence.wait(at).is_zero();
+                if go {
+                    cadence.sent(at);
+                }
+                go
+            })
+            .count();
+        assert!((50..=51).contains(&sent), "sent {sent} at a 50 fps cap");
+    }
+
     #[test]
     fn a_small_source_is_never_upscaled() {
         assert_eq!(fit(1000, 600, 1280, 800), (1000, 600));
@@ -2658,6 +3109,15 @@ mod tests {
         )
         .await
         .expect("a peer connection builds without a network");
+        test_inner_with(events, peer, 64, 64)
+    }
+
+    fn test_inner_with(
+        events: tokio_mpsc::UnboundedSender<Notice>,
+        peer: VideoPeer,
+        width: usize,
+        height: usize,
+    ) -> (Arc<Inner>, Arc<Mutex<Vec<(i16, bool)>>>) {
         // The pipeline codes nothing before the transport connects.
         peer.assume_connected();
         let recorded = Arc::new(Mutex::new(Vec::new()));
@@ -2684,7 +3144,9 @@ mod tests {
             capture_error: Arc::new(Mutex::new(None)),
             frame_changes: tokio::sync::watch::channel(0).1,
             peer: Mutex::new(Some(Arc::new(peer))),
-            encoder: Mutex::new(Some(Encoder::new(64, 64, 1000, 30, 1).expect("an encoder"))),
+            encoder: Mutex::new(Some(VideoEncoder::Vp9(
+                Encoder::new(width, height, 1000, 30, 1).expect("an encoder"),
+            ))),
             input: Mutex::new(Some(InputTarget {
                 applier: Applier::Recording(recorded.clone()),
                 held: HeldState::default(),
@@ -2702,6 +3164,7 @@ mod tests {
             pipeline: Arc::new(AtomicBool::new(true)),
             events,
             encoded: Mutex::new(None),
+            local_frames: true,
         });
         (inner, recorded)
     }
@@ -2742,11 +3205,11 @@ mod tests {
             matches!(
                 received.try_recv(),
                 Ok(Notice {
-                    event: SessionEvent::Revoked { .. },
+                    event: SessionEvent::Revoked { code: "lease", .. },
                     ..
                 })
             ),
-            "the consumer is still told why the session ended",
+            "the consumer is still told the session's authority ended",
         );
 
         let rejected = inner.metrics.lock().unwrap().input_rejected;
@@ -3020,20 +3483,24 @@ mod tests {
 
         // The encoder is 64x64; a 32x32 frame is the dimension mismatch that
         // used to be counted and dropped behind a permanently black picture.
-        frame_tx.put(I420 {
-            width: 32,
-            height: 32,
-            data: vec![128u8; 32 * 32 + 2 * 16 * 16],
-        });
+        frame_tx.put(
+            I420 {
+                width: 32,
+                height: 32,
+                data: vec![128u8; 32 * 32 + 2 * 16 * 16],
+            },
+            Instant::now(),
+        );
         tokio::time::sleep(Duration::from_millis(150)).await;
 
         let mut reason = None;
         while let Ok(event) = received.try_recv() {
             if let Notice {
-                event: SessionEvent::Revoked { reason: why },
+                event: SessionEvent::Revoked { reason: why, code },
                 ..
             } = event
             {
+                assert_eq!(code, "error", "a refused frame is a fault, not a lost path");
                 reason = Some(why);
             }
         }
@@ -3074,6 +3541,7 @@ mod tests {
             ttl: Some(Duration::from_secs(30)),
             loopback_tcp: false,
             agent_indicator: false,
+            local_frames: true,
         }
     }
 
@@ -3241,6 +3709,7 @@ mod tests {
                 ttl: None,
                 loopback_tcp: false,
                 agent_indicator: false,
+                local_frames: true,
             },
             events,
         )
@@ -3282,8 +3751,17 @@ mod tests {
         );
 
         peer_tx.send(PeerEvent::State(State::Failed)).unwrap();
+        let mut transport_lost = false;
         tokio::time::timeout(Duration::from_secs(2), async {
             while let Some(notice) = received.recv().await {
+                // A lost path is the one revocation a new session can heal.
+                transport_lost |= matches!(
+                    notice.event,
+                    SessionEvent::Revoked {
+                        code: "transport",
+                        ..
+                    }
+                );
                 if matches!(
                     notice.event,
                     SessionEvent::State {
@@ -3298,11 +3776,158 @@ mod tests {
         })
         .await
         .unwrap();
+        assert!(
+            transport_lost,
+            "a failed transport must revoke with code transport"
+        );
         assert!(inner.revoked_reason().is_some());
         assert!(!inner.pipeline.load(Ordering::SeqCst));
         assert!(inner.input.lock().unwrap().is_none());
     }
 
+    #[test]
+    fn a_standing_queue_backs_the_rate_off_to_what_the_path_delivers() {
+        let start = Instant::now();
+        let queued = |ms: u64, delivered_kbps: u32| {
+            Some(PathReport {
+                queue_delay: Duration::from_millis(ms),
+                delivered_kbps,
+            })
+        };
+        let mut rate = RateControl::new(8000);
+        // A burst's worth of queue and no loss moves nothing.
+        assert_eq!(rate.update(&[], queued(15, 3000), start), None);
+        // A standing queue on a 4 Mbps link: 85% of what got through, at once,
+        // with no loss reported at all.
+        assert_eq!(rate.update(&[], queued(80, 4000), start), Some(3400));
+        // Not again until the back-off has had time to show in the feedback.
+        assert_eq!(
+            rate.update(&[], queued(80, 3400), start + Duration::from_millis(100)),
+            None
+        );
+        assert_eq!(
+            rate.update(&[], queued(60, 3400), start + Duration::from_millis(300)),
+            Some(2890)
+        );
+        // A stream that sent little is not taken for a slow link: at most half.
+        assert_eq!(
+            rate.update(&[], queued(60, 100), start + Duration::from_millis(600)),
+            Some(1228)
+        );
+        // Clean loss reports do not raise it while the queue has not drained...
+        assert_eq!(
+            rate.update(&[0], queued(15, 1200), start + Duration::from_secs(2)),
+            None
+        );
+        // ...and do once it has.
+        assert_eq!(
+            rate.update(&[0], queued(2, 1200), start + Duration::from_secs(3)),
+            Some(1390)
+        );
+        // Nothing drops below the floor.
+        let mut rate = RateControl::new(8000);
+        for step in 0..20u64 {
+            rate.update(
+                &[],
+                queued(200, 1),
+                start + DELAY_BACKOFF_EVERY * step as u32,
+            );
+        }
+        assert_eq!(rate.target, 1000);
+    }
+
+    #[test]
+    fn without_transport_feedback_the_rate_follows_loss_alone() {
+        let start = Instant::now();
+        let mut rate = RateControl::new(8000);
+        assert_eq!(rate.update(&[], None, start), None);
+        assert_eq!(rate.update(&[64], None, start), Some(5600));
+        assert_eq!(
+            rate.update(&[64], None, start + Duration::from_millis(500)),
+            None
+        );
+        assert_eq!(
+            rate.update(&[10], None, start + Duration::from_secs(1)),
+            None
+        );
+        assert_eq!(
+            rate.update(&[0], None, start + Duration::from_secs(2)),
+            Some(6112)
+        );
+    }
+
+    #[test]
+    fn a_large_frame_holds_the_next_until_the_link_has_carried_it() {
+        let start = Instant::now();
+        let mut budget = SendBudget::default();
+        // Frames at the target, one per 20 ms at 4000 kbps, never wait, and
+        // neither does the ordinary overshoot of a frame at twice the budget.
+        for n in 0..50u32 {
+            let at = start + Duration::from_millis(20) * n;
+            assert_eq!(budget.wait(at, 4000), Duration::ZERO, "frame {n} waited");
+            budget.sent(at, if n % 5 == 0 { 20_000 } else { 10_000 }, 4000);
+        }
+        // A 100 kB key frame drains in 160 ms (4000 kbps and a quarter): it
+        // goes at once, and the next waits out all of it past the 60 ms burst
+        // allowance.
+        let at = start + Duration::from_secs(1);
+        assert_eq!(budget.wait(at, 4000), Duration::ZERO);
+        budget.sent(at, 100_000, 4000);
+        let wait = budget.wait(at, 4000);
+        assert!(
+            (Duration::from_millis(99)..=Duration::from_millis(101)).contains(&wait),
+            "waited {wait:?}"
+        );
+        assert_eq!(budget.wait(at + wait, 4000), Duration::ZERO);
+    }
+
+    #[test]
+    fn motion_halves_only_when_the_encoder_sets_the_pace_and_does_not_flap() {
+        let interval = Duration::from_millis(16);
+        let (slow, fast) = (Duration::from_millis(30), Duration::from_millis(2));
+        let mut size = MotionSize::default();
+        for _ in 0..MotionSize::SLOW_RUN * 4 {
+            size.coded(slow, false, true, interval);
+        }
+        assert!(
+            !size.half,
+            "slow small frames (typing on a busy host) keep full size"
+        );
+        for _ in 0..MotionSize::SLOW_RUN * 4 {
+            size.coded(slow, true, false, interval);
+        }
+        assert!(
+            !size.half,
+            "a source slower than the cap (30 fps, 30 ms encode) never halves"
+        );
+        for _ in 0..MotionSize::SLOW_RUN - 1 {
+            size.coded(slow, true, true, interval);
+        }
+        size.coded(fast, true, true, interval);
+        assert!(!size.half, "a broken run of slow frames keeps full size");
+        for _ in 0..MotionSize::SLOW_RUN {
+            size.coded(slow, true, true, interval);
+        }
+        assert!(size.half, "a run of slow large frames halves");
+        // The marginal band: half-size frames that are small but still slow,
+        // between large ones. Neither may send it back to full size.
+        for i in 0..MotionSize::SMALL_RUN * 10 {
+            size.coded(slow, i % 7 == 0, true, interval);
+            assert!(size.half, "marginal half-size motion must not flap back");
+        }
+        for _ in 0..MotionSize::SMALL_RUN * 2 {
+            size.coded(fast, true, true, interval);
+        }
+        assert!(size.half, "large half-size frames stay half, however fast");
+        for _ in 0..MotionSize::SMALL_RUN {
+            size.coded(fast, false, true, interval);
+        }
+        assert!(
+            !size.half,
+            "a run of small, fast half-size frames returns to full size"
+        );
+    }
+
     #[tokio::test]
     async fn the_pipeline_caps_the_rate_codes_the_last_frame_and_refines_a_still_desktop_once() {
         let (events, _events_rx) = tokio_mpsc::unbounded_channel();
@@ -3319,11 +3944,14 @@ mod tests {
 
         // 40 frames over 200 ms is 200 fps; the requested 20 fps caps what leaves.
         for _ in 0..40 {
-            frame_tx.put(I420 {
-                width: 64,
-                height: 64,
-                data: vec![128u8; 64 * 64 + 2 * 32 * 32],
-            });
+            frame_tx.put(
+                I420 {
+                    width: 64,
+                    height: 64,
+                    data: vec![128u8; 64 * 64 + 2 * 32 * 32],
+                },
+                Instant::now(),
+            );
             tokio::time::sleep(Duration::from_millis(5)).await;
         }
         let motion = inner.metrics.lock().unwrap().encoded_frames;
@@ -3362,5 +3990,74 @@ mod tests {
             "a still stream still sends"
         );
         assert_eq!((later.key_frames, later.refined_frames), (1, 1));
+        assert_eq!((later.codec, later.encoder), ("vp9", "libvpx"));
+    }
+
+    #[tokio::test]
+    async fn a_receiver_that_asks_for_h264_is_sent_h264_from_the_first_frame() {
+        let Some(info) = tokio::task::spawn_blocking(crate::h264::probe)
+            .await
+            .unwrap()
+        else {
+            eprintln!("skipped: no H.264 encoder starts on this machine");
+            return;
+        };
+        let (peer, _answer) =
+            crate::peer::tests::answered(vec![crate::peer::tests::h264_receiver_codec()]).await;
+        let (events, _events_rx) = tokio_mpsc::unbounded_channel();
+        let (inner, _recorded) = test_inner_with(events, peer, 320, 240);
+        // The answer is real, so ICE runs and, with no candidates, never
+        // connects; each state it reports would take back `assume_connected`.
+        let pinned = current_peer(&inner).expect("the test's peer");
+        let pin = tokio::spawn(async move {
+            loop {
+                pinned.assume_connected();
+                tokio::time::sleep(Duration::from_millis(5)).await;
+            }
+        });
+        let (frame_tx, frame_rx) = latest_frame();
+        spawn_pipeline(
+            &inner,
+            current_peer(&inner).expect("the test's peer"),
+            frame_rx,
+            Arc::new(AtomicBool::new(true)),
+            20,
+            1000,
+        );
+        for shade in 0..10u8 {
+            frame_tx.put(
+                I420 {
+                    width: 320,
+                    height: 240,
+                    data: vec![shade * 20; 320 * 240 * 3 / 2],
+                },
+                Instant::now(),
+            );
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+        // Opening a hardware session can take a good part of a second, more
+        // with other tests holding the GPU: wait for the still to be refined.
+        let deadline = Instant::now() + Duration::from_secs(10);
+        while inner.metrics.lock().unwrap().refined_frames == 0 && Instant::now() < deadline {
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+        let metrics = inner.metrics.lock().unwrap().clone();
+        assert_eq!((metrics.codec, metrics.encoder), ("h264", info.encoder));
+        assert!(metrics.encoded_frames >= 2, "{metrics:?}");
+        assert_eq!(
+            metrics.key_frames, 1,
+            "one IDR, then inter frames: {metrics:?}"
+        );
+        assert_eq!(metrics.refined_frames, 1, "a still desktop is refined once");
+        assert_eq!(
+            metrics.halved_frames, 0,
+            "H.264 is always coded at full size"
+        );
+        pin.abort();
+        inner.close("done", "closed").await;
+        assert!(
+            lock(&inner.encoder).is_none(),
+            "closing releases the encoder"
+        );
     }
 }