VideoCapture

public final class VideoCapture<T extends VideoOutput> extends UseCase

java.lang.Object
   ↳ androidx.camera.core.UseCase
     ↳ androidx.camera.video.VideoCapture

A use case that provides camera stream suitable for video application.

VideoCapture is used to create a camera stream suitable for a video application such as recording a high-quality video to a file. The camera stream is used by the extended classes of VideoOutput. withOutput can be used to create a VideoCapture instance associated with the given VideoOutput. Take Recorder as an example, 

        VideoCapture<Recorder> videoCapture
                = VideoCapture.withOutput(new Recorder.Builder().build());
 Then getOutput can retrieve the Recorder instance.
Parameters
<T extends VideoOutput>

the type of VideoOutput

Summary

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

Builder for a VideoCapture.

Public methods
@NonNull DynamicRange

Returns the dynamic range.
int

Returns the mirror mode.
@NonNull T

Gets the VideoOutput associated with this VideoCapture.
@Nullable ResolutionInfo

Returns information about the selected resolution.
@NonNull Range<Integer>

Returns the target frame rate range, in frames per second, for the associated VideoCapture use case.
int

Returns the desired rotation of the output video.
boolean

Returns whether video stabilization is enabled.
void
setTargetRotation(int rotation)

Sets the desired rotation of the output video.
@NonNull String
static @NonNull VideoCapture<T>
<T extends VideoOutput> withOutput(@NonNull T videoOutput)

Create a VideoCapture associated with the given VideoOutput.

Inherited methods
From androidx.camera.core.UseCase
static int
snapToSurfaceRotation(@IntRange(from = 0, to = 359) int orientation)

A utility function that can convert the orientation degrees of OrientationEventListener to the nearest Surface rotation.

Public methods

getDynamicRange

Added in 1.3.0
public @NonNull DynamicRange getDynamicRange()

Returns the dynamic range.

The dynamic range is set by setDynamicRange. If the dynamic range set is not a fully defined dynamic range, such as HDR_UNSPECIFIED_10_BIT, then it will be returned just as provided, and will not be returned as a fully defined dynamic range.

If the dynamic range was not provided to setDynamicRange, this will return the default of SDR

Returns
@NonNull DynamicRange

the dynamic range set for this VideoCapture use case.

getMirrorMode

Added in 1.3.0
public int getMirrorMode()

Returns the mirror mode.

The mirror mode is set by setMirrorMode. If not set, it defaults to MIRROR_MODE_OFF.

Returns
int

The mirror mode of the intended target.

getOutput

Added in 1.1.0
public @NonNull T getOutput()

Gets the VideoOutput associated with this VideoCapture.

Returns
@NonNull T

the value provided to withOutput used to create this VideoCapture.

getResolutionInfo

Added in 1.5.0-alpha04
public @Nullable ResolutionInfo getResolutionInfo()

Returns information about the selected resolution.

Note that the getResolution might not be the same as the resolution of the recorded video because the video might have been rotated according to the camera sensor orientation and the target rotation, and/or have been cropped according to the androidx.camera.core.ViewPort settings. The recorded video resolution can be determined by applying the getRotationDegrees to the size of getCropRect.

The resolution information may change if:

  • The use case is unbound and then rebound.
  • setTargetRotation is called to change the target rotation.

If changes occur, the application should call getResolutionInfo() again to get the latest ResolutionInfo.

Returns
@Nullable ResolutionInfo

the resolution information if the use case is bound by the bindToLifecycle API, or null if the use case is not yet bound.

getTargetFrameRate

Added in 1.3.0
public @NonNull Range<Integer> getTargetFrameRate()

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

The target frame rate can be set prior to constructing a VideoCapture using setTargetFrameRate If not set, the target frame rate defaults to the value of FRAME_RATE_RANGE_UNSPECIFIED

Returns
@NonNull Range<Integer>

The target frame rate of the intended target.

getTargetRotation

Added in 1.3.0
public int getTargetRotation()

Returns the desired rotation of the output video.

The rotation can be set prior to constructing a VideoCapture using setTargetRotation or dynamically by calling setTargetRotation. If not set, the target rotation defaults to the value of getRotation of the default display at the time the use case is bound.

Returns
int

The rotation of the intended target.
See also
setTargetRotation

isVideoStabilizationEnabled

Added in 1.4.0
public boolean isVideoStabilizationEnabled()

Returns whether video stabilization is enabled.

setTargetRotation

Added in 1.3.0
public void setTargetRotation(int rotation)

Sets the desired rotation of the output video.

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

While rotation can also be set via setTargetRotation, using setTargetRotation(int) allows the target rotation to be set dynamically.

In general, it is best to use an android.view.OrientationEventListener to set the target rotation. This way, the rotation output will indicate which way is down for a given video. This is important since display orientation may be locked by device default, user setting, or app configuration, and some devices may not transition to a reverse-portrait display orientation. In these cases, set target rotation dynamically according to the android.view.OrientationEventListener, without re-creating the use case. snapToSurfaceRotation is a helper function to convert the orientation of the android.view.OrientationEventListener to a rotation value. See snapToSurfaceRotation for more information and sample code.

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. To return to the default value, set the value to 

context.getSystemService(WindowManager.class).getDefaultDisplay().getRotation();

For a Recorder output, calling this method has no effect on the ongoing recording, but will affect recordings started after calling this method. 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

Desired rotation of the output video, expressed as one of ROTATION_0, ROTATION_90, ROTATION_180, or ROTATION_270.

toString

public @NonNull String toString()

withOutput

Added in 1.1.0
public static @NonNull VideoCapture<T> <T extends VideoOutput> withOutput(@NonNull T videoOutput)

Create a VideoCapture associated with the given VideoOutput.

Throws
java.lang.NullPointerException

if videoOutput is null.