nitro_camera library
nitro_camera — a high-performance, vision-camera-style Flutter camera plugin built on the Nitro FFI bridge.
Layered architecture (see lib/src/):
nitro_camera.native.dart+generated/— the FFI/native boundary (nitro spec + generated Kotlin/Swift/C++ bridges; do not move — the native build systems reference these paths).models/— pure data types (devices, formats, resolved config, session state, events).configuration/— declarative config + constraint-based format negotiation.controller/— the imperative + declarative session controller.processing/— isolate-based frame processing.widgets/— declarativeCameraView+CameraPreview.
Classes
- AnyResolution
- AutoFocusConstraint
- Prefer a format whose auto-focus system matches system.
- CameraConfiguration
- Immutable, declarative description of a desired camera session state.
- CameraConfigurationDiff
- The set of fields that changed between two CameraConfigurations.
- CameraConstraint
- A single prioritised capture constraint.
- CameraController
- High-level controller that mirrors the vision_camera API surface.
- CameraDeviceFormat
- A capture format available on a CameraDeviceInfo.
- CameraDeviceInfo
- Vision-camera-compatible camera device info, parsed from the native JSON.
- CameraDevicesObserver
-
Watches camera hot-plug events (e.g. USB cameras) and re-enumerates the
device list — the analogue of vision-camera's
addOnCameraDevicesChangedListener/useCameraDevices. - CameraEvent
- A lifecycle / error event emitted by a camera session on NitroCamera.eventStream.
- CameraFrame
-
A raw camera frame emitted by the frame-processing stream.
pixelsis a zero-copy view into the native camera buffer (BGRA / RGBA). Process the frame synchronously inside the stream listener; do NOT hold a reference past that point. -
CameraFrameProcessor<
R> - Runs a FrameHandler on a dedicated background Isolate, keeping heavy per-frame work off the UI isolate.
- CameraPreview
- Renders the live camera preview using Flutter's GPU-accelerated Texture widget or a native Platform View.
- CameraSessionEvent
-
A typed camera lifecycle / error / interruption event, parsed from the FFI
CameraEvent record delivered on
NitroCamera.eventStream. - CameraView
-
Declarative camera widget — the Flutter analogue of vision-camera's
<Camera>. - ClosestResolution
- CodeResult
- A decoded code.
- CodeScanner
- Scans camera frames for barcodes / QR codes of a selectable kind.
- ConcurrentCameraSet
-
A set of cameras that can stream SIMULTANEOUSLY (multi-cam — Android API 30+
concurrent cameras / iOS
AVCaptureMultiCamSession). Produced from the raw ID combinations by CameraController.resolveConcurrentSets / CameraController.getConcurrentCameraSets, so an app can select a pairing (e.g. back + front) by device rather than cross-referencing ID strings. - DetectedBarcode
- A detected barcode/QR (native ML Kit barcode detector).
- DetectedFace
- A detected face (native ML Kit face detector).
- DetectionBounds
- An axis-aligned bounding box in frame pixel coordinates (origin top-left of the detector's input frame, before display rotation/mirror). Use normalized against the frame size for a resolution-independent box.
- DetectionResult
- One frame's worth of native-detector results.
- FormatResolver
- Negotiates a concrete CameraDeviceFormat from a device's available formats and a prioritised list of CameraConstraints.
- FormatStats
-
Aggregate statistics across the candidate formats, used to normalise
resolution penalties (so
max/mincan be scored relative to the field). - FpsConstraint
-
Prefer a format supporting fps. Penalty grows with distance from the
format's
[minFps, maxFps]range. - FrameData
- A camera frame handed to a CameraFrameProcessor handler. The bytes are a copy owned by the worker isolate (the native zero-copy view cannot cross an isolate boundary), so the handler may keep or transform them freely.
- FrameProcessorPlugin
-
A per-frame processor instantiated ON THE WORKER ISOLATE with the options
passed to FrameProcessorPlugins.init. Mirrors vision-camera's
FrameProcessorPlugin(AndroidFrameProcessorPlugin(options)/callback(frame, params)). - FrameProcessorPluginRunner
- A running (or startable) instance of a named plugin: a persistent worker isolate executing the plugin on every frame, with drop-latest backpressure and zero-copy frame hand-off (see CameraFrameProcessor).
- FrameProcessorPlugins
-
Global name → factory registry (main isolate). The static API mirrors
vision-camera's
FrameProcessorPluginRegistry.addFrameProcessorPlugin/initFrameProcessorPlugin. - FrameProcessStats
- Per-frame processing statistics, emitted for EVERY processed frame (successful or not) — the basis for scan benchmarking UIs.
- MaxResolution
- MinResolution
- OrientationManager
- Streams the physical device orientation (0/90/180/270, sensor-derived) and optionally drives a CameraController's target output orientation.
- PhotoCaptureOptions
-
Type-safe options for a single photo capture (
CameraController.takePhoto). - PhotoHdrConstraint
- Require photo-HDR support (penalty 1 if the format can't do it).
- PhotoResult
- Result returned after a photo is captured.
- PinchToZoomDetector
-
A pinch-to-zoom wrapper that drives
controller.setZoom. - RawDecode
- A raw engine decode: text + symbology (no frame metadata yet).
- RecordingOptions
- Per-recording options for NitroCamera.startVideoRecording.
- RecordingResult
- Result returned after a video recording is stopped.
- ResolutionConstraint
- Prefer a resolution according to target for the given stream.
- ResolvedCameraConfig
- The concrete configuration that negotiation actually selected.
- ScanCodesPlugin
-
Scans frames for codes of the kind named by
options['kind'](a CodeScanKind name, default'all'). Emits a map per hit:{text, format, isGs1, points}. - ScanConfirmer
- Confirms detections across consecutive frames and de-duplicates emissions — pure logic, unit-testable without a camera.
- SessionState
-
A typed snapshot of the live native camera session — the parsed form of
NitroCamera.getSessionStateJson. Prefer this over hand-parsing JSON. - TapToFocusDetector
-
A GestureDetector wrapper that translates tap positions to normalised
camera coordinates (0.0–1.0) and calls
controller.setFocusPoint. - TargetResolution
- How to negotiate capture resolution against a device's available formats.
- VideoHdrConstraint
- Require video-HDR support (penalty 1 if the format can't do it).
- VideoStabilizationConstraint
- Prefer a format that supports the given video-stabilization mode. Penalty 1 if unsupported.
Enums
- AutoFocusMode
- Auto-focus behaviour.
- AutoFocusSystem
- The auto-focus system of a capture format.
- CameraEventType
- Kind of CameraEvent delivered on NitroCamera.eventStream.
- CameraExtension
-
Vendor camera extensions (Android
CameraExtensionCharacteristics, API 31+; always absent on iOS). Query-only for now — extension capture sessions are a planned feature. - CameraLensType
- The optical lens type of the camera.
- CameraPosition
- Which physical side of the device the camera faces.
- CodeFormat
- Barcode / code symbologies the scanner can detect.
- CodeScanKind
- Which family of codes to look for in a frame.
- FlashMode
- Flash / torch mode.
- FrameDropReason
-
Why the pipeline dropped a frame — the typed form of a
CameraEventType.frameDropped event's message (vision-camera's
onFrameDroppedreason). - HardwareLevel
-
Camera2
INFO_SUPPORTED_HARDWARE_LEVELtiers (always full on iOS). - InterruptionReason
- Why the camera session was interrupted (mirrors AVFoundation reasons).
- NativeDetector
- Which native ML detector to run. Wire values match the native side.
- OutputOrientationMode
-
How captured output (photos/videos and the locked preview) should be
oriented. Mirrors vision-camera's
OrientationSource. - PermissionStatus
- Camera permission status.
- PhotoOutputFormat
- The photo file container written by a capture.
- PhysicalDeviceType
-
The physical lens types backing a (possibly logical) camera device.
Wire values match vision-camera's
PhysicalCameraDeviceType. - PixelFormat
- The pixel format of the raw frame-processing stream.
- PreviewMode
- Defines how the camera preview is rendered.
- PreviewResizeMode
-
How the preview fills its box (vision-camera's
resizeMode). - QualityPrioritization
- Photo capture speed-vs-quality tradeoff.
- RecordingFinishedReason
- Why a video recording finished.
- ScanMode
- How a CodeScanner delivers results.
- StreamType
- Which capture stream a resolution constraint targets.
- ThermalState
-
Device thermal pressure — the normalized form of a
CameraEventType.thermalStateChanged event's level. Apps should shed load
(lower fps / resolution, stop HDR) as this climbs. Mirrors iOS
ProcessInfo.ThermalState; AndroidPowerManagerthermal statuses are mapped onto the same four levels. - VideoCodec
- Video compression codec for recording.
- VideoFileType
- Container/file type for recorded video.
- VideoStabilizationMode
- Video stabilization mode applied to the capture pipeline.
Extensions
-
CameraDeviceSelection
on List<
CameraDeviceInfo> - Fluent selection sugar over a device list.
- FormatNegotiation on CameraDeviceInfo
-
Convenience negotiation helpers on a device, mirroring vision-camera's
getCameraFormat(device, constraints). - FrameResize on FrameData
- CPU frame resizing for a FrameData — the vision-camera-resizer analogue.
- RecordingResultMetadata on RecordingResult
Constants
- kScannerWindowFraction → const double
- Fraction of the frame's short side scanned by the streaming CodeScanner — matches the centered viewfinder window in the UI. Cropping before decoding is the main speed lever: the binarizer + readers touch ~half the pixels, and the user aims the code inside the window anyway. The center square is rotation- and cover-crop-invariant, so no orientation math is needed to map the UI window into the frame.
Functions
-
createScanCodesPlugin(
Map< String, Object?> options) → FrameProcessorPlugin - Factory for ScanCodesPlugin (top-level, isolate-sendable).
-
decodeCodeFrame(
FrameData f, CodeScanKind kind, {double windowCropFraction = 1.0}) → CodeResult? -
Decodes one frame's luma plane, looking only for
kind's formats. -
mapDecodedPointsToWindow(
List< double> points, int w, int h, bool rotated, {int frameOrientation = 0, bool mirrored = false}) → List<double> - Maps points from decoded-bitmap pixel space back to the scan window's normalized (0..1) space as displayed — ready to paint over the on-screen viewfinder.
-
registerBuiltInFrameProcessorPlugins(
) → void -
Registers all plugins shipped with nitro_camera (currently
scanCodes). Call once, e.g. frommain(). -
scanFrameAdaptive(
FrameData f, CodeScanKind kind) → CodeResult? - Streaming decode with the adaptive ladder + last-hit cache. Used by the CodeScanner worker handlers; call decodeCodeFrame for stateless one-shot decodes.
-
scannerWorkerInit(
Object? arg) → void -
Worker bootstrap: applies the ROI fraction sent as the frame processor's
workerInitArg. Top-level so it is isolate-sendable. -
selectCameraDevice(
List< CameraDeviceInfo> devices, {CameraPosition? position, List<PhysicalDeviceType> ? physicalDevices}) → CameraDeviceInfo? -
Picks the best CameraDeviceInfo from
devices, mirroring vision-camera'sgetCameraDeviceranking:
Typedefs
-
FrameHandler<
R> = R Function(FrameData frame) -
A frame-processing function. It runs on a background isolate, so it must be
a top-level or static function (a closure capturing state cannot be sent to
an isolate). Its return type
Rmust be sendable across isolates (primitives,List/Mapof sendables,TransferableTypedData, etc.). -
FrameProcessorPluginFactory
= FrameProcessorPlugin Function(Map<
String, Object?> options) -
Creates a FrameProcessorPlugin from init
options. Must be a top-level or static function — it crosses the isolate boundary. - WorkerInitializer = void Function(Object? initArg)
-
Runs ONCE on the worker isolate before any frame is handled — the hook for
setting up worker-side state (e.g. instantiating a frame-processor plugin
into an isolate global). Must be a top-level or static function;
initArgmust be sendable.
Exceptions / Errors
- CameraException
- Base type for every error surfaced by nitro_camera.
- CaptureException
- A photo capture failed.
- DeviceException
- The camera device could not be opened or disappeared.
- PermissionException
- Camera / microphone permission is missing or was denied.
- RecorderException
- A video recording failed.
- SessionException
- The session is in the wrong state for the requested operation, or native session configuration failed.