camera_android_camerax

The Android implementation of camera built with the CameraX library.

Note: If any of the limitations prevent you from using using camera_android_camerax or if you run into any problems, please report these issues under flutter/flutter with [camerax] in the title. You may also opt back into the camera_android implementation if you need.

Usage

As of camera: ^0.11.0, this package is endorsed, which means you can simply use camera normally. This package will be automatically be included in your app when you do, so you do not need to add it to your pubspec.yaml.

However, if you import this package to use any of its APIs directly, you should add it to your pubspec.yaml as usual.

Limitations

240p resolution configuration for video recording

240p resolution configuration for video recording is unsupported by CameraX, and thus, the plugin will fall back to target 480p (ResolutionPreset.medium) if configured with ResolutionPreset.low.

Setting stream options for video capture

Calling startVideoCapturing with VideoCaptureOptions configured with streamOptions is currently unsupported do to limitations of the platform interface, and thus that parameter will silently be ignored.

What requires Android permissions

Writing to external storage to save image files

In order to save captured images and videos to files on Android 10 and below, CameraX requires specifying the WRITE_EXTERNAL_STORAGE permission (see the CameraX documentation). This is already done in the plugin, so no further action is required on your end.

To understand the privacy impact of specifying the WRITE_EXTERNAL_STORAGE permission, see the WRITE_EXTERNAL_STORAGE documentation. We have seen apps also have the READ_EXTERNAL_STORAGE permission automatically added to the merged Android manifest; it appears to be implied from WRITE_EXTERNAL_STORAGE. If you do not want the READ_EXTERNAL_STORAGE permission to be included in the merged Android manifest of your app, then take the following steps to remove it:

1. Ensure that your app nor any of the plugins that it depends on require the READ_EXTERNAL_STORAGE permission.
2. Add the following to your app's your_app/android/app/src/main/AndroidManifest.xml:

  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    tools:node="remove" />

Notes on video capture

Setting description while recording

To avoid cancelling any active recording when calling setDescriptionWhileRecording, you must start the recording with startVideoCapturing with enablePersistentRecording set to true.

Notes on image streaming

Allowing image streaming in the background

As of Android 14, to allow for background image streaming, you will need to specify the foreground TYPE_CAMERA foreground service permission in your app's manifest. Specifically, in your_app/android/app/src/main/AndroidManifest.xml add the following:

<manifest ...>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
  ...
</manifest>

Configuring NV21 image format

If you initialize a CameraController with ImageFormatGroup.nv21, then streamed images will still have the ImageFormatGroup.yuv420 format, but their image data will be formatted in NV21. See https://developer.android.com/reference/kotlin/androidx/camera/core/ImageAnalysis#OUTPUT_IMAGE_FORMAT_NV21().

Contributing

For more information on contributing to this plugin, see CONTRIBUTING.md.

---

Fork notes (xcc3641)

Patched copy of camera_android_camerax used by CocoCut (flutter_yige).

Why: upstream binds the VideoCapture use case inside startVideoCapturing and unbinds it again in stopVideoRecording, so every shutter press reconfigures the CameraX capture session and the preview visibly stalls. Measured on a Pixel 8 Pro (Android 17), recording_start_ms was 436–511 ms and did not improve on repeat presses. With VideoCapture bound from camera start-up it is 33–60 ms.

The patch (one file, lib/src/android_camera_camerax.dart):

1. createCameraWithSettings binds VideoCapture instead of ImageAnalysis as the third use case, with a fallback to upstream's layout for LEGACY devices that cannot do Preview + ImageCapture + VideoCapture.
2. stopVideoRecording no longer unbinds VideoCapture.
3. _configureImageAnalysis unbinds VideoCapture first, so image streaming still only ever asks CameraX for three concurrent use cases.

Point 3 matters: asking for four use cases makes CameraX re-solve the stream configuration and the preview/recording rotation comes back wrong.

Upstream status: main still has all three behaviours. flutter/flutter#143049 reports the same symptom and was closed without a root cause.

Upgrading: replace everything with the new pub release on top of the pristine import commit, then re-apply the patch commit.