VideoCapture.Builder

public final class VideoCapture.Builder<T extends VideoOutput> implements ExtendableBuilder

Builder for a VideoCapture.

Parameters
<T extends VideoOutput>

the type of VideoOutput

Summary

Public constructors
Builder(@NonNull T videoOutput)

Creates a new Builder object.

Public methods
@NonNull VideoCapture<T>

Builds a VideoCapture from the current state.
@NonNull VideoCapture.Builder<T>

Sets the DynamicRange.
@NonNull VideoCapture.Builder<T>
setMirrorMode(int mirrorMode)

Sets the mirror mode.
@NonNull VideoCapture.Builder<T>

Sets the target frame rate range in frames per second for the associated VideoCapture use case.
@NonNull VideoCapture.Builder<T>
setTargetRotation(int rotation)

Sets the rotation of the intended target for images from this configuration.
@NonNull VideoCapture.Builder<T>

Enable video stabilization.

Public constructors

Builder

Added in 1.3.0
public Builder(@NonNull T videoOutput)

Creates a new Builder object.

Public methods

build

Added in 1.3.0
public @NonNull VideoCapture<T> build()

Builds a VideoCapture from the current state.

Returns
@NonNull VideoCapture<T>

A VideoCapture populated with the current state.

setDynamicRange

Added in 1.3.0
public @NonNull VideoCapture.Builder<T> setDynamicRange(@NonNull DynamicRange dynamicRange)

Sets the DynamicRange.

The dynamic range specifies how the range of colors, highlights and shadows that are captured by the video producer are displayed on a display. Some dynamic ranges will allow the video to make full use of the extended range of brightness of a display when the video is played back.

The supported dynamic ranges for video capture depend on the capabilities of the camera and the VideoOutput. The supported dynamic ranges can normally be queried through the specific video output. For example, the available dynamic ranges for the Recorder video output can be queried through the androidx.camera.video.VideoCapabilities returned by getVideoCapabilities via getSupportedDynamicRanges.

It is possible to choose a high dynamic range (HDR) with unspecified encoding by providing HDR_UNSPECIFIED_10_BIT.

If the dynamic range is not provided, the returned video capture use case will use a default of SDR.

Returns
@NonNull VideoCapture.Builder<T>

The current Builder.
See also
DynamicRange

setMirrorMode

Added in 1.3.0
public @NonNull VideoCapture.Builder<T> setMirrorMode(int mirrorMode)

Sets the mirror mode.

Valid values include: MIRROR_MODE_OFF, MIRROR_MODE_ON and MIRROR_MODE_ON_FRONT_ONLY. If not set, it defaults to MIRROR_MODE_OFF.

This API only changes the mirroring behavior on VideoCapture, but does not affect other UseCases. If the application wants to be consistent with the default Preview behavior where the rear camera is not mirrored but the front camera is mirrored, then MIRROR_MODE_ON_FRONT_ONLY is recommended.

Parameters
int mirrorMode

The mirror mode of the intended target.
Returns
@NonNull VideoCapture.Builder<T>

The current Builder.

setTargetFrameRate

Added in 1.3.0
public @NonNull VideoCapture.Builder<T> setTargetFrameRate(@NonNull Range<Integer> targetFrameRate)

Sets the target frame rate range in frames per second for the associated VideoCapture use case.

This target will be used as a part of the heuristics for the algorithm that determines the final frame rate range and resolution of all concurrently bound use cases.

It is not guaranteed that this target frame rate will be the final range, as other use cases as well as frame rate restrictions of the device may affect the outcome of the algorithm that chooses the actual frame rate.

For supported frame rates, see getSupportedFrameRateRanges.

Parameters
@NonNull Range<Integer> targetFrameRate

the target frame rate range.

setTargetRotation

Added in 1.3.0
public @NonNull VideoCapture.Builder<T> setTargetRotation(int rotation)

Sets the rotation of the intended target for images from this configuration.

Valid values include: ROTATION_0, ROTATION_90, ROTATION_180, ROTATION_270. Rotation values are relative to the "natural" rotation, ROTATION_0.

In general, it is best to additionally set the target rotation dynamically on the use case. See setTargetRotation for additional documentation.

If not set, the target rotation will default to the value of getRotation of the default display at the time the use case is bound.

For a Recorder output, the final rotation degrees of the video, including the degrees set by this method and the orientation of the camera sensor, will be reflected by several possibilities, 1) the rotation degrees is written into the video metadata, 2) the video content is directly rotated, 3) both, i.e. rotation metadata and rotated video content which combines to the target rotation. CameraX will choose a strategy according to the use case.

Parameters
int rotation

The rotation of the intended target.
Returns
@NonNull VideoCapture.Builder<T>

The current Builder.
See also
setTargetRotation
OrientationEventListener

setVideoStabilizationEnabled

Added in 1.4.0
public @NonNull VideoCapture.Builder<T> setVideoStabilizationEnabled(boolean enabled)

Enable video stabilization.

It will enable stabilization for the video capture use case. However, it is not guaranteed the stabilization will be enabled for the preview use case. If you want to enable preview stabilization, use setPreviewStabilizationEnabled instead.

Preview stabilization, where streams are stabilized with the same quality of stabilization for Preview and VideoCapture use cases, is enabled. This mode aims to give clients a 'what you see is what you get' effect. In this mode, the FoV reduction will be a maximum of 20 % both horizontally and vertically (10% from left, right, top, bottom) for the given zoom ratio / crop region. The resultant FoV will also be the same across all use cases (that have the same aspect ratio). This is the tradeoff between video stabilization and preview stabilization.

It is recommended to query the device capability via isStabilizationSupported before enabling this feature, otherwise HAL error might be thrown.

If both preview stabilization and video stabilization are enabled or disabled, the final result will be

Preview VideoCapture Result
ON ON Both Preview and VideoCapture will be stabilized, VideoCapture quality might be worse than only VideoCapture stabilized
ON OFF None of Preview and VideoCapture will be stabilized
ON NOT SPECIFIED Both Preview and VideoCapture will be stabilized
OFF ON None of Preview and VideoCapture will be stabilized
OFF OFF None of Preview and VideoCapture will be stabilized
OFF NOT SPECIFIED None of Preview and VideoCapture will be stabilized
NOT SPECIFIED ON Only VideoCapture will be stabilized, Preview might be stabilized depending on devices
NOT SPECIFIED OFF None of Preview and VideoCapture will be stabilized
Parameters
boolean enabled

True if enable, otherwise false.
Returns
@NonNull VideoCapture.Builder<T>

the current Builder.
See also
isStabilizationSupported
setPreviewStabilizationEnabled