CameraController

COORDINATE_SYSTEM_VIEW_REFERENCED

public static final int COORDINATE_SYSTEM_VIEW_REFERENCED = 1

ImageAnalysis.Analyzer option for returning PreviewView coordinates.

When the ImageAnalysis.Analyzer is configured with this option, it will receive a Matrix that will receive a value that represents the transformation from camera sensor to the PreviewView, which can be used for highlighting detected result in PreviewView. For example, laying over a bounding box on top of the detected face.

Note this option only works if the ImageAnalysis.Analyzer is set via setImageAnalysisAnalyzer. It will not be effective when used with camera-core directly.

IMAGE_ANALYSIS

public static final int IMAGE_ANALYSIS = 2

Bitmask option to enable ImageAnalysis. In setEnabledUseCases, if (enabledUseCases ℑ_ANALYSIS) != 0, then controller will enable image analysis features.

IMAGE_CAPTURE

public static final int IMAGE_CAPTURE = 1

Bitmask option to enable ImageCapture. In setEnabledUseCases, if (enabledUseCases ℑ_CAPTURE) != 0, then controller will enable image capture features.

TAP_TO_FOCUS_FAILED

public static final int TAP_TO_FOCUS_FAILED = 4

The previous tap-to-focus action was failed to complete. This is usually due to device limitations.

TAP_TO_FOCUS_FOCUSED

public static final int TAP_TO_FOCUS_FOCUSED = 2

The previous tap-to-focus action was completed successfully and the camera is focused.

TAP_TO_FOCUS_NOT_FOCUSED

public static final int TAP_TO_FOCUS_NOT_FOCUSED = 3

The previous tap-to-focus action was completed successfully but the camera is still unfocused, similar to the CONTROL_AF_STATE_NOT_FOCUSED_LOCKED state. The end user might be able to get a better result by trying again with different camera distances and/or lighting.

TAP_TO_FOCUS_NOT_STARTED

public static final int TAP_TO_FOCUS_NOT_STARTED = 0

No tap-to-focus action has been started by the end user.

TAP_TO_FOCUS_STARTED

public static final int TAP_TO_FOCUS_STARTED = 1

A tap-to-focus action has started but not completed. The app also gets notified with this state if a new action happens before the previous one could finish.

VIDEO_CAPTURE

@ExperimentalVideo
public static final int VIDEO_CAPTURE = 4

Bitmask option to enable video capture use case. In setEnabledUseCases, if (enabledUseCases &VIDEO;_CAPTURE) != 0, then controller will enable video capture features.

CameraController

public final CameraController()

clearImageAnalysisAnalyzer

@MainThread
public void clearImageAnalysisAnalyzer()

Removes a previously set analyzer.

This will stop data from streaming to the ImageAnalysis.

If the current getDefaultTargetResolution returns non-null value, calling this method will reconfigure the camera which might cause additional latency. To avoid this, call this method when the lifecycle is not active.

enableTorch

@MainThread
public @NonNull ListenableFuture<Void> enableTorch(boolean torchEnabled)

Enable the torch or disable the torch.

No-ops if the camera is not ready. The ListenableFuture completes successfully in this case.

getCameraControl

@MainThread
public @Nullable CameraControl getCameraControl()

Gets the CameraControl of the currently attached camera.

For controls available directly through CameraController as well as CameraControl, it's recommended to use the ones with CameraController, e.g. setLinearZoom v.s. setLinearZoom. CameraControl is a lower-layer API and may require more steps to achieve the same effect, and will not maintain control values when switching between cameras.

getCameraInfo

@MainThread
public @Nullable CameraInfo getCameraInfo()

Gets the CameraInfo of the currently attached camera.

For info available directly through CameraController as well as CameraInfo, it's recommended to use the ones with CameraController, e.g. getTorchState v.s. getTorchState. CameraInfo is a lower-layer API and may require more steps to achieve the same effect, and will not maintain values when switching between cameras.

getCameraSelector

@MainThread
public @NonNull CameraSelector getCameraSelector()

Gets the CameraSelector.

The default value isDEFAULT_BACK_CAMERA.

getImageAnalysisBackgroundExecutor

@MainThread
public @Nullable Executor getImageAnalysisBackgroundExecutor()

Gets the default executor for ImageAnalysis background tasks.

getImageAnalysisBackpressureStrategy

@MainThread
public int getImageAnalysisBackpressureStrategy()

Returns the mode with which images are acquired.

If not set, it defaults to STRATEGY_KEEP_ONLY_LATEST.

getImageAnalysisImageQueueDepth

@MainThread
public int getImageAnalysisImageQueueDepth()

Gets the image queue depth of ImageAnalysis.

getImageAnalysisTargetSize

@MainThread
public @Nullable CameraController.OutputSize getImageAnalysisTargetSize()

Returns the intended output size for ImageAnalysis set by setImageAnalysisTargetSize, or null if not set.

getImageCaptureFlashMode

@MainThread
public int getImageCaptureFlashMode()

Gets the flash mode for ImageCapture.

getImageCaptureIoExecutor

@MainThread
public @Nullable Executor getImageCaptureIoExecutor()

Gets the default executor for ImageCapture IO tasks.

getImageCaptureMode

@MainThread
public int getImageCaptureMode()

Returns the image capture mode.

getImageCaptureTargetSize

@MainThread
public @Nullable CameraController.OutputSize getImageCaptureTargetSize()

Returns the intended output size for ImageCapture set by setImageCaptureTargetSize, or null if not set.

getInitializationFuture

public @NonNull ListenableFuture<Void> getInitializationFuture()

Gets a ListenableFuture that completes when camera initialization completes.

This future may fail with an InitializationException and associated cause that can be retrieved by getCause. The cause will be a CameraUnavailableException if it fails to access any camera during initialization.

In the rare case that the future fails with CameraUnavailableException, the camera will become unusable. This could happen for various reasons, for example hardware failure or the camera being held by another process. If the failure is temporary, killing and restarting the app might fix the issue.

The initialization also try to bind use cases before completing the ListenableFuture. The ListenableFuture will complete successfully regardless of whether the use cases are ready to be bound, e.g. it will complete successfully even if the controller is not set on a PreviewView. However the ListenableFuture will fail if the enabled use cases are not supported by the current camera.

getPreviewTargetSize

@MainThread
public @Nullable CameraController.OutputSize getPreviewTargetSize()

Returns the intended output size for Preview set by setPreviewTargetSize, or null if not set.

getTapToFocusState

@MainThread
public @NonNull LiveData<Integer> getTapToFocusState()

Returns a LiveData with the latest tap-to-focus state.

When tap-to-focus feature is enabled, the LiveData will receive updates of focusing states. This happens when the end user taps on PreviewView, and then again when focusing is finished either successfully or unsuccessfully. The following table displays the states the LiveData can be in, and the possible transitions between them.

getTorchState

@MainThread
public @NonNull LiveData<Integer> getTorchState()

Returns a LiveData of current TorchState.

The torch can be turned on and off via enableTorch which will trigger the change event to the returned LiveData.

getVideoCaptureTargetSize

@ExperimentalVideo
@MainThread
public @Nullable CameraController.OutputSize getVideoCaptureTargetSize()

Returns the intended output size for VideoCapture set by setVideoCaptureTargetSize, or null if not set.

getZoomState

@MainThread
public @NonNull LiveData<ZoomState> getZoomState()

Returns a LiveData of ZoomState.

The LiveData will be updated whenever the set zoom state has been changed. This can occur when the application updates the zoom via setZoomRatio or setLinearZoom. The zoom state can also change anytime a camera starts up, for example when setCameraSelector is called.

hasCamera

@MainThread
public boolean hasCamera(@NonNull CameraSelector cameraSelector)

Checks if the given CameraSelector can be resolved to a camera.

Use this method to check if the device has the given camera.

Only call this method after camera is initialized. e.g. after the ListenableFuture from getInitializationFuture is finished. Calling it prematurely throws IllegalStateException. Example:

controller.getInitializationFuture().addListener(() -> {
    if (controller.hasCamera(cameraSelector)) {
        controller.setCameraSelector(cameraSelector);
    } else {
        // Update UI if the camera is not available.
    }
    // Attach PreviewView after we know the camera is available.
    previewView.setController(controller);
}, ContextCompat.getMainExecutor(requireContext()));

isImageAnalysisEnabled

@MainThread
public boolean isImageAnalysisEnabled()

Checks if ImageAnalysis is enabled.

isImageCaptureEnabled

@MainThread
public boolean isImageCaptureEnabled()

Checks if ImageCapture is enabled.

ImageCapture is enabled by default. It has to be enabled before takePicture can be called.

isPinchToZoomEnabled

@MainThread
public boolean isPinchToZoomEnabled()

Returns whether pinch-to-zoom is enabled.

By default pinch-to-zoom is enabled.

isRecording

@ExperimentalVideo
@MainThread
public boolean isRecording()

Returns whether there is a in progress video recording.

isTapToFocusEnabled

@MainThread
public boolean isTapToFocusEnabled()

Returns whether tap-to-focus is enabled.

By default tap-to-focus is enabled.

isVideoCaptureEnabled

@ExperimentalVideo
@MainThread
public boolean isVideoCaptureEnabled()

Checks if video capture is enabled.

Video capture is disabled by default. It has to be enabled before startRecording can be called.

setCameraSelector

@MainThread
public void setCameraSelector(@NonNull CameraSelector cameraSelector)

Sets the CameraSelector.

Calling this method with a CameraSelector that resolves to a different camera will change the camera being used by the controller. If camera initialization is complete, the controller will immediately rebind use cases with the new CameraSelector; otherwise, the new CameraSelector will be used when the camera becomes ready.

The default value is DEFAULT_BACK_CAMERA.

setEnabledUseCases

@MainThread
public void setEnabledUseCases(int enabledUseCases)

Enables or disables use cases.

Use cases need to be enabled before they can be used. By default, IMAGE_CAPTURE and IMAGE_ANALYSIS are enabled, and VIDEO_CAPTURE is disabled. This is necessary because VIDEO_CAPTURE is an experimental feature that might not work with other use cases, especially on lower end devices. When that happens, this method will fail with an IllegalStateException.

To make sure VIDEO_CAPTURE works, IMAGE_CAPTURE and IMAGE_ANALYSIS needs to be disabled when enabling VIDEO_CAPTURE. For example:

// By default, image capture is enabled. Taking picture works.
controller.takePicture(...);

// Switch to video capture to shoot video.
controller.setEnabledUseCases(VIDEO_CAPTURE);
controller.startRecording(...);
controller.stopRecording(...);

// Switch back to image capture and image analysis before taking another picture.
controller.setEnabledUseCases(IMAGE_CAPTURE|IMAGE_ANALYSIS);
controller.takePicture(...);

setImageAnalysisAnalyzer

@MainThread
public void setImageAnalysisAnalyzer(
    @NonNull Executor executor,
    @NonNull ImageAnalysis.Analyzer analyzer
)

Sets an analyzer to receive and analyze images.

Applications can process or copy the image by implementing the ImageAnalysis.Analyzer. The image needs to be closed by calling close when the analyzing is done.

Setting an analyzer function replaces any previous analyzer. Only one analyzer can be set at any time.

If the getDefaultTargetResolution returns a non-null value, calling this method will reconfigure the camera which might cause additional latency. To avoid this, set the value before controller is bound to the lifecycle.

setImageAnalysisBackgroundExecutor

@MainThread
public void setImageAnalysisBackgroundExecutor(@Nullable Executor executor)

Sets the executor that will be used for ImageAnalysis background tasks.

If not set, the background executor will default to an automatically generated Executor.

Changing the value will reconfigure the camera, which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setImageAnalysisBackpressureStrategy

@MainThread
public void setImageAnalysisBackpressureStrategy(int strategy)

Sets the backpressure strategy to apply to the image producer to deal with scenarios where images may be produced faster than they can be analyzed.

The available values are STRATEGY_BLOCK_PRODUCER and STRATEGY_KEEP_ONLY_LATEST. If not set, the backpressure strategy will default to STRATEGY_KEEP_ONLY_LATEST.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setImageAnalysisImageQueueDepth

@MainThread
public void setImageAnalysisImageQueueDepth(int depth)

Sets the image queue depth of ImageAnalysis.

This sets the number of images available in parallel to ImageAnalysis.Analyzer . The value is only used if the backpressure strategy is STRATEGY_BLOCK_PRODUCER.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setImageAnalysisTargetSize

@MainThread
public void setImageAnalysisTargetSize(
    @Nullable CameraController.OutputSize targetSize
)

Sets the intended output size for ImageAnalysis.

The value is used as a hint when determining the resolution and aspect ratio of the output buffer. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of ImageAnalysis.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setImageCaptureFlashMode

@MainThread
public void setImageCaptureFlashMode(int flashMode)

Sets the flash mode for ImageCapture.

If not set, the flash mode will default to FLASH_MODE_OFF.

setImageCaptureIoExecutor

@MainThread
public void setImageCaptureIoExecutor(@Nullable Executor executor)

Sets the default executor that will be used for ImageCapture IO tasks.

This executor will be used for any IO tasks specifically for ImageCapture, such as takePicture. If no executor is set, then a default Executor specifically for IO will be used instead.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setImageCaptureMode

@MainThread
public void setImageCaptureMode(int captureMode)

Sets the image capture mode.

Valid capture modes are CAPTURE_MODE_MINIMIZE_LATENCY, which prioritizes latency over image quality, or CAPTURE_MODE_MAXIMIZE_QUALITY, which prioritizes image quality over latency.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setImageCaptureTargetSize

@MainThread
public void setImageCaptureTargetSize(
    @Nullable CameraController.OutputSize targetSize
)

Sets the intended image size for ImageCapture.

The value is used as a hint when determining the resolution and aspect ratio of the captured image. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of ImageCapture.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setLinearZoom

@MainThread
public @NonNull ListenableFuture<Void> setLinearZoom(@FloatRange(from = 0.0, to = 1.0) float linearZoom)

Sets current zoom by a linear zoom value ranging from 0f to 1.0f. LinearZoom 0f represents the minimum zoom while linearZoom 1.0f represents the maximum zoom. The advantage of linearZoom is that it ensures the field of view (FOV) varies linearly with the linearZoom value, for use with slider UI elements (while setZoomRatio works well for pinch-zoom gestures).

No-ops if the camera is not ready. The ListenableFuture completes successfully in this case.

setPinchToZoomEnabled

@MainThread
public void setPinchToZoomEnabled(boolean enabled)

Enables/disables pinch-to-zoom.

Once enabled, end user can pinch on the PreviewView to zoom in/out if the bound camera supports zooming.

setPreviewTargetSize

@MainThread
public void setPreviewTargetSize(@Nullable CameraController.OutputSize targetSize)

Sets the intended output size for Preview.

The value is used as a hint when determining the resolution and aspect ratio of the preview. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of Preview.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

setTapToFocusEnabled

@MainThread
public void setTapToFocusEnabled(boolean enabled)

Enables/disables tap-to-focus.

Once enabled, end user can tap on the PreviewView to set focus point.

setVideoCaptureTargetSize

@ExperimentalVideo
@MainThread
public void setVideoCaptureTargetSize(
    @Nullable CameraController.OutputSize targetSize
)

Sets the intended video size for VideoCapture.

The value is used as a hint when determining the resolution and aspect ratio of the video. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of VideoCapture.

Changing the value will reconfigure the camera which will cause video capture to stop. To avoid this, set the value before controller is bound to lifecycle.

setZoomRatio

@MainThread
public @NonNull ListenableFuture<Void> setZoomRatio(float zoomRatio)

Sets current zoom by ratio.

Valid zoom values range from getMinZoomRatio to getMaxZoomRatio.

No-ops if the camera is not ready. The ListenableFuture completes successfully in this case.

startRecording

@ExperimentalVideo
@MainThread
public void startRecording(
    @NonNull OutputFileOptions outputFileOptions,
    @NonNull Executor executor,
    @NonNull OnVideoSavedCallback callback
)

Takes a video and calls the OnVideoSavedCallback when done.

stopRecording

@ExperimentalVideo
@MainThread
public void stopRecording()

Stops a in progress video recording.

takePicture

@MainThread
public void takePicture(
    @NonNull ImageCapture.OutputFileOptions outputFileOptions,
    @NonNull Executor executor,
    @NonNull ImageCapture.OnImageSavedCallback imageSavedCallback
)

Captures a new still image and saves to a file along with application specified metadata.

The callback will be called only once for every invocation of this method.

By default, the saved image is mirrored to match the output of the preview if front camera is used. To override this behavior, the app needs to explicitly set the flag to false using setReversedHorizontal and setMetadata.

takePicture

@MainThread
public void takePicture(
    @NonNull Executor executor,
    @NonNull ImageCapture.OnImageCapturedCallback callback
)

Captures a new still image for in memory access.

The listener is responsible for calling close on the returned image.