PendingRecording

@RequiresApi(value = 21)
class PendingRecording


A recording that can be started at a future time.

A pending recording allows for configuration of a recording before it is started. Once a pending recording is started with start, any changes to the pending recording will not affect the actual recording; any modifications to the recording will need to occur through the controls of the Recording class returned by start.

A pending recording can be created using one of the Recorder methods for starting a recording such as prepareRecording.

There may be more settings that can only be changed per-recorder instead of per-recording, because it requires expensive operations like reconfiguring the camera. For those settings, use the Recorder.Builder methods to configure before creating the Recorder instance, then create the pending recording with it.

Summary

Public functions

PendingRecording

Configures the recording to be a persistent recording.

Recording
start(listenerExecutor: Executor, listener: Consumer<VideoRecordEvent!>)

Starts the recording, making it an active recording.

PendingRecording
@RequiresPermission(value = Manifest.permission.RECORD_AUDIO)
withAudioEnabled()

Enables audio to be recorded for this recording.

Public functions

asPersistentRecording

Added in 1.3.0
@ExperimentalPersistentRecording
fun asPersistentRecording(): PendingRecording

Configures the recording to be a persistent recording.

A persistent recording will only be stopped by explicitly calling stop or close and will ignore events that would normally cause recording to stop, such as lifecycle events or explicit unbinding of a VideoCapture use case that the recording's Recorder is attached to.

Even though lifecycle events or explicit unbinding use cases won't stop a persistent recording, it will still stop the camera from producing data, resulting in the in-progress persistent recording stopping getting data until the camera stream is activated again. For example, when the activity goes into background, the recording will keep waiting for new data to be recorded until the activity is back to foreground.

A Recorder instance is recommended to be associated with a single VideoCapture instance, especially when using persistent recording. Otherwise, there might be unexpected behavior. Any in-progress persistent recording created from the same Recorder should be stopped before starting a new recording, even if the Recorder is associated with a different VideoCapture.

To switch to a different camera stream while a recording is in progress, first create the recording as persistent recording, then rebind the VideoCapture it's associated with to a different camera. The implementation may be like:

// Prepare the Recorder and VideoCapture, then bind the VideoCapture to the back camera.
Recorder recorder = Recorder.Builder().build();
VideoCapture videoCapture = VideoCapture.withOutput(recorder);
cameraProvider.bindToLifecycle(
        lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, videoCapture);

// Prepare the persistent recording and start it.
Recording recording = recorder
        .prepareRecording(context, outputOptions)
        .asPersistentRecording()
        .start(eventExecutor, eventListener);

// Record from the back camera for a period of time.

// Rebind the VideoCapture to the front camera.
cameraProvider.unbindAll();
cameraProvider.bindToLifecycle(
        lifecycleOwner, CameraSelector.DEFAULT_FRONT_CAMERA, videoCapture);

// Record from the front camera for a period of time.

// Stop the recording explicitly.
recording.stop();

The audio data will still be recorded after the VideoCapture is unbound. Pause the recording first and resume it later to stop recording audio while rebinding use cases.

If the recording is unable to receive data from the new camera, possibly because of incompatible surface combination, an exception will be thrown when binding to lifecycle.

start

Added in 1.1.0
fun start(listenerExecutor: Executor, listener: Consumer<VideoRecordEvent!>): Recording

Starts the recording, making it an active recording.

Only a single recording can be active at a time, so if another recording is active, this will throw an IllegalStateException.

If there are no errors starting the recording, the returned Recording can be used to pause, resume, or stop the recording.

Upon successfully starting the recording, a VideoRecordEvent.Start event will be the first event sent to the provided event listener.

If errors occur while starting the recording, a VideoRecordEvent.Finalize event will be the first event sent to the provided listener, and information about the error can be found in that event's getError method. The returned Recording will be in a finalized state, and all controls will be no-ops.

If the returned Recording is garbage collected, the recording will be automatically stopped. A reference to the active recording must be maintained as long as the recording needs to be active. If the recording is garbage collected, the VideoRecordEvent.Finalize event will contain error ERROR_RECORDING_GARBAGE_COLLECTED.

The Recording will be stopped automatically if the VideoCapture its Recorder is attached to is unbound unless it's created as a persistent recording.

Parameters
listenerExecutor: Executor

the executor that the event listener will be run on.

listener: Consumer<VideoRecordEvent!>

the event listener to handle video record events.

Throws
java.lang.IllegalStateException

if the associated Recorder currently has an unfinished active recording.

withAudioEnabled

Added in 1.1.0
@RequiresPermission(value = Manifest.permission.RECORD_AUDIO)
fun withAudioEnabled(): PendingRecording

Enables audio to be recorded for this recording.

This method must be called prior to start to enable audio in the recording. If this method is not called, the Recording generated by start will not contain audio, and getAudioState will always return AUDIO_STATE_DISABLED for all RecordingStats send to the listener set passed to start.

Recording with audio requires the RECORD_AUDIO permission; without it, recording will fail at start with an IllegalStateException.

Returns
PendingRecording

this pending recording

Throws
java.lang.IllegalStateException

if the Recorder this recording is associated to doesn't support audio.

java.lang.SecurityException

if the RECORD_AUDIO permission is denied for the current application.