Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Libraries Community Compose
The Android Developer Challenge is back! Submit your idea before December 2.

CameraX

CameraX is an addition to Android Jetpack that makes it easier to add camera capabilities to your app. The library provides a number of compatibility fixes and workarounds to help make the developer experience consistent across many devices.

For information on how to use the CameraX library in your app or library, see CameraX Overview.

Latest Update Current Stable Release Next Release Candidate Beta Release Alpha Release
October 9, 2019 - - - 1.0.0-alpha06

Declaring dependencies

To add a dependency on CameraX, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
  // CameraX core library
  def camerax_version = "1.0.0-alpha06"
  // CameraX view library
  def camerax_view_version = "1.0.0-alpha03"
  // CameraX extensions library
  def camerax_ext_version = "1.0.0-alpha03"
  implementation "androidx.camera:camera-core:$camerax_version"
  // If you want to use Camera2 extensions
  implementation "androidx.camera:camera-camera2:$camerax_version"
  // If you to use the Camera View class
  implementation "androidx.camera:camera-view:$camerax_view_version"
  // If you to use Camera Extensions
  implementation "androidx.camera:camera-extensions:$camerax_ext_version"
}

Camera-Camera2 and Camera-Core Version 1.0.0

Camera-Camera2 and Camera-Core Version 1.0.0-alpha06

October 9, 2019

androidx.camera:camera-camera2:1.0.0-alpha06 and androidx.camera:camera-core:1.0.0-alpha06 are released. These are the commits included in camera-camera2:1.0.0-alpha06 and these are the commits included in camera-core:1.0.0-alpha06.

New features

Changes to setting aspect ratios:

  • setTargetAspectRatioMode() was added and accepts an enum argument. This sets the Aspect Ratio Mode with options RATIO_4_3 or RATIO_16_9 instead of an arbitrary aspect ratio. This closer reflects the fact that only certain aspect ratios are provided from the camera, rather than any arbitrary ratio.
    • Currently, the only available ratios are 16:9 and 4:3. In the case of 1:1, only certain devices have this available from the camera, and then only at limited resolutions. Applications designing a 1:1 interface or processing should use the more flexible 16:9 or 4:3 choices and crop the display or process a subregion.
    • These aspect ratios are oriented to use the maximum sensor area.
  • getTargetAspectRatio() was added to use case config APIs, returning the aspect ratio the use case output is targeted for.
  • The method setTargetAspectRatio(Rational aspectRatio) has been changed for ImageCapture to setTargetAspectRatioCustom(Rational aspectRatio). When set, the ImageCapture output will be cropped accordingly.

Executor APIs

  • The following functions accept an executor parameter, which allows the app to control which executor the function runs on.
    • Preview.setOnPreviewOutputUpdateListener() API. If the executor is not present for that function, it executes on the main thread.
    • Preview.setOnPreviewOutputUpdateListener
    • FocusMeteringAction.Builder.setAutoFocusCallback
    • ImageAnalysis.setAnalyzer
    • ImageCapture.takePicture
    • CameraView.takePicture
    • CameraView.startRecording
    • VideoCapture.startRecording

CameraInfo added with check Flash Available and Sensor Rotation APIs

  • Added CameraInfo and a getCameraInfo method, which allows apps to check if a lens facing CameraInfo is available and if a flash is available on that camera. For example:

    try {
    CameraInfo cameraInfo = CameraX.getCameraInfo(currentCameraLensFacing);
    LiveData<Boolean> isFlashAvailable = cameraInfo.isFlashAvailable();
    flashToggle.setVisibility(isFlashAvailable.getValue() ? View.VISIBLE : View.INVISIBLE);
} catch (CameraInfoUnavailableException e) {
    Log.w(TAG, "Cannot get flash available information", e);
    flashToggle.setVisibility(View.VISIBLE);
}

  • CameraInfo.getSensorRotationDegrees() was added. It provides the camera sensor orientation relative to the device’s natural orientation, or for convenience, relative to an orientation described by a Surface rotation (which describes an orientation relative to natural orientation).

API changes and bug fixes

  • Aspect Ratios: For each use case, applications should call only one of setTargetResolution() or setTargetAspectRatio(). Calling both on the same builder will return an error.
    • In general it’s recommended to use setTargetAspectRatio() based on the application’s UI design. Specific resolutions will be based on the use case. For example, preview will be near screen resolutions and image capture will provide high resolution stills. See the automatic resolutions table for more information.
    • Use setTargetResolution() for more specific cases, such as when minimum (to save computation) or maximum resolutions (for processing details) are required.
  • Executor API: Removed the setCallbackHandler() call from use case configuration APIs. Instead, applications can set the executor as a parameter in various other APIs that set a callback.
  • Updated null annotations for various functions.
  • Fixed an issue that caused java.lang.IllegalStateException at Camera$StateCallback.onError to be thrown when opening the camera.
  • Fixed issue where resolutions would be selected that were too small (less than 640x480) when app is requesting larger or default resolutions resulting in a blocky or blurry preview image. Applications that specifically need smaller resolutions can explicitly request them.
  • Fixed an issue where the camera would show black screen (failed to start the camera) after returning from an intent that launched another camera application.
  • Fixed a bug that threw the following error when apps are repeatedly started or stopped; java.lang.IllegalArgumentException: CaptureRequest contains unconfigured Input/Output Surface!
  • Fixed the following error that occurs when disabling ImageAnalysis: java.lang.IllegalStateException: maxImages (4) has already been acquired, call #close before acquiring more.
  • Added additional tests for camera disconnect flow.
  • Improved test system robustness when running back-to-back camera tests.

Camera-Camera2 and Camera-Core Version 1.0.0-alpha05

September 5, 2019

androidx.camera:camera-camera2:1.0.0-alpha05 and androidx.camera:camera-core:1.0.0-alpha05 are released. These are the commits included in camera-camera2:1.0.0-alpha05 and these are the commits included camera-core:1.0.0-alpha05.

  • API Change: Renamed use case error variables:

    • ImageCapture.UseCaseError is renamed ImageCapture.ImageCaptureError
    • VideoCapture.UseCaseError is renamed VideoCapture.VideoCaptureError

  • Added CameraControl API w/Tap-to-Focus APIs

    • Added API to get a CameraControl from CameraX for a camera, selected by lens facing:

      CameraX.getCameraControl(LensFacing lensFacing)

    • Added MeteringPointFactory, MeteringPoint, MeteringMode, and FocusMeteringAction to run Tap-to-Focus:

      MeteringPointFactory factory = new SensorOrientedMeteringPointFactory(width, height);
MeteringPoint point = factory.createPoint(x, y);
FocusMeteringAction action = FocusMeteringAction.Builder.from(point,
                                 MeteringMode.AF_ONLY)
    .addPoint(point2, MeteringMode.AE_ONLY) // could have many
    .setAutoFocusCallback(new OnAutoFocusListener(){
        public void onFocusCompleted(boolean isSuccess) {
        }
    })
    // auto calling cancelFocusAndMetering in 5 sec.
    .setAutoCancelDuration(5, TimeUnit.Second)
    .build();

    • Added API for CameraControl to start and cancel focus metering:

      getCameraControl(lensFacing).startFocusAndMetering(action); getCameraControl(lensFacing).cancelFocusAndMetering();

    • Added APIs for Metering Point Factories that assist translating tap coordinates to sensor coordinates, based on view classes:

      MeteringPointFactory factory = new TextureViewMeteringPointFactory(textureView); MeteringPointFactory factory = new DisplayOrientedMeteringPointFactory(context, lensFacing, viewWidth, viewHeight);

  • Enforce calling the following methods on the Main (UI) thread, throwing an IllegalStateException when they are not. Future versions will allow usage on other threads and ensure serialization.

    • CameraX.bindToLifecycle()
    • CameraX.unbind()
    • CameraX.unbindAll()
    • ImageAnalysis.setAnalyzer()
    • ImageAnalysis.getAnalyzer()
    • ImageAnalysis.removeAnalyzer()
    • Preview.removePreviewOutputListener()
    • Preview.getOnPreviewOutputUpdateListener()
    • Preview.setOnPreviewOutputUpdateListener()

  • Various config settings now accept null parameters and corresponding getters may return null.

  • Fixed issue when testing on emulators that do not support AF/AE/AWB settings.

  • Fixed crash bug on rotation while analyzing image.

  • Fixed bug where preview appears black on start (no camera data), after rotation or switching between front and back cameras.

  • Removed testing for multiple concurrent image analysis use cases. To ensure compatibility, applications should only attach a single image analysis use case.

  • Added initial robolectric tests for fake camera in camera-testing suite (WIP).

  • Camera2Inititalizer test removed, as its coverage was unclear/misleading.

Camera-Camera2 and Camera-Core Version 1.0.0-alpha04

August 7, 2019

androidx.camera:camera-camera2:1.0.0-alpha04 and androidx.camera:camera-core:1.0.0-alpha04 are released. The commits included in this version can be found here.

New Features

Changes to Aspect Ratio and Resolution selection

CameraX's goal is to successfully initialize a camera session. This means CameraX will compromise on resolution/aspect ratios based on device capability, in order to start a capture session as its first goal, and so exact requests may not be honored. This may be due to:

  • Devices not supporting the requested resolution
  • Compatibility issues such as on LEGACY devices where certain resolutions must be used to operate correctly
  • On some devices, certain formats are only available at certain aspect ratios
  • A preference for a “nearest mod16” for JPEG or video encoding. See CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP

Although CameraX creates and manages the session, you should always check the returned image sizes on the use case output in your code and adjust accordingly.

Some changes have been made for setting resolutions and aspect ratios, intended to make the API more clear:

  • Preview use case is now considered to have a default 4:3 aspect ratio when none is set.
  • When CameraX internally considers changes to requested resolutions and aspect ratios based on device capability, it will first try to maintain the same aspect ratio (as determined by any of setTargetAspectRatio or setTargetResolution calls)
  • A “Nearest mod16” version of the resolution is considered as the same aspect ratio.

ImageAnalysis Non-Blocking Mode

  • The behaviour of ImageReaderMode.ACQUIRE_LATEST_IMAGE is now non-blocking. It acquires the latest image in the queue, but discards unused images continuously to allow the camera pipeline to avoid blocking.
  • The analyzer can hold a single image indefinitely without stalling the pipeline.
  • If the application provides an executor which then blocks, the ImageAnalysis use case will block.
  • The default executor set internally behaves as a non-blocking executor.

Bug Fixes

  • Fixed timeout issues waiting for 3A convergence when capturing images on devices with no auto-focus, auto exposure, and auto-whitebalance
  • Fixed issue when rapidly taking pictures with ImageCapture. Fixes error: java.lang.IllegalStateException: maxImages (2) has already been acquired
  • Fixed issue when setLensFacing was not called for a use case, resulting in java.lang.IllegalArgumentException: Unable to get camera ID for use case.
  • Fixed issue where LEGACY device required specific aspect ratio as maximum JPEG resolution
  • Fixed issue when backgrounding the app while camera is opening
  • Fixed issue on API < 25, removing error checkAndUpdateEglState: invalid current EGLDisplay
  • Fixed issue when unbinding preview after enabling and starting extensions
  • Build artifacts for camera-view and camera-extensions are now published as alpha versions

Camera-Camera2 and Camera-Core Version 1.0.0-alpha03

July 2, 2019

androidx.camera:camera-core:1.0.0-alpha03 and androidx.camera:camera-camera2:1.0.0-alpha03 are released. The commits included in this version can be found here.

API Changes

  • Added javadoc clarification for “target” in setTarget configuration calls

Camera-Core

  • Fixed unconfigured Input/Output Surface crash on rapid open/close or bind/unbind
  • Move to new Futures implementations
  • Test fixes for more robust testing
  • Core integration test now shows capture time for photos
  • Developed internal compat class for Executors
  • Timing test app capture images waits for previous to complete & improved stability

Extensions

  • Added versioning checks
  • Additional test coverage - extension event callbacks
  • Improvements for internally corresponding image and meta-data
  • Fixes to mode switching in test app

Camera-Camera2 and Camera-Core Version 1.0.0-alpha02

June 5, 2019

androidx.camera:camera-core:1.0.0-alpha02 and androidx.camera:camera-camera2:1.0.0-alpha02 are released. The commits included in this version can be found here.

Bug fixes

  • Fixed div by zero issue when using emulator
  • Fixed NullPointerException/Surface Abandoned error occurring on some devices when quickly taking photos while unbinding and rebinding use cases rapidly.
  • Fixed internal issue to ensure capture request updates affect all surfaces consistently
  • Stability improvements when restarting use cases in new app instances
  • Internal architecture changes to prepare for supporting executors in the API
  • Additional Javadoc clarifications on CameraX class and lifecycle management
  • Added instrumented testing for Antelope performance test app
  • Remove need for '-keepattributes Signature' in app Proguard config

Camera-Camera2 and Camera-Core 1.0.0-alpha01

May 7, 2019

androidx.camera:camera-core:1.0.0-alpha01 and androidx.camera:camera-camera2:1.0.0-alpha01 are released. The commits included in this version are available here.

Camera-Extensions and Camera-View Version 1.0.0

Camera-Extensions and Camera-View Version 1.0.0-alpha03

October 9, 2019

androidx.camera:camera-extensions:1.0.0-alpha03 and androidx.camera:camera-view:1.0.0-alpha03 are released. These are the commits included in camera-extensions:1.0.0-alpha03 and these are the commits included in camera-view:1.0.0-alpha03.

New Features

  • Added Context initializer for extensions. Extensions version incremented to 1.1.0

Camera-Extensions and Camera-View Version 1.0.0-alpha02

September 5, 2019

androidx.camera:camera-extensions:1.0.0-alpha02 and androidx.camera:camera-view:1.0.0-alpha02 are released. These are the commits included in camera-extensions:1.0.0-alpha02 and these are the commits included camera-view:1.0.0-alpha02.

  • Added tests to verify PreviewImageProcessorImpl has correctly implemented timestamps.
  • Fix ExtensionTest test failure on Nexus 5 (API level 21) and ensure preview is available.

Camera-Extensions and Camera-View Version 1.0.0-alpha01

August 7, 2019

androidx.camera:camera-extensions:1.0.0-alpha01 and androidx.camera:camera-view:1.0.0-alpha01 are released. These are the commits included in camera-extensions:1.0.0-alpha01 and these are the commits included camera-view:1.0.0-alpha01

  • New library for future Camera Extensions for accessing effects on supported devices. This library is a work in progress.
  • New Camera View class. This library is a work in progress.