camera-rs 0.5.0

Intent-driven cross-platform camera capture with bounded native frames
Documentation

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:

  • nusb is a low-level USB transport library, while libuvc also 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 camera::{CameraSystem, CaptureProfile, DeviceSelector};

#[tokio::main(flavor = "current_thread")]
async fn main() -> camera::CameraResult<()> {
    let system = CameraSystem::new();
    let mut capture = system
        .capture(DeviceSelector::Default)
        .profile(CaptureProfile::Preview)
        .resolution(1280, 720)
        .start()
        .await?;

    let frame = capture.next_frame().await?;
    println!("{:?}, {} native bytes", frame.layout(), frame.bytes().len());
    println!("negotiated: {:?}", capture.negotiated());
    capture.close().await
}

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
camera-rs = { version = "0.5", default-features = false, features = ["backend-v4l2"] }

# Core request/format/identity contracts without Tokio
camera-rs = { version = "0.5", default-features = 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 camera::{ConversionRequest, RgbConverter};

# fn convert(frame: &camera::CapturedFrame) -> camera::CameraResult<()> {
let request = ConversionRequest::new(640, 360)?;
let mut rgb = vec![0; request.output_len()?];
let mut converter = RgbConverter::new();
converter.convert_into(frame, request, &mut rgb)?;
# Ok(()) }

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 camera::{CameraErrorKind, RecoveryHint};

# fn handle(error: camera::CameraError) {
match error.recovery_hint() {
    RecoveryHint::RequestPermission => request_camera_permission(),
    RecoveryHint::Retry | RecoveryHint::ReenumerateDevice => schedule_retry(),
    RecoveryHint::DropFrame => return,
    _ => report(error.code(), &error.to_string()),
}

if error.kind() == CameraErrorKind::DeviceBusy {
    show_camera_in_use();
}
# }
# fn request_camera_permission() {}
# fn schedule_retry() {}
# fn report(_: &str, _: &str) {}
# fn show_camera_in_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.