UvcCamera class abstract interface

High-level camera API. One instance drives one camera.

uvcCamera is the shared default instance. Create more with UvcCamera.new to stream several cameras at once. Each instance owns its own native session, preview, recording, and error stream. Call dispose when an instance is no longer needed.

Lifecycle calls (openUsbDevice, openFd, openPreview, startPreview, startPreviewAuto, stopPreview, closeFd, closeUsbDevice, dispose) run one at a time per instance, in call order, on the native session's own thread. A call made while another is in progress waits for it. Only stopPreview, closeFd, closeUsbDevice, and dispose act early: they end the frame verification of a start in progress, which then reports UvcErrorCode.interrupted.

Calls that can fail throw UvcException, except startPreview and startPreviewAuto, which return a result, and readers such as takePicture and getControl, which return null.

Two cameras behind one USB 2.0 hub, or on a phone's single port, share one bus. The second stream may then only start in a lower mode or fail, and startPreviewAuto falls back to smaller modes.

Constructors

UvcCamera()

Creates an independent camera instance.

factory

Properties

deviceEvents → Stream<UvcDeviceEvent>

Stream of USB attach/detach events for UVC-capable devices.

no setter

hashCode → int

The hash code for this object.

no setter, inherited

isPreviewing → bool

Whether this instance's native preview stream is currently running.

no setter

isRecording → bool

Whether an MP4 recording started by startVideoRecording is in progress.

no setter

lastError → String

Last error message of this instance, or an empty string.

no setter

openedDeviceId → int?

Device id passed to the openUsbDevice call that is currently open, or null when no device is open or it was opened through openFd.

no setter

previewTransform → UvcPreviewTransform

Current preview transform applied to the Flutter Texture output.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

stallEvents → Stream<UvcStallEvent>

Stream of stall detection and recovery events.

no setter

streamErrors → Stream<UvcStreamError>

Stream of errors emitted by the native frame pipeline.

no setter

Methods

attachPreviewTexture(int textureId, {int? width, int? height}) → Future<void>

Attaches this instance's preview stream to an existing texture.

closeFd() → Future<void>

Closes the native UVC session opened via openFd.

closeUsbDevice() → Future<void>

Stops the preview and closes the active USB device connection. An open waiting for the USB permission dialog is cancelled.

copyLatestFrame() → UvcPreviewFrame?

Copies the latest RGBA frame from this instance's native preview buffer.

copyLatestFrameTransformed(UvcPreviewTransform transform) → UvcPreviewFrame?

Copies the latest RGBA frame with transform applied to the pixel data.

createPreviewTexture() → Future<int>

Creates a Flutter texture suitable for native preview rendering.

debugBmControls() → List<UvcBmControlInfo>

Returns controls present in descriptor bmControls without GET_* probing.

disableStallDetection() → void

Disables stall detection.

dispose() → Future<void>

Stops preview and recording, closes the device, unbinds any attached texture, and frees the native session. The instance is unusable afterwards. Textures still need disposePreviewTexture.

disposePreviewTexture(int textureId) → Future<void>

Releases a texture created by createPreviewTexture.

enableStallDetection([UvcStallDetectionConfig config = const UvcStallDetectionConfig()]) → void

Enables watchdog-based stall detection for this instance's preview.

ensureCameraPermission() → Future<bool>

Requests the CAMERA permission.

getControl(UvcControlId controlId) → int?

Returns the current value for a specific UVC control.

getDigitalWindowControl() → UvcDigitalWindowControl?

getFocusRelativeControl() → UvcFocusRelativeControl?

getPanTiltAbsoluteControl() → UvcPanTiltAbsoluteControl?

getPanTiltRelativeControl() → UvcPanTiltRelativeControl?

getRegionOfInterestControl() → UvcRegionOfInterestControl?

getRollRelativeControl() → UvcRollRelativeControl?

getStreamStats() → UvcStreamStats

Returns the latest cumulative native stream statistics snapshot.

getWhiteBalanceComponent() → UvcWhiteBalanceComponent?

Compound control getters return null when the control is unavailable. Setters throw UvcException when the device rejects the value.

getZoomRelativeControl() → UvcZoomRelativeControl?

latestFrameSequence() → int

Returns the latest delivered preview frame sequence.

listUsbDevices() → Future<List<UvcUsbDevice>>

Lists USB devices that expose a UVC video interface.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

openFd(int fd) → Future<void>

Opens a UVC device using an already acquired platform file descriptor. Android only. Use openUsbDevice on Windows and Linux. Throws UnsupportedError on other platforms. A device this instance opened through openUsbDevice is closed first, and openedDeviceId becomes null. Throws UvcException when the native open fails.

openPreview(UvcCameraMode mode) → Future<void>

Starts the native preview stream for mode without frame verification.

openUsbDevice(int deviceId) → Future<void>

Opens a USB device by deviceId.

rotatePreviewClockwise() → void

Rotates the preview 90° clockwise relative to the current rotation.

rotatePreviewCounterClockwise() → void

Rotates the preview 90° counter-clockwise relative to the current rotation.

setControl(UvcControlId controlId, int value) → void

Sets a specific UVC control value. Throws UvcException when the device rejects it.

setDigitalWindowControl(UvcDigitalWindowControl value) → void

setFocusRelativeControl(UvcFocusRelativeControl value) → void

setLogLevel(UvcLogLevel level) → void

Sets the package-wide native UVC log level.

setPanTiltAbsoluteControl(UvcPanTiltAbsoluteControl value) → void

setPanTiltRelativeControl(UvcPanTiltRelativeControl value) → void

setPreviewTransform(UvcPreviewTransform transform) → void

Replaces the entire preview transform in a single call.

setRegionOfInterestControl(UvcRegionOfInterestControl value) → void

setRollRelativeControl(UvcRollRelativeControl value) → void

setWhiteBalanceComponent(UvcWhiteBalanceComponent value) → void

setZoomRelativeControl(UvcZoomRelativeControl value) → void

startPreview(UvcCameraMode mode, {UvcPreviewPolicy policy = UvcPreviewPolicy.stableFrames, int consecutiveValidFrames = 3, Duration timeout = const Duration(seconds: 2)}) → Future<UvcPreviewStartResult>

Starts the preview stream for mode and verifies frame delivery.

startPreviewAuto({List<UvcCameraMode>? candidates, UvcAutoPreviewPreference preference = UvcAutoPreviewPreference.reliability, UvcPreviewPolicy policy = UvcPreviewPolicy.stableFrames, int consecutiveValidFrames = 3, Duration perModeTimeout = const Duration(seconds: 2), int maxCandidates = 8}) → Future<UvcAutoPreviewResult>

Tries candidate modes in order and keeps the first one that streams and verifies successfully.

startVideoRecording(String path, {int bitrateBps = 0, UvcPreviewTransform? transform}) → void

Starts MP4 (H.264) video recording of the preview stream to path.

stopPreview() → Future<void>

Stops the active preview stream.

stopVideoRecording() → void

Stops video recording, drains the encoder, and finalizes the MP4 file.

supportedControls() → List<UvcCameraControl>

Returns all controls supported by the currently opened device.

supportedModes() → List<UvcCameraMode>

Returns the camera modes reported by the currently opened device.

takePicture({int quality = 90, UvcPreviewTransform? transform}) → UvcStillPicture?

Encodes the latest preview frame to JPEG in the native layer.

togglePreviewFlipHorizontal() → void

Toggles the left-right mirror flag on the preview output.

togglePreviewFlipVertical() → void

Toggles the top-bottom mirror flag on the preview output.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited