Recorder

@RequiresApi(value = 21)
class Recorder : 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.

Summary

Nested types

@RequiresApi(value = 21)
class Recorder.Builder

Builder class for Recorder objects.

Constants

const QualitySelector!

Default quality selector for recordings.

const Int

Video capabilities are derived from CamcorderProfile.

const Int

Video capabilities are derived from codec capabilities.

Public functions

Int

Gets the aspect ratio of this Recorder.

Executor?

Returns the executor provided to the builder for this recorder.

QualitySelector

Gets the quality selector of this Recorder.

Int

Gets the target video encoding bitrate of this Recorder.

java-static VideoCapabilities

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

java-static VideoCapabilities
getVideoCapabilities(
    cameraInfo: CameraInfo,
    videoCapabilitiesSource: Int
)

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

Int

Gets the video capabilities source of this Recorder.

Unit

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

PendingRecording
@RequiresApi(value = 26)
prepareRecording(
    context: Context,
    fileDescriptorOutputOptions: FileDescriptorOutputOptions
)

Prepares a recording that will be saved to a ParcelFileDescriptor.

PendingRecording
prepareRecording(context: Context, fileOutputOptions: FileOutputOptions)

Prepares a recording that will be saved to a File.

PendingRecording
prepareRecording(
    context: Context,
    mediaStoreOutputOptions: MediaStoreOutputOptions
)

Prepares a recording that will be saved to a MediaStore.

Constants

DEFAULT_QUALITY_SELECTOR

Added in 1.1.0
const val DEFAULT_QUALITY_SELECTORQualitySelector!

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-alpha04
const val VIDEO_CAPABILITIES_SOURCE_CAMCORDER_PROFILE = 0: Int

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.

VIDEO_CAPABILITIES_SOURCE_CODEC_CAPABILITIES

Added in 1.4.0-alpha04
const val VIDEO_CAPABILITIES_SOURCE_CODEC_CAPABILITIES = 1: Int

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.

Public functions

getAspectRatio

Added in 1.3.0
fun getAspectRatio(): Int

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
fun getExecutor(): Executor?

Returns the executor provided to the builder for this recorder.

Returns
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
fun getQualitySelector(): QualitySelector

Gets the quality selector of this Recorder.

Returns
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
fun getTargetVideoEncodingBitRate(): Int

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
java-static fun getVideoCapabilities(cameraInfo: CameraInfo): VideoCapabilities

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
cameraInfo: CameraInfo

info about the camera.

Returns
VideoCapabilities

VideoCapabilities with respect to the input camera info.

getVideoCapabilities

Added in 1.4.0-alpha04
java-static fun getVideoCapabilities(
    cameraInfo: CameraInfo,
    videoCapabilitiesSource: Int
): VideoCapabilities

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
cameraInfo: CameraInfo

info about the camera.

videoCapabilitiesSource: Int

the video capabilities source.

Returns
VideoCapabilities

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

getVideoCapabilitiesSource

Added in 1.4.0-alpha04
fun getVideoCapabilitiesSource(): Int

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.4.0-alpha04
fun onSurfaceRequested(request: SurfaceRequest): Unit

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
request: SurfaceRequest

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)
fun prepareRecording(
    context: Context,
    fileDescriptorOutputOptions: FileDescriptorOutputOptions
): PendingRecording

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
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.

fileDescriptorOutputOptions: FileDescriptorOutputOptions

the options that configures how the output will be handled.

Returns
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.

prepareRecording

Added in 1.1.0
fun prepareRecording(context: Context, fileOutputOptions: FileOutputOptions): PendingRecording

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
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.

fileOutputOptions: FileOutputOptions

the options that configures how the output will be handled.

Returns
PendingRecording

a PendingRecording that is associated with this Recorder.

prepareRecording

Added in 1.1.0
fun prepareRecording(
    context: Context,
    mediaStoreOutputOptions: MediaStoreOutputOptions
): PendingRecording

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
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.

mediaStoreOutputOptions: MediaStoreOutputOptions

the options that configures how the output will be handled.

Returns
PendingRecording

a PendingRecording that is associated with this Recorder.