feat(moq-video)!: make hardware encoders always-on (openh264 stays the software fallback) (#1819)

kixelated · moq-bot[bot] · claude · web-flow · commit e3664b8677ee · 2026-06-21T03:05:52.000Z
Co-authored-by: moq-bot[bot] &lt;186640430+moq-bot[bot]@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
Co-authored-by: quidamschwarz &lt;113550619+quidamschwarz@users.noreply.github.com&gt;
Co-authored-by: nuts-rice &lt;red44443@gmail.com&gt;
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -108,7 +108,7 @@ lto = "fat"
 codegen-units = 1
 strip = true
 
-# moq-video's `nvenc` feature needs a `dynamic-loading` mode on
+# moq-video's always-on NVENC backend (Linux) needs a `dynamic-loading` mode on
 # nvidia-video-codec-sdk so libnvidia-encode is dlopen'd at runtime instead of
 # linked: that lets a portable moq-cli build (and load) on machines without the
 # NVIDIA driver, and lets a GPU-less CI/release builder compile it. Upstream
diff --git a/flake.nix b/flake.nix
@@ -107,10 +107,10 @@
             # cpal's `alsa-sys` (moq-audio `capture` feature) links libasound on
             # Linux via pkg-config; macOS uses CoreAudio, so no dep there.
             pkgs.alsa-lib
-            # moq-video `vaapi` feature: the moq-vaapi crate (moq-dev/vaapi) vendors
-            # the libva headers so bindgen needs no system libva, but libva is
-            # dlopen'd at runtime, so this provides libva.so for actually running
-            # vaapi encode in the devShell. macOS has no VAAPI.
+            # moq-video's VAAPI backend (always-on for Linux): the moq-vaapi crate
+            # (moq-dev/vaapi) vendors the libva headers so bindgen needs no system
+            # libva, but libva is dlopen'd at runtime, so this provides libva.so for
+            # actually running vaapi encode in the devShell. macOS has no VAAPI.
             pkgs.libva
           ];
 
diff --git a/nix/overlay.nix b/nix/overlay.nix
@@ -240,7 +240,7 @@ let
 
   # Every system lib the workspace needs to compile with all features on:
   # bindgen (clang) for ffmpeg/vaapi, GStreamer for moq-gst, ALSA for
-  # moq-audio's capture feature, libva for moq-video's vaapi feature. The
+  # moq-audio's capture feature, libva for moq-video's VAAPI backend. The
   # Linux-only libs match the devShell's `lib.optionals (!isDarwin)` set.
   checkCommonArgs = {
     src = checkSrc;
diff --git a/rs/moq-boy/src/video.rs b/rs/moq-boy/src/video.rs
@@ -89,8 +89,8 @@ fn encoder_thread(
 		let enc = match encoder.as_mut() {
 			Some(enc) => enc,
 			None => {
-				// Game Boy is 160x144; force software (libx264) since hardware
-				// encoders can reject such tiny resolutions.
+				// Game Boy is 160x144; force the openh264 software encoder since
+				// hardware encoders can reject such tiny resolutions.
 				let mut config = moq_video::encode::Config::new(WIDTH, HEIGHT, 60);
 				config.kind = moq_video::encode::Kind::Software;
 				match moq_video::encode::Encoder::new(&config) {
diff --git a/rs/moq-video/Cargo.toml b/rs/moq-video/Cargo.toml
@@ -8,51 +8,24 @@ license = "MIT OR Apache-2.0"
 version = "0.0.4"
 edition = "2024"
 rust-version.workspace = true
-# Not publishable to crates.io until `moq-vaapi` (the `vaapi` feature's dep) is
-# published; it's an in-workspace path dependency for now. Flip back then.
-publish = false
 
 keywords = ["quic", "http3", "webtransport", "media", "video"]
 categories = ["multimedia", "multimedia::video", "multimedia::encoding"]
 
 [lib]
 doctest = false
 
-[features]
-# NVIDIA NVENC hardware encoder (Linux). Off by default; enable for a build that
-# should use NVENC where present. Everything is dlopen'd at runtime: cudarc loads
-# CUDA, and nvidia-video-codec-sdk's `dynamic-loading` (a fork feature, see the
-# root [patch.crates-io]) loads libnvidia-encode. So an nvenc-enabled binary still
-# links on a GPU-less builder and still starts on machines without the NVIDIA
-# driver, falling back to software (see backend::open). `cuda-12020` pins the CUDA
-# API version so the build needs no CUDA toolkit.
-nvenc = ["dep:nvidia-video-codec-sdk", "nvidia-video-codec-sdk/dynamic-loading", "cudarc/fallback-dynamic-loading", "cudarc/cuda-12020"]
-# Intel/AMD VAAPI hardware encoder (Linux). Off by default; enable for a build
-# that should use VAAPI where present. The `moq-vaapi` crate (moq-dev/vaapi) builds
-# against its own vendored libva headers and dlopen's libva at runtime, so a
-# vaapi-enabled binary builds without system libva-dev, links on a libva-less
-# builder, and still loads on machines without libva, falling back to software
-# (see backend::open).
-vaapi = ["dep:moq-vaapi"]
-
 [dependencies]
 anyhow = "1"
 bytes = "1"
-cudarc = { version = "0.19", optional = true, default-features = false, features = ["driver"] }
 # Catalog types (VideoConfig / VideoCodec) the decode consumer reads.
 hang = { workspace = true }
 moq-mux = { workspace = true }
 moq-net = { workspace = true }
-# VAAPI H.264 encoder, gated behind the `vaapi` feature + a linux cfg. Listed here
-# (not under a target table) so the feature can reference it on any host; the code
-# that uses it is `cfg(target_os = "linux")` and it only builds when `vaapi` is
-# enabled (which only happens on Linux, where libva headers exist).
-moq-vaapi = { workspace = true, optional = true }
-# NVENC backend, gated behind the `nvenc` feature + a linux cfg. Listed here
-# (not under a target table) so the feature can reference it on any host; the
-# code that uses it is `cfg(target_os = "linux")`.
-nvidia-video-codec-sdk = { version = "0.4", optional = true }
 # Vendored, statically-linked software H.264 fallback (no system dependency).
+# Always compiled in: hardware encoders (VideoToolbox / Media Foundation /
+# NVENC / VAAPI) are preferred, but openh264 is the fallback when none is usable
+# (GPU-less box, or a resolution a hardware encoder rejects).
 openh264 = "0.9.3"
 thiserror = "2"
 tokio = { workspace = true, features = ["rt", "macros", "sync", "time"] }
@@ -61,6 +34,26 @@ tracing = "0.1"
 yuv = "0.8.14"
 
 [target.'cfg(target_os="linux")'.dependencies]
+# NVENC hardware encoder, always-on for Linux. Everything is dlopen'd at runtime:
+# cudarc loads CUDA, and nvidia-video-codec-sdk's `dynamic-loading` (a fork
+# feature, see the root [patch.crates-io]) loads libnvidia-encode. So the binary
+# links on a GPU-less builder and still starts on machines without the NVIDIA
+# driver, falling back to the next encoder (see backend::open). `cuda-12020` pins
+# the CUDA API version so the build needs no CUDA toolkit.
+cudarc = { version = "0.19", default-features = false, features = ["driver", "fallback-dynamic-loading", "cuda-12020"] }
+# Probe for the NVIDIA driver libraries before calling cudarc / the NVENC SDK,
+# which panic (process-abort under release `panic = "abort"`) if their library is
+# absent. Lets a GPU-less host fall back to the next encoder instead of crashing.
+libloading = "0.8"
+# Intel/AMD VAAPI hardware encoder, always-on for Linux. Builds against its own
+# vendored libva headers and dlopen's libva at runtime, so it builds without
+# system libva-dev and still loads on machines without libva, falling back to the
+# next encoder (see backend::open).
+moq-vaapi = { workspace = true }
+# default-features off so the crate's `cuda-version-from-build-system` default
+# stays off: we pin the CUDA version via our own cudarc dep (cuda-12020) instead,
+# so the build needs no CUDA toolkit.
+nvidia-video-codec-sdk = { version = "0.4", default-features = false, features = ["dynamic-loading"] }
 # Native V4L2 webcam capture (replaces nokhwa). `v4l` streams MMAP buffers;
 # MJPEG cameras are decoded with the pure-Rust `zune-jpeg` (no libjpeg/IJG).
 v4l = "0.14"
diff --git a/rs/moq-video/DESIGN-native-codecs.md b/rs/moq-video/DESIGN-native-codecs.md
@@ -102,8 +102,8 @@ encode/
   backend/
     mod.rs          # Backend trait + open_backend(kind, config) fallback chain
     videotoolbox.rs # cfg(target_os = "macos")
-    nvenc.rs        # cfg(all(target_os = "linux", feature = "nvenc"))
-    vaapi.rs        # cfg(all(target_os = "linux", feature = "vaapi"))
+    nvenc.rs        # cfg(target_os = "linux")
+    vaapi.rs        # cfg(target_os = "linux")
     openh264.rs     # software fallback, all platforms
 ```
 
@@ -214,36 +214,36 @@ Wrinkles to handle:
 ```toml
 [features]
 default = []                       # capture pulled in by moq-cli's `capture` feature
-nvenc  = ["dep:nvidia-video-codec-sdk"]   # linux only, opt-in
-vaapi  = ["dep:moq-vaapi", "moq-vaapi/dlopen"] # linux only, opt-in
-# videotoolbox + openh264 need no feature: gated by cfg(target_os) / always-on
+software = ["dep:openh264"]        # opt-in software fallback, all targets
 
 [target.'cfg(target_os = "macos")'.dependencies]
 objc2-video-toolbox = "..."
 objc2-core-media = "..."
 objc2-core-video = "..."
 
 [target.'cfg(target_os = "linux")'.dependencies]
-nvidia-video-codec-sdk = { version = "0.4", optional = true }
-moq-vaapi = { workspace = true, optional = true }       # in-tree; vendored cros-libva + cros-codecs
+# Hardware encoders are always-on for Linux (cfg-gated, no feature). Both
+# dlopen their drivers at runtime, so they link on a GPU-less builder.
+nvidia-video-codec-sdk = { version = "0.4", features = ["dynamic-loading"] }
+moq-vaapi = "0.0.2"                 # standalone; vendored cros-libva + cros-codecs
 
 [dependencies]
-openh264 = "..."   # software fallback, all targets
-nokhwa = { version = "...", features = ["input-avfoundation", "input-v4l", "input-msmf", "decoding-mjpeg"] }
-dcv-color-primitives = "..."
+openh264 = "..."   # always-on software fallback
 ```
 
-Release builds for Linux enable both `nvenc` and `vaapi`; the runtime fallback
-chain skips whichever driver is absent. Neither is a build-time hard dep on the
-driver, so the binary still builds and runs on a box with neither GPU (it falls
-to openh264).
+Hardware encoders are always-on (VideoToolbox on macOS, Media Foundation on
+Windows, NVENC + VAAPI on Linux); the runtime fallback chain skips whichever
+driver is absent. None is a build-time hard dep on the driver, so the binary
+still builds and runs on a box with no GPU. openh264 is always compiled in as
+the software fallback, so a GPU-less box still encodes (it's also what moq-boy
+uses for its tiny 160x144 frames, which hardware encoders may reject).
 
 ### Selection / fallback (`Kind` mapping)
 
 `open_backend(kind, config)` builds an ordered candidate list and returns the
 first that opens, mirroring today's `open_encoder` loop:
 
-- `Auto`   -> \[videotoolbox | nvenc | vaapi] (cfg-filtered) then openh264.
+- `Auto`   -> \[videotoolbox | nvenc | vaapi] (cfg-filtered), then openh264.
 - `Hardware` -> hardware-only; `NoEncoder` if none opens.
 - `Software` -> openh264 only.
 - `Named(id)` -> that backend only.
@@ -254,14 +254,13 @@ A backend "fails to open" (driver missing, no device) the same way an ffmpeg
 
 ## Packaging payoff
 
-- **macOS**: VideoToolbox + openh264 link only system frameworks + a vendored
-  static lib. One brew bottle per arch, no `Depends`.
+- **macOS**: VideoToolbox links only system frameworks. One brew bottle per
+  arch, no `Depends`.
 - **Linux**: one binary that
 
-  - `dlopen`s `libnvidia-encode.so` if an NVIDIA driver is present (no build dep),
-  - links `libva` (tiny, stable soname across releases) for Intel/AMD; package
-    `Depends: libva2`, `Recommends: intel-media-va-driver | mesa-va-drivers`,
-  - statically carries openh264 as the always-works fallback.
+  - `dlopen`s `libnvidia-encode` if an NVIDIA driver is present (no build dep),
+  - `dlopen`s `libva` for Intel/AMD (no build dep on libva-dev),
+  - falls back to the always-compiled-in openh264 when no GPU encoder is usable.
 
   That single artifact runs across Ubuntu 20.04 -> 24.04, Debian, Fedora, etc.,
   which is the whole reason for the change.
diff --git a/rs/moq-video/src/capture/mediafoundation.rs b/rs/moq-video/src/capture/mediafoundation.rs
@@ -6,7 +6,7 @@
 //! GPU-resident NV12 texture ([`Frame::Texture`]) that the hardware encoder MFT
 //! consumes zero-copy. Without a GPU (e.g. a headless VM) it falls back to the
 //! source reader's software video processor, copying each sample to a packed CPU
-//! [`I420`] ([`Frame::I420`]) for openh264.
+//! [`I420`] ([`Frame::I420`]) the encoder uploads.
 
 use std::ffi::c_void;
 use std::ptr;
diff --git a/rs/moq-video/src/capture/v4l2.rs b/rs/moq-video/src/capture/v4l2.rs
@@ -4,7 +4,7 @@
 //! [`I420`] for the encoder. Two source formats cover essentially all UVC
 //! webcams: YUYV (raw 4:2:2, resampled directly) and MJPEG (decoded to RGB with
 //! the pure-Rust [`zune_jpeg`], then converted). This is the CPU path feeding
-//! openh264 / NVENC; there's no GPU surface here.
+//! NVENC / VAAPI / openh264; there's no GPU surface here.
 
 use v4l::buffer::Type as BufType;
 use v4l::io::mmap::Stream as MmapStream;
diff --git a/rs/moq-video/src/encode/backend/mod.rs b/rs/moq-video/src/encode/backend/mod.rs
@@ -9,7 +9,8 @@
 //!
 //! [`open`] picks the best backend for a [`Codec`](super::Codec) +
 //! [`Kind`](super::Kind): only candidates that support the requested codec are
-//! considered, hardware (platform-gated) before software.
+//! considered, hardware (platform-gated) before the always-available openh264
+//! software fallback.
 
 use bytes::Bytes;
 
@@ -25,10 +26,10 @@ mod videotoolbox;
 #[cfg(target_os = "windows")]
 mod mediafoundation;
 
-#[cfg(all(target_os = "linux", feature = "nvenc"))]
+#[cfg(target_os = "linux")]
 mod nvenc;
 
-#[cfg(all(target_os = "linux", feature = "vaapi"))]
+#[cfg(target_os = "linux")]
 mod vaapi;
 
 /// An opened video encoder. Feed it frames at the configured resolution; get
@@ -67,21 +68,22 @@ const HARDWARE: &[Candidate] = &[
 		codecs: &[Codec::H264, Codec::H265],
 		open: mediafoundation::MediaFoundation::open,
 	},
-	#[cfg(all(target_os = "linux", feature = "nvenc"))]
+	#[cfg(target_os = "linux")]
 	Candidate {
 		name: nvenc::NAME,
 		codecs: &[Codec::H264, Codec::H265],
 		open: nvenc::Nvenc::open,
 	},
-	#[cfg(all(target_os = "linux", feature = "vaapi"))]
+	#[cfg(target_os = "linux")]
 	Candidate {
 		name: vaapi::NAME,
 		codecs: &[Codec::H264],
 		open: vaapi::Vaapi::open,
 	},
 ];
 
-/// Software fallbacks, all platforms. Only H.264 (openh264) has one; H.265 is
+/// Software fallbacks, all platforms, always available so a box with no usable
+/// hardware encoder can still encode. Only H.264 (openh264) has one; H.265 is
 /// hardware-only. A slice so future software codecs slot in.
 const SOFTWARE: &[Candidate] = &[Candidate {
 	name: openh264::NAME,
diff --git a/rs/moq-video/src/encode/backend/nvenc.rs b/rs/moq-video/src/encode/backend/nvenc.rs
@@ -1,7 +1,7 @@
 //! Hardware H.264 / H.265 backend via NVIDIA NVENC (`nvidia-video-codec-sdk` +
 //! cudarc).
 //!
-//! Linux only, behind the `nvenc` feature. The NVENC API lives in the driver
+//! Linux only, always-on (cfg-gated). The NVENC API lives in the driver
 //! (`libnvidia-encode.so`) and cudarc loads CUDA dynamically, so this is not a
 //! build-time dependency on the CUDA toolkit. NVENC emits Annex-B with in-band
 //! parameter sets (SPS/PPS for H.264, VPS/SPS/PPS for H.265), matching the
@@ -68,6 +68,18 @@ impl Nvenc {
 			)));
 		}
 
+		// cudarc and the NVENC SDK dlopen their driver libraries lazily and
+		// *panic* (which aborts the process, since release builds set
+		// `panic = "abort"`) when a library is missing, e.g. on a host with no
+		// NVIDIA driver. With hardware encoders always-on, `Kind::Auto` (the
+		// default) hits this on every GPU-less Linux box, so probe the libraries
+		// up front and return an error to fall back to the next encoder.
+		if !driver_libs_present() {
+			return Err(Error::Codec(anyhow::anyhow!(
+				"NVIDIA driver libraries not found (libcuda / libnvidia-encode); NVENC unavailable"
+			)));
+		}
+
 		// cudarc 0.19's DriverError is Debug-only (no Display), so format with `{e:?}`.
 		let codec_guid = codec_guid(config.codec);
 
@@ -176,3 +188,43 @@ impl Backend for Nvenc {
 		NAME
 	}
 }
+
+/// Whether both NVIDIA driver libraries NVENC needs can be dlopen'd: libcuda
+/// (used by cudarc) and libnvidia-encode (the NVENC API). Each crate loads its
+/// library lazily and panics if it's absent, so we probe the same names here
+/// first and turn a missing driver into a recoverable `Err`.
+fn driver_libs_present() -> bool {
+	// libcuda is the CUDA driver API; matches cudarc's "cuda" search.
+	const CUDA: &[&str] = &["libcuda.so.1", "libcuda.so"];
+	// Matches the NVENC SDK's own dynamic-loading candidate list.
+	const NVENC: &[&str] = &["libnvidia-encode.so.1", "libnvidia-encode.so"];
+
+	// SAFETY: we only open the library to test presence and immediately drop the
+	// handle; we never call into it. Loading runs the library's initializers,
+	// which is sound for these driver libs.
+	let loadable = |names: &[&str]| {
+		names
+			.iter()
+			.any(|name| unsafe { libloading::Library::new(*name) }.is_ok())
+	};
+	loadable(CUDA) && loadable(NVENC)
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use crate::encode::Config;
+
+	/// On a host without the NVIDIA driver, opening NVENC must return an `Err`
+	/// (so `Kind::Auto` falls back) rather than panicking in cudarc / the NVENC
+	/// SDK loader. On a box that does have the driver this is a no-op.
+	#[test]
+	fn missing_driver_errors_instead_of_panicking() {
+		if driver_libs_present() {
+			return; // real driver present: open() would legitimately try to run
+		}
+		// width % 64 == 0 so we get past the pitch guard to the driver probe.
+		let config = Config::new(1920, 1080, 30);
+		assert!(Nvenc::open(&config).is_err());
+	}
+}
diff --git a/rs/moq-video/src/encode/backend/vaapi.rs b/rs/moq-video/src/encode/backend/vaapi.rs
@@ -1,4 +1,4 @@
-//! Intel/AMD VAAPI hardware backend via the `moq-vaapi` crate (Linux, `vaapi` feature).
+//! Intel/AMD VAAPI hardware backend via the `moq-vaapi` crate (Linux, always-on).
 //!
 //! `moq-vaapi` is a focused VA-API H.264 encoder vendored and trimmed from
 //! cros-libva + discord/cros-codecs. It takes tightly-packed NV12 and emits an
diff --git a/rs/moq-video/src/encode/encoder.rs b/rs/moq-video/src/encode/encoder.rs
diff --git a/rs/moq-video/src/frame.rs b/rs/moq-video/src/frame.rs
