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

Concurrent preview display, video recording, image capture, and image streaming

The CameraX plugin only supports the concurrent camera use cases supported by Camerax; see their documentation for more information. To avoid the usage of unsupported concurrent use cases, the plugin behaves according to the following:

• If the preview is paused (via pausePreview), concurrent video recording and image capture and/or image streaming (via startVideoCapturing(cameraId, VideoCaptureOptions(streamCallback:...))) is supported.
• If the preview is not paused
  • and the camera device is at least supported hardware LIMITED, then concurrent image capture and video recording is supported.
  • and the camera device is at least supported hardware LEVEL_3, then concurrent video recording and image streaming is supported, but concurrent video recording, image streaming, and image capture is not supported.

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.