Recorder

public final class Recorder implements VideoOutput

An implementation of VideoOutput for starting video recordings that are saved to a File, ParcelFileDescriptor, or MediaStore.

A recorder can be used to save the video frames sent from the VideoCapture use case in common recording formats such as MPEG4.

Usage example of setting up VideoCapture with a recorder as output: 

ProcessCameraProvider cameraProvider = ...;
CameraSelector cameraSelector = ...;
...
// Create our preview to show on screen
Preview preview = new Preview.Builder.build();
// Create the video capture use case with a Recorder as the output
VideoCapturevideoCapture = VideoCapture.withOutput(new Recorder.Builder().build());

// Bind use cases to Fragment/Activity lifecycle
cameraProvider.bindToLifecycle(this, cameraSelector, preview, videoCapture);

Once the recorder is attached to a video source as a VideoOutput, e.g. using it to create a VideoCapture by calling withOutput, a new recording can be generated with one of the prepareRecording methods, such as prepareRecording. The PendingRecording class then can be used to adjust per-recording settings and to start the recording. It also requires passing a listener to start to listen for VideoRecordEvents such as VideoRecordEvent.Start, VideoRecordEvent.Pause, VideoRecordEvent.Resume, and VideoRecordEvent.Finalize. This listener will also receive regular recording status updates via the VideoRecordEvent.Status event.

Attaching a single Recorder instance to multiple video sources at the same time may causes unexpected behaviors and is not recommended.

A recorder can also capture and save audio alongside video. The audio must be explicitly enabled with withAudioEnabled before starting the recording.

See also
withOutput
PendingRecording

Summary

Nested types
public final class Recorder.Builder

Builder class for Recorder objects.

Constants
static final QualitySelector

Default quality selector for recordings.
static final int

Video capabilities are derived from CamcorderProfile.
static final int

Video capabilities are derived from codec capabilities.

Public methods
int

Gets the aspect ratio of this Recorder.
@Nullable Executor

Returns the executor provided to the builder for this recorder.
@NonNull QualitySelector

Gets the quality selector of this Recorder.
int

Gets the target video encoding bitrate of this Recorder.
static @NonNull VideoCapabilities

Returns the VideoCapabilities of Recorder with respect to input camera information.
static @NonNull VideoCapabilities
getVideoCapabilities(
    @NonNull CameraInfo cameraInfo,
    int videoCapabilitiesSource
)

Returns the VideoCapabilities of Recorder with respect to input camera information and video capabilities source.
int

Gets the video capabilities source of this Recorder.
void

Called when a new Surface has been requested by a video frame producer.
@NonNull PendingRecording
@RequiresApi(value = 26)
prepareRecording(
    @NonNull Context context,
    @NonNull FileDescriptorOutputOptions fileDescriptorOutputOptions
)

Prepares a recording that will be saved to a ParcelFileDescriptor.
@NonNull PendingRecording
prepareRecording(
    @NonNull Context context,
    @NonNull FileOutputOptions fileOutputOptions
)

Prepares a recording that will be saved to a File.
@NonNull PendingRecording
prepareRecording(
    @NonNull Context context,
    @NonNull MediaStoreOutputOptions mediaStoreOutputOptions
)

Prepares a recording that will be saved to a MediaStore.

Constants

DEFAULT_QUALITY_SELECTOR

Added in 1.1.0
public static final QualitySelector DEFAULT_QUALITY_SELECTOR

Default quality selector for recordings.

The default quality selector chooses a video quality suitable for recordings based on device and compatibility constraints. It is equivalent to: 

QualitySelector.fromOrderedList(Arrays.asList(Quality.FHD, Quality.HD, Quality.SD),
        FallbackStrategy.higherQualityOrLowerThan(Quality.FHD));
See also
QualitySelector

VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE

Added in 1.4.0
public static final int VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE = 0

Video capabilities are derived from CamcorderProfile.

The Quality supported by the video capabilities of this source are determined by the device's CamcorderProfile. This means that the quality of recorded videos is guaranteed by the device manufacturer. This is the recommended type for recording high-quality video.

See also
setVideoCapabilitiesSource

VIDEO_CAPABILITIES_SOURCE_CODEC_CAPABILITIES

Added in 1.4.0
public static final int VIDEO_CAPABILITIES_SOURCE_CODEC_CAPABILITIES = 1

Video capabilities are derived from codec capabilities.

The Quality supported by the video capabilities of this source are determined by the codec capabilities. However, the recorded videos is not guaranteed. For example, there may be frame drops due to thermal throttling or memory pressure. Therefore, it is recommended to use VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE unless there is a specific reason. A common use case is when the application strives to record UHD video whenever feasible, but the device's CamcorderProfile does not include a UHD quality setting, even though the codec is capable of recording UHD video.

See also
setVideoCapabilitiesSource

Public methods

getAspectRatio

Added in 1.3.0
public int getAspectRatio()

Gets the aspect ratio of this Recorder.

Returns
int

the value from setAspectRatio or RATIO_DEFAULT if not set.

getExecutor

Added in 1.1.0
public @Nullable Executor getExecutor()

Returns the executor provided to the builder for this recorder.

Returns
@Nullable Executor

the Executor provided to setExecutor on the builder used to create this recorder. If no executor was provided, returns {code null}.

getQualitySelector

Added in 1.1.0
public @NonNull QualitySelector getQualitySelector()

Gets the quality selector of this Recorder.

Returns
@NonNull QualitySelector

the QualitySelector provided to setQualitySelector on the builder used to create this recorder, or the default value of DEFAULT_QUALITY_SELECTOR if no quality selector was provided.

getTargetVideoEncodingBitRate

Added in 1.3.0
public int getTargetVideoEncodingBitRate()

Gets the target video encoding bitrate of this Recorder.

Returns
int

the value provided to setTargetVideoEncodingBitRate on the builder used to create this recorder. Returns 0, if setTargetVideoEncodingBitRate is not called.

getVideoCapabilities

Added in 1.3.0
public static @NonNull VideoCapabilities getVideoCapabilities(@NonNull CameraInfo cameraInfo)

Returns the VideoCapabilities of Recorder with respect to input camera information.

VideoCapabilities provides methods to query supported dynamic ranges and qualities. This information can be used for things like checking if HDR is supported for configuring VideoCapture to record HDR video.

The source of the returned VideoCapabilities is VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE. To get a VideoCapabilities from a different source, use getVideoCapabilities.

Parameters
@NonNull CameraInfo cameraInfo

info about the camera.
Returns
@NonNull VideoCapabilities

VideoCapabilities with respect to the input camera info.

getVideoCapabilities

Added in 1.4.0
public static @NonNull VideoCapabilities getVideoCapabilities(
    @NonNull CameraInfo cameraInfo,
    int videoCapabilitiesSource
)

Returns the VideoCapabilities of Recorder with respect to input camera information and video capabilities source.

VideoCapabilities provides methods to query supported dynamic ranges and qualities. This information can be used for things like checking if HDR is supported for configuring VideoCapture to record HDR video.

The possible video capabilities sources include VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE and VIDEO_CAPABILITIES_SOURCE_CODEC_CAPABILITIES.

Parameters
@NonNull CameraInfo cameraInfo

info about the camera.
int videoCapabilitiesSource

the video capabilities source.
Returns
@NonNull VideoCapabilities

VideoCapabilities with respect to the input camera info and video capabilities source.

getVideoCapabilitiesSource

Added in 1.4.0
public int getVideoCapabilitiesSource()

Gets the video capabilities source of this Recorder.

Returns
int

the value provided to setVideoCapabilitiesSource on the builder used to create this recorder, or the default value VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE if not set.

onSurfaceRequested

Added in 1.5.0-alpha02
public void onSurfaceRequested(@NonNull SurfaceRequest request)

Called when a new Surface has been requested by a video frame producer.

Users of this class should not call this method directly. It will be called by the video frame producer. Implementors of this class should be aware that this method is called when a video frame producer is ready to receive a surface that it can use to send video frames to the video output. The video frame producer may repeatedly request a surface more than once, but only the latest SurfaceRequest should be considered active. All previous surface requests will complete by sending a androidx.camera.core.SurfaceRequest.Result to the consumer passed to provideSurface.

A request is considered active until it is fulfilled, marked as 'will not complete', or cancelled by the video frame producer. After one of these conditions occurs, a request is considered completed.

Once a request is successfully completed, it is guaranteed that if a new request is made, the Surface used to fulfill the previous request will be detached from the video frame producer and the resultListener provided in provideSurface will be invoked with a androidx.camera.core.SurfaceRequest.Result containing RESULT_SURFACE_USED_SUCCESSFULLY.

Parameters
@NonNull SurfaceRequest request

the request for a surface which contains the requirements of the surface and methods for completing the request.

prepareRecording

Added in 1.1.0
@RequiresApi(value = 26)
public @NonNull PendingRecording prepareRecording(
    @NonNull Context context,
    @NonNull FileDescriptorOutputOptions fileDescriptorOutputOptions
)

Prepares a recording that will be saved to a ParcelFileDescriptor.

The provided FileDescriptorOutputOptions specifies the ParcelFileDescriptor to use.

Currently, file descriptors as output destinations are not supported on pre-Android O (API 26) devices.

Calling this method multiple times will generate multiple PendingRecordings, each of the recordings can be used to adjust per-recording settings individually. The recording will not begin until start is called. Only a single pending recording can be started per Recorder instance.

Parameters
@NonNull Context context

the context used to enforce runtime permissions, interface with the media scanner service, and attribute access to permission protected data, such as audio. If using this context to audit audio access on API level 31+, a context created with createAttributionContext should be used.
@NonNull FileDescriptorOutputOptions fileDescriptorOutputOptions

the options that configures how the output will be handled.
Returns
@NonNull PendingRecording

a PendingRecording that is associated with this Recorder.
Throws
java.lang.UnsupportedOperationException

if this method is called on per-Android O (API 26) devices.
See also
FileDescriptorOutputOptions

prepareRecording

Added in 1.1.0
public @NonNull PendingRecording prepareRecording(
    @NonNull Context context,
    @NonNull FileOutputOptions fileOutputOptions
)

Prepares a recording that will be saved to a File.

The provided FileOutputOptions specifies the file to use.

Calling this method multiple times will generate multiple PendingRecordings, each of the recordings can be used to adjust per-recording settings individually. The recording will not begin until start is called. Only a single pending recording can be started per Recorder instance.

Parameters
@NonNull Context context

the context used to enforce runtime permissions, interface with the media scanner service, and attribute access to permission protected data, such as audio. If using this context to audit audio access on API level 31+, a context created with createAttributionContext should be used.
@NonNull FileOutputOptions fileOutputOptions

the options that configures how the output will be handled.
Returns
@NonNull PendingRecording

a PendingRecording that is associated with this Recorder.
See also
FileOutputOptions

prepareRecording

Added in 1.1.0
public @NonNull PendingRecording prepareRecording(
    @NonNull Context context,
    @NonNull MediaStoreOutputOptions mediaStoreOutputOptions
)

Prepares a recording that will be saved to a MediaStore.

The provided MediaStoreOutputOptions specifies the options which will be used to save the recording to a MediaStore.

Calling this method multiple times will generate multiple PendingRecordings, each of the recordings can be used to adjust per-recording settings individually. The recording will not begin until start is called. Only a single pending recording can be started per Recorder instance.

Parameters
@NonNull Context context

the context used to enforce runtime permissions, interface with the media scanner service, and attribute access to permission protected data, such as audio. If using this context to audit audio access on API level 31+, a context created with createAttributionContext should be used.
@NonNull MediaStoreOutputOptions mediaStoreOutputOptions

the options that configures how the output will be handled.
Returns
@NonNull PendingRecording

a PendingRecording that is associated with this Recorder.
See also
MediaStoreOutputOptions