# Camera API 0.5
0.5 keeps the 0.4 capture model and replaces its public error enum with a stable structured error contract. There is one capture implementation exposed at three levels: a convenient owning `Capture`, a complete `Device`/`Session` API, and stable external-backend traits.
## Simple capture
`CameraSystem::capture(selector)` returns a builder. `start()` resolves the device, negotiates a native mode, validates the first frame and returns `Capture`, which owns the session plus a latest-frame receiver. `close().await` requests and waits for cleanup; `Drop` only requests cleanup. An OS call already running in a blocking worker cannot be forcibly cancelled by dropping its Rust future.
## Device and backend selection
`DeviceSelector` supports the platform default, an exact `DeviceId`, facing, USB VID/PID/serial and name matching. Exact IDs never change device after failure. Multiple matches are an error. A persisted ID preserves its backend namespace, while `IdentityStability::EnumerationOnly` warns that the native portion is not durable across enumeration cycles.
`BackendPolicy` has strict semantics:
| Policy | Meaning |
| --- | --- |
| `PlatformDefault` | Use the documented platform preference; it does not claim runtime benchmarking. |
| `Require(id)` | Only this backend; never fall back. |
| `Prefer(ids)` | For default-device capture, try in order and return an attempt report if all fail. Permission failures stop fallback. |
`backend_availability` separates `NotCompiled`, `UnsupportedTarget` and `Available`. Opening can still fail with permission, busy, removal or driver errors.
## Request, plan and negotiated result
`CaptureRequest` expresses preferred or exact resolution, preferred and minimum rational frame rate, accepted formats in preference order, optional required aspect ratio, an optimization priority, memory budget, startup deadline and recovery policy. Hard constraints are checked independently against the negotiated result: exact resolution applies only to width and height, minimum frame rate is a lower bound, and any listed capture format is accepted. `CaptureProfile` supplies useful starting points without creating a second capture path.
`plan()` ranks advertised modes and reports alternatives and estimated pool memory. It is advisory. `start()` performs the same ranking, asks the native backend to start, reads the actual mode and validates the first frame. Driver changes that violate hard constraints fail. The final `NegotiatedCapture` is authoritative for the started session.
Capabilities are conditional. `DeviceCapabilities` distinguishes complete known modes, representative samples backed by continuous/stepwise ranges, and unknown discovery. It lists native formats and reports whether each RGB conversion is available or which feature/external decoder is required. V4L2 exposes its ranged size and frame-interval metadata separately and probes an explicitly requested in-range mode instead of rejecting it merely because it was not one of the representative samples. Custom backends construct validated multi-mode capabilities with `DeviceCapabilities::from_modes`; those public modes are the same data used by `plan()` and `start()`. Unknown YUV color information remains unknown; conversion requires an explicit override instead of silently choosing a matrix or range.
Application-provided backend enumeration, open, capability, start and stop calls run away from async executor threads. `open_timeout` and `capabilities_timeout` provide explicit control-operation deadlines. A capture builder uses one absolute startup deadline across device selection/open, capability discovery, backend options, ordered backend/configuration fallback, and first-frame validation.
## Native frames and conversion
All capture requests deliver `CapturedFrame` in the selected native format. The data path is:
```text
backend -> bounded immutable frame pool -> per-consumer queue/rate limit -> optional conversion
```
`frame.plane(index)`, `rgb_view()` and `ndarray_view()` derive views from `FrameLayout`, stride and byte length. They do not inspect an internal storage enum, convert or copy. A native RGB frame can therefore be viewed even when stored as generic bytes.
`RgbConverter::convert_into` writes into reusable caller storage. `ConversionRequest` specifies the output dimensions and optional color override. The existing scalar, NEON, SSSE3 and AVX2 kernels remain the implementation; MJPEG decoding is available only with `decode-mjpeg`. H264 remains a native payload requiring an external decoder.
Native frames may be copied from platform/driver buffers into the library pool. A future driver-buffer lease would be a separate advanced capability because retaining driver buffers can stall capture.
## Independent subscribers and memory
```rust
# use camera::{FrameRate, OverflowPolicy, SubscriptionOptions};
let preview = SubscriptionOptions::latest();
let recording = SubscriptionOptions::buffered(8)
.overflow(OverflowPolicy::DropOldest);
let inference = SubscriptionOptions::latest()
.max_rate(FrameRate::new(10, 1)?);
# Ok::<(), camera::CameraError>(())
```
`max_rate` limits that receiver, not the camera. Queues are finite and never called “lossless.” Queue depth must fit within the shared memory budget. Multiple consumers can still exhaust a shared pool by retaining frames; copy explicitly for long-term ownership. Pool drops and per-receiver drops are separate metrics.
## State, events and diagnostics
`state()` is the current value. `watch_state()` is a coalescing state watch. `events()` is a bounded event stream; lag is returned as `SessionEvent::Missed { count }`. Lifecycle changes, negotiated adjustments and resource pressure use explicit event variants.
All operations use the single `CameraError` type. Its private struct representation can gain diagnostics without breaking downstream pattern matches; callers branch on the non-exhaustive `CameraErrorKind` returned by `kind()`. `RecoveryHint` provides a conservative action independent of backend prose. `code()` is the direct machine-code shortcut. Both enums and `OperationStage` expose stable snake-case codes through `Display`, `FromStr`, and—when enabled—Serde.
Backend, device, stage, operation, and native status are available separately. `BackendPolicy::Prefer` retains each `BackendAttempt` with its original typed `CameraError`, control batches retain typed `causes()`, device-watcher snapshots retain an `Arc<CameraError>`, and failed session state retains the original error. Aggregate errors choose the highest-priority actionable recovery hint and put their first typed cause on the standard source chain. `source_error()` gives direct access to that source after an error is cloned.
The display message is intended for diagnostics only. Callers must not compare or parse it. Typical decisions use `kind()` for product-specific behavior and `recovery_hint()` for retry, permission, re-enumeration, configuration, frame-drop, or resource-pressure handling.
Frame metadata includes plane offsets/lengths/strides, color metadata, orientation, host capture time, optional source timestamp with clock domain, and source/publication sequence distinction. Nominal FPS is not measured throughput. Compare CPU, allocations, copies and frame age/P95/P99 under the same hardware, input and build flags.
When a reconnect policy is enabled, an explicit backend disconnect wakes recovery immediately; a silent source still uses `stall_timeout`. The first soft recovery restarts the existing stream, then failed attempts reopen the native device. Retry delays use 100/200/400 ms fast probes before returning to the configured `delay`. Existing receivers remain attached across the inactive/recovering window and only become terminal when the session is closed or recovery exhausts `max_attempts`. A recovery is not reported as `Streaming` until the new epoch publishes and validates its first frame.
Malformed frames are isolated from session lifecycle. One bad frame is discarded without restarting a healthy camera; eight consecutive conversion failures request recovery, while a successful frame clears the burst. `FrameMetrics::{consecutive_conversion_errors,max_consecutive_conversion_errors}` expose the current and largest burst. MJPEG validates SOI/EOI before TurboJPEG, accepts and trims transport padding after EOI, and recreates the decoder only after an actual decoder failure. Repeated frame-error logs are summarized at most once per second.
## Backend options and controls
Backend options are typed and rejected when used with a different selected backend. 0.4 exposes implemented settings only: `V4l2Options::mmap_buffers`, `Camera2Options::{max_images, request_template}`, and `AvFoundationOptions::late_frames`. Camera2 validates its reader depth before streaming and passes the selected NDK request template into native request creation; AVFoundation passes its late-frame policy to `AVCaptureVideoDataOutput`. UVC’s authorized-descriptor open path remains an explicit system method. Media Foundation does not publish placeholder fields.
Controls retain the generic descriptor/value API and add `Exposure`, `WhiteBalance`, `Focus` and `Kelvin` helpers. Helpers perform mode ordering and unit conversion, but do not promise unsupported hardware precision. Batch operations are sequential and report every result; they are not atomic. Unsupported controls are omitted, while unexpected descriptor-query failures now fail the query instead of making a control silently disappear.
## External backends
Register a `BackendProvider` on `CameraSystem::builder()`. `BackendDevice` handles capabilities/start/stop, while `FrameSink` publishes through the same bounded epoch-protected frame pool. A backend that detects physical removal or a terminal transport error calls `FrameSink::disconnect()` so automatic recovery does not wait for `stall_timeout`. `WritableFrameLease` borrows writable storage directly from that pool, becomes immutable on `commit`, and returns its slot without publication when dropped. Control calls may use dynamic dispatch; frame callbacks should request a writable lease or publish directly rather than spawning one async task per frame. Unknown formats may be transported under a namespaced backend, but generic conversion is never implied.
## Runtime boundaries
Without default features, format/request/capability/identity contracts compile without Tokio. `runtime-tokio` enables asynchronous systems, sessions, backends and frame receivers. `blocking` exposes `camera::blocking` and reuses one persistent multi-thread runtime; it does not create a runtime per method call.
## Migration boundary
There is no compatibility layer for the pre-0.5 public `CameraError` variants. Replace variant construction with constructors such as `device_not_found`, `timeout`, and `backend_failure`; replace enum pattern matching with `kind()` or `recovery_hint()`. Do not convert a camera error to `String` when wrapping it in an application error—use a transparent `#[from] camera::CameraError` variant so metadata and sources remain available.
The 0.4 capture migration boundary remains: there is no compatibility layer for `BackendType`, `StreamRequest`, `OutputFormat`, `SelectionPolicy`, `Camera`, `CaptureSession`, parameterless `subscribe()`, `negotiated_config()` or `stop()`.