Capture: binding crate for libargus

.changeset/libargus-sys.md

@@ -0,0 +1,5 @@
+---
+libargus-sys: minor
+---
+
+Add a `libargus-sys` crate with bindings to the NVIDIA Jetson libargus camera API.

Cargo.toml

@@ -20,6 +20,7 @@ members = [
     "livekit-wakeword",
     "tools/bindgens",
     "libwebrtc",
+    "libargus-sys",
     "soxr-sys",
     "yuv-sys",
     "imgproc",
@@ -69,6 +70,7 @@ livekit-net = { version = "0.1.3", path = "livekit-net" }
 livekit-protocol = { version = "0.7.13", path = "livekit-protocol" }
 livekit-region = { version = "0.1.1", path = "livekit-region" }
 livekit-rpc = { version = "0.1.1", path = "livekit-rpc" }
+libargus-sys = { version = "0.1.0", path = "libargus-sys" }
 soxr-sys = { version = "0.1.3", path = "soxr-sys" }
 webrtc-sys = { version = "0.3.45", path = "webrtc-sys" }
 webrtc-sys-build = { version = "0.3.19", path = "webrtc-sys/build" }

knope.toml

@@ -225,3 +225,11 @@ versioned_files = [
   { path = "Cargo.toml", dependency = "livekit-capture" },
 ]
 changelog = "livekit-capture/CHANGELOG.md"
+
+[packages.libargus-sys]
+versioned_files = [
+  "libargus-sys/Cargo.toml",
+  "Cargo.lock",
+  { path = "Cargo.toml", dependency = "libargus-sys" },
+]
+changelog = "libargus-sys/CHANGELOG.md"

libargus-sys/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "libargus-sys"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+description = "Native NVIDIA libargus (Jetson) capture shim and FFI bindings"
+readme = "README.md"
+repository.workspace = true
+links = "lk_argus"
+
+[build-dependencies]
+cc = { workspace = true }

libargus-sys/README.md

@@ -0,0 +1,72 @@
+# libargus-sys
+
+Native shim and raw FFI bindings for capturing NVIDIA Jetson MIPI CSI cameras
+through [libargus] as NV12 DMA buffers, used by the `source-device-argus`
+feature of `livekit-capture`.
+
+[libargus]: https://docs.nvidia.com/jetson/l4t-multimedia/group__LibargusAPI.html
+
+## How it builds
+
+The C++ shim (`src/lk_argus.cpp`, ABI in `src/lk_argus.h`) is compiled only
+when **all** of the following hold at build time:
+
+- the target is aarch64 Linux,
+- the Jetson Multimedia API headers are present
+  (`/usr/src/jetson_multimedia_api`, package
+  `nvidia-l4t-jetson-multimedia-api`),
+- the Tegra userspace libraries `libnvargus_socketclient.so` and
+  `libnvbufsurface.so` are present (`/usr/lib/aarch64-linux-gnu/tegra`).
+
+On every other target — or when the probe fails — the crate still builds and
+exposes the same API, but every entry point is an inert stub returning
+`LK_ARGUS_ERR_UNAVAILABLE`, and the `AVAILABLE` constant is `false`.
+Consumers therefore need no build script or `cfg` of their own: "not a
+Jetson" degrades exactly like "Jetson with zero cameras".
+
+### Cross-compilation
+
+Point the probe at a sysroot copy of the Jetson filesystem:
+
+| Environment variable | Default |
+| --- | --- |
+| `JETSON_MULTIMEDIA_API_DIR` | `/usr/src/jetson_multimedia_api` |
+| `JETSON_TEGRA_LIB_DIR` | `/usr/lib/aarch64-linux-gnu/tegra` |
+
+The C++ toolchain itself is configured through the standard [`cc` crate
+variables][cc-env] (`CXX_aarch64_unknown_linux_gnu`, `CXXFLAGS=--sysroot=…`).
+
+[cc-env]: https://docs.rs/cc/latest/cc/#external-configuration-via-environment-variables
+
+## Supported JetPack versions
+
+JetPack 5 through 7 (L4T r35–r39). The Argus API has been stable across this
+range; JetPack 6.1 rewrote the stack internals but kept the API. JetPack 4's
+`nvbuf_utils`-era buffer API is not supported. NVIDIA's long-term successor
+to Argus is SIPL (JetPack 7+); Argus is in sustaining mode but remains the
+supported CSI capture path on Orin-class devices.
+
+## Runtime requirements
+
+- A Jetson device with the Argus stack: the `nvargus-daemon` service must be
+  running (the shim talks to it through `libnvargus_socketclient`).
+- A CSI camera module with a device-tree entry and ISP tuning file. USB (UVC)
+  webcams do not go through Argus.
+
+If `nvargus-daemon` dies mid-capture, frame acquisition reports
+`LK_ARGUS_ERR_DISCONNECTED`; destroy the session and re-create it once the
+daemon has restarted (`systemctl restart nvargus-daemon`).
+
+## Design notes
+
+- Frames are ISP-processed NV12 delivered as DMA buffer fds: zero CPU copies,
+  one VIC hardware blit from the EGLStream frame into a persistent
+  `NvBufSurface` ring.
+- Ring slots are *leased*: a slot's fd stays valid until
+  `lk_argus_frame_release`, however long a consumer (e.g. a hardware encoder)
+  holds the frame. An exhausted ring is reported as retryable backpressure
+  (`LK_ARGUS_ERR_NO_FREE_BUFFER`), never overwritten.
+- The process keeps a single shared `CameraProvider` (created lazily,
+  intentionally never destroyed): repeated create/destroy cycles are flaky on
+  some JetPack releases.
+- See `src/lk_argus.h` for the full ABI and the thread-safety contract.

libargus-sys/build.rs

@@ -0,0 +1,98 @@
+// Copyright 2026 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::path::PathBuf;
+
+/// Locates the directory containing the Tegra userspace libraries the shim
+/// links against, requiring the libraries themselves to be present so that
+/// headers alone (e.g. in a partially-provisioned container or on a
+/// non-Jetson aarch64 board) never produce a build that fails to link.
+fn find_tegra_lib_dir() -> Option<PathBuf> {
+    const REQUIRED_LIBS: [&str; 2] = ["libnvargus_socketclient.so", "libnvbufsurface.so"];
+
+    let candidates: Vec<PathBuf> = match std::env::var_os("JETSON_TEGRA_LIB_DIR") {
+        Some(dir) => vec![PathBuf::from(dir)],
+        None => vec![
+            // JetPack 5+ (L4T r35+)
+            PathBuf::from("/usr/lib/aarch64-linux-gnu/tegra"),
+            // Symlink directory shipped on some releases
+            PathBuf::from("/usr/lib/aarch64-linux-gnu/nvidia"),
+        ],
+    };
+
+    candidates
+        .into_iter()
+        .find(|dir| REQUIRED_LIBS.iter().all(|lib| dir.join(lib).exists()))
+}
+
+fn main() {
+    println!("cargo:rustc-check-cfg=cfg(libargus_available)");
+    println!("cargo:rerun-if-env-changed=JETSON_MULTIMEDIA_API_DIR");
+    println!("cargo:rerun-if-env-changed=JETSON_TEGRA_LIB_DIR");
+
+    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    let target_arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
+    if target_os != "linux" || target_arch != "aarch64" {
+        return;
+    }
+
+    let mmapi_root = std::env::var_os("JETSON_MULTIMEDIA_API_DIR")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from("/usr/src/jetson_multimedia_api"));
+    let argus_include = mmapi_root.join("argus/include");
+    let mmapi_include = mmapi_root.join("include");
+
+    if !argus_include.exists() || !mmapi_include.exists() {
+        println!(
+            "cargo:warning=Argus headers not found under {}; building libargus-sys without the \
+             native shim (set JETSON_MULTIMEDIA_API_DIR to override)",
+            mmapi_root.display()
+        );
+        return;
+    }
+
+    // Require the link libraries too: headers can be present without the
+    // Tegra runtime (containers, sysroots), and emitting link directives in
+    // that state would fail the final link instead of degrading gracefully.
+    let Some(tegra_lib_dir) = find_tegra_lib_dir() else {
+        println!(
+            "cargo:warning=Tegra libraries (libnvargus_socketclient.so, libnvbufsurface.so) not \
+             found; building libargus-sys without the native shim (set JETSON_TEGRA_LIB_DIR to \
+             override)"
+        );
+        return;
+    };
+
+    println!("cargo:rerun-if-changed=src/lk_argus.cpp");
+    println!("cargo:rerun-if-changed=src/lk_argus.h");
+
+    cc::Build::new()
+        .cpp(true)
+        .file("src/lk_argus.cpp")
+        .include("src")
+        .include(&argus_include)
+        .include(&mmapi_include)
+        .flag("-std=c++14")
+        .flag("-Wno-deprecated-declarations")
+        .compile("lk_argus");
+
+    println!("cargo:rustc-cfg=libargus_available");
+    println!("cargo:rustc-link-search=native={}", tegra_lib_dir.display());
+    println!("cargo:rustc-link-search=native=/usr/lib/aarch64-linux-gnu");
+    println!("cargo:rustc-link-lib=dylib=nvargus_socketclient");
+    println!("cargo:rustc-link-lib=dylib=nvbufsurface");
+
+    // Communicate availability to dependent crates via `DEP_LK_ARGUS_AVAILABLE`.
+    println!("cargo:available=1");
+}