Stay organized with collections Save and categorize content based on your preferences.

Recorder

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

Builder class for Recorder objects.

Constants
static final QualitySelector

Default quality selector for recordings.

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

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

Public methods

getAspectRatio

public int getAspectRatio()

Gets the aspect ratio of this Recorder.

Returns
int

the value from setAspectRatio or RATIO_DEFAULT if not set.

getExecutor

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

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

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.

onSurfaceRequested

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

@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 java.lang.UnsupportedOperationException

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

prepareRecording

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

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