chore(deps): address cargo audit findings

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

.cargo/audit.toml

@@ -0,0 +1,14 @@
+# quick-xml is pulled in only through wayland-scanner's build-time Wayland XML
+# code generation path:
+#
+#   wayland-scanner v0.31.10 -> quick-xml v0.39.x
+#
+# The current wayland-scanner release requires quick-xml ^0.39, so it cannot
+# accept the fixed quick-xml >=0.41.0 line yet. This project does not parse
+# attacker-controlled XML at runtime through quick-xml. Remove these ignores as
+# soon as wayland-scanner or the wayland-* crates release a compatible fix.
+[advisories]
+ignore = [
+  "RUSTSEC-2026-0194",
+  "RUSTSEC-2026-0195",
+]

.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+# Continuous integration for wl-webrtc.
+#
+# Triggered on push/PR to master. Runs the full quality gate that the recent
+# audit baselined:
+#   - clippy: 0 errors (undocumented_unsafe_blocks is deny in Cargo.toml; other
+#     warnings are advisory for now).
+#   - build --release: integration tests in tests/integration_test.rs shell out
+#     to target/release/wl-webrtc, so the release binary must exist before tests
+#     run.
+#   - test --release: 79 unit + 3 integration; the 1 hardware-ignored test
+#     stays ignored in CI (needs Wayland session + VAAPI GPU).
+#   - cargo audit: separate job so a RUSTSEC advisory fails the build without
+#     conflating with compile errors.
+#
+# The job pins Linux only — the project is Wayland/VAAPI-specific and has no
+# macOS/Windows story. Oracle audit 2026-06-28 P2 plan.
+
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-test:
+    name: Build + Clippy + Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain (stable)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          # NOTE: do NOT use --no-install-recommends for libclang-dev — on
+          # Debian Bookworm (the node:20-bookworm image used by act_runner
+          # under ubuntu-latest) the recommended toolchain bits are needed
+          # by bindgen. The pkg-config based deps (pipewire/wayland/etc)
+          # are also more reliable without the flag.
+          sudo apt-get install -y \
+            ffmpeg \
+            libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libva-dev \
+            libwayland-dev wayland-protocols \
+            libdrm-dev \
+            libpipewire-0.3-dev \
+            libclang-dev clang
+
+      - name: Resolve LIBCLANG_PATH
+        # bindgen needs libclang on the LD path. The actual install location
+        # varies by Debian/Ubuntu version (llvm-14, llvm-15, ...), so we
+        # discover it dynamically instead of hardcoding /usr/lib/llvm-14/lib.
+        # Writing to $GITHUB_ENV propagates the value to subsequent steps
+        # inside the act_runner Docker container; the workflow-level `env:`
+        # block is not reliably visible there.
+        #
+        # Find pattern note: Debian Bookworm installs the runtime library as
+        # `libclang-14.so.1` (versioned, no plain libclang.so.* symlink),
+        # so a strict 'libclang.so.*' pattern returns nothing. The broader
+        # 'libclang*.so*' matches every bindgen-compatible filename variant:
+        # libclang.so, libclang-14.so, libclang.so.1, libclang-14.so.1.
+        run: |
+          set -e
+          LIBCL=$(find /usr -name 'libclang*.so*' 2>/dev/null | head -1)
+          test -n "$LIBCL" || { echo "ERROR: no libclang shared lib found under /usr"; exit 1; }
+          LIBDIR=$(dirname "$LIBCL")
+          echo "Resolved LIBCLANG_PATH=$LIBDIR (found $LIBCL)"
+          echo "LIBCLANG_PATH=$LIBDIR" >> "$GITHUB_ENV"
+
+      - name: Cache cargo registry + build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock', 'Cargo.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Clippy (release, all targets)
+        run: cargo clippy --release --all-targets
+
+      - name: Build release (required before tests)
+        run: cargo build --release --all-targets
+
+      - name: Test (release)
+        run: cargo test --release
+
+  audit:
+    name: Security audit (RUSTSEC)
+    runs-on: ubuntu-latest
+    # Keep separate from build-test so a vulnerability advisory fails the
+    # check independently of compile state.
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain (stable)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install cargo-audit
+        run: cargo install cargo-audit --locked
+
+      - name: Audit dependencies
+        run: cargo audit --deny warnings

.gitignore

@@ -21,3 +21,6 @@ Thumbs.db
 .playwright-mcp/
 wl-webrtc.log
 webrtc-p0-success.png
+
+# Stray review-tool output (regenerated per review run)
+review.json

Cargo.lock

@@ -94,9 +94,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
 
 [[package]]
 name = "arrayvec"

Cargo.toml

@@ -2,6 +2,12 @@
 name = "wl-webrtc"
 version = "0.1.0"
 edition = "2021"
+# MSRV pinned to 1.87 to match the actual API floor — the codebase uses
+# u32::is_multiple_of (1.87) and Option::is_none_or (1.82) introduced by
+# clippy autofixes. README's Prerequisites section mirrors this. Bumping
+# this floor requires checking clippy::incompatible_msrv against the new
+# value.
+rust-version = "1.87"
 description = "Wayland screen capture and encoding tool"
 
 [dependencies]
@@ -33,4 +39,4 @@ dirs = "6"
 tempfile = "3.27.0"
 
 [lints.clippy]
-undocumented_unsafe_blocks = "warn"
+undocumented_unsafe_blocks = "deny"

README.md

@@ -4,7 +4,7 @@ Wayland screen capture and encoding tool.
 
 ## Prerequisites
 
-- **Rust toolchain** (1.70+): `rustup default stable`
+- **Rust toolchain** (1.87+; MSRV pinned to match `u32::is_multiple_of` / `Option::is_none_or` usage): `rustup default stable`
 - **FFmpeg 6.0+** dev libraries with VAAPI support:
   - Arch: `pacman -S ffmpeg`
   - Ubuntu/Debian: `apt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libva-dev`
@@ -38,19 +38,46 @@ wl-webrtc --output output.mp4 --drm-device /dev/dri/renderD128
 
 # Verbose mode
 wl-webrtc --output output.mp4 -v
+
+# WebRTC streaming mode (HTTP signaling server)
+wl-webrtc --port 8080 -v
+
+# Force a fresh portal authorization dialog (ignore saved restore token)
+wl-webrtc --output output.mp4 --no-persist
+
+# Pin the capture backend instead of auto-detecting
+wl-webrtc --output output.mp4 --backend portal    # or: --backend screencopy
 ```
 
 ## CLI Arguments
 
+> `src/args.rs` is the authoritative source. Run `wl-webrtc --help` for the live list.
+
 | Argument | Default | Description |
 |---|---|---|
-| `-o`, `--output` | (required) | Output file path (e.g., output.mp4) |
+| `-o`, `--output` | (optional) | Output file path (e.g. output.mp4). Optional when using `--port` for WebRTC mode. |
 | `--output-name` | auto | Wayland output name to capture |
 | `--fps` | 30 | Target frames per second |
 | `--codec` | h264 | Video codec (h264 only for MVP) |
 | `--hw-accel` | vaapi | Hardware acceleration method |
 | `--drm-device` | auto | DRM render device path |
 | `--bitrate` | auto | Target bitrate in bps |
+| `--max-bitrate` | 8000000 | Max bitrate cap for WebRTC mode (caps BWE escalation; no effect in MP4 mode) |
 | `--gop-size` | auto | Group of Pictures size |
 | `-v`, `--verbose` | false | Enable verbose logging |
-| `--port` | 0 | WebTransport server port (unused in MVP) |
+| `--backend` | auto | Capture backend: `screencopy` (wlroots) or `portal` (KWin/KDE). Auto-detected if omitted. |
+| `--port` | 0 | WebRTC HTTP signaling server port. `0` keeps MP4 file output mode. |
+| `--no-persist` | false | Force re-authorization (ignore saved portal restore token) |
+| `--stats` | false | Print per-second pipeline statistics for stutter diagnosis |
+
+## Capture backends
+
+The tool supports two Wayland capture backends, auto-detected by default:
+
+- **wlr-screencopy** (preferred when `zwlr_screencopy_manager_v1` is advertised):
+  works on wlroots-based compositors (Sway, Hyprland, etc.).
+- **XDG Portal / PipeWire** (fallback when D-Bus ScreenCast is available):
+  works on KWin/KDE and any compositor that implements the XDG Desktop Portal
+  screen-cast protocol. The first run shows an authorization dialog; a restore
+  token is cached under `wl-webrtc/portal-restore-token` so subsequent runs
+  don't re-prompt (use `--no-persist` to force a fresh authorization).

src/avhw/device.rs

@@ -0,0 +1,128 @@
+use std::ffi::CString;
+use std::path::Path;
+use std::ptr;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use super::util::ff_err;
+
+pub struct AvHwDevCtx {
+    ptr: *mut ffi::AVBufferRef,
+}
+
+// SAFETY: AvHwDevCtx wraps an FFmpeg AVBufferRef which is not Send by default,
+// but we guarantee exclusive access through &mut self. The underlying VAAPI
+// device context is thread-safe for the operations we perform.
+unsafe impl Send for AvHwDevCtx {}
+
+impl AvHwDevCtx {
+    pub fn new_vaapi(drm_device: &Path) -> Result<Self> {
+        let device_cstr = CString::new(drm_device.to_str().unwrap())?;
+        let mut p: *mut ffi::AVBufferRef = ptr::null_mut();
+        // SAFETY: device_cstr is a valid C string for the duration of the call;
+        // p is a valid out-pointer that FFmpeg initializes on success.
+        let ret = unsafe {
+            ffi::av_hwdevice_ctx_create(
+                &mut p,
+                ffi::AVHWDeviceType::AV_HWDEVICE_TYPE_VAAPI,
+                device_cstr.as_ptr(),
+                ptr::null_mut(),
+                0,
+            )
+        };
+        if ret < 0 {
+            bail!(
+                "Failed to create VAAPI device context from {}: {}",
+                drm_device.display(),
+                ff_err(ret)
+            );
+        }
+        Ok(Self { ptr: p })
+    }
+
+    pub fn as_ptr(&self) -> *mut ffi::AVBufferRef {
+        self.ptr
+    }
+
+    pub fn ref_clone(&self) -> *mut ffi::AVBufferRef {
+        // SAFETY: av_buffer_ref atomically increments refcount and returns a new ref.
+        unsafe { ffi::av_buffer_ref(self.ptr) }
+    }
+}
+
+impl Drop for AvHwDevCtx {
+    fn drop(&mut self) {
+        if !self.ptr.is_null() {
+            // SAFETY: av_buffer_unref decrements refcount; frees the buffer when it hits zero.
+            unsafe { ffi::av_buffer_unref(&mut self.ptr) };
+        }
+    }
+}
+
+pub struct AvHwFrameCtx {
+    ptr: *mut ffi::AVBufferRef,
+}
+
+// SAFETY: AvHwFrameCtx wraps an FFmpeg AVBufferRef to an AVHWFramesContext.
+// It is only accessed through &mut self, ensuring no concurrent mutation.
+// The underlying hardware frames pool is thread-safe for the send/receive pattern.
+unsafe impl Send for AvHwFrameCtx {}
+
+impl AvHwFrameCtx {
+    fn new_inner(hw_dev: &AvHwDevCtx, w: u32, h: u32, sw_fmt: ff::format::Pixel) -> Result<Self> {
+        // SAFETY: hw_dev is a live AVHWDeviceContext; FFmpeg returns either a valid
+        // frames context ref or null (checked below).
+        let mut p = unsafe { ffi::av_hwframe_ctx_alloc(hw_dev.as_ptr()) };
+        if p.is_null() {
+            bail!("av_hwframe_ctx_alloc returned null");
+        }
+        // SAFETY: p is a valid AVBufferRef from av_hwframe_ctx_alloc.
+        // Its .data field points to an AVHWFramesContext that we must configure.
+        unsafe {
+            let fc = (*p).data as *mut ffi::AVHWFramesContext;
+            (*fc).format = ff::format::Pixel::VAAPI.into();
+            (*fc).sw_format = sw_fmt.into();
+            (*fc).width = w as i32;
+            (*fc).height = h as i32;
+            (*fc).initial_pool_size = 4;
+        }
+        // SAFETY: p is a valid AVHWFramesContext ref configured above and not yet
+        // transferred or freed.
+        let ret = unsafe { ffi::av_hwframe_ctx_init(p) };
+        if ret < 0 {
+            // SAFETY: p is valid but init failed; clean up.
+            unsafe { ffi::av_buffer_unref(&mut p) };
+            bail!("av_hwframe_ctx_init failed: {}", ff_err(ret));
+        }
+        Ok(Self { ptr: p })
+    }
+
+    pub fn for_capture(
+        hw_dev: &AvHwDevCtx,
+        w: u32,
+        h: u32,
+        sw_fmt: ff::format::Pixel,
+    ) -> Result<Self> {
+        Self::new_inner(hw_dev, w, h, sw_fmt)
+    }
+
+    pub fn as_ptr(&self) -> *mut ffi::AVBufferRef {
+        self.ptr
+    }
+
+    pub fn ref_clone(&self) -> *mut ffi::AVBufferRef {
+        // SAFETY: av_buffer_ref atomically increments refcount and returns a new ref.
+        unsafe { ffi::av_buffer_ref(self.ptr) }
+    }
+}
+
+impl Drop for AvHwFrameCtx {
+    fn drop(&mut self) {
+        if !self.ptr.is_null() {
+            // SAFETY: av_buffer_unref decrements refcount; frees when zero.
+            unsafe { ffi::av_buffer_unref(&mut self.ptr) };
+        }
+    }
+}

src/avhw/dmabuf.rs

@@ -0,0 +1,125 @@
+use std::mem;
+// AsRawFd is required by `frame.fd.as_raw_fd()` below but rustc emits a false
+// "unused_imports" warning because OwnedFd also has an inherent `as_raw_fd`.
+// E0599 if removed -> must stay; warning is a known rustc quirk.
+use std::os::fd::AsRawFd;
+use std::os::raw::c_void;
+use std::path::Path;
+use std::ptr;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use crate::cap_portal::PwDmaBufFrame;
+
+use super::{ff_err, AvHwDevCtx, AvHwFrameCtx};
+
+/// Test whether `drm_device` can import the PipeWire DMA-BUF frame via VAAPI.
+pub fn test_dma_buf_import(drm_device: &Path, frame: &PwDmaBufFrame) -> Result<()> {
+    let hw_dev = AvHwDevCtx::new_vaapi(drm_device)?;
+    let frames =
+        AvHwFrameCtx::for_capture(&hw_dev, frame.width, frame.height, ff::format::Pixel::BGRA)?;
+
+    // SAFETY: frames is a live VAAPI frames context; frame carries valid DMA-BUF metadata.
+    unsafe { import_dma_buf_to_vaapi(frames.as_ptr(), frame) }?;
+
+    Ok(())
+}
+
+/// Import a DMA-BUF into a VAAPI hardware frame via zero-copy `av_hwframe_map`.
+///
+/// # Safety
+/// Imports a DMA-BUF frame into a VAAPI hardware frame pool for GPU-side processing.
+///
+/// Takes the negotiated format/geometry from `frame` (a `PwDmaBufFrame` from
+/// PipeWire capture) plus the target `frames_ctx` (VAAPI frame pool from
+/// `AvHwFrameCtx`) and returns an `ff::frame::Video` whose data[3] points to
+/// the hardware frame.
+///
+/// # Safety
+///
+/// - `frames_ctx` must point to an initialized AVHWCramesContext for VAAPI
+/// - `frame.fd` must be a valid DMA-BUF file descriptor
+pub unsafe fn import_dma_buf_to_vaapi(
+    frames_ctx: *mut ffi::AVBufferRef,
+    frame: &PwDmaBufFrame,
+) -> Result<ff::frame::Video> {
+    let duped_fd = libc::dup(frame.fd.as_raw_fd());
+    if duped_fd < 0 {
+        bail!("dup(fd) failed: {}", std::io::Error::last_os_error());
+    }
+
+    let mut desc: ffi::AVDRMFrameDescriptor = mem::zeroed();
+    desc.nb_objects = 1;
+    desc.objects[0].fd = duped_fd;
+    desc.objects[0].size = (frame.height as usize) * (frame.stride as usize);
+    desc.objects[0].format_modifier = frame.modifier;
+    desc.nb_layers = 1;
+    desc.layers[0].format = frame.format;
+    desc.layers[0].nb_planes = 1;
+    desc.layers[0].planes[0].object_index = 0;
+    desc.layers[0].planes[0].offset = frame.offset as isize;
+    desc.layers[0].planes[0].pitch = frame.stride as isize;
+
+    let desc_box = Box::new(desc);
+    let desc_ptr = Box::into_raw(desc_box);
+
+    let buf_ref = ffi::av_buffer_create(
+        desc_ptr as *mut u8,
+        std::mem::size_of::<ffi::AVDRMFrameDescriptor>(),
+        Some(cleanup_drm_descriptor),
+        ptr::null_mut(),
+        0,
+    );
+    if buf_ref.is_null() {
+        let desc_box = Box::from_raw(desc_ptr);
+        libc::close(desc_box.objects[0].fd);
+        bail!("av_buffer_create returned null for DRM descriptor");
+    }
+
+    let mut src = ff::frame::Video::empty();
+    {
+        let sp = src.as_mut_ptr();
+        (*sp).format = ffi::AVPixelFormat::AV_PIX_FMT_DRM_PRIME as i32;
+        (*sp).width = frame.width as i32;
+        (*sp).height = frame.height as i32;
+        (*sp).data[0] = (*buf_ref).data;
+        (*sp).buf[0] = buf_ref;
+    }
+
+    let mut dst = ff::frame::Video::empty();
+    // SAFETY: frames_ctx is guaranteed by this unsafe function's contract to be a
+    // valid initialized VAAPI frames context; we set format/hw_frames_ctx on a
+    // freshly allocated dst frame.
+    unsafe {
+        let dp = dst.as_mut_ptr();
+        (*dp).format = ffi::AVPixelFormat::AV_PIX_FMT_VAAPI as i32;
+        (*dp).hw_frames_ctx = ffi::av_buffer_ref(frames_ctx);
+        if (*dp).hw_frames_ctx.is_null() {
+            bail!("av_buffer_ref(frames_ctx) returned null");
+        }
+    }
+    // SAFETY: src and dst are initialized AVFrames; dst has a valid hw_frames_ctx
+    // ref and av_hwframe_map fills dst from src.
+    let ret = unsafe {
+        ffi::av_hwframe_map(
+            dst.as_mut_ptr(),
+            src.as_ptr(),
+            ffi::AV_HWFRAME_MAP_READ as i32,
+        )
+    };
+    if ret < 0 {
+        bail!("av_hwframe_map failed: {}", ff_err(ret));
+    }
+
+    Ok(dst)
+}
+
+unsafe extern "C" fn cleanup_drm_descriptor(_opaque: *mut c_void, data: *mut u8) {
+    let desc = data as *mut ffi::AVDRMFrameDescriptor;
+    if !desc.is_null() && (*desc).nb_objects > 0 && (*desc).objects[0].fd >= 0 {
+        libc::close((*desc).objects[0].fd);
+    }
+    let _ = Box::from_raw(data as *mut ffi::AVDRMFrameDescriptor);
+}

src/avhw/encode.rs

@@ -0,0 +1,302 @@
+use std::mem;
+use std::ptr;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+use ffmpeg_next::packet::Mut as _;
+
+use super::encode_output::{self, FrameOutput, PacketOutput};
+use super::hash::hash_sampled_y_plane;
+use super::{
+    ff_err, BitrateCommand, CpuNv12Frame, EncodeOutcome, ResolutionChange, SwEncodeTiming,
+};
+
+pub struct SwEncEncode {
+    pub(super) sws_ctx: *mut ffi::SwsContext,
+    pub(super) enc_video: ff::codec::encoder::video::Video,
+    pub(super) output: Option<FrameOutput>,
+    pub(super) yuv_frame: *mut ffi::AVFrame,
+    pub(super) last_frame_hash: u64,
+    pub(super) frame_count: u64,
+    pub(super) starting_timestamp: Option<i64>,
+    pub(super) frames_written: bool,
+    pub(super) webrtc_disconnected: bool,
+    pub(super) webrtc_paused: Option<Arc<AtomicBool>>,
+    pub(super) bitrate_rx: crossbeam_channel::Receiver<BitrateCommand>,
+    pub(super) resolution_rx: crossbeam_channel::Receiver<ResolutionChange>,
+    pub(super) enc_width: u32,
+    pub(super) enc_height: u32,
+    pub(super) fps: u32,
+    pub(super) bitrate: u64,
+    pub(super) gop_size: u32,
+    /// Set true when WebRTC requests a keyframe. Forces the next frame to
+    /// `AV_PICTURE_TYPE_I` and bypasses the dedup hash check. Cleared only
+    /// after `avcodec_send_frame` accepts the forced frame.
+    pub(super) force_keyframe_pending: bool,
+    /// Last per-frame timing snapshot. Reset to `Default` at the start of
+    /// every `encode_cpu_frame` call (even on early returns) so stale values
+    /// from a previous frame can never leak out.
+    pub(super) last_timing: SwEncodeTiming,
+    /// Capture time of the frame currently being encoded. Saved from the
+    /// input `CpuNv12Frame` so `drain_encoder` can propagate it into the
+    /// emitted `EncodedH264Frame` for the frame_age stat (issue #20).
+    pub(super) last_capture_time: Option<Instant>,
+}
+
+/// WebRTC media clock frequency in Hz. Matches RTP clock for video (RFC 3551).
+/// Used as encoder time_base denominator for WebRTC mode (1/90000) so that
+/// PTS values directly become RTP timestamps with microsecond precision.
+/// MP4 mode keeps 1/fps time_base for file output simplicity.
+pub const WEBRTC_RTP_CLOCK_HZ: i128 = 90_000;
+
+// SAFETY: SwEncEncode owns sws_ctx/yuv_frame/enc_video exclusively after construction.
+// It is moved to a single encode thread and only accessed through &mut self there.
+unsafe impl Send for SwEncEncode {}
+
+impl SwEncEncode {
+    pub fn flush(&mut self) -> Result<()> {
+        // SAFETY: Sending a null frame flushes the opened software encoder;
+        // no frame data is dereferenced. enc_video is exclusively borrowed via &mut self.
+        unsafe {
+            let ret = ffi::avcodec_send_frame(self.enc_video.as_mut_ptr(), ptr::null());
+            if ret < 0 && ret != ffi::AVERROR_EOF {
+                bail!("software encoder flush send failed: {}", ff_err(ret));
+            }
+        }
+        let start_ts = self.starting_timestamp.unwrap_or(0);
+        let _ = self.drain_encoder(start_ts)?;
+
+        Ok(())
+    }
+
+    pub fn take_timing(&mut self) -> SwEncodeTiming {
+        mem::take(&mut self.last_timing)
+    }
+
+    pub fn encode_cpu_frame(&mut self, frame: &CpuNv12Frame) -> Result<EncodeOutcome> {
+        self.last_timing = SwEncodeTiming::default();
+        // Save capture_time so drain_encoder can propagate it into the
+        // EncodedH264Frame emitted via the WebRTC channel (issue #20).
+        self.last_capture_time = Some(frame.capture_time);
+
+        if self.webrtc_disconnected {
+            return Ok(EncodeOutcome::SkippedDisconnected);
+        }
+
+        // Must drain before the stride check: the import thread emits
+        // ResolutionChange before the new (smaller-stride) frame arrives.
+        while let Ok(cmd) = self.bitrate_rx.try_recv() {
+            match cmd {
+                BitrateCommand::UpdateBitrate { target_bps } => {
+                    // #23 defensive guardrail: clamp to reasonable max even if policy layer
+                    // is bypassed. 50 Mbps is a hard ceiling; primary cap is enforced in
+                    // state_portal.rs webrtc_thread_loop via --max-bitrate flag.
+                    const ENCODER_BITRATE_HARD_CAP: u64 = 50_000_000;
+                    let target_bps = target_bps.min(ENCODER_BITRATE_HARD_CAP);
+                    tracing::info!(target_bps, "updating encoder bitrate from BWE feedback");
+                    self.bitrate = target_bps;
+                    // SAFETY: enc_video is an opened AVCodecContext exclusively owned by &mut self.
+                    unsafe {
+                        let ctx = self.enc_video.as_mut_ptr();
+                        (*ctx).bit_rate = target_bps as i64;
+                    }
+                }
+                BitrateCommand::UpdateResolution { .. } => {}
+                BitrateCommand::ForceKeyframe => {
+                    self.force_keyframe_pending = true;
+                    tracing::debug!("encode thread: ForceKeyframe requested");
+                }
+            }
+        }
+
+        let force_this_frame = self.force_keyframe_pending;
+
+        while let Ok(change) = self.resolution_rx.try_recv() {
+            self.recreate_encoder(change.width, change.height)?;
+        }
+
+        if frame.y_stride < self.enc_width as usize || frame.uv_stride < self.enc_width as usize {
+            bail!("CPU NV12 frame stride is smaller than encoder width");
+        }
+        if let Some(ref paused) = self.webrtc_paused {
+            if paused.load(Ordering::Relaxed) {
+                return Ok(EncodeOutcome::SkippedPaused);
+            }
+        }
+
+        let width = self.enc_width as usize;
+        let height = self.enc_height as usize;
+        let required_y_len = frame.y_stride * height.saturating_sub(1) + width;
+        if frame.y_data.len() < required_y_len {
+            bail!("CPU NV12 frame Y plane is smaller than encoder dimensions");
+        }
+
+        let frame_index = self.frame_count;
+        self.frame_count = self.frame_count.saturating_add(1);
+        let current_hash = hash_sampled_y_plane(&frame.y_data, width, height, frame.y_stride);
+        let force_gop_frame =
+            self.gop_size > 0 && frame_index.is_multiple_of(u64::from(self.gop_size));
+        if frame_index > 0
+            && !force_gop_frame
+            && !force_this_frame
+            && current_hash == self.last_frame_hash
+        {
+            tracing::debug!(frame_index, "skipping duplicate frame");
+            self.last_frame_hash = current_hash;
+            return Ok(EncodeOutcome::SkippedDuplicate);
+        }
+        self.last_frame_hash = current_hash;
+
+        let sws_start = Instant::now();
+        // SAFETY: yuv_frame is an owned reusable YUV420P frame at the same dimensions as sw_nv12;
+        // sws_ctx was created for NV12 -> YUV420P with no resize, so sws_scale only converts format.
+        unsafe {
+            let ret = ffi::av_frame_make_writable(self.yuv_frame);
+            if ret < 0 {
+                bail!("av_frame_make_writable failed: {}", ff_err(ret));
+            }
+            let src_slices = [
+                frame.y_data.as_ptr(),
+                frame.uv_data.as_ptr(),
+                ptr::null(),
+                ptr::null(),
+            ];
+            let src_strides = [frame.y_stride as i32, frame.uv_stride as i32, 0, 0];
+            let scaled = ffi::sws_scale(
+                self.sws_ctx,
+                src_slices.as_ptr(),
+                src_strides.as_ptr(),
+                0,
+                self.enc_height as i32,
+                (*self.yuv_frame).data.as_ptr() as *mut *mut u8,
+                (*self.yuv_frame).linesize.as_ptr() as *const i32,
+            );
+            if scaled < 0 {
+                bail!("sws_scale failed for software encoder: {scaled}");
+            }
+        }
+        let sws_us = sws_start.elapsed().as_micros() as u64;
+
+        let pts = frame.pts;
+        if self.starting_timestamp.is_none() {
+            self.starting_timestamp = Some(pts);
+        }
+        let start_ts = self.starting_timestamp.unwrap_or(0);
+
+        let enc_start = Instant::now();
+        // SAFETY: yuv_frame is initialized, writable, and matches the opened encoder format.
+        // pict_type is reset every frame: the AVFrame is reused, so without resetting to NONE
+        // a previously-forced I-type would leak into subsequent P-frames. With forced-idr=1
+        // set on the encoder, AV_PICTURE_TYPE_I produces a true IDR NALU.
+        unsafe {
+            (*self.yuv_frame).pts = pts;
+            (*self.yuv_frame).pict_type = if force_this_frame {
+                ffi::AVPictureType::AV_PICTURE_TYPE_I
+            } else {
+                ffi::AVPictureType::AV_PICTURE_TYPE_NONE
+            };
+            let ret = ffi::avcodec_send_frame(self.enc_video.as_mut_ptr(), self.yuv_frame);
+            if ret < 0 {
+                bail!(
+                    "avcodec_send_frame failed for software encoder: {}",
+                    ff_err(ret)
+                );
+            }
+        }
+
+        if force_this_frame {
+            self.force_keyframe_pending = false;
+        }
+
+        let output_bytes = self.drain_encoder(start_ts)?;
+        let encode_us = enc_start.elapsed().as_micros() as u64;
+
+        self.last_timing = SwEncodeTiming {
+            sws_us,
+            encode_us,
+            output_bytes,
+        };
+
+        Ok(EncodeOutcome::Encoded)
+    }
+
+    pub(super) fn write_trailer_if_needed(&mut self) -> Result<()> {
+        if self.frames_written {
+            if let Some(FrameOutput::Muxer(ref mut octx)) = self.output {
+                octx.write_trailer()
+                    .map_err(|e| anyhow::anyhow!("Failed to write trailer: {e}"))?;
+            }
+        }
+        Ok(())
+    }
+
+    fn drain_encoder(&mut self, start_ts: i64) -> Result<usize> {
+        let mut total_bytes = 0usize;
+        loop {
+            let mut pkt = ff::Packet::empty();
+            // SAFETY: enc_video is an open encoder; pkt is writable packet storage.
+            let ret = unsafe {
+                ffi::avcodec_receive_packet(self.enc_video.as_mut_ptr(), pkt.as_mut_ptr())
+            };
+            if ret < 0 {
+                if ret == ffi::AVERROR(ffi::EAGAIN) || ret == ffi::AVERROR_EOF {
+                    break;
+                }
+                bail!("avcodec_receive_packet failed: {}", ff_err(ret));
+            }
+
+            // Count encoded bytes produced before the Muxer/Channel match to
+            // avoid branch duplication and handle multi-packet drain correctly.
+            // SAFETY: pkt was just filled by a successful avcodec_receive_packet;
+            // the size field is valid and initialized.
+            let pkt_size = unsafe { (*pkt.as_mut_ptr()).size };
+            if pkt_size > 0 {
+                total_bytes += pkt_size as usize;
+            }
+
+            match self.output {
+                Some(FrameOutput::Muxer(ref mut octx)) => {
+                    encode_output::write_muxer_packet(
+                        &mut pkt,
+                        octx,
+                        self.enc_video.time_base(),
+                        start_ts,
+                    )?;
+                    self.frames_written = true;
+                }
+                Some(FrameOutput::Channel(ref tx))
+                    if encode_output::send_channel_packet(
+                        &mut pkt,
+                        tx,
+                        start_ts,
+                        self.last_capture_time.unwrap_or_else(Instant::now),
+                    )? == PacketOutput::Disconnected =>
+                {
+                    self.webrtc_disconnected = true;
+                    break;
+                }
+                Some(FrameOutput::Channel(_)) => {}
+                None => {}
+            }
+        }
+        Ok(total_bytes)
+    }
+}
+
+impl Drop for SwEncEncode {
+    fn drop(&mut self) {
+        if !self.sws_ctx.is_null() {
+            // SAFETY: sws_ctx is owned by this state and was returned by sws_getContext.
+            unsafe { ffi::sws_freeContext(self.sws_ctx) };
+            self.sws_ctx = ptr::null_mut();
+        }
+        if !self.yuv_frame.is_null() {
+            // SAFETY: yuv_frame is owned by this state and was allocated by av_frame_alloc.
+            unsafe { ffi::av_frame_free(&mut self.yuv_frame) };
+        }
+    }
+}

src/avhw/encode_init.rs

@@ -0,0 +1,133 @@
+use std::path::Path;
+use std::ptr;
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+
+use anyhow::Result;
+use ffmpeg_next::ffi;
+
+use super::encode_output::FrameOutput;
+use super::software::{
+    alloc_yuv420p_frame, create_nv12_to_yuv420p_sws, create_software_h264_encoder,
+    create_software_h264_muxer,
+};
+use super::{BitrateCommand, EncodedH264Frame, ResolutionChange, SwEncEncode, SwEncodeTiming};
+
+impl SwEncEncode {
+    #[allow(clippy::too_many_arguments)]
+    pub(super) fn new_muxer(
+        output_path: &Path,
+        enc_width: u32,
+        enc_height: u32,
+        fps: u32,
+        bitrate: u64,
+        gop_size: u32,
+    ) -> Result<Self> {
+        let sws_ctx = create_nv12_to_yuv420p_sws(enc_width, enc_height)?;
+        let (enc_video, octx) =
+            create_software_h264_muxer(output_path, enc_width, enc_height, fps, bitrate, gop_size)?;
+        let yuv_frame = alloc_yuv420p_frame(enc_width, enc_height)?;
+        let (dummy_tx, bitrate_rx) = crossbeam_channel::bounded(1);
+        drop(dummy_tx);
+        let (dummy_resolution_tx, resolution_rx) = crossbeam_channel::bounded(1);
+        drop(dummy_resolution_tx);
+
+        Ok(Self {
+            sws_ctx,
+            enc_video,
+            output: Some(FrameOutput::Muxer(octx)),
+            yuv_frame,
+            last_frame_hash: 0,
+            frame_count: 0,
+            starting_timestamp: None,
+            frames_written: false,
+            webrtc_disconnected: false,
+            webrtc_paused: None,
+            bitrate_rx,
+            resolution_rx,
+            enc_width,
+            enc_height,
+            fps,
+            bitrate,
+            gop_size,
+            force_keyframe_pending: false,
+            last_timing: SwEncodeTiming::default(),
+            last_capture_time: None,
+        })
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn new_webrtc(
+        enc_width: u32,
+        enc_height: u32,
+        fps: u32,
+        bitrate: u64,
+        gop_size: u32,
+        tx: crossbeam_channel::Sender<EncodedH264Frame>,
+        webrtc_paused: Arc<AtomicBool>,
+        bitrate_rx: crossbeam_channel::Receiver<BitrateCommand>,
+        resolution_rx: crossbeam_channel::Receiver<ResolutionChange>,
+    ) -> Result<Self> {
+        let sws_ctx = create_nv12_to_yuv420p_sws(enc_width, enc_height)?;
+        let enc_video =
+            create_software_h264_encoder(enc_width, enc_height, fps, bitrate, gop_size)?;
+        let yuv_frame = alloc_yuv420p_frame(enc_width, enc_height)?;
+
+        Ok(Self {
+            sws_ctx,
+            enc_video,
+            output: Some(FrameOutput::Channel(tx)),
+            yuv_frame,
+            last_frame_hash: 0,
+            frame_count: 0,
+            starting_timestamp: None,
+            frames_written: false,
+            webrtc_disconnected: false,
+            webrtc_paused: Some(webrtc_paused),
+            bitrate_rx,
+            resolution_rx,
+            enc_width,
+            enc_height,
+            fps,
+            bitrate,
+            gop_size,
+            force_keyframe_pending: false,
+            last_timing: SwEncodeTiming::default(),
+            last_capture_time: None,
+        })
+    }
+
+    pub(super) fn recreate_encoder(&mut self, width: u32, height: u32) -> Result<()> {
+        if width == self.enc_width && height == self.enc_height {
+            return Ok(());
+        }
+
+        tracing::info!(
+            from = format_args!("{}x{}", self.enc_width, self.enc_height),
+            to = format_args!("{}x{}", width, height),
+            "recreating WebRTC software encoder for resolution change"
+        );
+
+        if !self.sws_ctx.is_null() {
+            // SAFETY: sws_ctx is owned exclusively by self and will be replaced below.
+            unsafe { ffi::sws_freeContext(self.sws_ctx) };
+            self.sws_ctx = ptr::null_mut();
+        }
+        if !self.yuv_frame.is_null() {
+            // SAFETY: yuv_frame is owned exclusively by self and will be replaced below.
+            unsafe { ffi::av_frame_free(&mut self.yuv_frame) };
+        }
+
+        self.sws_ctx = create_nv12_to_yuv420p_sws(width, height)?;
+        self.enc_video =
+            create_software_h264_encoder(width, height, self.fps, self.bitrate, self.gop_size)?;
+        self.yuv_frame = alloc_yuv420p_frame(width, height)?;
+        self.enc_width = width;
+        self.enc_height = height;
+        self.last_frame_hash = 0;
+        self.frame_count = 0;
+        self.force_keyframe_pending = true;
+
+        Ok(())
+    }
+}

src/avhw/encode_output.rs

@@ -0,0 +1,99 @@
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::packet::Mut as _;
+
+use super::EncodedH264Frame;
+
+pub enum FrameOutput {
+    Muxer(ff::format::context::Output),
+    Channel(crossbeam_channel::Sender<EncodedH264Frame>),
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum PacketOutput {
+    Written,
+    Dropped,
+    Disconnected,
+}
+
+pub(super) fn write_muxer_packet(
+    pkt: &mut ff::Packet,
+    octx: &mut ff::format::context::Output,
+    enc_tb: ff::Rational,
+    start_ts: i64,
+) -> Result<()> {
+    // SAFETY: muxer output was created with stream 0 during setup; streams
+    // is non-null and stream 0 remains owned by the format context.
+    let stream_tb = unsafe {
+        let fmt = *octx.as_ptr();
+        if fmt.nb_streams == 0 || fmt.streams.is_null() {
+            bail!("no streams in output context");
+        }
+        let st = *fmt.streams.add(0);
+        ff::Rational::from((*st).time_base)
+    };
+    pkt.rescale_ts(enc_tb, stream_tb);
+
+    if let Some(pts) = pkt.pts() {
+        pkt.set_pts(Some(pts - start_ts));
+    }
+    if let Some(dts) = pkt.dts() {
+        pkt.set_dts(Some(dts - start_ts));
+    }
+
+    pkt.set_stream(0);
+    pkt.write_interleaved(octx)
+        .map_err(|e| anyhow::anyhow!("Failed to write packet: {e}"))
+}
+
+pub(super) fn send_channel_packet(
+    pkt: &mut ff::Packet,
+    tx: &crossbeam_channel::Sender<EncodedH264Frame>,
+    start_ts: i64,
+    capture_time: Instant,
+) -> Result<PacketOutput> {
+    // SAFETY: pkt is a valid AVPacket just filled by avcodec_receive_packet;
+    // this copies fields for read-only inspection before pkt is dropped.
+    let raw = unsafe { *pkt.as_mut_ptr() };
+    if raw.size <= 0 || raw.data.is_null() {
+        return Ok(PacketOutput::Dropped);
+    }
+
+    // SAFETY: `pkt` is a valid AVPacket just filled by a successful
+    // `avcodec_receive_packet` call. We checked `size > 0` and `data` is
+    // non-null, so `data` points to `size` initialized bytes owned by the
+    // packet. `u8` has alignment 1, and the slice is copied into a Vec before
+    // the packet is unreffed.
+    let data = unsafe { std::slice::from_raw_parts(raw.data, raw.size as usize) };
+    let pts_ticks = match pkt.pts() {
+        Some(p) => p - start_ts,
+        None => {
+            tracing::warn!("encoder produced packet without PTS, dropping");
+            return Ok(PacketOutput::Dropped);
+        }
+    };
+
+    match tx.try_send(EncodedH264Frame {
+        data: data.to_vec(),
+        pts_ticks,
+        capture_time,
+    }) {
+        Ok(()) => Ok(PacketOutput::Written),
+        Err(crossbeam_channel::TrySendError::Full(frame)) => {
+            tracing::warn!(
+                "WebRTC channel full, dropping frame: {} bytes lost",
+                frame.data.len()
+            );
+            Ok(PacketOutput::Dropped)
+        }
+        Err(crossbeam_channel::TrySendError::Disconnected(frame)) => {
+            tracing::warn!(
+                "WebRTC channel disconnected: {} bytes lost",
+                frame.data.len()
+            );
+            Ok(PacketOutput::Disconnected)
+        }
+    }
+}

src/avhw/filter.rs

@@ -0,0 +1,174 @@
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use crate::transform::Transform;
+
+use super::{ff_err, AvHwDevCtx, AvHwFrameCtx};
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn build_swenc_filter_graph(
+    hw_dev: &AvHwDevCtx,
+    frames_rgb: &AvHwFrameCtx,
+    width: u32,
+    height: u32,
+    enc_width: u32,
+    enc_height: u32,
+    fps: u32,
+) -> Result<ff::filter::Graph> {
+    let mut graph = ff::filter::Graph::new();
+    let buffersrc =
+        ff::filter::find("buffer").ok_or_else(|| anyhow::anyhow!("filter 'buffer' not found"))?;
+    let buffersink = ff::filter::find("buffersink")
+        .ok_or_else(|| anyhow::anyhow!("filter 'buffersink' not found"))?;
+    let scale_vaapi = ff::filter::find("scale_vaapi")
+        .ok_or_else(|| anyhow::anyhow!("filter 'scale_vaapi' not found"))?;
+
+    // FFmpeg 8.0+ rejects VAAPI pix_fmt in buffer args before hw_frames_ctx is attached.
+    // Use a SW placeholder, then override format/hw_frames_ctx with av_buffersrc_parameters_set.
+    let args = format!(
+        "video_size={}x{}:pix_fmt=bgra:time_base=1/{fps}:pixel_aspect=1/1",
+        width, height,
+    );
+    let mut src_ctx = graph.add(&buffersrc, "in", &args)?;
+
+    // SAFETY: av_buffersrc_parameters_alloc returns newly allocated parameters
+    // or null, which is checked below.
+    let par = unsafe { ffi::av_buffersrc_parameters_alloc() };
+    if par.is_null() {
+        bail!("av_buffersrc_parameters_alloc returned null");
+    }
+    // SAFETY: par and src_ctx are valid; frames_rgb.ref_clone returns an owned hw_frames_ctx ref
+    // that buffersrc consumes on successful parameter set.
+    unsafe {
+        (*par).format = Into::<ffi::AVPixelFormat>::into(ff::format::Pixel::VAAPI) as i32;
+        (*par).width = width as i32;
+        (*par).height = height as i32;
+        (*par).time_base = ffi::AVRational {
+            num: 1,
+            den: fps as i32,
+        };
+        (*par).hw_frames_ctx = frames_rgb.ref_clone();
+        let ret = ffi::av_buffersrc_parameters_set(src_ctx.as_mut_ptr(), par);
+        ffi::av_free(par as *mut _);
+        if ret < 0 {
+            bail!("av_buffersrc_parameters_set failed: {}", ff_err(ret));
+        }
+    }
+
+    let mut scale_ctx = graph.add(
+        &scale_vaapi,
+        "scale",
+        &format!("{enc_width}:{enc_height}:format=nv12"),
+    )?;
+    // SAFETY: scale_vaapi keeps a ref-counted device context while the graph is alive.
+    unsafe {
+        (*scale_ctx.as_mut_ptr()).hw_device_ctx = hw_dev.ref_clone();
+    }
+
+    let mut sink_ctx = graph.add(&buffersink, "out", "")?;
+    src_ctx.link(0, &mut scale_ctx, 0);
+    scale_ctx.link(0, &mut sink_ctx, 0);
+    graph
+        .validate()
+        .map_err(|e| anyhow::anyhow!("software GPU filter graph validation failed: {e}"))?;
+
+    Ok(graph)
+}
+
+pub(super) fn build_filter_graph(
+    hw_dev: &AvHwDevCtx,
+    frames_rgb: &AvHwFrameCtx,
+    width: u32,
+    height: u32,
+    fps: u32,
+    transform: Transform,
+) -> Result<ff::filter::Graph> {
+    let mut graph = ff::filter::Graph::new();
+
+    let buffersrc =
+        ff::filter::find("buffer").ok_or_else(|| anyhow::anyhow!("filter 'buffer' not found"))?;
+    let buffersink = ff::filter::find("buffersink")
+        .ok_or_else(|| anyhow::anyhow!("filter 'buffersink' not found"))?;
+    let scale_vaapi = ff::filter::find("scale_vaapi")
+        .ok_or_else(|| anyhow::anyhow!("filter 'scale_vaapi' not found"))?;
+
+    // buffersrc - use AVBufferSrcParameters to set hw_frames_ctx properly.
+    let args = format!(
+        "video_size={}x{}:pix_fmt={}:time_base=1/{fps}:pixel_aspect=1/1",
+        width,
+        height,
+        Into::<ffi::AVPixelFormat>::into(ff::format::Pixel::VAAPI) as i32,
+    );
+    let mut src_ctx = graph.add(&buffersrc, "in", &args)?;
+
+    // SAFETY: av_buffersrc_parameters_alloc allocates params for the buffersrc.
+    let par = unsafe { ffi::av_buffersrc_parameters_alloc() };
+    if par.is_null() {
+        bail!("av_buffersrc_parameters_alloc returned null");
+    }
+    // SAFETY: Set hw_frames_ctx on the buffersrc parameters, then apply.
+    unsafe {
+        (*par).format = Into::<ffi::AVPixelFormat>::into(ff::format::Pixel::VAAPI) as i32;
+        (*par).width = width as i32;
+        (*par).height = height as i32;
+        (*par).time_base = ffi::AVRational {
+            num: 1,
+            den: fps as i32,
+        };
+        (*par).hw_frames_ctx = frames_rgb.ref_clone();
+        let ret = ffi::av_buffersrc_parameters_set(src_ctx.as_mut_ptr(), par);
+        ffi::av_free(par as *mut _);
+        if ret < 0 {
+            bail!("av_buffersrc_parameters_set failed: {}", ff_err(ret));
+        }
+    }
+
+    // scale_vaapi: hardware scaling and colourspace conversion (keeps original dimensions).
+    let mut scale_ctx = graph.add(
+        &scale_vaapi,
+        "scale",
+        &format!("{width}:{height}:format=nv12"),
+    )?;
+    // SAFETY: scale_vaapi needs hw_device_ctx for VAAPI device access.
+    unsafe {
+        (*scale_ctx.as_mut_ptr()).hw_device_ctx = hw_dev.ref_clone();
+    }
+
+    let mut sink_ctx = graph.add(&buffersink, "out", "")?;
+    src_ctx.link(0, &mut scale_ctx, 0);
+
+    match transform {
+        Transform::Normal => {
+            scale_ctx.link(0, &mut sink_ctx, 0);
+        }
+        other => {
+            let transpose = ff::filter::find("transpose_vaapi")
+                .ok_or_else(|| anyhow::anyhow!("filter 'transpose_vaapi' not found"))?;
+            let dir_val = match other {
+                Transform::Normal90 => "1",
+                Transform::Normal180 => "4",
+                Transform::Normal270 => "2",
+                Transform::Flipped => "5",
+                Transform::Flipped90 => "3",
+                Transform::Flipped180 => "6",
+                Transform::Flipped270 => "0",
+                Transform::Normal => unreachable!(),
+            };
+            let mut trans_ctx = graph.add(&transpose, "transpose", &format!("dir={dir_val}"))?;
+            // SAFETY: trans_ctx is a live transpose_vaapi filter context;
+            // scale_vaapi/transpose_vaapi keep a ref-counted device context.
+            unsafe {
+                (*trans_ctx.as_mut_ptr()).hw_device_ctx = hw_dev.ref_clone();
+            }
+            scale_ctx.link(0, &mut trans_ctx, 0);
+            trans_ctx.link(0, &mut sink_ctx, 0);
+        }
+    }
+
+    graph
+        .validate()
+        .map_err(|e| anyhow::anyhow!("Filter graph validation failed: {e}"))?;
+
+    Ok(graph)
+}

src/avhw/hardware.rs

@@ -0,0 +1,280 @@
+use std::path::Path;
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+use ffmpeg_next::packet::Mut as _;
+
+use crate::transform::Transform;
+
+use super::{
+    ff_err, filter::build_filter_graph, hardware_encoder, hardware_muxer, AvHwDevCtx, AvHwFrameCtx,
+    EncodeStages,
+};
+
+pub struct EncState {
+    enc_video: ff::codec::encoder::video::Video,
+    frames_rgb: AvHwFrameCtx,
+    video_filter: ff::filter::Graph,
+    hw_device_ctx: AvHwDevCtx,
+    octx: ff::format::context::Output,
+    starting_timestamp: Option<i64>,
+    frames_written: bool,
+}
+
+// SAFETY: EncState is moved to exactly one thread (the encode worker) and used
+// exclusively there. All fields are either plain Copy types (Option<i64>, bool)
+// or ffmpeg-next / AvHw* owned wrappers whose raw inner pointers are not actually
+// shared across threads - they're touched only from the owning encode thread.
+// This impl exists only to satisfy Rust's auto-Send inference (which can't see
+// through the raw pointers hidden inside the wrappers). Do NOT add fields that
+// introduce shared mutable state without re-auditing this assumption; see
+// AGENTS.md "Unsafe and FFI work" for the documented exclusivity requirement.
+unsafe impl Send for EncState {}
+
+impl EncState {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        drm_device: &Path,
+        output_path: &Path,
+        width: u32,
+        height: u32,
+        enc_width: u32,
+        enc_height: u32,
+        bitrate: u64,
+        gop_size: u32,
+        fps: u32,
+        transform: Transform,
+        existing_hw_ctx: Option<AvHwDevCtx>,
+    ) -> Result<Self> {
+        tracing::info!(
+            "EncState::new: {width}x{height} enc={enc_width}x{enc_height} transform={transform:?}"
+        );
+        let hw_device_ctx = match existing_hw_ctx {
+            Some(ctx) => ctx,
+            None => AvHwDevCtx::new_vaapi(drm_device)?,
+        };
+
+        let frames_rgb =
+            AvHwFrameCtx::for_capture(&hw_device_ctx, width, height, ff::format::Pixel::BGRA)?;
+
+        let mut video_filter =
+            build_filter_graph(&hw_device_ctx, &frames_rgb, width, height, fps, transform)?;
+
+        let mut sink_ctx = video_filter
+            .get("out")
+            .ok_or_else(|| anyhow::anyhow!("filter 'out' not found"))?;
+        // SAFETY: sink_ctx is a live buffersink; the returned hw_frames_ctx is
+        // borrowed, so av_buffer_ref creates an owned reference.
+        let sink_hw_frames = unsafe {
+            let raw = ffi::av_buffersink_get_hw_frames_ctx(sink_ctx.as_mut_ptr());
+            if raw.is_null() {
+                bail!("buffersink has no hw_frames_ctx - filter graph may not be configured for hardware output");
+            }
+            let hw_ref = ffi::av_buffer_ref(raw);
+            if hw_ref.is_null() {
+                bail!("av_buffer_ref failed for buffersink hw_frames_ctx - likely out of memory");
+            }
+            hw_ref
+        };
+
+        // SAFETY: sink_hw_frames is an owned AVBufferRef to an AVHWFramesContext
+        // returned by the validated filter graph.
+        unsafe {
+            let fc = (*sink_hw_frames).data as *mut ffi::AVHWFramesContext;
+            let actual_w = (*fc).width as u32;
+            let actual_h = (*fc).height as u32;
+            if actual_w != enc_width || actual_h != enc_height {
+                tracing::warn!(
+                    "Filter output dimensions {actual_w}x{actual_h} differ from encoder dimensions {enc_width}x{enc_height}"
+                );
+            }
+        }
+
+        let enc_video = hardware_encoder::open_h264_vaapi_encoder(
+            &hw_device_ctx,
+            sink_hw_frames,
+            enc_width,
+            enc_height,
+            bitrate,
+            gop_size,
+            fps,
+        )?;
+
+        let octx = hardware_muxer::create_output_context(output_path, &enc_video)?;
+
+        Ok(Self {
+            enc_video,
+            frames_rgb,
+            video_filter,
+            hw_device_ctx,
+            octx,
+            starting_timestamp: None,
+            frames_written: false,
+        })
+    }
+
+    pub fn frames_rgb(&self) -> &AvHwFrameCtx {
+        &self.frames_rgb
+    }
+
+    pub fn encode_frame(&mut self, hw_frame: &ff::frame::Video) -> Result<EncodeStages> {
+        let mut filter_src_ctx = self
+            .video_filter
+            .get("in")
+            .ok_or_else(|| anyhow::anyhow!("filter 'in' not found"))?;
+        let mut filter_src = filter_src_ctx.source();
+        let mut filter_sink_ctx = self
+            .video_filter
+            .get("out")
+            .ok_or_else(|| anyhow::anyhow!("filter 'out' not found"))?;
+        let mut filter_sink = filter_sink_ctx.sink();
+
+        // Scale stage = filter graph push + pull (scale_vaapi for resolution
+        // change + format conversion to NV12). Timed separately from the
+        // actual avcodec_send_frame so the per-stage stats answer "where is
+        // latency?" honestly. See Oracle audit 2026-06-28 step 4.
+        let scale_start = Instant::now();
+        filter_src
+            .add(hw_frame)
+            .map_err(|e| anyhow::anyhow!("Filter source add failed: {e}"))?;
+
+        let mut scale_us = 0u64;
+        let mut encode_us = 0u64;
+        loop {
+            let mut filtered = ff::frame::Video::empty();
+            match filter_sink.frame(&mut filtered) {
+                Ok(()) => {
+                    if filtered.pts().is_none() {
+                        filtered.set_pts(hw_frame.pts());
+                    }
+                }
+                Err(ff::Error::Other { errno }) if errno == ffi::EAGAIN => break,
+                Err(e) => bail!("Filter sink get frame failed: {e}"),
+            }
+            // First successful pull closes the scale-stage measurement; later
+            // pulls (rare extras) roll into encode time.
+            if scale_us == 0 {
+                scale_us = scale_start.elapsed().as_micros() as u64;
+            }
+
+            let pts = filtered.pts().unwrap_or(0);
+            if self.starting_timestamp.is_none() {
+                self.starting_timestamp = Some(pts);
+            }
+            let start_ts = self.starting_timestamp.unwrap();
+
+            let encode_start = Instant::now();
+            // SAFETY: avcodec_send_frame sends a valid NV12 VAAPI surface to the encoder.
+            let ret =
+                unsafe { ffi::avcodec_send_frame(self.enc_video.as_mut_ptr(), filtered.as_ptr()) };
+            if ret < 0 {
+                bail!("avcodec_send_frame failed: {}", ff_err(ret));
+            }
+            self.drain_encoder(start_ts)?;
+            encode_us += encode_start.elapsed().as_micros() as u64;
+        }
+
+        Ok(EncodeStages {
+            scale_us,
+            // HW path stays on GPU - no CPU readback, transfer is N/A.
+            transfer_us: 0,
+            encode_us,
+        })
+    }
+
+    pub fn flush(&mut self) -> Result<()> {
+        let mut filter_src_ctx = self
+            .video_filter
+            .get("in")
+            .ok_or_else(|| anyhow::anyhow!("filter 'in' not found"))?;
+        let mut filter_src = filter_src_ctx.source();
+        if let Err(e) = filter_src.flush() {
+            tracing::debug!("filter source flush error: {e}");
+        }
+
+        let mut filter_sink_ctx = self
+            .video_filter
+            .get("out")
+            .ok_or_else(|| anyhow::anyhow!("filter 'out' not found"))?;
+        let mut filter_sink = filter_sink_ctx.sink();
+        loop {
+            let mut filtered = ff::frame::Video::empty();
+            match filter_sink.frame(&mut filtered) {
+                Ok(()) => {
+                    let start_ts = self.starting_timestamp.unwrap_or(0);
+                    // SAFETY: filtered is a valid VAAPI frame drained from the
+                    // filter graph; enc_video is an opened encoder.
+                    let ret = unsafe {
+                        ffi::avcodec_send_frame(self.enc_video.as_mut_ptr(), filtered.as_ptr())
+                    };
+                    if ret < 0 {
+                        bail!("avcodec_send_frame failed during flush: {}", ff_err(ret));
+                    }
+                    self.drain_encoder(start_ts)?;
+                }
+                Err(_) => break,
+            }
+        }
+
+        // SAFETY: Sending null frame signals end of stream to encoder.
+        unsafe {
+            ffi::avcodec_send_frame(self.enc_video.as_mut_ptr(), std::ptr::null());
+        }
+
+        let start_ts = self.starting_timestamp.unwrap_or(0);
+        self.drain_encoder(start_ts)?;
+
+        if self.frames_written {
+            self.octx
+                .write_trailer()
+                .map_err(|e| anyhow::anyhow!("Failed to write trailer: {e}"))?;
+        }
+
+        Ok(())
+    }
+
+    fn drain_encoder(&mut self, start_ts: i64) -> Result<()> {
+        loop {
+            let mut pkt = ff::Packet::empty();
+            // SAFETY: avcodec_receive_packet retrieves an encoded packet.
+            let ret = unsafe {
+                ffi::avcodec_receive_packet(self.enc_video.as_mut_ptr(), pkt.as_mut_ptr())
+            };
+            if ret < 0 {
+                if ret == ffi::AVERROR(ffi::EAGAIN) || ret == ffi::AVERROR_EOF {
+                    break;
+                }
+                bail!("avcodec_receive_packet failed: {}", ff_err(ret));
+            }
+
+            let enc_tb = self.enc_video.time_base();
+            // SAFETY: octx was created with stream 0 during muxer setup; streams
+            // is non-null and stream 0 remains owned by the format context.
+            let stream_tb = unsafe {
+                let fmt = *self.octx.as_ptr();
+                if fmt.nb_streams == 0 || fmt.streams.is_null() {
+                    bail!("no streams in output context");
+                }
+                let st = *fmt.streams.add(0);
+                ff::Rational::from((*st).time_base)
+            };
+            pkt.rescale_ts(enc_tb, stream_tb);
+
+            if let Some(pts) = pkt.pts() {
+                pkt.set_pts(Some(pts - start_ts));
+            }
+            if let Some(dts) = pkt.dts() {
+                pkt.set_dts(Some(dts - start_ts));
+            }
+
+            pkt.set_stream(0);
+            pkt.write_interleaved(&mut self.octx)
+                .map_err(|e| anyhow::anyhow!("Failed to write packet: {e}"))?;
+
+            self.frames_written = true;
+        }
+        Ok(())
+    }
+}

src/avhw/hardware_encoder.rs

@@ -0,0 +1,83 @@
+use std::ffi::CString;
+
+use anyhow::Result;
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use super::{ff_err, AvHwDevCtx};
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn open_h264_vaapi_encoder(
+    hw_device_ctx: &AvHwDevCtx,
+    sink_hw_frames: *mut ffi::AVBufferRef,
+    enc_width: u32,
+    enc_height: u32,
+    bitrate: u64,
+    gop_size: u32,
+    fps: u32,
+) -> Result<ff::codec::encoder::video::Video> {
+    let codec = ff::encoder::find_by_name("h264_vaapi")
+        .ok_or_else(|| anyhow::anyhow!("h264_vaapi encoder not found"))?;
+
+    let mut enc = {
+        let ctx = ff::codec::Context::new_with_codec(codec);
+        ctx.encoder().video()?
+    };
+
+    enc.set_width(enc_width);
+    enc.set_height(enc_height);
+    enc.set_format(ff::format::Pixel::VAAPI);
+    enc.set_bit_rate(bitrate as usize);
+    enc.set_gop(gop_size);
+    enc.set_time_base(ff::Rational::new(1, fps as i32));
+    enc.set_max_b_frames(0);
+
+    // VBV rate limiting: caps IDR burst size for WebRTC. Without this a 4K
+    // scene change can produce a 256KB keyframe that overflows the UDP send
+    // buffer. bufsize=bitrate/4 is about 250ms of video at the target bitrate.
+    // SAFETY: enc.as_mut_ptr() is a valid AVCodecContext for the not-yet-opened
+    // encoder. rc_max_rate and rc_buffer_size are plain integer fields; assigning
+    // i64/i32 values is a simple struct-field write on a properly aligned pointer.
+    unsafe {
+        let ctx_ptr = enc.as_mut_ptr();
+        (*ctx_ptr).rc_max_rate = bitrate as i64;
+        (*ctx_ptr).rc_buffer_size = (bitrate / 4) as i32;
+    }
+
+    // SAFETY: AV_CODEC_FLAG_GLOBAL_HEADER must be set BEFORE opening the encoder.
+    // It triggers SPS/PPS extradata generation needed by the muxer for
+    // Annex B to AVCC conversion.
+    unsafe {
+        (*enc.as_mut_ptr()).flags |= ffi::AV_CODEC_FLAG_GLOBAL_HEADER as i32;
+    }
+    // SAFETY: Assign hw device and frames ctx to the encoder.
+    unsafe {
+        (*enc.as_mut_ptr()).hw_device_ctx = hw_device_ctx.ref_clone();
+        (*enc.as_mut_ptr()).hw_frames_ctx = sink_hw_frames;
+    }
+
+    // SAFETY: Set repeat_pps=1 on the encoder so PPS is inserted in every encoded frame.
+    // This ensures decoders can start decoding from any frame (important for WebRTC).
+    // repeat_pps is only available in FFmpeg 7.0+ (not in 6.x). On older
+    // FFmpeg, IDR frames carry SPS by default; PPS repetition depends on the driver.
+    // For SPS repetition: IDR frames carry SPS by default, controlled by gop_size/idr_interval.
+    {
+        let key = CString::new("repeat_pps").unwrap();
+        let val = CString::new("1").unwrap();
+        // SAFETY: enc is a valid AVCodecContext for the not-yet-opened encoder;
+        // priv_data is the codec's private options struct. key/val are NUL-terminated
+        // CString that live across the call. av_opt_set is FFmpeg's standard
+        // option-setter. Failure is non-fatal (returns < 0 on older FFmpeg).
+        let ret = unsafe {
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0)
+        };
+        if ret < 0 {
+            tracing::warn!("av_opt_set repeat_pps failed ({}), likely FFmpeg < 7.0; continuing without per-frame PPS", ff_err(ret));
+        }
+    }
+
+    let opened = enc
+        .open()
+        .map_err(|e| anyhow::anyhow!("Failed to open h264_vaapi encoder: {e}"))?;
+    Ok(opened.0)
+}

src/avhw/hardware_muxer.rs

@@ -0,0 +1,92 @@
+use std::ffi::CString;
+use std::path::Path;
+use std::ptr;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use super::ff_err;
+
+pub(super) fn create_output_context(
+    output_path: &Path,
+    enc_video: &ff::codec::encoder::video::Video,
+) -> Result<ff::format::context::Output> {
+    let output_cstr = CString::new(output_path.to_str().unwrap())?;
+    let mut fmt_ctx_ptr: *mut ffi::AVFormatContext = ptr::null_mut();
+
+    // SAFETY: avformat_alloc_output_context2 creates format context from
+    // the file extension. Does NOT open the file.
+    let ret = unsafe {
+        ffi::avformat_alloc_output_context2(
+            &mut fmt_ctx_ptr,
+            ptr::null_mut(),
+            ptr::null(),
+            output_cstr.as_ptr(),
+        )
+    };
+    if ret < 0 || fmt_ctx_ptr.is_null() {
+        bail!("Failed to allocate output format context: {}", ff_err(ret));
+    }
+
+    // SAFETY: enc_video is a valid AVCodecContext pointer; codec_id is a plain
+    // i32 enum discriminant read from it. fmt_ctx_ptr is a valid AVFormatContext
+    // allocated above; oformat is a const pointer field read from it.
+    // avformat_query_codec checks codec+format compatibility; both pointers are
+    // valid and FF_COMPLIANCE_NORMAL is a constant. All three reads happen in one
+    // block so a single SAFETY rationale covers them.
+    let compat = unsafe {
+        let codec_id = (*enc_video.as_ptr()).codec_id;
+        let oformat = (*fmt_ctx_ptr).oformat;
+        ffi::avformat_query_codec(oformat, codec_id, ffi::FF_COMPLIANCE_NORMAL)
+    };
+    if compat < 0 {
+        bail!("H.264 codec not supported by output container format");
+    }
+
+    // SAFETY: avformat_new_stream creates a new stream in the format context.
+    let stream_ptr = unsafe { ffi::avformat_new_stream(fmt_ctx_ptr, ptr::null()) };
+    if stream_ptr.is_null() {
+        bail!("Failed to create new stream in output context");
+    }
+
+    // SAFETY: avcodec_parameters_from_context copies encoder params + extradata.
+    let ret =
+        unsafe { ffi::avcodec_parameters_from_context((*stream_ptr).codecpar, enc_video.as_ptr()) };
+    if ret < 0 {
+        bail!(
+            "Failed to copy encoder parameters to stream: {}",
+            ff_err(ret)
+        );
+    }
+
+    // SAFETY: Copy encoder time_base to stream.
+    unsafe {
+        (*stream_ptr).time_base = (*enc_video.as_ptr()).time_base;
+    }
+
+    // SAFETY: avio_open opens the output file for writing.
+    let ret = unsafe {
+        ffi::avio_open(
+            &mut (*fmt_ctx_ptr).pb,
+            output_cstr.as_ptr(),
+            ffi::AVIO_FLAG_WRITE,
+        )
+    };
+    if ret < 0 {
+        bail!(
+            "Failed to open output file '{}': {}",
+            output_path.display(),
+            ff_err(ret)
+        );
+    }
+
+    // SAFETY: avformat_write_header writes the container header.
+    let ret = unsafe { ffi::avformat_write_header(fmt_ctx_ptr, ptr::null_mut()) };
+    if ret < 0 {
+        bail!("Failed to write output header: {}", ff_err(ret));
+    }
+
+    // SAFETY: We created fmt_ctx_ptr above and it's valid.
+    Ok(unsafe { ff::format::context::Output::wrap(fmt_ctx_ptr) })
+}

src/avhw/hash.rs

@@ -0,0 +1,23 @@
+const FNV1A_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
+const FNV1A_PRIME: u64 = 0x100000001b3;
+const Y_PLANE_HASH_ROW_STEP: usize = 8;
+
+pub(super) fn hash_sampled_y_plane(
+    y_data: &[u8],
+    width: usize,
+    height: usize,
+    stride: usize,
+) -> u64 {
+    let mut hash = FNV1A_OFFSET_BASIS;
+
+    for row in (0..height).step_by(Y_PLANE_HASH_ROW_STEP) {
+        let row_start = row * stride;
+        let row_end = row_start + width;
+        for &byte in &y_data[row_start..row_end] {
+            hash ^= u64::from(byte);
+            hash = hash.wrapping_mul(FNV1A_PRIME);
+        }
+    }
+
+    hash
+}

src/avhw/import.rs

@@ -0,0 +1,263 @@
+use std::path::Path;
+use std::slice;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use super::filter::build_swenc_filter_graph;
+use super::{ff_err, AvHwDevCtx, AvHwFrameCtx};
+use super::{BitrateCommand, CpuNv12Frame, ResolutionChange};
+
+pub struct SwEncImport {
+    hw_dev: AvHwDevCtx,
+    frames_rgb: AvHwFrameCtx,
+    filter_graph: ff::filter::Graph,
+    width: u32,
+    height: u32,
+    enc_width: u32,
+    enc_height: u32,
+    fps: u32,
+    resolution_rx: Option<crossbeam_channel::Receiver<BitrateCommand>>,
+    encoder_resolution_tx: Option<crossbeam_channel::Sender<ResolutionChange>>,
+}
+
+impl SwEncImport {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        drm_device: &Path,
+        width: u32,
+        height: u32,
+        enc_width: u32,
+        enc_height: u32,
+        fps: u32,
+    ) -> Result<Self> {
+        let hw_dev = AvHwDevCtx::new_vaapi(drm_device)?;
+        let frames_rgb =
+            AvHwFrameCtx::for_capture(&hw_dev, width, height, ff::format::Pixel::BGRA)?;
+        let filter_graph = build_swenc_filter_graph(
+            &hw_dev,
+            &frames_rgb,
+            width,
+            height,
+            enc_width,
+            enc_height,
+            fps,
+        )?;
+
+        Ok(Self {
+            hw_dev,
+            frames_rgb,
+            filter_graph,
+            width,
+            height,
+            enc_width,
+            enc_height,
+            fps,
+            resolution_rx: None,
+            encoder_resolution_tx: None,
+        })
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn new_with_resolution_control(
+        drm_device: &Path,
+        width: u32,
+        height: u32,
+        enc_width: u32,
+        enc_height: u32,
+        fps: u32,
+        resolution_rx: crossbeam_channel::Receiver<BitrateCommand>,
+        encoder_resolution_tx: crossbeam_channel::Sender<ResolutionChange>,
+    ) -> Result<Self> {
+        let mut this = Self::new(drm_device, width, height, enc_width, enc_height, fps)?;
+        this.resolution_rx = Some(resolution_rx);
+        this.encoder_resolution_tx = Some(encoder_resolution_tx);
+        Ok(this)
+    }
+
+    pub fn frames_rgb(&self) -> &AvHwFrameCtx {
+        let _ = self.hw_dev.as_ptr();
+        &self.frames_rgb
+    }
+
+    pub fn import_and_scale(&mut self, hw_frame: &ff::frame::Video) -> Result<CpuNv12Frame> {
+        self.poll_resolution_commands()?;
+
+        let mut filter_src_ctx = self
+            .filter_graph
+            .get("in")
+            .ok_or_else(|| anyhow::anyhow!("filter 'in' not found"))?;
+        let mut filter_src = filter_src_ctx.source();
+        let mut filter_sink_ctx = self
+            .filter_graph
+            .get("out")
+            .ok_or_else(|| anyhow::anyhow!("filter 'out' not found"))?;
+        let mut filter_sink = filter_sink_ctx.sink();
+
+        filter_src
+            .add(hw_frame)
+            .map_err(|e| anyhow::anyhow!("software pipeline filter source add failed: {e}"))?;
+
+        let mut first = None;
+        let mut extra_count = 0usize;
+        loop {
+            let mut filtered = ff::frame::Video::empty();
+            match filter_sink.frame(&mut filtered) {
+                Ok(()) => {
+                    if filtered.pts().is_none() {
+                        filtered.set_pts(hw_frame.pts());
+                    }
+                    let cpu_frame = self.transfer_filtered_to_cpu(&filtered)?;
+                    if first.is_none() {
+                        first = Some(cpu_frame);
+                    } else {
+                        extra_count += 1;
+                    }
+                }
+                Err(ff::Error::Other { errno }) if errno == ffi::EAGAIN => break,
+                Err(e) => bail!("software pipeline filter sink get frame failed: {e}"),
+            }
+        }
+
+        if extra_count > 0 {
+            tracing::warn!(
+                "software import filter produced {extra_count} extra frame(s); dropping extras"
+            );
+        }
+
+        first.ok_or_else(|| anyhow::anyhow!("software pipeline produced no scaled frame"))
+    }
+
+    pub fn flush_import(&mut self) -> Result<Vec<CpuNv12Frame>> {
+        let mut filter_src_ctx = self
+            .filter_graph
+            .get("in")
+            .ok_or_else(|| anyhow::anyhow!("filter 'in' not found"))?;
+        let mut filter_src = filter_src_ctx.source();
+        if let Err(e) = filter_src.flush() {
+            tracing::debug!("filter source flush error: {e}");
+        }
+
+        let mut filter_sink_ctx = self
+            .filter_graph
+            .get("out")
+            .ok_or_else(|| anyhow::anyhow!("filter 'out' not found"))?;
+        let mut filter_sink = filter_sink_ctx.sink();
+        let mut frames = Vec::new();
+        loop {
+            let mut filtered = ff::frame::Video::empty();
+            match filter_sink.frame(&mut filtered) {
+                Ok(()) => frames.push(self.transfer_filtered_to_cpu(&filtered)?),
+                Err(_) => break,
+            }
+        }
+
+        Ok(frames)
+    }
+
+    fn poll_resolution_commands(&mut self) -> Result<()> {
+        let Some(rx) = self.resolution_rx.as_ref().cloned() else {
+            return Ok(());
+        };
+
+        let mut requested = None;
+        while let Ok(cmd) = rx.try_recv() {
+            match cmd {
+                BitrateCommand::UpdateResolution { width, height } => {
+                    requested = Some((width & !1, height & !1));
+                }
+                BitrateCommand::UpdateBitrate { .. } => {}
+                BitrateCommand::ForceKeyframe => {}
+            }
+        }
+
+        let Some((width, height)) = requested else {
+            return Ok(());
+        };
+        if width == self.enc_width && height == self.enc_height {
+            return Ok(());
+        }
+
+        tracing::info!(
+            from = format_args!("{}x{}", self.enc_width, self.enc_height),
+            to = format_args!("{}x{}", width, height),
+            "rebuilding software import filter graph for resolution change"
+        );
+        let _ = self.flush_import();
+        self.filter_graph = build_swenc_filter_graph(
+            &self.hw_dev,
+            &self.frames_rgb,
+            self.width,
+            self.height,
+            width,
+            height,
+            self.fps,
+        )?;
+        self.enc_width = width;
+        self.enc_height = height;
+
+        if let Some(tx) = &self.encoder_resolution_tx {
+            tx.send(ResolutionChange { width, height })
+                .map_err(|_| anyhow::anyhow!("encoder resolution channel disconnected"))?;
+        }
+
+        Ok(())
+    }
+
+    fn transfer_filtered_to_cpu(&self, filtered: &ff::frame::Video) -> Result<CpuNv12Frame> {
+        // SAFETY: av_frame_alloc returns a newly allocated AVFrame or null,
+        // which is checked below.
+        let mut sw_nv12 = unsafe { ffi::av_frame_alloc() };
+        if sw_nv12.is_null() {
+            bail!("av_frame_alloc failed for NV12 transfer frame");
+        }
+
+        // SAFETY: sw_nv12 is an allocated destination frame; filtered is a valid VAAPI NV12
+        // surface produced by scale_vaapi at encoder dimensions.
+        let transfer_ret = unsafe { ffi::av_hwframe_transfer_data(sw_nv12, filtered.as_ptr(), 0) };
+        if transfer_ret < 0 {
+            // SAFETY: sw_nv12 was allocated above and has not been freed yet.
+            unsafe { ffi::av_frame_free(&mut sw_nv12) };
+            bail!(
+                "av_hwframe_transfer_data failed for GPU-downscaled frame: {}",
+                ff_err(transfer_ret)
+            );
+        }
+
+        // SAFETY: sw_nv12 was filled by av_hwframe_transfer_data. NV12 planes 0 and 1 are
+        // initialized for enc_width x enc_height; linesize values define each row's byte span.
+        let frame = unsafe {
+            let y_ptr = (*sw_nv12).data[0];
+            let uv_ptr = (*sw_nv12).data[1];
+            if y_ptr.is_null() || uv_ptr.is_null() {
+                ffi::av_frame_free(&mut sw_nv12);
+                bail!("NV12 transfer frame missing Y/UV plane data");
+            }
+            let y_stride = (*sw_nv12).linesize[0] as usize;
+            let uv_stride = (*sw_nv12).linesize[1] as usize;
+            if (*sw_nv12).width != self.enc_width as i32
+                || (*sw_nv12).height != self.enc_height as i32
+            {
+                ffi::av_frame_free(&mut sw_nv12);
+                bail!("NV12 transfer frame has unexpected dimensions");
+            }
+            let y_len = y_stride * self.enc_height as usize;
+            let uv_len = uv_stride * (self.enc_height as usize / 2);
+            let y_data = slice::from_raw_parts(y_ptr, y_len).to_vec();
+            let uv_data = slice::from_raw_parts(uv_ptr, uv_len).to_vec();
+            let pts = filtered.pts().unwrap_or(0);
+            ffi::av_frame_free(&mut sw_nv12);
+            CpuNv12Frame {
+                y_data,
+                uv_data,
+                y_stride,
+                uv_stride,
+                pts,
+                capture_time: std::time::Instant::now(),
+            }
+        };
+
+        Ok(frame)
+    }
+}

src/avhw/mod.rs

@@ -0,0 +1,227 @@
+use std::path::Path;
+
+use anyhow::Result;
+
+use crate::transform::{transpose_if_transform_transposed, Transform};
+
+mod device;
+mod dmabuf;
+mod encode;
+mod encode_init;
+mod encode_output;
+mod filter;
+mod hardware;
+mod hardware_encoder;
+mod hardware_muxer;
+mod hash;
+mod import;
+mod software;
+mod state;
+mod types;
+mod util;
+
+pub use device::{AvHwDevCtx, AvHwFrameCtx};
+pub use dmabuf::{import_dma_buf_to_vaapi, test_dma_buf_import};
+pub use encode::{SwEncEncode, WEBRTC_RTP_CLOCK_HZ};
+#[allow(unused_imports)]
+pub use encode_output::FrameOutput;
+pub use hardware::EncState;
+#[cfg(test)]
+use hash::hash_sampled_y_plane;
+pub use import::SwEncImport;
+pub use state::SwEncState;
+pub use types::{
+    BitrateCommand, CpuNv12Frame, EncodeOutcome, EncodeStages, EncodedH264Frame, ResolutionChange,
+    SwEncodeTiming,
+};
+pub(crate) use util::ff_err;
+
+// ---------------------------------------------------------------------------
+// Shared encoder creation (used by both wlr-screencopy and portal paths)
+// ---------------------------------------------------------------------------
+
+/// Create a fully configured encoder with VAAPI hardware acceleration.
+///
+/// Convenience wrapper around [`EncState::new`] that computes default values
+/// for `bitrate` and `gop_size` when not provided, and handles encoder dimension
+/// transposition for rotated/transformed outputs.
+#[allow(clippy::too_many_arguments)]
+pub fn create_encoder(
+    drm_device: &Path,
+    output_path: &Path,
+    width: u32,
+    height: u32,
+    fps: u32,
+    transform: Transform,
+    bitrate: Option<u64>,
+    gop_size: Option<u32>,
+    existing_hw_ctx: Option<AvHwDevCtx>,
+) -> Result<EncState> {
+    let (enc_w, enc_h) = transpose_if_transform_transposed(transform, width as i32, height as i32);
+    let actual_bitrate =
+        bitrate.unwrap_or_else(|| 2 * (width as u64) * (height as u64) * (fps as u64) / 100);
+    let actual_gop_size = gop_size.unwrap_or(fps);
+    EncState::new(
+        drm_device,
+        output_path,
+        width,
+        height,
+        enc_w as u32,
+        enc_h as u32,
+        actual_bitrate,
+        actual_gop_size,
+        fps,
+        transform,
+        existing_hw_ctx,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Centralizes the `stride * row` byte-offset pattern used by the Y-plane hash
+    // tests below, so clippy::erasing_op (row == 0) and clippy::identity_op (row == 1)
+    // both pass without sacrificing the row-index intent the tests are written around.
+    fn row_range(row: usize, stride: usize, width: usize) -> std::ops::Range<usize> {
+        let start = stride * row;
+        start..start + width
+    }
+
+    // ── Task 1: VBV x264opts formatting ──
+
+    #[test]
+    fn vbv_x264opts_format() {
+        let bitrate: u64 = 5_000_000;
+        // x264 expects kbit/s and kbit, not bps
+        let vbv_maxrate_kbps = bitrate / 1000;
+        let vbv_bufsize_kbps = (bitrate / 4) / 1000;
+        let opts = format!(
+            "repeat_headers=1:vbv-maxrate={vbv_maxrate_kbps}:vbv-bufsize={vbv_bufsize_kbps}"
+        );
+        assert_eq!(vbv_maxrate_kbps, 5000);
+        assert_eq!(vbv_bufsize_kbps, 1250);
+        assert!(opts.contains("vbv-maxrate=5000"));
+        assert!(opts.contains("vbv-bufsize=1250"));
+    }
+
+    #[test]
+    fn vbv_bufsize_is_quarter_of_maxrate() {
+        for bitrate in [1_000_000, 5_000_000, 10_000_000] {
+            // x264 expects kbit/s and kbit; both scaled by /1000, ratio preserved
+            let maxrate_kbps = bitrate / 1000;
+            let bufsize_kbps = (bitrate / 4) / 1000;
+            assert_eq!(
+                bufsize_kbps * 4,
+                maxrate_kbps,
+                "bufsize should be maxrate/4"
+            );
+        }
+    }
+
+    // ── Task 3: GOP formula ──
+
+    #[test]
+    fn webrtc_gop_formula() {
+        // Formula under test: GOP = max(fps * 2, 20). Hid behind a runtime lambda so
+        // clippy can't constant-fold the assertions into tautologies (which would
+        // silently strip the floor-case coverage for 5fps).
+        fn gop(fps: u32) -> u32 {
+            (fps * 2).max(20)
+        }
+        assert_eq!(gop(15), 30); // 15fps -> 30
+        assert_eq!(gop(30), 60); // 30fps -> 60
+        assert_eq!(gop(60), 120); // 60fps -> 120
+        assert_eq!(gop(5), 20); // 5fps -> 20 (floor)
+    }
+
+    #[test]
+    fn h264_level_values() {
+        // Level 4.0 supports up to 1080p@30fps (used for file muxer)
+        assert_eq!(40i32, 40);
+        // Level 4.2 supports up to 1440p@30fps (used for WebRTC low-latency encoder)
+        assert_eq!(42i32, 42);
+    }
+
+    // ── Task 4: Duplicate frame hash detection ──
+
+    #[test]
+    fn hash_sampled_y_plane_first_frame_consistent() {
+        let width = 64;
+        let height = 64;
+        let stride = 64;
+        let y_data = vec![0u8; stride * height];
+        let hash1 = hash_sampled_y_plane(&y_data, width, height, stride);
+        let hash2 = hash_sampled_y_plane(&y_data, width, height, stride);
+        assert_eq!(hash1, hash2, "same input should produce same hash");
+    }
+
+    #[test]
+    fn hash_sampled_y_plane_detects_different_frames() {
+        let width = 64;
+        let height = 64;
+        let stride = 64;
+        let y_data1 = vec![0u8; stride * height];
+        let y_data2 = vec![128u8; stride * height];
+        let hash1 = hash_sampled_y_plane(&y_data1, width, height, stride);
+        let hash2 = hash_sampled_y_plane(&y_data2, width, height, stride);
+        assert_ne!(
+            hash1, hash2,
+            "different frame data should produce different hashes"
+        );
+    }
+
+    #[test]
+    fn hash_sampled_y_plane_samples_every_8th_row() {
+        // Changing a non-sampled row (e.g., row 1) should NOT change the hash
+        let width = 64;
+        let height = 64;
+        let stride = 64;
+        let y_data1 = vec![0u8; stride * height];
+        let mut y_data2 = vec![0u8; stride * height];
+        // Row 1 is NOT sampled (sampling is every 8th row: 0, 8, 16, ...)
+        y_data2[row_range(1, stride, width)].fill(255);
+        let hash1 = hash_sampled_y_plane(&y_data1, width, height, stride);
+        let hash2 = hash_sampled_y_plane(&y_data2, width, height, stride);
+        assert_eq!(
+            hash1, hash2,
+            "non-sampled row change should not affect hash"
+        );
+    }
+
+    #[test]
+    fn hash_sampled_y_plane_sensitive_to_sampled_row() {
+        // Changing a sampled row (row 0) SHOULD change the hash
+        let width = 64;
+        let height = 64;
+        let stride = 64;
+        let y_data1 = vec![0u8; stride * height];
+        let mut y_data2 = vec![0u8; stride * height];
+        // Row 0 IS sampled (every 8th row starting from 0)
+        y_data2[row_range(0, stride, width)].fill(255);
+        let hash1 = hash_sampled_y_plane(&y_data1, width, height, stride);
+        let hash2 = hash_sampled_y_plane(&y_data2, width, height, stride);
+        assert_ne!(
+            hash1, hash2,
+            "sampled row change should produce different hash"
+        );
+    }
+
+    #[test]
+    fn hash_sampled_y_plane_handles_stride_greater_than_width() {
+        // Stride can be larger than width due to alignment; unused padding should not affect hash
+        let width = 32;
+        let height = 16;
+        let stride = 64; // padded stride
+        let y_data1 = vec![0u8; stride * height];
+        let mut y_data2 = vec![0u8; stride * height];
+        // Fill the padding area (columns 32..63) of row 0 with garbage
+        y_data2[width..stride].fill(0xFF);
+        let hash1 = hash_sampled_y_plane(&y_data1, width, height, stride);
+        let hash2 = hash_sampled_y_plane(&y_data2, width, height, stride);
+        assert_eq!(
+            hash1, hash2,
+            "padding bytes beyond width should not affect hash"
+        );
+    }
+}

src/avhw/software.rs

@@ -0,0 +1,268 @@
+use std::ffi::CString;
+use std::path::Path;
+use std::ptr;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use super::ff_err;
+
+pub(super) fn create_nv12_to_yuv420p_sws(width: u32, height: u32) -> Result<*mut ffi::SwsContext> {
+    // SAFETY: sws_getContext creates an owned scaler context for same-size NV12 -> YUV420P.
+    let ctx = unsafe {
+        ffi::sws_getContext(
+            width as i32,
+            height as i32,
+            ffi::AVPixelFormat::AV_PIX_FMT_NV12,
+            width as i32,
+            height as i32,
+            ffi::AVPixelFormat::AV_PIX_FMT_YUV420P,
+            2,
+            ptr::null_mut(),
+            ptr::null_mut(),
+            ptr::null_mut(),
+        )
+    };
+    if ctx.is_null() {
+        bail!("Failed to create NV12 -> YUV420P sws_scale context");
+    }
+    Ok(ctx)
+}
+
+pub(super) fn alloc_yuv420p_frame(width: u32, height: u32) -> Result<*mut ffi::AVFrame> {
+    // SAFETY: Allocate an AVFrame, configure format/dimensions, then allocate writable buffers.
+    unsafe {
+        let mut frame = ffi::av_frame_alloc();
+        if frame.is_null() {
+            bail!("av_frame_alloc failed");
+        }
+        (*frame).width = width as i32;
+        (*frame).height = height as i32;
+        (*frame).format = ffi::AVPixelFormat::AV_PIX_FMT_YUV420P as i32;
+        let ret = ffi::av_frame_get_buffer(frame, 0);
+        if ret < 0 {
+            ffi::av_frame_free(&mut frame);
+            bail!("av_frame_get_buffer failed: {}", ff_err(ret));
+        }
+        Ok(frame)
+    }
+}
+
+pub(super) fn create_software_h264_muxer(
+    output_path: &Path,
+    width: u32,
+    height: u32,
+    fps: u32,
+    bitrate: u64,
+    gop_size: u32,
+) -> Result<(
+    ff::codec::encoder::video::Video,
+    ff::format::context::Output,
+)> {
+    let output_cstr = CString::new(output_path.to_str().unwrap())?;
+    let codec = ff::encoder::find_by_name("libx264")
+        .or_else(|| ff::encoder::find_by_name("libopenh264"))
+        .ok_or_else(|| {
+            anyhow::anyhow!("No H.264 software encoder found (tried libx264, libopenh264)")
+        })?;
+    let codec_name = codec.name().to_string();
+
+    let mut enc = {
+        let ctx = ff::codec::Context::new_with_codec(codec);
+        ctx.encoder().video()?
+    };
+    enc.set_width(width);
+    enc.set_height(height);
+    enc.set_format(ff::format::Pixel::YUV420P);
+    enc.set_bit_rate(bitrate as usize);
+    enc.set_gop(gop_size);
+    enc.set_time_base(ff::Rational::new(1, fps as i32));
+    enc.set_max_b_frames(3);
+
+    // SAFETY: global headers are needed by MP4 and harmless for other common muxers.
+    unsafe {
+        (*enc.as_mut_ptr()).flags |= ffi::AV_CODEC_FLAG_GLOBAL_HEADER as i32;
+    }
+
+    if codec_name == "libx264" {
+        // SAFETY: priv_data and codec context belong to the unopened encoder;
+        // strings live for each av_opt_set call.
+        unsafe {
+            let key = CString::new("preset").unwrap();
+            let val = CString::new("fast").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            let key = CString::new("threads").unwrap();
+            let val = CString::new("6").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            (*enc.as_mut_ptr()).profile = ffi::AV_PROFILE_H264_HIGH;
+            // SAFETY: enc is a valid, initialized AVCodecContext from
+            // avcodec_alloc_context3. Setting level is a simple i32 field
+            // assignment on a properly aligned struct.
+            (*enc.as_mut_ptr()).level = 40; // H.264 Level 4.0 (up to 1080p@30)
+        }
+    }
+
+    let opened = enc
+        .open()
+        .map_err(|e| anyhow::anyhow!("Failed to open {codec_name} encoder: {e}"))?;
+    let enc_video = opened.0;
+
+    let use_null = output_path
+        .to_str()
+        .map(|s| s.contains("null"))
+        .unwrap_or(false);
+    let fmt_name = if use_null {
+        CString::new("null").unwrap()
+    } else {
+        CString::new("").unwrap()
+    };
+    let fmt_name_ptr = if use_null {
+        fmt_name.as_ptr()
+    } else {
+        ptr::null()
+    };
+
+    let mut fmt_ctx_ptr: *mut ffi::AVFormatContext = ptr::null_mut();
+    // SAFETY: fmt_ctx_ptr is initialized by FFmpeg; C strings live across the call.
+    let ret = unsafe {
+        ffi::avformat_alloc_output_context2(
+            &mut fmt_ctx_ptr,
+            ptr::null_mut(),
+            fmt_name_ptr,
+            output_cstr.as_ptr(),
+        )
+    };
+    if ret < 0 || fmt_ctx_ptr.is_null() {
+        bail!("Failed to allocate output format context: {}", ff_err(ret));
+    }
+
+    // SAFETY: fmt_ctx_ptr is valid; stream and codec parameters are owned by the format context.
+    let stream_ptr = unsafe { ffi::avformat_new_stream(fmt_ctx_ptr, ptr::null()) };
+    if stream_ptr.is_null() {
+        bail!("Failed to create output stream");
+    }
+
+    // SAFETY: stream_ptr and encoder context are valid; parameters are copied into stream.
+    let ret =
+        unsafe { ffi::avcodec_parameters_from_context((*stream_ptr).codecpar, enc_video.as_ptr()) };
+    if ret < 0 {
+        bail!("Failed to copy codec parameters to stream: {}", ff_err(ret));
+    }
+    // SAFETY: stream_ptr is valid and writable during muxer setup.
+    unsafe {
+        (*stream_ptr).time_base = (*enc_video.as_ptr()).time_base;
+    }
+
+    // SAFETY: open an AVIO only for muxers that require files; null muxer advertises NOFILE.
+    unsafe {
+        if (*(*fmt_ctx_ptr).oformat).flags & ffi::AVFMT_NOFILE == 0 {
+            let ret = ffi::avio_open(
+                &mut (*fmt_ctx_ptr).pb,
+                output_cstr.as_ptr(),
+                ffi::AVIO_FLAG_WRITE,
+            );
+            if ret < 0 {
+                bail!(
+                    "Failed to open output file '{}': {}",
+                    output_path.display(),
+                    ff_err(ret)
+                );
+            }
+        }
+    }
+
+    // SAFETY: fmt_ctx_ptr is fully configured.
+    let ret = unsafe { ffi::avformat_write_header(fmt_ctx_ptr, ptr::null_mut()) };
+    if ret < 0 {
+        bail!("Failed to write output header: {}", ff_err(ret));
+    }
+
+    // SAFETY: ownership of fmt_ctx_ptr transfers to ffmpeg-next Output wrapper.
+    let octx = unsafe { ff::format::context::Output::wrap(fmt_ctx_ptr) };
+    tracing::info!("Using software H.264 encoder: {codec_name}");
+    Ok((enc_video, octx))
+}
+
+pub(super) fn create_software_h264_encoder(
+    width: u32,
+    height: u32,
+    fps: u32,
+    bitrate: u64,
+    gop_size: u32,
+) -> Result<ff::codec::encoder::video::Video> {
+    let codec = ff::encoder::find_by_name("libx264")
+        .or_else(|| ff::encoder::find_by_name("libopenh264"))
+        .ok_or_else(|| anyhow::anyhow!("No H.264 software encoder found"))?;
+    let codec_name = codec.name().to_string();
+
+    let mut enc = {
+        let ctx = ff::codec::Context::new_with_codec(codec);
+        ctx.encoder().video()?
+    };
+    enc.set_width(width);
+    enc.set_height(height);
+    enc.set_format(ff::format::Pixel::YUV420P);
+    enc.set_bit_rate(bitrate as usize);
+    enc.set_gop(gop_size);
+    // 90kHz media clock matches RTP directly. Eliminates 1/fps quantization
+    // that previously caused sequential RTP timestamps during 60fps capture,
+    // leading to 2x RTP time inflation and 10s+ browser jitter buffer growth.
+    // See issue #25.
+    enc.set_time_base(ff::Rational::new(1, 90_000));
+    // Explicit framerate is REQUIRED when time_base is not 1/fps, otherwise
+    // libx264 infers wrong fps from the 90kHz time_base and VBV rate control
+    // breaks. Per Oracle review round for #25.
+    enc.set_frame_rate(Some(ff::Rational::new(fps as i32, 1)));
+    enc.set_max_b_frames(0);
+
+    if codec_name == "libx264" {
+        // SAFETY: priv_data and codec context belong to the unopened encoder;
+        // each CString lives for the duration of its av_opt_set call.
+        unsafe {
+            let key = CString::new("preset").unwrap();
+            let val = CString::new("veryfast").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            let key = CString::new("tune").unwrap();
+            let val = CString::new("zerolatency").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            let key = CString::new("threads").unwrap();
+            let val = CString::new("6").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            // High profile via AVCodecContext.profile (not x264opts - x264 rejects it there).
+            // High enables CABAC + 8x8dct automatically.
+            (*enc.as_mut_ptr()).profile = ffi::AV_PROFILE_H264_HIGH;
+            // SAFETY: enc is a valid, initialized AVCodecContext from
+            // avcodec_alloc_context3. Setting level is a simple i32 field
+            // assignment on a properly aligned struct.
+            (*enc.as_mut_ptr()).level = 42; // H.264 Level 4.2 (up to 1440p@30)
+                                            // SAFETY: priv_data belongs to the unopened libx264 encoder context.
+                                            // `forced-idr` is an FFmpeg-level private option (not x264-native),
+                                            // so it must be set via av_opt_set, NOT via the x264opts string.
+                                            // With forced-idr=1, setting AV_PICTURE_TYPE_I on an input frame
+                                            // produces a true IDR NALU with inline SPS/PPS (repeat_headers=1).
+            let key = CString::new("forced-idr").unwrap();
+            let val = CString::new("1").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            let key = CString::new("x264opts").unwrap();
+            // x264's vbv-maxrate unit is kbit/s and vbv-bufsize is kbit (NOT bps).
+            // Confirmed via x264 source encoder/ratecontrol.c:658-661 which multiplies
+            // these values by 1000 to convert kbit -> bit at use site. Passing bps makes
+            // VBV effectively unbounded (5.5 Mbps becomes 5.5 Gbps, clipped to 2 Gbps).
+            // See https://github.com/mirror/x264/blob/c24e06c2e184345ceb33eb20a15d1024d9fd3497/encoder/ratecontrol.c#L658-L661
+            let vbv_maxrate_kbps = bitrate / 1000;
+            let vbv_bufsize_kbps = (bitrate / 4) / 1000;
+            let val = CString::new(format!(
+                "repeat_headers=1:vbv-maxrate={vbv_maxrate_kbps}:vbv-bufsize={vbv_bufsize_kbps}"
+            ))
+            .unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+        }
+    }
+
+    let opened = enc
+        .open()
+        .map_err(|e| anyhow::anyhow!("Failed to open {codec_name} encoder: {e}"))?;
+    tracing::info!("WebRTC encoder: {codec_name} {width}x{height} @ {fps}fps {bitrate}bps (profile High, preset veryfast)");
+    Ok(opened.0)
+}

src/avhw/state.rs

@@ -0,0 +1,109 @@
+use std::path::Path;
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+use std::time::Instant;
+
+use anyhow::Result;
+use ffmpeg_next as ff;
+
+use super::{AvHwFrameCtx, EncodeStages, EncodedH264Frame, SwEncEncode, SwEncImport};
+
+pub struct SwEncState {
+    import: SwEncImport,
+    encode: SwEncEncode,
+}
+
+// SAFETY: SwEncState owns import and encode state exclusively and existing sync callers move it
+// between threads only with external serialization; all FFI handles are accessed through &mut self.
+unsafe impl Send for SwEncState {}
+
+impl SwEncState {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        drm_device: &Path,
+        output_path: &Path,
+        width: u32,
+        height: u32,
+        enc_width: u32,
+        enc_height: u32,
+        fps: u32,
+        bitrate: u64,
+        gop_size: u32,
+    ) -> Result<Self> {
+        tracing::info!(
+            "SwEncState::new: GPU downscale {width}x{height} BGRA -> {enc_width}x{enc_height} NV12, software H.264"
+        );
+        let import = SwEncImport::new(drm_device, width, height, enc_width, enc_height, fps)?;
+        let encode =
+            SwEncEncode::new_muxer(output_path, enc_width, enc_height, fps, bitrate, gop_size)?;
+        Ok(Self { import, encode })
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn new_webrtc(
+        drm_device: &Path,
+        width: u32,
+        height: u32,
+        enc_width: u32,
+        enc_height: u32,
+        fps: u32,
+        bitrate: u64,
+        gop_size: u32,
+        tx: crossbeam_channel::Sender<EncodedH264Frame>,
+        webrtc_paused: Arc<AtomicBool>,
+    ) -> Result<Self> {
+        tracing::info!(
+            "SwEncState::new_webrtc: GPU downscale {width}x{height} BGRA -> {enc_width}x{enc_height} NV12, software H.264 -> WebRTC"
+        );
+        let import = SwEncImport::new(drm_device, width, height, enc_width, enc_height, fps)?;
+        let (dummy_tx, bitrate_rx) = crossbeam_channel::bounded(1);
+        drop(dummy_tx);
+        let (dummy_resolution_tx, resolution_rx) = crossbeam_channel::bounded(1);
+        drop(dummy_resolution_tx);
+        let encode = SwEncEncode::new_webrtc(
+            enc_width,
+            enc_height,
+            fps,
+            bitrate,
+            gop_size,
+            tx,
+            webrtc_paused,
+            bitrate_rx,
+            resolution_rx,
+        )?;
+        Ok(Self { import, encode })
+    }
+
+    pub fn frames_rgb(&self) -> &AvHwFrameCtx {
+        self.import.frames_rgb()
+    }
+
+    pub fn encode_frame(&mut self, hw_frame: &ff::frame::Video) -> Result<EncodeStages> {
+        // SW path: import_and_scale bundles GPU filter graph (scale) + GPU->CPU
+        // readback (transfer) into one call. Timing them separately requires
+        // extending import_and_scale's signature; for now both roll into
+        // scale_us and transfer_us stays 0 with this comment as the honest
+        // statement. Oracle audit 2026-06-28 step 4.
+        let scale_start = Instant::now();
+        let cpu_frame = self.import.import_and_scale(hw_frame)?;
+        let scale_us = scale_start.elapsed().as_micros() as u64;
+
+        let encode_start = Instant::now();
+        self.encode.encode_cpu_frame(&cpu_frame)?;
+        let encode_us = encode_start.elapsed().as_micros() as u64;
+
+        Ok(EncodeStages {
+            scale_us,
+            transfer_us: 0,
+            encode_us,
+        })
+    }
+
+    pub fn flush(&mut self) -> Result<()> {
+        for frame in self.import.flush_import()? {
+            self.encode.encode_cpu_frame(&frame)?;
+        }
+        self.encode.flush()?;
+        self.encode.write_trailer_if_needed()
+    }
+}

src/avhw/types.rs

@@ -0,0 +1,88 @@
+/// Commands sent from the WebRTC thread to the SW encoder when the
+/// bandwidth estimate changes significantly.
+pub enum BitrateCommand {
+    UpdateBitrate {
+        target_bps: u64,
+    },
+    UpdateResolution {
+        width: u32,
+        height: u32,
+    },
+    /// Force the next encoded frame to be an IDR. Sent by the WebRTC thread
+    /// in response to str0m `Event::KeyframeRequest` or a resolution change.
+    ForceKeyframe,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct ResolutionChange {
+    pub width: u32,
+    pub height: u32,
+}
+
+/// Per-frame timing snapshot for the software encoder, consumed by the stats
+/// thread. `sws_us` measures NV12->YUV420P conversion, `encode_us` measures
+/// `avcodec_send_frame` + drain, and `output_bytes` counts encoded bytes
+/// produced by libavcodec (even if downstream delivery later drops them).
+#[derive(Default, Clone, Copy, Debug)]
+pub struct SwEncodeTiming {
+    pub sws_us: u64,
+    pub encode_us: u64,
+    pub output_bytes: usize,
+}
+
+/// Outcome of a single `encode_cpu_frame` call. Used by the encode thread
+/// to decide whether to report timing stats (only real encodes tick encoded_fps).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EncodeOutcome {
+    /// Frame was actually encoded and produced output bytes.
+    Encoded,
+    /// Frame was dropped because WebRTC is paused (no client connected).
+    SkippedPaused,
+    /// Frame was dropped because the encoder is in disconnected state.
+    SkippedDisconnected,
+    /// Frame was dropped because its Y-plane hash matched the previous frame.
+    SkippedDuplicate,
+}
+
+/// Per-stage timing breakdown for one encode cycle on the hardware path.
+/// Returned by `EncState::encode_frame` so callers can fold the numbers
+/// into `crate::stats::FrameTimings`. `transfer_us` is always 0 on the HW
+/// path because the frame stays on the GPU; the SW path's struct (if added
+/// later) would carry a real readback measurement.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct EncodeStages {
+    pub scale_us: u64,
+    pub transfer_us: u64,
+    pub encode_us: u64,
+}
+
+/// Encoded H.264 frame with timing metadata for WebRTC output.
+///
+/// MP4 file output (FrameOutput::Muxer) does NOT use this - it writes via
+/// avformat which preserves PTS internally. WebRTC output (FrameOutput::Channel)
+/// requires explicit PTS propagation so RTP timestamps reflect real capture time.
+/// Without this, WebRTC clients' jitter buffers grow to seconds under
+/// damage-driven variable frame rate. See issue #24.
+#[derive(Debug)]
+pub struct EncodedH264Frame {
+    /// H.264 NAL byte stream (Annex B or AVCC depending on encoder configuration)
+    pub data: Vec<u8>,
+    /// PTS in encoder time_base units (1/fps seconds), normalized so first frame = 0.
+    /// Derived from real capture time, NOT frame counter.
+    pub pts_ticks: i64,
+    /// Wall-clock capture time, propagated from CpuNv12Frame for frame_age stat.
+    pub capture_time: std::time::Instant,
+}
+
+/// Owned CPU NV12 frame data for cross-thread transfer.
+/// Produced by main thread (VAAPI import + GPU scale + transfer), consumed by encode thread.
+pub struct CpuNv12Frame {
+    pub y_data: Vec<u8>,
+    pub uv_data: Vec<u8>,
+    pub y_stride: usize,
+    pub uv_stride: usize,
+    pub pts: i64,
+    /// Wall-clock time when this frame was captured (PipeWire delivery).
+    /// Used for frame_age stat: time from capture to WebRTC send.
+    pub capture_time: std::time::Instant,
+}

src/avhw/util.rs

@@ -0,0 +1,20 @@
+use ffmpeg_next::ffi;
+
+/// Convert an FFmpeg error code to a human-readable string.
+pub(crate) fn av_err_to_string(err: i32) -> String {
+    let mut buf = vec![0u8; 128];
+    // SAFETY: buf points to 128 writable bytes and lives for the duration of
+    // av_strerror.
+    unsafe {
+        ffi::av_strerror(err, buf.as_mut_ptr() as *mut i8, buf.len());
+    }
+    String::from_utf8_lossy(&buf)
+        .trim_end_matches('\0')
+        .to_string()
+}
+
+/// Format an FFmpeg error code with both numeric value and description.
+/// Example output: "error -22 (Invalid argument)"
+pub(crate) fn ff_err(ret: i32) -> String {
+    format!("error {ret} ({})", av_err_to_string(ret))
+}

src/bin/sw_encode_bench.rs

@@ -62,22 +62,32 @@ fn pix_fmt(p: ff::format::Pixel) -> ffi::AVPixelFormat {
 }
 
 fn receive_first_frame(cap: &CapPortal) -> Result<wl_webrtc::cap_portal::PwDmaBufFrame> {
+    // Drain-and-wait loop that mirrors production's repeated-poll semantics
+    // (state_portal.rs::poll_and_encode driven by main.rs's outer loop), but with
+    // a single bounded 10s total deadline appropriate for a bench tool. Unlike a
+    // single 10s blocking wait, this loop actually iterates: each turn drains ALL
+    // pending control events (the ctrl channel is bounded to 8 — a single
+    // if-let would silently miss backlog) and then waits a short slice for a
+    // frame, so StreamEnded/Error arriving mid-wait are observed within ~200ms.
+    const TOTAL_DEADLINE: std::time::Duration = std::time::Duration::from_secs(10);
+    const WAIT_SLICE: std::time::Duration = std::time::Duration::from_millis(200);
+    let deadline = Instant::now() + TOTAL_DEADLINE;
     loop {
-        if let Ok(ctrl) = cap.event_receiver().try_recv() {
+        while let Ok(ctrl) = cap.event_receiver().try_recv() {
             match ctrl {
                 PwCtrlEvent::StreamEnded => bail!("PipeWire stream ended before first frame"),
                 PwCtrlEvent::FormatChanged { .. } => {}
                 PwCtrlEvent::Error(e) => bail!("PipeWire error: {e}"),
             }
         }
-        match cap
+        let remaining = match deadline.checked_duration_since(Instant::now()) {
-            .frame_receiver()
+            Some(r) if !r.is_zero() => r,
-            .recv_timeout(std::time::Duration::from_secs(10))
+            _ => bail!("Timeout waiting for first frame (10s)"),
-        {
+        };
+        let slice = remaining.min(WAIT_SLICE);
+        match cap.frame_receiver().recv_timeout(slice) {
             Ok(frame) => return Ok(frame),
-            Err(crossbeam_channel::RecvTimeoutError::Timeout) => {
+            Err(crossbeam_channel::RecvTimeoutError::Timeout) => continue,
-                bail!("Timeout waiting for first frame (10s)");
-            }
             Err(crossbeam_channel::RecvTimeoutError::Disconnected) => {
                 bail!("PipeWire frame channel disconnected");
             }
@@ -142,6 +152,9 @@ fn main() -> Result<()> {
 
     println!("[3/4] Testing mmap on DMA-BUF...");
     let mmap_size = (src_stride as usize) * (src_height as usize);
+    // SAFETY: first_frame.fd is an open DMA-BUF; offset/size come from PipeWire's
+    // negotiated format. PROT_READ+MAP_SHARED is the standard read-only DMA-BUF
+    // mapping. Returns MAP_FAILED on error (checked below).
     let mmap_ptr = unsafe {
         libc::mmap(
             ptr::null_mut(),
@@ -173,6 +186,8 @@ fn main() -> Result<()> {
         "[3/4] mmap SUCCESS — CPU can read DMA-BUF ({:.1} MB)\n",
         mmap_size as f64 / 1024.0 / 1024.0
     );
+    // SAFETY: mmap_ptr was returned by mmap above and is not MAP_FAILED (checked);
+    // mmap_size matches the original mapping. POSIX munmap(2) releases the mapping.
     unsafe {
         libc::munmap(mmap_ptr, mmap_size);
     }
@@ -205,6 +220,9 @@ fn main() -> Result<()> {
 
     let codec_name = codec.name();
     if codec_name == "libx264" {
+        // SAFETY: enc is a valid AVCodecContext for the not-yet-opened encoder;
+        // priv_data is the x264 private options struct. All CStrings live across
+        // both av_opt_set calls. These set the x264 "preset" and "tune" options.
         unsafe {
             let key = CString::new("preset").unwrap();
             let val = CString::new("veryfast").unwrap();
@@ -220,6 +238,8 @@ fn main() -> Result<()> {
 
     // Create output format context via FFI
     let mut fmt_ctx_ptr: *mut ffi::AVFormatContext = ptr::null_mut();
+    // SAFETY: fmt_ctx_ptr is an out-parameter initialized by FFmpeg; output_cstr
+    // lives across the call. Returns 0 on success; we check below.
     let ret = unsafe {
         ffi::avformat_alloc_output_context2(
             &mut fmt_ctx_ptr,
@@ -232,21 +252,30 @@ fn main() -> Result<()> {
         bail!("Failed to allocate output format context: error {ret}");
     }
 
+    // SAFETY: fmt_ctx_ptr is the valid output context allocated above.
+    // avformat_new_stream returns a pointer to a new AVStream or NULL on failure.
     let stream_ptr = unsafe { ffi::avformat_new_stream(fmt_ctx_ptr, ptr::null()) };
     if stream_ptr.is_null() {
         bail!("Failed to create new stream");
     }
 
+    // SAFETY: stream_ptr and enc_video.as_ptr() are valid pointers; codecpar is
+    // the output destination inside stream. avcodec_parameters_from_context copies
+    // encoder parameters into the stream's codecpar.
     let ret =
         unsafe { ffi::avcodec_parameters_from_context((*stream_ptr).codecpar, enc_video.as_ptr()) };
     if ret < 0 {
         bail!("Failed to copy encoder parameters: error {ret}");
     }
 
+    // SAFETY: stream_ptr and enc_video are valid; time_base is a plain AVRational
+    // field copied from encoder to stream.
     unsafe {
         (*stream_ptr).time_base = (*enc_video.as_ptr()).time_base;
     }
 
+    // SAFETY: fmt_ctx_ptr is valid; pb is the AVIOContext slot to initialize;
+    // output_cstr is a valid NUL-terminated path; AVIO_FLAG_WRITE is a constant.
     let ret = unsafe {
         ffi::avio_open(
             &mut (*fmt_ctx_ptr).pb,
@@ -261,17 +290,23 @@ fn main() -> Result<()> {
         );
     }
 
+    // SAFETY: fmt_ctx_ptr is fully configured (streams + pb set); NULL options
+    // is the default. Returns 0 on success.
     let ret = unsafe { ffi::avformat_write_header(fmt_ctx_ptr, ptr::null_mut()) };
     if ret < 0 {
         bail!("Failed to write header: error {ret}");
     }
 
+    // SAFETY: fmt_ctx_ptr is a fully initialized output context (header written).
+    // Output::wrap takes ownership of the pointer into a safe RAII wrapper.
     let mut octx = unsafe { ff::format::context::Output::wrap(fmt_ctx_ptr) };
 
     // Create sws_scale context: BGRZ (BGR0) -> YUV420P
     let bgr0_fmt = pix_fmt(ff::format::Pixel::BGRZ);
     let yuv420p_fmt = pix_fmt(ff::format::Pixel::YUV420P);
 
+    // SAFETY: all parameters are valid enum/pixel format values; NULL filters are
+    // allowed by FFmpeg. sws_getContext returns a heap-allocated SwsContext or NULL.
     let sws_ctx = unsafe {
         ffi::sws_getContext(
             src_width as i32,
@@ -291,6 +326,9 @@ fn main() -> Result<()> {
     }
 
     // Allocate reusable YUV frame
+    // SAFETY: av_frame_alloc returns NULL only on OOM. After allocation we set
+    // width/height/format fields and call av_frame_get_buffer to allocate plane
+    // data. On failure we free the frame via av_frame_free before bailing.
     let mut yuv_frame = unsafe {
         let mut f = ffi::av_frame_alloc();
         if f.is_null() {
@@ -349,6 +387,9 @@ fn main() -> Result<()> {
 
         let mmap_start = Instant::now();
         let frame_size = (frame.stride as usize) * (frame.height as usize);
+        // SAFETY: frame.fd is an open DMA-BUF owned by the frame; offset/size come
+        // from PipeWire's negotiated format. PROT_READ+MAP_SHARED for read-only
+        // DMA-BUF access. Returns MAP_FAILED on error (checked below).
         let mmap_ptr = unsafe {
             libc::mmap(
                 ptr::null_mut(),
@@ -369,8 +410,15 @@ fn main() -> Result<()> {
         stats.mmap_us.push(mmap_start.elapsed().as_micros() as u64);
 
         let scale_start = Instant::now();
+        // SAFETY: mmap_ptr is a valid mapping of frame_size bytes (checked above);
+        // constructing a read-only slice over it for the duration of sws_scale is
+        // sound as long as we don't hold it past munmap (we don't).
         let src_data = unsafe { std::slice::from_raw_parts(mmap_ptr as *const u8, frame_size) };
 
+        // SAFETY: yuv_frame and sws_ctx are valid; src_data is a valid slice of the
+        // mmap'd DMA-BUF for this frame. sws_scale reads src planes (BGR0 -> YUV420P)
+        // and writes into yuv_frame's data planes. av_frame_make_writable ensures
+        // yuv_frame is not shared before writing.
         unsafe {
             ffi::av_frame_make_writable(yuv_frame);
 
@@ -391,6 +439,8 @@ fn main() -> Result<()> {
             .scale_us
             .push(scale_start.elapsed().as_micros() as u64);
 
+        // SAFETY: mmap_ptr was returned by mmap above and is not MAP_FAILED; frame_size
+        // matches the original mapping. Release before dropping frame (which closes fd).
         unsafe {
             libc::munmap(mmap_ptr, frame_size);
         }
@@ -398,6 +448,9 @@ fn main() -> Result<()> {
 
         let encode_start = Instant::now();
 
+        // SAFETY: yuv_frame is allocated and writable; enc_video is the opened encoder.
+        // Setting pts is a plain i64 field write. avcodec_send_frame submits the frame
+        // for encoding; returns < 0 on error (we log and continue).
         unsafe {
             (*yuv_frame).pts = pts;
             pts += 1;
@@ -419,7 +472,7 @@ fn main() -> Result<()> {
             .push(frame_start.elapsed().as_micros() as u64);
 
         frames_encoded += 1;
-        if frames_encoded % 30 == 0 {
+        if frames_encoded.is_multiple_of(30) {
             let fps = frames_encoded as f64 / total_start.elapsed().as_secs_f64();
             println!(
                 "  [{}/{}] {:.1} FPS",
@@ -431,6 +484,8 @@ fn main() -> Result<()> {
     let total_elapsed = total_start.elapsed();
 
     println!("\nFlushing encoder...");
+    // SAFETY: enc_video is the opened encoder; passing NULL frame signals EOF to
+    // drain the encoder's internal pipeline. Returns < 0 on error (ignored here).
     unsafe {
         ffi::avcodec_send_frame(enc_video.as_mut_ptr(), ptr::null());
     }
@@ -440,6 +495,9 @@ fn main() -> Result<()> {
         .map_err(|e| anyhow::anyhow!("Failed to write trailer: {e}"))?;
 
     // Cleanup
+    // SAFETY: yuv_frame is the allocated frame from earlier (still owned by us);
+    // sws_ctx is the allocated sws context. av_frame_free and sws_freeContext take
+    // ownership and free their respective heap allocations.
     unsafe {
         ffi::av_frame_free(&mut yuv_frame as *mut _);
         ffi::sws_freeContext(sws_ctx);
@@ -526,6 +584,9 @@ fn drain_encoder(
 ) -> Result<()> {
     loop {
         let mut pkt = ff::Packet::empty();
+        // SAFETY: enc_video is the opened encoder; pkt is an empty Packet whose
+        // inner AVPacket pointer is valid. avcodec_receive_packet fills pkt with
+        // the next encoded packet, or returns EAGAIN/EOF when drained.
         let ret = unsafe { ffi::avcodec_receive_packet(enc_video.as_mut_ptr(), pkt.as_mut_ptr()) };
         if ret < 0 {
             if ret == ffi::AVERROR(ffi::EAGAIN) || ret == ffi::AVERROR_EOF {
@@ -536,6 +597,9 @@ fn drain_encoder(
         }
 
         let enc_tb = enc_video.time_base();
+        // SAFETY: octx.as_ptr() is a valid AVFormatContext; streams is a NULL-terminated
+        // array of AVStream*. We index [0] which exists because we created exactly one
+        // stream in setup. Reading time_base is a plain AVRational field access.
         let stream_tb = unsafe {
             let streams = (*octx.as_ptr()).streams;
             let st = *streams.add(0);

src/bin/vaapi_import_bench.rs

@@ -126,6 +126,9 @@ impl Drop for SwsContext {
 
 fn av_err_to_string(ret: i32) -> String {
     let mut buf = vec![0u8; 128];
+    // SAFETY: buf is a 128-byte Vec initialized to zeros; av_strerror writes at most
+    // buf.len() bytes (including NUL) into the buffer. The ret value is an FFmpeg
+    // error code. We treat the buffer as `*mut i8` for the C string out-param.
     unsafe {
         ffi::av_strerror(ret, buf.as_mut_ptr() as *mut i8, buf.len());
     }
@@ -134,22 +137,32 @@ fn av_err_to_string(ret: i32) -> String {
 }
 
 fn receive_first_frame(cap: &CapPortal) -> Result<wl_webrtc::cap_portal::PwDmaBufFrame> {
+    // Drain-and-wait loop that mirrors production's repeated-poll semantics
+    // (state_portal.rs::poll_and_encode driven by main.rs's outer loop), but with
+    // a single bounded 10s total deadline appropriate for a bench tool. Unlike a
+    // single 10s blocking wait, this loop actually iterates: each turn drains ALL
+    // pending control events (the ctrl channel is bounded to 8 — a single
+    // if-let would silently miss backlog) and then waits a short slice for a
+    // frame, so StreamEnded/Error arriving mid-wait are observed within ~200ms.
+    const TOTAL_DEADLINE: std::time::Duration = std::time::Duration::from_secs(10);
+    const WAIT_SLICE: std::time::Duration = std::time::Duration::from_millis(200);
+    let deadline = Instant::now() + TOTAL_DEADLINE;
     loop {
-        if let Ok(ctrl) = cap.event_receiver().try_recv() {
+        while let Ok(ctrl) = cap.event_receiver().try_recv() {
             match ctrl {
                 PwCtrlEvent::StreamEnded => bail!("PipeWire stream ended before first frame"),
                 PwCtrlEvent::FormatChanged { .. } => {}
                 PwCtrlEvent::Error(e) => bail!("PipeWire error: {e}"),
             }
         }
-        match cap
+        let remaining = match deadline.checked_duration_since(Instant::now()) {
-            .frame_receiver()
+            Some(r) if !r.is_zero() => r,
-            .recv_timeout(std::time::Duration::from_secs(10))
+            _ => bail!("Timeout waiting for first frame (10s)"),
-        {
+        };
+        let slice = remaining.min(WAIT_SLICE);
+        match cap.frame_receiver().recv_timeout(slice) {
             Ok(frame) => return Ok(frame),
-            Err(crossbeam_channel::RecvTimeoutError::Timeout) => {
+            Err(crossbeam_channel::RecvTimeoutError::Timeout) => continue,
-                bail!("Timeout waiting for first frame (10s)");
-            }
             Err(crossbeam_channel::RecvTimeoutError::Disconnected) => {
                 bail!("PipeWire frame channel disconnected");
             }
@@ -163,6 +176,9 @@ fn drain_encoder(
 ) -> Result<()> {
     loop {
         let mut pkt = ff::Packet::empty();
+        // SAFETY: enc_video is the opened encoder; pkt is an empty Packet whose inner
+        // AVPacket pointer is valid. avcodec_receive_packet fills pkt with the next
+        // encoded packet or returns EAGAIN/EOF when drained.
         let ret = unsafe { ffi::avcodec_receive_packet(enc_video.as_mut_ptr(), pkt.as_mut_ptr()) };
         if ret < 0 {
             if ret == ffi::AVERROR(ffi::EAGAIN) || ret == ffi::AVERROR_EOF {
@@ -172,6 +188,9 @@ fn drain_encoder(
             break;
         }
         let enc_tb = enc_video.time_base();
+        // SAFETY: octx.as_ptr() is a valid AVFormatContext; streams is a NULL-terminated
+        // array; we index [0] which exists because we created exactly one stream in
+        // setup. Reading time_base is a plain AVRational field access.
         let stream_tb = unsafe {
             let streams = (*octx.as_ptr()).streams;
             let st = *streams.add(0);
@@ -398,17 +417,10 @@ fn import_frame(
 ) -> Result<ff::frame::Video> {
     // SAFETY: frames_ctx is a live VAAPI frames context configured for the capture format; frame
     // carries a valid DMA-BUF fd and metadata from PipeWire for the duration of the call.
+    // SAFETY: frames_ctx is a valid VAAPI frames context; `frame` carries the
+    // DMA-BUF metadata read by the function.
     unsafe {
-        import_dma_buf_to_vaapi(
+        import_dma_buf_to_vaapi(frames_ctx.as_ptr(), frame)
-            frames_ctx.as_ptr(),
-            frame.fd.as_raw_fd(),
-            frame.width,
-            frame.height,
-            frame.format,
-            frame.modifier,
-            frame.stride,
-            frame.offset,
-        )
     }
 }
 
@@ -596,7 +608,7 @@ fn run_cpu_pipeline(
         stats.total_us.push(total_us);
         stats.frames_encoded += 1;
 
-        if stats.frames_encoded <= 3 || stats.frames_encoded % 30 == 0 {
+        if stats.frames_encoded <= 3 || stats.frames_encoded.is_multiple_of(30) {
             println!(
                 "       CPU frame {:>4}/{frames}: import={:.2}ms transfer={:.2}ms scale={:.2}ms encode={:.2}ms total={:.2}ms",
                 stats.frames_encoded,
@@ -754,7 +766,7 @@ fn run_gpu_pipeline(
         stats.total_us.push(total_us);
         stats.frames_encoded += 1;
 
-        if stats.frames_encoded <= 3 || stats.frames_encoded % 30 == 0 {
+        if stats.frames_encoded <= 3 || stats.frames_encoded.is_multiple_of(30) {
             println!(
                 "       GPU frame {:>4}/{frames}: import={:.2}ms filter={:.2}ms transfer={:.2}ms format={:.2}ms encode={:.2}ms total={:.2}ms",
                 stats.frames_encoded,
@@ -919,17 +931,13 @@ fn main() -> Result<()> {
         AvHwFrameCtx::for_capture(&hw_dev, src_width, src_height, ff::format::Pixel::BGRA)?;
     println!("       VAAPI frames context created OK (sw_format=BGRA)");
 
+    // SAFETY: delegates to avhw::import_dma_buf_to_vaapi (itself an unsafe fn).
+    // frames_ctx is a valid AVBufferRef from AvHwFrameCtx::for_capture above;
+    // `first_frame` is the PipeWire-formatted PwDmaBufFrame whose metadata the
+    // function reads directly. See that function's own SAFETY contract for the
+    // full rationale.
     let vaapi_frame = unsafe {
-        import_dma_buf_to_vaapi(
+        import_dma_buf_to_vaapi(frames_ctx.as_ptr(), &first_frame)
-            frames_ctx.as_ptr(),
-            first_frame.fd.as_raw_fd(),
-            first_frame.width,
-            first_frame.height,
-            first_frame.format,
-            first_frame.modifier,
-            first_frame.stride,
-            first_frame.offset,
-        )
     };
 
     match &vaapi_frame {
@@ -949,6 +957,9 @@ fn main() -> Result<()> {
 
             let mmap_size = (first_frame.stride as usize) * (first_frame.height as usize);
             let mmap_start = Instant::now();
+            // SAFETY: first_frame.fd is an open DMA-BUF; offset/size from PipeWire.
+            // PROT_READ+MAP_SHARED is the standard read-only DMA-BUF mapping. Returns
+            // MAP_FAILED on error (checked below).
             let mmap_ptr = unsafe {
                 libc::mmap(
                     ptr::null_mut(),
@@ -970,6 +981,8 @@ fn main() -> Result<()> {
                     mmap_size as f64 / 1024.0 / 1024.0,
                     mmap_elapsed.as_secs_f64() * 1000.0
                 );
+                // SAFETY: mmap_ptr is a valid mapping (MAP_FAILED path was handled
+                // above); mmap_size matches the original mapping. POSIX munmap(2).
                 unsafe {
                     libc::munmap(mmap_ptr, mmap_size);
                 }

src/cap_portal.rs

@@ -95,6 +95,23 @@ pub struct PwDmaBufFrame {
     pub pts: i64,
 }
 
+/// PipeWire-negotiated video format snapshot, stashed in a `Cell` for cross-callback
+/// sharing (format-change callback writes it; process callback reads it). The four
+/// fields are the minimal subset of `PwDmaBufFrame`'s metadata that the process
+/// callback needs to construct the frame once a buffer arrives.
+///
+/// `Copy` is required because we store it inside `Cell<Option<PortalFormatInfo>>`;
+/// `Cell` requires its contents to be `Copy` (no borrowed interior state).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PortalFormatInfo {
+    pub width: u32,
+    pub height: u32,
+    /// DRM FourCC format code (e.g. `0x34325258` for XR24 / XRGB8888).
+    pub drm_format: u32,
+    /// DRM format modifier describing buffer layout (linear, tiling, etc.).
+    pub modifier: u64,
+}
+
 /// PipeWire 控制事件枚举
 ///
 /// 从 PipeWire 捕获线程发送给消费者的控制事件。
@@ -158,6 +175,9 @@ impl CapPortal {
         let (frame_tx, frame_rx) = bounded(1);
         let (event_tx, event_rx) = bounded(8);
 
+        // SAFETY: eventfd(2) is a POSIX syscall with no preconditions; the init value
+        // and flags (CLOEXEC + NONBLOCK) are valid. Returns either a fresh fd (>= 0)
+        // or -1 on error, which we check immediately below.
         let efd = unsafe { libc::eventfd(0, libc::EFD_CLOEXEC | libc::EFD_NONBLOCK) };
         if efd < 0 {
             return Err(anyhow::anyhow!(
@@ -165,9 +185,13 @@ impl CapPortal {
                 std::io::Error::last_os_error()
             ));
         }
+        // SAFETY: `efd` is the open eventfd we just created (>= 0 checked above) and
+        // own. dup(2) returns either a fresh fd or -1.
         let write_fd = unsafe { libc::dup(efd) };
         if write_fd < 0 {
             let err = std::io::Error::last_os_error();
+            // SAFETY: `efd` is still the open eventfd we own; closing on the error
+            // path before returning to avoid fd leak.
             unsafe { libc::close(efd) };
             return Err(anyhow::anyhow!("dup eventfd failed: {err}"));
         }
@@ -178,6 +202,10 @@ impl CapPortal {
             frame_tx,
             event_tx,
             dropped: pw_dropped.clone(),
+            // SAFETY: `efd` is the freshly-created eventfd (>= 0 checked above) and we
+            // are its sole owner. OwnedFd::from_raw_fd takes ownership and will close()
+            // it on Drop. Ownership transfers into PwThreadCtx and then into the
+            // PipeWire thread via pipewire_thread.
             shutdown_read: unsafe { OwnedFd::from_raw_fd(efd) },
             pw_fd,
             node_id,
@@ -190,11 +218,16 @@ impl CapPortal {
                 pipewire_thread(ctx);
             })
             .map_err(|e| {
+                // SAFETY: `write_fd` is the open dup'd eventfd we own (>= 0 checked
+                // above); closing on thread-spawn failure to avoid fd leak.
                 unsafe { libc::close(write_fd) };
                 anyhow::anyhow!("thread spawn failed: {e}")
             })?;
 
         Ok(Self {
+            // SAFETY: `write_fd` is the freshly-dup'd eventfd (>= 0 checked above) and
+            // we are its sole owner. OwnedFd::from_raw_fd takes ownership and will
+            // close() it on Drop (which fires when CapPortal is dropped).
             shutdown_fd: unsafe { OwnedFd::from_raw_fd(write_fd) },
             frame_rx,
             event_rx,
@@ -433,6 +466,9 @@ fn verify_secure_dir(path: &std::path::Path) -> bool {
                 return false;
             }
             // Must be owned by current user
+            // SAFETY: libc::getuid has no preconditions and cannot fail; it simply
+            // returns the calling process's real user ID.
+    // SAFETY: libc::getuid has no preconditions and cannot fail.
     if meta.uid() != unsafe { libc::getuid() } {
                 tracing::warn!(
                     "Token parent dir not owned by current user: {}",
@@ -511,6 +547,7 @@ fn load_restore_token_from(path: PathBuf) -> Option<String> {
         tracing::warn!("Token path is not a regular file: {}", path.display());
         return None;
     }
+    // SAFETY: libc::getuid has no preconditions and cannot fail.
     if meta.uid() != unsafe { libc::getuid() } {
         tracing::warn!("Token file not owned by current user: {}", path.display());
         return None;
@@ -604,6 +641,9 @@ impl Drop for CapPortal {
         // Signal the PipeWire loop to quit via eventfd.
         // eventfd write is a kernel syscall — thread-safe and lock-free.
         let val: u64 = 1u64;
+        // SAFETY: shutdown_fd is a valid open eventfd (owned by Self); the buffer is
+        // a stack u64 of size 8 bytes which matches the count argument. POSIX write(2)
+        // is the standard fd-write syscall; eventfd writes must be exactly 8 bytes.
         let _ = unsafe {
             libc::write(
                 self.shutdown_fd.as_raw_fd(),
@@ -657,7 +697,7 @@ fn pipewire_thread(ctx: PwThreadCtx) {
         shutdown_read,
         pw_fd,
         node_id,
-        fps,
+        fps: _,
     } = ctx;
 
     let mainloop = match pw::main_loop::MainLoopBox::new(None) {
@@ -721,7 +761,7 @@ fn pipewire_thread(ctx: PwThreadCtx) {
         }
     };
 
-    let format_info: Rc<Cell<Option<(u32, u32, u32, u64)>>> = Rc::new(Cell::new(None));
+    let format_info: Rc<Cell<Option<PortalFormatInfo>>> = Rc::new(Cell::new(None));
 
     let event_tx_state = event_tx.clone();
     let _listener = stream
@@ -773,9 +813,14 @@ fn pipewire_thread(ctx: PwThreadCtx) {
                 let max_framerate = info.max_framerate();
                 // 保存协商后的格式信息，供 process 回调读取
                 let previous_format = format_info.get();
-                format_info.set(Some((width, height, drm_format, modifier)));
+                format_info.set(Some(PortalFormatInfo {
-                if let Some((previous_width, previous_height, _, _)) = previous_format {
+                    width,
-                    if width != previous_width || height != previous_height {
+                    height,
+                    drm_format,
+                    modifier,
+                }));
+                if let Some(prev) = previous_format {
+                    if width != prev.width || height != prev.height {
                         tracing::warn!(
                             "PipeWire dimensions changed: {}x{} (format renegotiation)",
                             width,
@@ -801,8 +846,20 @@ fn pipewire_thread(ctx: PwThreadCtx) {
         .process({
             let format_info = format_info.clone();
             let frame_tx = frame_tx.clone();
-            let dropped = dropped;
             move |stream, _| {
+                // SAFETY: raw_buf ownership invariant — PipeWire's process callback
+                // contract requires that every buffer acquired via `dequeue_raw_buffer`
+                // is returned to the queue EXACTLY ONCE via `queue_raw_buffer` before
+                // the callback returns — on every exit path, success or error. Failure
+                // to requeue leaks the buffer slot and eventually stalls the stream.
+                //
+                // Audit map of this closure (verified 2026-06-28):
+                //   - null raw_buf  (dequeue returned NULL) → nothing to requeue, return.
+                //   - null spa_buf / no data / bad fd / null chunk / no format_info /
+                //     invalid dims / dup_fd < 0 → all requeue before early-return.
+                //   - success (try_send Ok / Full / Disconnected) → final requeue at end.
+                // The fd ownership is independent: dup() creates a fresh fd that lives
+                // inside PwDmaBufFrame; on try_send error the frame Drops and closes it.
                 let raw_buf = unsafe { stream.dequeue_raw_buffer() };
                 if raw_buf.is_null() {
                     tracing::trace!("process: null raw_buf");
@@ -810,36 +867,49 @@ fn pipewire_thread(ctx: PwThreadCtx) {
                 }
 
                 // 获取 SPA buffer 结构体，包含数据数组、元数据等
+                // SAFETY: raw_buf was checked non-null above. `pw_buffer.buffer` is a
+                // valid raw pointer for the lifetime of raw_buf (PipeWire keeps the
+                // buffer alive until we queue it back).
                 let spa_buf = unsafe { (*raw_buf).buffer };
                 if spa_buf.is_null() {
                     tracing::trace!("process: null spa_buf");
+                    // SAFETY: raw_buf is the non-null buffer we still own; returning it.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 }
 
                 // 获取 buffer 中的数据项数量和数据指针
                 // 对于 DMA-BUF 帧，通常只有 1 个数据项（包含 fd）
+                // SAFETY: spa_buf checked non-null above; `n_datas` is a plain u32 field.
                 let n_datas = unsafe { (*spa_buf).n_datas };
+                // SAFETY: same as above; `datas` is a raw pointer field, may be null.
                 let datas_ptr = unsafe { (*spa_buf).datas };
                 if n_datas == 0 || datas_ptr.is_null() {
                     tracing::trace!("process: no data (n_datas={n_datas})");
+                    // SAFETY: raw_buf still owned, returning it.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 }
 
                 // 从第一个数据项中获取 DMA-BUF 文件描述符
                 // 通过 libspa 的 Data 包装类型安全地访问 SPA 数据结构
+                // SAFETY: datas_ptr is non-null and n_datas > 0 (checked above). We cast
+                // to pw::spa::buffer::Data and take a shared borrow; PipeWire does not
+                // mutate the data array during a process cycle, so a shared reference
+                // for the duration of this callback is sound.
                 let data_ref: &pw::spa::buffer::Data =
                     unsafe { &*(datas_ptr as *const pw::spa::buffer::Data) };
                 let fd = data_ref.fd();
                 if fd < 0 {
                     tracing::trace!("process: invalid fd={fd}");
+                    // SAFETY: raw_buf still owned, returning it.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 }
 
                 if data_ref.as_raw().chunk.is_null() {
                     tracing::trace!("process: null chunk");
+                    // SAFETY: raw_buf still owned, returning it.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 }
@@ -850,6 +920,12 @@ fn pipewire_thread(ctx: PwThreadCtx) {
                 // 从 SPA_META_Header 元数据中提取 PTS (显示时间戳)
                 // 遍历 buffer 的所有元数据项，查找 Header 类型的元数据
                 // PTS 可用于音视频同步和帧率控制
+                // SAFETY: spa_buf is non-null. `metas` is checked for null before
+                // iteration. We iterate `i in 0..n_metas` reading shared POD fields
+                // (type_, size, data) — PipeWire keeps the meta array immutable during
+                // a process cycle. The size guard (`meta.size >= size_of::<spa_meta_header>()`)
+                // and null-data check before reading ensure we never read past the
+                // meta's actual extent.
                 let pts: i64 = unsafe {
                     let mut pts_val: i64 = 0;
                     let n_metas = (*spa_buf).n_metas;
@@ -872,12 +948,15 @@ fn pipewire_thread(ctx: PwThreadCtx) {
                 };
 
                 // 验证格式信息已协商完成，且分辨率和格式有效
-                let Some((width, height, format, modifier)) = format_info.get() else {
+                let Some(fmt) = format_info.get() else {
+                    // SAFETY: raw_buf still owned, returning it.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 };
+                let PortalFormatInfo { width, height, drm_format: format, modifier } = fmt;
                 if width == 0 || height == 0 || format == 0 {
                     tracing::trace!("process: invalid dimensions {width}x{height} format={format}");
+                    // SAFETY: raw_buf still owned, returning it.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 }
@@ -885,15 +964,27 @@ fn pipewire_thread(ctx: PwThreadCtx) {
                 // 复制 DMA-BUF 文件描述符
                 // 必须 dup，因为原始 fd 由 PipeWire 管理，我们不能持有它
                 // dup 后的 fd 由 PwDmaBufFrame 持有，生命周期独立于 PipeWire buffer
+                // SAFETY: `fd` is the open DMA-BUF fd reported by PipeWire (>= 0 checked
+                // above). libc::dup is the standard POSIX fd duplication call. The
+                // original `fd` remains owned by PipeWire (returned with raw_buf later).
                 let dup_fd = unsafe { libc::dup(fd) };
                 if dup_fd < 0 {
+                    // SAFETY: raw_buf still owned, returning it. No fd cleanup needed
+                    // because dup() failed and never returned a new fd.
                     unsafe { stream.queue_raw_buffer(raw_buf) };
                     return;
                 }
 
                 // 构建帧数据对象，所有必要的帧信息已收集完毕
+                // SAFETY: `dup_fd` is a freshly-dup'd open file descriptor (>= 0 checked
+                // above) and we are its sole owner. OwnedFd::from_raw_fd takes ownership
+                // and will close() it on Drop. The fd's lifecycle is independent of
+                // raw_buf: whether try_send succeeds (frame moves into the channel) or
+                // fails (Full/Disconnected — the error payload owns the frame and drops
+                // it at the end of the match arm), exactly one close() occurs per dup().
+                let frame_fd = unsafe { OwnedFd::from_raw_fd(dup_fd) };
                 let frame = PwDmaBufFrame {
-                    fd: unsafe { OwnedFd::from_raw_fd(dup_fd) },
+                    fd: frame_fd,
                     offset,
                     stride,
                     modifier,
@@ -910,6 +1001,8 @@ fn pipewire_thread(ctx: PwThreadCtx) {
                     }
                     Err(crossbeam_channel::TrySendError::Disconnected(_)) => {}
                 }
+                // SAFETY: final exactly-once requeue of raw_buf. Every path above
+                // either returned early with its own requeue, or falls through to here.
                 unsafe { stream.queue_raw_buffer(raw_buf) };
             }
         })
@@ -949,6 +1042,10 @@ fn pipewire_thread(ctx: PwThreadCtx) {
         move |fd| {
             // Drain the eventfd so it doesn't re-trigger
             let mut buf: u64 = 0;
+            // SAFETY: `fd` is the registered eventfd owned by the mainloop source; the
+            // buffer is a stack u64 of 8 bytes matching the count argument. POSIX
+            // read(2) is the standard fd-read syscall; eventfd semantics require the
+            // 8-byte buffer.
             let _ = unsafe {
                 libc::read(
                     fd.as_raw_fd(),

src/cap_wlr_screencopy.rs

@@ -21,9 +21,9 @@ pub struct CapWlrScreencopy {
 }
 
 impl CaptureSource for CapWlrScreencopy {
-    /// Unit type: wlr-screencopy is fully asynchronous — `alloc_frame()`
+    /// Unit type: wlr-screencopy is fully asynchronous — frame allocation is
-    /// always returns `None`. The frame object is created by Dispatch
+    /// driven by Dispatch impls calling `manager.capture_output()`, so there
-    /// impls calling `manager.capture_output()`, not by this method.
+    /// is no synchronous `alloc_frame`-style API on this trait.
     type Frame = ();
 
     fn new(
@@ -40,14 +40,6 @@ impl CaptureSource for CapWlrScreencopy {
         })
     }
 
-    fn alloc_frame(&mut self) -> Option<Self::Frame> {
-        // wlr-screencopy is asynchronous: the Dispatch impl creates a new
-        // ZwlrScreencopyFrameV1 which triggers the buffer allocation flow
-        // (buffer event → negotiate format → create DMA-BUF). This method
-        // always returns None.
-        None
-    }
-
     fn queue_copy(&mut self, buffer: &WlBuffer, _qh: &QueueHandle<State<Self>>) {
         if let Some(frame) = &self.current_frame {
             frame.copy(buffer);

src/main.rs

@@ -148,6 +148,9 @@ fn run_wlr_screencopy(args: Args) -> Result<()> {
             revents: 0,
         };
         // timeout=0 表示非阻塞，立即返回当前 fd 状态
+        // SAFETY: `pfd` is a stack-allocated libc::pollfd initialized above with a
+        // valid wayland_fd and POLLIN events; nfds=1 matches the single-element
+        // array; timeout=0 is non-blocking. POSIX poll(2) writes revents in place.
         let ret = unsafe { libc::poll(&mut pfd, 1, 0) };
         tracing::info!(
             "Raw poll on wayland fd={wayland_fd}: ret={ret}, revents={}",
@@ -173,7 +176,7 @@ fn run_wlr_screencopy(args: Args) -> Result<()> {
     // 注册 SIGINT / SIGTERM 信号用于优雅退出
     // signal_hook_mio 将 Unix 信号转换为 fd 可读事件，
     // 这样信号也可以通过 epoll 统一监听，不需要单独的信号处理器
-    let mut signals = signal_hook_mio::v1_0::Signals::new(&[
+    let mut signals = signal_hook_mio::v1_0::Signals::new([
         signal_hook::consts::SIGINT,  // Ctrl+C
         signal_hook::consts::SIGTERM, // kill 命令默认信号
     ])?;
@@ -310,7 +313,7 @@ fn run_portal_pipewire(args: Args) -> Result<()> {
     // Set up signal handling only (no Wayland fd needed)
     // Portal 后端不需要监听 Wayland fd，只需处理 Unix 信号
     // 因为帧数据是通过 PipeWire 独立投递的，不走 Wayland 协议
-    let mut signals = signal_hook_mio::v1_0::Signals::new(&[
+    let mut signals = signal_hook_mio::v1_0::Signals::new([
         signal_hook::consts::SIGINT,
         signal_hook::consts::SIGTERM,
     ])?;

src/state.rs

@@ -65,8 +65,6 @@ pub trait CaptureSource: Sized + 'static {
         qh: &QueueHandle<State<Self>>,
     ) -> Result<Self>;
 
-    fn alloc_frame(&mut self) -> Option<Self::Frame>;
-
     fn queue_copy(&mut self, buffer: &WlBuffer, qh: &QueueHandle<State<Self>>);
 
     fn on_done_with_frame(&mut self, frame: Self::Frame);
@@ -83,6 +81,7 @@ pub struct OutputInfo {
     pub logical_position: (i32, i32),
 }
 
+#[derive(Default)]
 pub struct PartialOutputInfo {
     pub name: Option<String>,
     /// Name from wl_output::Name (v4) — used to match wlr-output-management heads
@@ -95,22 +94,11 @@ pub struct PartialOutputInfo {
     pub done_count: u32,
 }
 
-impl Default for PartialOutputInfo {
-    fn default() -> Self {
-        Self {
-            name: None,
-            wl_name: None,
-            transform: None,
-            physical_size: None,
-            logical_position: None,
-            mode_size: None,
-            done_count: 0,
-        }
-    }
-}
 
 /// Stores head info from wlr-output-management for name-based matching with wl_output.
-struct WlrHeadInfo {
+// `pub(crate)` (not module-private): exposed via `EncConstructionStage::ProbingOutputs.wlr_heads`
+// which is reached from main.rs during the wlr-screencopy probing loop.
+pub(crate) struct WlrHeadInfo {
     position: Option<(i32, i32)>,
 }
 
@@ -138,7 +126,7 @@ impl StreamingEncoder {
         }
     }
 
-    fn encode_frame(&mut self, hw_frame: &ffmpeg_next::frame::Video) -> anyhow::Result<()> {
+    fn encode_frame(&mut self, hw_frame: &ffmpeg_next::frame::Video) -> anyhow::Result<crate::avhw::EncodeStages> {
         match self {
             StreamingEncoder::Mp4(enc) => enc.encode_frame(hw_frame),
             StreamingEncoder::WebRtc(enc) => enc.encode_frame(hw_frame),
@@ -156,8 +144,14 @@ impl StreamingEncoder {
 // ---------------------------------------------------------------------------
 // EncConstructionStage
 // ---------------------------------------------------------------------------
+//
+// `pub(crate)` (not `pub`): this enum leaks the private `WlrHeadInfo` type via
+// its `wlr_heads` field, and the construction-stage state machine is an
+// internal implementation detail. Crate-internal consumers (main.rs) get there
+// via `crate::state::`; there is no need to expose this across the crate
+// boundary. See Oracle audit 2026-06-28.
 
-pub enum EncConstructionStage<S: CaptureSource> {
+pub(crate) enum EncConstructionStage<S: CaptureSource> {
     ProbingOutputs {
         outputs: Vec<PartialOutputInfo>,
         bound_outputs: Vec<WlOutput>,
@@ -197,10 +191,12 @@ pub enum EncConstructionStage<S: CaptureSource> {
 pub enum InFlightSurface<S: CaptureSource> {
     None,
     AllocQueued,
-    Allocd(S::Frame),
     CopyQueued {
         surface: ff::frame::Video,
-        drm_map: ff::ffi::AVDRMFrameDescriptor,
+        // Boxed: AVDRMFrameDescriptor is ~592 bytes (4 objects + 4 layers),
+        // which would balloon every InFlightSurface variant via enum alignment.
+        // The box shrinks the enum to ~32 bytes regardless of variant.
+        drm_map: Box<ff::ffi::AVDRMFrameDescriptor>,
         frame: S::Frame,
         buffer: WlBuffer,
     },
@@ -211,7 +207,7 @@ pub enum InFlightSurface<S: CaptureSource> {
 // ---------------------------------------------------------------------------
 
 pub struct State<S: CaptureSource> {
-    pub stage: EncConstructionStage<S>,
+    pub(crate) stage: EncConstructionStage<S>,
     pub in_flight_surface: InFlightSurface<S>,
     pub starting_timestamp: Option<i64>,
     pub stats_start_time: Option<Instant>,
@@ -512,6 +508,10 @@ impl<S: CaptureSource> State<S> {
         unsafe {
             (*map_frame.as_mut_ptr()).format = ffi::AVPixelFormat::AV_PIX_FMT_DRM_PRIME as i32;
         }
+        // SAFETY: map_frame and surface are valid, owned AVFrame pointers from
+        // av_hwframe_get/surface.alloc above. AV_HWFRAME_MAP_READ flag (0 here)
+        // requests a read-only mapping. The DRM_PRIME format set above instructs
+        // FFmpeg to populate data[0] with an AVDRMFrameDescriptor on success.
         let ret = unsafe { ffi::av_hwframe_map(map_frame.as_mut_ptr(), surface.as_ptr(), 0) };
         if ret < 0 {
             tracing::error!("av_hwframe_map failed: {}", crate::avhw::ff_err(ret));
@@ -571,7 +571,7 @@ impl<S: CaptureSource> State<S> {
         );
         self.in_flight_surface = InFlightSurface::CopyQueued {
             surface,
-            drm_map: desc,
+            drm_map: Box::new(desc),
             frame,
             buffer: wl_buffer,
         };
@@ -629,16 +629,23 @@ impl<S: CaptureSource> State<S> {
         };
         if should_encode {
             let encode_start = Instant::now();
-            if let Err(e) = enc.encode_frame(&surface) {
+            match enc.encode_frame(&surface) {
-                tracing::error!("encode_frame failed: {}", e);
+                Ok(stages) => {
-                self.errored = true;
-            }
                     let encode_elapsed = encode_start.elapsed().as_micros() as u64;
                     self.stats.record_encode(&FrameTimings {
+                        scale_us: stages.scale_us,
+                        transfer_us: stages.transfer_us,
+                        encode_us: stages.encode_us,
                         total_us: encode_elapsed,
                         ..Default::default()
                     });
                 }
+                Err(e) => {
+                    tracing::error!("encode_frame failed: {}", e);
+                    self.errored = true;
+                }
+            }
+        }
         self.stats_frames += 1;
         if let Some(last) = self.stats_last_time {
             if last.elapsed() >= std::time::Duration::from_secs(10) {
@@ -1509,7 +1516,7 @@ impl<S: CaptureSource> Dispatch<ZwlrOutputManagerV1, ()> for State<S> {
         event: <ZwlrOutputManagerV1 as Proxy>::Event,
         _data: &(),
         _conn: &wayland_client::Connection,
-        qhandle: &QueueHandle<State<S>>,
+        _qhandle: &QueueHandle<State<S>>,
     ) {
         match event {
             WlrOutputManagerEvent::Head { head } => {
@@ -1530,7 +1537,7 @@ impl<S: CaptureSource> Dispatch<ZwlrOutputManagerV1, ()> for State<S> {
                     }
                 }
             }
-            WlrOutputManagerEvent::Finished { .. } => {
+            WlrOutputManagerEvent::Finished => {
                 tracing::warn!("zwlr_output_manager_v1::Finished received during probing");
             }
             _ => {}
@@ -1583,7 +1590,7 @@ impl<S: CaptureSource> Dispatch<ZwlrOutputHeadV1, ()> for State<S> {
                     }
                 }
             }
-            WlrHeadEvent::Finished { .. } => {
+            WlrHeadEvent::Finished => {
                 tracing::debug!("zwlr_output_head_v1::Finished received");
             }
             _ => {}

src/state_portal.rs

@@ -1,4 +1,7 @@
 // 采集门户状态模块 —— 通过 PipeWire/DMA-BUF 进行屏幕采集并编码
+// AsRawFd is required by frame.fd.as_raw_fd() in build_drm_descriptor below
+// but rustc emits a false "unused_imports" warning because OwnedFd also has
+// an inherent as_raw_fd — same quirk as avhw.rs. E0599 if removed → keep it.
 use std::os::fd::AsRawFd;
 use std::path::PathBuf;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -42,6 +45,26 @@ struct WebrtcThread {
     sent_gap_rx: crossbeam_channel::Receiver<(f64, Option<f64>)>,
 }
 
+/// Static configuration handed to the WebRTC sender thread. Immutable for the
+/// thread's lifetime; a resolution tier change rebuilds the whole pipeline
+/// (and spawns a new thread) rather than mutating this.
+struct WebRtcThreadConfig {
+    fps: u32,
+    enc_width: u32,
+    enc_height: u32,
+    max_bitrate: u64,
+}
+
+/// Channel endpoints owned exclusively by the WebRTC sender thread after spawn.
+/// The reverse endpoints stay with StatePortal (or the encode thread) for
+/// inbound/outbound traffic.
+struct WebRtcThreadChannels {
+    webrtc_rx: crossbeam_channel::Receiver<EncodedH264Frame>,
+    sent_gap_tx: crossbeam_channel::Sender<(f64, Option<f64>)>,
+    bitrate_tx: crossbeam_channel::Sender<BitrateCommand>,
+    resolution_tx: crossbeam_channel::Sender<BitrateCommand>,
+}
+
 /// 门户模式的主状态机
 ///
 /// 负责管理从 PipeWire 采集屏幕帧、通过 VAAPI 硬件编码的完整生命周期。
@@ -288,15 +311,19 @@ impl StatePortal {
                         .spawn(move || {
                             webrtc_thread_loop(
                                 wrtc,
-                                webrtc_rx,
+                                WebRtcThreadConfig {
                                     fps,
                                     enc_width,
                                     enc_height,
                                     max_bitrate,
-                                paused,
+                                },
+                                WebRtcThreadChannels {
+                                    webrtc_rx,
                                     sent_gap_tx,
                                     bitrate_tx,
                                     resolution_tx,
+                                },
+                                paused,
                             )
                         })?;
                     self.webrtc_thread = Some(WebrtcThread {
@@ -338,8 +365,15 @@ impl StatePortal {
 
         // 每秒输出一次结构化管道统计（仅 --stats 启用时记录日志）
         if self.args.stats && self.stats.should_snapshot() {
-            self.stats.set_pipewire_dropped(0, 0);
+            // Wire PipeWire drop counter (delta-tracked via pw_dropped_prev) and
-            self.stats.set_queue_depths(0, 0);
+            // capture channel depth. Oracle audit 2026-06-28: previously hardcoded
+            // (0, 0), which silently zeroed two real diagnostic fields.
+            let total_dropped = self.cap.dropped_count();
+            self.stats.set_pipewire_dropped(total_dropped, self.pw_dropped_prev);
+            self.pw_dropped_prev = total_dropped;
+            // capture queue depth is real; encoded side has no exposed depth — the
+            // encoder thread publishes timings only, not a frame queue length.
+            self.stats.set_queue_depths(self.cap.capture_queue_depth(), 0);
             if let Some(ref enc_thread) = self.enc_thread {
                 while let Ok(timing) = enc_thread.timing_rx.try_recv() {
                     self.stats.record_encode_thread(
@@ -478,55 +512,47 @@ impl StatePortal {
 
         if let Some(enc) = self.enc.as_mut() {
             // 将 DMA-BUF 帧零拷贝导入 VAAPI 硬件帧池
+            // SAFETY: delegates to avhw::import_dma_buf_to_vaapi (itself an unsafe fn);
+            // frames_rgb pointer is a valid AVBufferRef owned by enc, and `frame` is the
+            // PipeWire-formatted PwDmaBufFrame whose metadata the function reads directly.
+            // See that function's own SAFETY contract.
             let mut vaapi_frame = unsafe {
-                avhw::import_dma_buf_to_vaapi(
+                avhw::import_dma_buf_to_vaapi(enc.frames_rgb().as_ptr(), &frame)
-                    enc.frames_rgb().as_ptr(),
-                    frame.fd.as_raw_fd(),
-                    frame.width,
-                    frame.height,
-                    frame.format,
-                    frame.modifier,
-                    frame.stride,
-                    frame.offset,
-                )
             }?;
 
             let import_us = t_import_start.elapsed().as_micros() as u64;
-            let t_encode_start = Instant::now();
 
             // 设置帧的显示时间戳（PTS），基于已编码帧序号
+            // SAFETY: vaapi_frame is the freshly-imported valid AVFrame returned by
+            // import_dma_buf_to_vaapi above; pts is a plain i64 field on AVFrame.
             unsafe {
                 (*vaapi_frame.as_mut_ptr()).pts = pts;
             }
 
             // 送入编码器完成：缩放 → 回读 → 格式转换 → H.264 编码
-            enc.encode_frame(&vaapi_frame)?;
+            let stages = enc.encode_frame(&vaapi_frame)?;
             let total_us = t_import_start.elapsed().as_micros() as u64;
-            let encode_us = t_encode_start.elapsed().as_micros() as u64;
+            let encode_us = stages.encode_us;
 
             self.frames_encoded += 1;
 
-            // 记录帧计时到管道统计（import + encode 内部各阶段暂不可分离，用 total 覆盖）
+            // 记录帧计时到管道统计（scale 来自 filter graph；transfer 在 HW 路径恒为 0）
             let timings = FrameTimings {
                 import_us,
+                scale_us: stages.scale_us,
+                transfer_us: stages.transfer_us,
                 encode_us,
                 total_us,
                 ..Default::default()
             };
             self.stats.record_encode(&timings);
         } else if let Some(import) = self.enc_import.as_mut() {
+            // SAFETY: same contract as the enc branch above — frames_rgb owned by
+            // import, `frame` carries the PipeWire DMA-BUF metadata.
             let mut vaapi_frame = unsafe {
-                avhw::import_dma_buf_to_vaapi(
+                avhw::import_dma_buf_to_vaapi(import.frames_rgb().as_ptr(), &frame)
-                    import.frames_rgb().as_ptr(),
-                    frame.fd.as_raw_fd(),
-                    frame.width,
-                    frame.height,
-                    frame.format,
-                    frame.modifier,
-                    frame.stride,
-                    frame.offset,
-                )
             }?;
+            // SAFETY: vaapi_frame is the valid AVFrame returned above; pts is plain i64.
             unsafe {
                 (*vaapi_frame.as_mut_ptr()).pts = pts;
             }
@@ -696,16 +722,22 @@ fn encode_thread_loop(
 
 fn webrtc_thread_loop(
     mut wrtc: WebRtcState,
-    webrtc_rx: crossbeam_channel::Receiver<EncodedH264Frame>,
+    config: WebRtcThreadConfig,
-    fps: u32,
+    channels: WebRtcThreadChannels,
-    enc_width: u32,
-    enc_height: u32,
-    max_bitrate: u64,
     paused: Arc<AtomicBool>,
-    sent_gap_tx: crossbeam_channel::Sender<(f64, Option<f64>)>,
-    bitrate_tx: crossbeam_channel::Sender<BitrateCommand>,
-    resolution_tx: crossbeam_channel::Sender<BitrateCommand>,
 ) {
+    let WebRtcThreadConfig {
+        fps,
+        enc_width,
+        enc_height,
+        max_bitrate,
+    } = config;
+    let WebRtcThreadChannels {
+        webrtc_rx,
+        sent_gap_tx,
+        bitrate_tx,
+        resolution_tx,
+    } = channels;
     let mut frames_sent: u64 = 0;
     let mut last_send: Option<std::time::Instant> = None;
     let mut last_sent_bitrate: Option<u64> = None;
@@ -756,7 +788,7 @@ fn webrtc_thread_loop(
             let should_send = match last_sent_bitrate {
                 None => true,
                 Some(last) => {
-                    let diff = if bwe > last { bwe - last } else { last - bwe };
+                    let diff = bwe.abs_diff(last);
                     diff * 10 > last
                 }
             };
@@ -946,7 +978,12 @@ fn resolve_drm_device(args: &Args) -> Result<Option<PathBuf>> {
 /// 用于验证 DMA-BUF 元数据映射的正确性。
 #[cfg(test)]
 fn build_drm_descriptor(frame: &PwDmaBufFrame) -> ffmpeg_next::ffi::AVDRMFrameDescriptor {
-    let mut desc: ffmpeg_next::ffi::AVDRMFrameDescriptor = unsafe { std::mem::zeroed() };
+    let mut desc: ffmpeg_next::ffi::AVDRMFrameDescriptor = {
+        // SAFETY: AVDRMFrameDescriptor is a POD struct from FFmpeg's C API with no
+        // pointers orDrop fields; all-zero is a valid initial state. Every field is
+        // explicitly overwritten in the lines below before the descriptor is used.
+        unsafe { std::mem::zeroed() }
+    };
     desc.nb_objects = 1; // 单个 DMA-BUF 对象
     desc.objects[0].fd = frame.fd.as_raw_fd(); // DMA-BUF 文件描述符
     desc.objects[0].size = 0; // 大小设为 0（内核自动确定）
@@ -969,6 +1006,9 @@ mod tests {
     fn make_test_frame() -> PwDmaBufFrame {
         // Create a dummy fd from stderr (always valid fd 2)
         // 使用 stderr（fd 2）的副本作为虚拟文件描述符
+        // SAFETY: stderr (fd 2) is always-open in any process; libc::dup(2) returns
+        // a fresh fd we solely own. OwnedFd::from_raw_fd takes ownership and closes
+        // it on Drop. Test-only; the fd is never actually memory-mapped.
         let fd = unsafe { OwnedFd::from_raw_fd(libc::dup(2)) };
         PwDmaBufFrame {
             fd,
@@ -1091,8 +1131,10 @@ mod tests {
     /// 测试：使用自定义偏移量和 stride 构建 DRM 描述符
     #[test]
     fn build_drm_descriptor_custom_offset_and_stride() {
+        // SAFETY: same as make_test_frame — dup of stderr (fd 2), test-only.
+        let test_fd = unsafe { OwnedFd::from_raw_fd(libc::dup(2)) };
         let frame = PwDmaBufFrame {
-            fd: unsafe { OwnedFd::from_raw_fd(libc::dup(2)) },
+            fd: test_fd,
             offset: 4096,                 // 4KB 对齐偏移
             stride: 3840 * 4,             // 4K 宽度 × 4 字节
             modifier: 0x0100000000000001, // AMD modifiers

src/stats.rs

@@ -38,7 +38,6 @@ pub struct PipelineStats {
     encoded_frames: u64,
     sent_frames: u64,
     pipewire_dropped: u64,
-    over_budget_count: u64,
     /// Count of frames dropped by encode thread due to Y-plane hash dedup
     /// (EncodeOutcome::SkippedDuplicate). Read from atomic counter set by
     /// encode thread, computed as delta since previous snapshot.
@@ -73,6 +72,12 @@ pub struct PipelineStats {
     window_start: Instant,
 }
 
+impl Default for PipelineStats {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl PipelineStats {
     pub fn new() -> Self {
         Self {
@@ -80,7 +85,6 @@ impl PipelineStats {
             encoded_frames: 0,
             sent_frames: 0,
             pipewire_dropped: 0,
-            over_budget_count: 0,
             duplicate_frames_skipped: 0,
             prev_duplicate_frames_skipped: 0,
             capture_queue_depth: 0,
@@ -207,11 +211,6 @@ impl PipelineStats {
         self.encoded_queue_depth = encoded;
     }
 
-    /// Record that a frame exceeded its time budget.
-    pub fn record_over_budget(&mut self) {
-        self.over_budget_count += 1;
-    }
-
     /// Returns true if at least 1 second has elapsed since the last snapshot
     /// (or since creation). If true, call `snapshot_and_reset` to get the stats.
     pub fn should_snapshot(&self) -> bool {
@@ -230,7 +229,6 @@ impl PipelineStats {
             encoded_frames: self.encoded_frames,
             sent_frames: self.sent_frames,
             pipewire_dropped: self.pipewire_dropped,
-            over_budget_count: self.over_budget_count,
             duplicate_frames_skipped: self.duplicate_frames_skipped,
             capture_queue_depth: self.capture_queue_depth,
             encoded_queue_depth: self.encoded_queue_depth,
@@ -269,7 +267,6 @@ impl PipelineStats {
         self.encoded_frames = 0;
         self.sent_frames = 0;
         self.pipewire_dropped = 0;
-        self.over_budget_count = 0;
         self.duplicate_frames_skipped = 0;
         self.capture_queue_depth = 0;
         self.encoded_queue_depth = 0;
@@ -304,7 +301,6 @@ pub struct StatsSnapshot {
     pub encoded_frames: u64,
     pub sent_frames: u64,
     pub pipewire_dropped: u64,
-    pub over_budget_count: u64,
     pub duplicate_frames_skipped: u64,
     // Queue depths
     pub capture_queue_depth: usize,
@@ -346,43 +342,72 @@ pub struct StatsSnapshot {
 
 impl std::fmt::Display for StatsSnapshot {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        // Layout note: each line answers one operational question.
+        //   - line 1: throughput (fps + frame counts + window length)
+        //   - line 2: drops (PipeWire backlog, encoder over-budget, frame-hash dedup)
+        //   - line 3: queue back-pressure (capture + encoded)
+        //   - line 4-6: gap timing (avg + p95 + max) — answers "is cadence stable?"
+        //   - line 7: capture-to-send age (avg + p95 + max) — answers "how stale?"
+        //   - line 8: per-stage encode timing (avg + p95) — answers "where is latency?"
+        //   - line 9: output bandwidth (bytes/sec + per-frame p95/max)
+        //
+        // The avg counterparts were computed but never displayed before Oracle
+        // audit 2026-06-28; they pair with the existing p95/max to surface both
+        // central tendency and tail behaviour in the same glance.
         write!(
             f,
-             "capture_fps={:.1} encoded_fps={:.1} sent_fps={:.1} \
+             "elapsed={:.1}s capture_fps={:.1} encoded_fps={:.1} sent_fps={:.1} \
-             pw_dropped={} over_budget={} duplicate_frames_skipped={} \
+              capture_frames={} encoded_frames={} sent_frames={} \
+              pw_dropped={} duplicate_frames_skipped={} \
               cap_q={} enc_q={} \
-             cap_gap_p95={:.1}ms cap_gap_max={:.1}ms \
+              cap_gap_avg={:.1}ms cap_gap_p95={:.1}ms cap_gap_max={:.1}ms \
-             enc_gap_p95={:.1}ms enc_gap_max={:.1}ms \
+              enc_gap_avg={:.1}ms enc_gap_p95={:.1}ms enc_gap_max={:.1}ms \
-             sent_gap_p95={:.1}ms sent_gap_max={:.1}ms \
+              sent_gap_avg={:.1}ms sent_gap_p95={:.1}ms sent_gap_max={:.1}ms \
-             frame_age_p95={:.1}ms frame_age_max={:.1}ms \
+              frame_age_avg={:.1}ms frame_age_p95={:.1}ms frame_age_max={:.1}ms \
               send_wait_p95={:.1}ms \
-             import_p95={:.1}ms scale_p95={:.1}ms transfer_p95={:.1}ms \
+              import_avg={:.1}ms import_p95={:.1}ms \
-             sws_p95={:.1}ms encode_p95={:.1}ms total_p95={:.1}ms \
+              scale_avg={:.1}ms scale_p95={:.1}ms transfer_avg={:.1}ms transfer_p95={:.1}ms \
-             output_bps={:.0} frame_bytes_max={}",
+              sws_avg={:.1}ms sws_p95={:.1}ms \
+              encode_avg={:.1}ms encode_p95={:.1}ms total_avg={:.1}ms total_p95={:.1}ms \
+              output_bps={:.0} frame_bytes_p95={} frame_bytes_max={}",
+            self.elapsed_secs,
             self.capture_fps,
             self.encoded_fps,
             self.sent_fps,
+            self.capture_frames,
+            self.encoded_frames,
+            self.sent_frames,
             self.pipewire_dropped,
-            self.over_budget_count,
             self.duplicate_frames_skipped,
             self.capture_queue_depth,
             self.encoded_queue_depth,
+            self.capture_gap_avg_ms,
             self.capture_gap_p95_ms,
             self.capture_gap_max_ms,
+            self.encoded_gap_avg_ms,
             self.encoded_gap_p95_ms,
             self.encoded_gap_max_ms,
+            self.sent_gap_avg_ms,
             self.sent_gap_p95_ms,
             self.sent_gap_max_ms,
+            self.frame_age_avg_ms,
             self.frame_age_p95_ms,
             self.frame_age_max_ms,
             self.send_wait_p95_ms,
+            self.import_avg_ms,
             self.import_p95_ms,
+            self.scale_avg_ms,
             self.scale_p95_ms,
+            self.transfer_avg_ms,
             self.transfer_p95_ms,
+            self.sws_avg_ms,
             self.sws_p95_ms,
+            self.encode_avg_ms,
             self.encode_p95_ms,
+            self.total_avg_ms,
             self.total_p95_ms,
             self.output_bytes_per_sec,
+            self.output_frame_bytes_p95,
             self.output_frame_bytes_max,
         )
     }

src/transform.rs

@@ -1,8 +1,12 @@
-/// Coordinate transformation module for Wayland output transforms.
+//! Coordinate transformation module for Wayland output transforms.
-///
+//!
-/// Handles the 8 `wl_output` transform variants (rotation + reflection)
+//! Historically exposed a family of `Rect`/`screen_to_frame`/`fit_inside_bounds`
-/// and ROI clipping for screen capture.
+//! helpers for ROI-based capture clipping. Those were never wired into the
-///
+//! capture pipeline (we capture full frames and let FFmpeg's filter graph handle
+//! any scaling/rotation); they have been removed. Only `Transform` and the
+//! `transpose_if_transform_transposed` helper remain — both are actively used by
+//! `state.rs` and `avhw.rs`.
+
 /// Wayland output transform enum, matching `wl_output::Transform`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Transform {
@@ -16,68 +20,6 @@ pub enum Transform {
     Flipped270,
 }
 
-/// Axis-aligned rectangle in integer coordinates.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct Rect {
-    pub x: i32,
-    pub y: i32,
-    pub w: i32,
-    pub h: i32,
-}
-
-/// Returns the 2×2 basis matrix (a, b, c, d) for the given transform.
-///
-/// The matrix represents the affine mapping from screen coordinates to
-/// frame coordinates:
-///
-/// ```text
-/// [new_x]   [a  b] [x]
-/// [new_y] = [c  d] [y]
-/// ```
-pub fn transform_basis(transform: Transform) -> (i32, i32, i32, i32) {
-    match transform {
-        Transform::Normal => (1, 0, 0, 1),
-        Transform::Normal90 => (0, 1, -1, 0),
-        Transform::Normal180 => (-1, 0, 0, -1),
-        Transform::Normal270 => (0, -1, 1, 0),
-        Transform::Flipped => (-1, 0, 0, 1),
-        Transform::Flipped90 => (0, 1, 1, 0),
-        Transform::Flipped180 => (1, 0, 0, -1),
-        Transform::Flipped270 => (0, -1, -1, 0),
-    }
-}
-
-/// Transform a rectangle from screen space to frame space.
-///
-/// Applies the 2×2 basis matrix and computes offsets so the result
-/// fits within the frame dimensions `(frame_w, frame_h)`.
-///
-/// ```text
-/// new_x = a * x + b * y + offset_x
-/// new_y = c * x + d * y + offset_y
-/// ```
-pub fn screen_to_frame(transform: Transform, rect: Rect, frame_w: i32, frame_h: i32) -> Rect {
-    let (a, b, c, d) = transform_basis(transform);
-
-    // Compute the offset so that the transformed origin maps correctly.
-    // For transforms with negative components, we need to shift by the
-    // frame dimension to keep coordinates in [0, frame_w) × [0, frame_h).
-    let offset_x = if a + b < 0 { frame_w } else { 0 };
-    let offset_y = if c + d < 0 { frame_h } else { 0 };
-
-    let new_x = a * rect.x + b * rect.y + offset_x;
-    let new_y = c * rect.x + d * rect.y + offset_y;
-    let new_w = a * rect.w + b * rect.h;
-    let new_h = c * rect.w + d * rect.h;
-
-    Rect {
-        x: new_x,
-        y: new_y,
-        w: new_w.abs(),
-        h: new_h.abs(),
-    }
-}
-
 /// Swap width and height for 90° or 270° rotations.
 ///
 /// After a quarter-turn rotation the output dimensions are transposed
@@ -93,140 +35,10 @@ pub fn transpose_if_transform_transposed(transform: Transform, w: i32, h: i32) -
     }
 }
 
-/// Clip a rectangle so it stays inside `(0, 0) .. (bounds_w, bounds_h)`.
-///
-/// The resulting rectangle has non-negative origin and its extent does
-/// not exceed the bounds.
-pub fn fit_inside_bounds(rect: Rect, bounds_w: i32, bounds_h: i32) -> Rect {
-    let x = rect.x.clamp(0, bounds_w);
-    let y = rect.y.clamp(0, bounds_h);
-    let right = (rect.x + rect.w).min(bounds_w);
-    let bottom = (rect.y + rect.h).min(bounds_h);
-    let w = (right - x).max(0);
-    let h = (bottom - y).max(0);
-    Rect { x, y, w, h }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    // ── transform_basis ───────────────────────────────────────────
-
-    #[test]
-    fn basis_normal_is_identity() {
-        assert_eq!(transform_basis(Transform::Normal), (1, 0, 0, 1));
-    }
-
-    #[test]
-    fn basis_90_cw_rotation() {
-        assert_eq!(transform_basis(Transform::Normal90), (0, 1, -1, 0));
-    }
-
-    #[test]
-    fn basis_180_rotation() {
-        assert_eq!(transform_basis(Transform::Normal180), (-1, 0, 0, -1));
-    }
-
-    #[test]
-    fn basis_270_cw_rotation() {
-        assert_eq!(transform_basis(Transform::Normal270), (0, -1, 1, 0));
-    }
-
-    #[test]
-    fn basis_flipped_horizontal() {
-        assert_eq!(transform_basis(Transform::Flipped), (-1, 0, 0, 1));
-    }
-
-    #[test]
-    fn basis_flipped_90() {
-        assert_eq!(transform_basis(Transform::Flipped90), (0, 1, 1, 0));
-    }
-
-    #[test]
-    fn basis_flipped_180() {
-        assert_eq!(transform_basis(Transform::Flipped180), (1, 0, 0, -1));
-    }
-
-    #[test]
-    fn basis_flipped_270() {
-        assert_eq!(transform_basis(Transform::Flipped270), (0, -1, -1, 0));
-    }
-
-    // ── screen_to_frame ───────────────────────────────────────────
-
-    #[test]
-    fn screen_to_frame_identity_unchanged() {
-        let rect = Rect {
-            x: 10,
-            y: 20,
-            w: 100,
-            h: 50,
-        };
-        let result = screen_to_frame(Transform::Normal, rect, 1920, 1080);
-        assert_eq!(
-            result,
-            Rect {
-                x: 10,
-                y: 20,
-                w: 100,
-                h: 50
-            }
-        );
-    }
-
-    #[test]
-    fn screen_to_frame_90_rotates_origin() {
-        // 90° CW: top-left (0,0) in screen should map to bottom-left in frame
-        let rect = Rect {
-            x: 0,
-            y: 0,
-            w: 100,
-            h: 50,
-        };
-        let result = screen_to_frame(Transform::Normal90, rect, 1080, 1920);
-        // a=0,b=1,c=-1,d=0 => offset_x=0, offset_y=1920 (c+d=-1<0)
-        // new_x = 0*0 + 1*0 + 0 = 0
-        // new_y = -1*0 + 0*0 + 1920 = 1920
-        assert_eq!(result.x, 0);
-        assert_eq!(result.y, 1920);
-        // w' = 0*100 + 1*50 = 50, h' = -1*100 + 0*50 = -100 -> abs=100
-        assert_eq!(result.w, 50);
-        assert_eq!(result.h, 100);
-    }
-
-    #[test]
-    fn screen_to_frame_180_rotates() {
-        let rect = Rect {
-            x: 100,
-            y: 200,
-            w: 300,
-            h: 400,
-        };
-        let result = screen_to_frame(Transform::Normal180, rect, 1920, 1080);
-        // a=-1,b=0,c=0,d=-1, offset_x=1920, offset_y=1080
-        assert_eq!(result.x, -100 + 1920);
-        assert_eq!(result.y, -200 + 1080);
-        assert_eq!(result.w, 300);
-        assert_eq!(result.h, 400);
-    }
-
-    #[test]
-    fn screen_to_frame_flipped_horizontal() {
-        let rect = Rect {
-            x: 50,
-            y: 30,
-            w: 200,
-            h: 100,
-        };
-        let result = screen_to_frame(Transform::Flipped, rect, 1920, 1080);
-        // a=-1,b=0,c=0,d=1, offset_x=1920, offset_y=0
-        assert_eq!(result.x, -50 + 1920);
-        assert_eq!(result.y, 30);
-        assert_eq!(result.w, 200);
-        assert_eq!(result.h, 100);
-    }
-
     // ── transpose_if_transform_transposed ─────────────────────────
 
     #[test]
@@ -292,118 +104,4 @@ mod tests {
             (1080, 1920)
         );
     }
-
-    // ── fit_inside_bounds ─────────────────────────────────────────
-
-    #[test]
-    fn fit_inside_already_fits() {
-        let rect = Rect {
-            x: 10,
-            y: 20,
-            w: 100,
-            h: 50,
-        };
-        let result = fit_inside_bounds(rect, 1920, 1080);
-        assert_eq!(result, rect);
-    }
-
-    #[test]
-    fn fit_inside_clips_right_and_bottom() {
-        let rect = Rect {
-            x: 1800,
-            y: 1000,
-            w: 200,
-            h: 200,
-        };
-        let result = fit_inside_bounds(rect, 1920, 1080);
-        assert_eq!(
-            result,
-            Rect {
-                x: 1800,
-                y: 1000,
-                w: 120,
-                h: 80
-            }
-        );
-    }
-
-    #[test]
-    fn fit_inside_clips_negative_origin() {
-        let rect = Rect {
-            x: -50,
-            y: -30,
-            w: 200,
-            h: 200,
-        };
-        let result = fit_inside_bounds(rect, 1920, 1080);
-        assert_eq!(
-            result,
-            Rect {
-                x: 0,
-                y: 0,
-                w: 150,
-                h: 170
-            }
-        );
-    }
-
-    #[test]
-    fn fit_inside_completely_out_of_bounds() {
-        let rect = Rect {
-            x: 2000,
-            y: 2000,
-            w: 100,
-            h: 100,
-        };
-        let result = fit_inside_bounds(rect, 1920, 1080);
-        assert_eq!(
-            result,
-            Rect {
-                x: 1920,
-                y: 1080,
-                w: 0,
-                h: 0
-            }
-        );
-    }
-
-    #[test]
-    fn fit_inside_zero_size_rect() {
-        let rect = Rect {
-            x: 100,
-            y: 100,
-            w: 0,
-            h: 0,
-        };
-        let result = fit_inside_bounds(rect, 1920, 1080);
-        assert_eq!(
-            result,
-            Rect {
-                x: 100,
-                y: 100,
-                w: 0,
-                h: 0
-            }
-        );
-    }
-
-    #[test]
-    fn fit_inside_zero_bounds() {
-        let rect = Rect {
-            x: 0,
-            y: 0,
-            w: 100,
-            h: 100,
-        };
-        let result = fit_inside_bounds(rect, 0, 0);
-        assert_eq!(
-            result,
-            Rect {
-                x: 0,
-                y: 0,
-                w: 0,
-                h: 0
-            }
-        );
-    }
 }

src/webrtc.rs

@@ -536,7 +536,7 @@ impl WebRtcInner {
         let now = Instant::now();
         let should_honor = self
             .last_forced_keyframe_at
-            .map_or(true, |last| now.duration_since(last) >= FORCED_KEYFRAME_MIN_INTERVAL);
+            .is_none_or(|last| now.duration_since(last) >= FORCED_KEYFRAME_MIN_INTERVAL);
         if should_honor {
             self.last_forced_keyframe_at = Some(now);
             self.need_keyframe = true;