camera-rs
Intent-driven, cross-platform camera capture for Rust. Version 0.5 adds one structured, backend-neutral error contract on top of the 0.4 capture API. Callers select a device, state hard constraints and preferences, then give each consumer its own bounded delivery policy. Capture always publishes immutable native-format frames; RGB conversion is an explicit consumer operation.
Rust 1.88 or newer is required.
Platform status
| Target | Backend | Build coverage | Hardware expectations |
|---|---|---|---|
| Linux | V4L2 | CI build, tests and sanitizer bridge tests | Normal /dev/video* access; no root required when device permissions are configured |
| Linux/macOS/Android | UVC | CI build and native lifecycle tests | Android requires UsbManager permission; bundled libusb has LGPL distribution obligations |
| macOS | AVFoundation | CI build and contract tests | Camera usage description and sandbox entitlement are required |
| iOS | AVFoundation | CI cross-build | Physical-device behavior must be validated by the application |
| Windows | Media Foundation | CI build and contract tests | Uses the Windows SDK; direct libusb UVC is not supported |
| Android | Camera2 | ARM64/ARMv7 cross-build and demo instrumentation build | API 24+ and runtime CAMERA permission |
| Android | V4L2 | Cross-build and diagnostic demo | Ordinary apps normally lack /dev/video* permission; the library never modifies device permissions |
Build and cross-compile results are not presented as physical-camera proof. The hardware notes identify the exact backend and device family for measured runs.
Why the UVC backend uses libuvc and libusb
The opt-in backend-uvc feature intentionally retains the bundled libuvc and
libusb implementation. We evaluated replacing the USB transport with the
pure-Rust nusb crate, but this is not a
drop-in dependency change:
nusbis a low-level USB transport library, whilelibuvcalso implements UVC descriptor parsing, stream negotiation, payload assembly and camera controls.- UVC cameras may stream over either bulk or isochronous USB endpoints. At the time of this release, cross-platform isochronous transfers are not available through nusb's released public API; the work remains tracked in nusb#47 and nusb#178.
- A bulk-only replacement would exclude otherwise supported isochronous UVC cameras. A complete replacement would require a new Rust UVC protocol layer as well as safe, tested isochronous implementations for every supported USB platform.
For now, compatibility takes priority over removing the native dependency. We may revisit a pure-Rust UVC backend when the transport and hardware coverage are mature enough to preserve both bulk and isochronous device support.
Enabling backend-uvc statically builds the bundled LGPL-2.1-or-later libusb.
Applications distributing that build must satisfy the applicable notice,
source and relinking obligations described in
THIRD_PARTY.md. On Android, applications should obtain USB
permission through UsbManager and pass the authorized file descriptor to the
adapter; root access is not required for that path.
use ;
async
Capture owns both the session and its default receiver, so a convenient call cannot accidentally drop capture lifetime. For preview, recognition and recording at the same time, open a Device, start one Session, then create independent SubscriptionOptions for every consumer.
Feature model
Features decide what is compiled; BackendPolicy decides runtime behavior.
| Purpose | Feature |
|---|---|
| Platform convenience bundle | native |
| Capture backends | backend-v4l2, backend-avfoundation, backend-camera2, backend-mf, backend-uvc |
| Async integration | runtime-tokio |
| Persistent synchronous facade | blocking |
| Raw/RGB conversion kernels | convert-rgb |
| MJPEG decoding through TurboJPEG | decode-mjpeg |
| Integrations | ndarray, serde |
| Experimental backend authoring | custom-backend |
The default convenience set is native and runtime-tokio. RGB conversion and
MJPEG decoding stay opt-in so a basic capture build does not require a JPEG
toolchain. A backend never implies JPEG decoding. Examples:
# Linux V4L2 capture, native frames only
= { = "0.5", = false, = ["backend-v4l2"] }
# Core request/format/identity contracts without Tokio
= { = "0.5", = false }
Android’s adapter defaults to Camera2 only. UVC, V4L2, RGB conversion and MJPEG decoding are opt-in adapter features.
The serde feature covers persisted device/backend identifiers as well as capture requests, selectors, policies, memory/recovery settings and typed backend options.
Consumer-side conversion
Use one converter and reuse caller-owned output storage. Slow consumers only convert frames they actually receive.
use ;
#
Native output means no format conversion. Platform planes or encoded payloads may still be copied into the library’s bounded immutable pool; this is not a promise of a borrowed driver buffer or GPU texture. Retained frames keep pool storage alive, and resource pressure is observable rather than overwriting bytes still held by consumers.
Structured errors
Every public operation returns camera::CameraError. Branch on stable semantic fields instead of matching display text:
use ;
#
#
#
#
#
code(), kind(), recovery_hint(), backend(), device(), stage(), operation(), and native_code() are structured diagnostics. Error kinds, recovery hints, and operation stages implement FromStr; with the serde feature they serialize as the same stable snake-case codes. Aggregate failures derive an actionable recovery hint and expose their first typed cause through the standard source chain, while backend_attempts() and causes() retain every typed failure. The human-readable Display message is diagnostic text and is not a compatibility surface.
The Android JNI boundary raises com.medivh.camera.CameraException. Its
schemaVersion, code, recovery, backend, stage, nativeCode and
diagnosticMessage accessors are stable caller-facing fields; applications do
not need to parse exception text.
Stability and releases
This crate follows Semantic Versioning for its documented public API. Before
1.0, minor releases may contain breaking API changes; patch releases do not.
Hardware-derived enums are treated as extensible. The custom-backend feature
is experimental and may change between minor releases. See
CONTRIBUTING.md and SECURITY.md.
See API contracts, architecture, build instructions, V4L2, and the Android adapter.
License
Copyright (c) 2026 ChenZibo. Licensed under either the MIT License or the Apache License, Version 2.0, at your option. See third-party notices for bundled dependency terms.