# PendingRecording

Artifact: [androidx.camera:camera-video](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/video/PendingRecording.kt+class:androidx.camera.video.PendingRecording) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/camera#1.1.0)

*** ** * ** ***

<br />

```
public final class PendingRecording
```

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)`, 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 `https://developer.android.com/reference/androidx/camera/video/Recording` class returned by `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)`.

A pending recording can be created using one of the `https://developer.android.com/reference/androidx/camera/video/Recorder` methods for starting a recording such as `https://developer.android.com/reference/androidx/camera/video/Recorder#prepareRecording(android.content.Context,androidx.camera.video.FileOutputOptions)`.

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 `https://developer.android.com/reference/androidx/camera/video/Recorder.Builder` methods to configure before creating the `https://developer.android.com/reference/androidx/camera/video/Recorder` instance, then create the pending recording with it.

## Summary

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/video/PendingRecording` | `@https://developer.android.com/reference/androidx/camera/video/ExperimentalPersistentRecording https://developer.android.com/reference/androidx/camera/video/PendingRecording#asPersistentRecording()()` Configures the recording to be a persistent recording. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/video/Recording` | `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html listenerExecutor, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/util/Consumer<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/video/VideoRecordEvent> listener )` Starts the recording, making it an active recording. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/video/PendingRecording` | `@https://developer.android.com/reference/androidx/annotation/RequiresPermission(value = "android.permission.RECORD_AUDIO") https://developer.android.com/reference/androidx/camera/video/PendingRecording#withAudioEnabled(kotlin.Boolean)(boolean initialMuted)` Enables audio to be recorded for this recording. |

## Public methods

### asPersistentRecording

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

```
@ExperimentalPersistentRecording
public final @NonNull PendingRecording asPersistentRecording()
```

Configures the recording to be a persistent recording.

A persistent recording will only be stopped by explicitly calling `https://developer.android.com/reference/androidx/camera/video/Recording#stop()` or `https://developer.android.com/reference/androidx/camera/video/Recording#close()` and will ignore events that would normally cause recording to stop, such as lifecycle events or explicit unbinding of a `https://developer.android.com/reference/androidx/camera/video/VideoCapture` use case that the recording's `https://developer.android.com/reference/androidx/camera/video/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 `https://developer.android.com/reference/androidx/camera/video/Recorder` instance is recommended to be associated with a single `https://developer.android.com/reference/androidx/camera/video/VideoCapture` instance, especially when using persistent recording. Otherwise, there might be unexpected behavior. Any in-progress persistent recording created from the same `https://developer.android.com/reference/androidx/camera/video/Recorder` should be stopped before starting a new recording, even if the `https://developer.android.com/reference/androidx/camera/video/Recorder` is associated with a different `https://developer.android.com/reference/androidx/camera/video/VideoCapture`.

To switch to a different camera stream while a recording is in progress, first create the recording as persistent recording, then rebind the `https://developer.android.com/reference/androidx/camera/video/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 `https://developer.android.com/reference/androidx/camera/video/VideoCapture` is unbound. `https://developer.android.com/reference/androidx/camera/video/Recording#pause()` the recording first and `https://developer.android.com/reference/androidx/camera/video/Recording#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](https://developer.android.com/jetpack/androidx/releases/camera#1.1.0)

```
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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html`.

If there are no errors starting the recording, the returned `https://developer.android.com/reference/androidx/camera/video/Recording` can be used to `https://developer.android.com/reference/androidx/camera/video/Recording#pause()`, `https://developer.android.com/reference/androidx/camera/video/Recording#resume()`, or `https://developer.android.com/reference/androidx/camera/video/Recording#stop()` the recording.

Upon successfully starting the recording, a `https://developer.android.com/reference/androidx/camera/video/VideoRecordEvent.Start` event will be the first event sent to the provided event listener.

If errors occur while starting the recording, a `https://developer.android.com/reference/androidx/camera/video/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 `https://developer.android.com/reference/androidx/camera/video/VideoRecordEvent.Finalize#getError()` method. The returned `https://developer.android.com/reference/androidx/camera/video/Recording` will be in a finalized state, and all controls will be no-ops.

If the returned `https://developer.android.com/reference/androidx/camera/video/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 `https://developer.android.com/reference/androidx/camera/video/VideoRecordEvent.Finalize` event will contain error `https://developer.android.com/reference/androidx/camera/video/VideoRecordEvent.Finalize#ERROR_RECORDING_GARBAGE_COLLECTED()`.

The `https://developer.android.com/reference/androidx/camera/video/Recording` will be stopped automatically if the `https://developer.android.com/reference/androidx/camera/video/VideoCapture` its `https://developer.android.com/reference/androidx/camera/video/Recorder` is attached to is unbound unless it's created `https://developer.android.com/reference/androidx/camera/video/PendingRecording#asPersistentRecording()`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html listenerExecutor` | the executor that the event listener will be run on. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/util/Consumer<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/video/VideoRecordEvent> listener` | the event listener to handle video record events. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the associated Recorder currently has an unfinished active recording. |

### withAudioEnabled

Added in [1.5.0](https://developer.android.com/jetpack/androidx/releases/camera#1.5.0)

```
@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 `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)` to enable audio in the recording. If this method is not called, the `https://developer.android.com/reference/androidx/camera/video/Recording` generated by `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)` will not contain audio, and `https://developer.android.com/reference/androidx/camera/video/AudioStats#getAudioState()` will always return `https://developer.android.com/reference/androidx/camera/video/AudioStats#AUDIO_STATE_DISABLED()` for all `https://developer.android.com/reference/androidx/camera/video/RecordingStats` send to the listener set passed to `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)`.

Recording with audio requires the `https://developer.android.com/reference/android/Manifest.permission.html#RECORD_AUDIO` permission; without it, recording will fail at `https://developer.android.com/reference/androidx/camera/video/PendingRecording#start(java.util.concurrent.Executor,androidx.core.util.Consumer)` with an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html`.

| Parameters |
|---|---|
| `boolean initialMuted` | (Optional) The initial mute state of the recording. Defaults to `false` (un-muted). After the recording is started, the mute state can be changed by calling `https://developer.android.com/reference/androidx/camera/video/Recording#mute(boolean)`. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/video/PendingRecording` | this pending recording |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the `https://developer.android.com/reference/androidx/camera/video/Recorder` this recording is associated to doesn't support audio. |
| `https://developer.android.com/reference/java/lang/SecurityException.html` | if the `https://developer.android.com/reference/android/Manifest.permission.html#RECORD_AUDIO` permission is denied for the current application. |