PendingRecording
public final 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 Recorder.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 methods |
|
|---|---|
final @NonNull PendingRecording |
Configures the recording to be a persistent recording. |
final @NonNull Recording |
Starts the recording, making it an active recording. |
final @NonNull PendingRecording |
@RequiresPermission(value = "android.permission.RECORD_AUDIO")Enables audio to be recorded for this recording. |
Public methods
asPersistentRecording
@ExperimentalPersistentRecording
public final @NonNull PendingRecording asPersistentRecording()
Configures the recording to be a persistent recording.
A persistent recording will only be stopped by explicitly calling Recording.stop or Recording.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
public final @NonNull Recording start(
@NonNull Executor listenerExecutor,
@NonNull Consumer<@NonNull VideoRecordEvent> listener
)
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 VideoRecordEvent.Finalize.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 VideoRecordEvent.Finalize.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 | |
|---|---|
@NonNull Executor listenerExecutor |
the executor that the event listener will be run on. |
@NonNull Consumer<@NonNull VideoRecordEvent> listener |
the event listener to handle video record events. |
| Throws | |
|---|---|
kotlin.IllegalStateException |
if the associated Recorder currently has an unfinished active recording. |
withAudioEnabled
@RequiresPermission(value = "android.permission.RECORD_AUDIO")
public final @NonNull PendingRecording withAudioEnabled(boolean initialMuted)
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 AudioStats.getAudioState will always return AudioStats.AUDIO_STATE_DISABLED for all RecordingStats send to the listener set passed to start.
Recording with audio requires the android.Manifest.permission.RECORD_AUDIO permission; without it, recording will fail at start with an IllegalStateException.
| Parameters | |
|---|---|
boolean initialMuted |
(Optional) The initial mute state of the recording. Defaults to |
| Returns | |
|---|---|
@NonNull PendingRecording |
this pending recording |
| Throws | |
|---|---|
kotlin.IllegalStateException |
if the |
java.lang.SecurityException |
if the |