VideoRecordEvent.Finalize
public final class VideoRecordEvent.Finalize extends VideoRecordEvent
| java.lang.Object | ||
| ↳ | androidx.camera.video.VideoRecordEvent | |
| ↳ | androidx.camera.video.VideoRecordEvent.Finalize | |
Indicates the finalization of recording.
The finalize event will be triggered regardless of whether the recording succeeds or fails. Use getError to obtain the error type and getCause to get the error cause. If there is no error, ERROR_NONE will be returned. Other error types indicate the recording is failed or stopped due to a certain reason. Please note that receiving a finalize event with error does not necessarily mean that the video file has not been generated. In some cases, the file can still be successfully generated depending on the error type. For example, a file will still be generated when the recording is finalized with ERROR_FILE_SIZE_LIMIT_REACHED. A file may or may not be generated when the recording is finalized with ERROR_INSUFFICIENT_STORAGE. Example to detect if an output file is generated:
if (videoRecordEvent instanceof VideoRecordEvent.Finalize) { VideoRecordEvent.Finalize finalizeEvent = (VideoRecordEvent.Finalize) videoRecordEvent; OutputOptions options = finalizeEvent.getOutputOptions(); switch (finalizeEvent.getError()) { case ERROR_INSUFFICIENT_STORAGE: if (options instanceof FileOutputOptions) { if (((FileOutputOptions) options).getFile().exists()) { // file exists } } else if (options instanceof MediaStoreOutputOptions) { Uri uri = finalizeEvent.getOutputResults().getOutputUri(); if (uri != Uri.EMPTY) { // file exists } } else if (options instanceof FileDescriptorOutputOptions) { // User has to check the referenced target of the file descriptor. } break; } }
For certain types of errors, the output file will not be constructed correctly, and it will be the user's responsibility to deal with the incomplete file, such as deleting it. Example to delete the file:
if (videoRecordEvent instanceof VideoRecordEvent.Finalize) { VideoRecordEvent.Finalize finalizeEvent = (VideoRecordEvent.Finalize) videoRecordEvent; OutputOptions options = finalizeEvent.getOutputOptions(); switch (finalizeEvent.getError()) { case ERROR_UNKNOWN: case ERROR_RECORDER_ERROR: case ERROR_ENCODING_FAILED: case ERROR_NO_VALID_DATA: if (options instanceof FileOutputOptions) { ((FileOutputOptions) options).getFile().delete(); } else if (options instanceof MediaStoreOutputOptions) { Uri uri = finalizeEvent.getOutputResults().getOutputUri(); if (uri != Uri.EMPTY) { context.getContentResolver().delete(uri, null, null); } } else if (options instanceof FileDescriptorOutputOptions) { // User has to clean up the referenced target of the file descriptor. } break; } }
If there's no error that prevents the file to be generated, the file can be accessed safely after receiving the finalize event.
Summary
Constants |
|
|---|---|
static final int |
The recording failed due to duration limitation. |
static final int |
The recording failed while encoding. |
static final int |
The recording failed due to file size limitation. |
static final int |
The recording failed due to insufficient storage space. |
static final int |
The recording failed due to invalid output options. |
static final int |
ERROR_NONE = 0The recording succeeded with no error. |
static final int |
The recording failed because no valid data was produced to be recorded. |
static final int |
The recording failed because the |
static final int |
The recording was stopped because the |
static final int |
The recording failed because the source becomes inactive and stops sending frames. |
static final int |
ERROR_UNKNOWN = 1An unknown error occurred. |
Public methods |
|
|---|---|
@Nullable Throwable |
getCause()Gets the error cause. |
int |
getError()Gets the error type for a video recording. |
@NonNull OutputResults |
Gets the |
boolean |
hasError()Indicates whether an error occurred. |
Inherited methods |
||||
|---|---|---|---|---|
|
Constants
ERROR_DURATION_LIMIT_REACHED
public static final int ERROR_DURATION_LIMIT_REACHED = 9
The recording failed due to duration limitation.
The duration limit refers to getDurationLimitMillis. The recording will be finalized automatically with this error when the limit is reached and the data produced before the limit is reached will be saved to the output file.
ERROR_ENCODING_FAILED
public static final int ERROR_ENCODING_FAILED = 6
The recording failed while encoding.
This error may be generated when the video or audio codec encounters an error during encoding. When this happens and the output file is generated, the output file is not properly constructed. The application will need to clean up the output file, such as deleting the file.
ERROR_FILE_SIZE_LIMIT_REACHED
public static final int ERROR_FILE_SIZE_LIMIT_REACHED = 2
The recording failed due to file size limitation.
The file size limit refers to getFileSizeLimit. The recording will be finalized automatically with this error when the limit is reached and the data produced before the limit is reached will be saved to the output file.
ERROR_INSUFFICIENT_STORAGE
public static final int ERROR_INSUFFICIENT_STORAGE = 3
The recording failed due to insufficient storage space.
There are two possible cases that will cause this error.
- The storage is already full before the recording starts, so no output file will be generated.
- The storage becomes full during recording, so the output file will be generated.
ERROR_INVALID_OUTPUT_OPTIONS
public static final int ERROR_INVALID_OUTPUT_OPTIONS = 5
The recording failed due to invalid output options.
This error is generated when invalid output options have been used while preparing a recording, such as with the prepareRecording method. The error will depend on the subclass of OutputOptions used.
No output file will be generated with this error.
ERROR_NONE
public static final int ERROR_NONE = 0
The recording succeeded with no error.
ERROR_NO_VALID_DATA
public static final int ERROR_NO_VALID_DATA = 8
The recording failed because no valid data was produced to be recorded.
This error is generated when the essential data for a recording to be played correctly is missing, for example, a recording must contain at least one key frame. The application will need to clean up the output file, such as deleting the file.
ERROR_RECORDER_ERROR
public static final int ERROR_RECORDER_ERROR = 7
The recording failed because the Recorder is in an unrecoverable error state.
When this happens and the output file is generated, the output file is not properly constructed. The application will need to clean up the output file, such as deleting the file. Such an error will usually require creating a new Recorder object to start a new recording.
ERROR_RECORDING_GARBAGE_COLLECTED
public static final int ERROR_RECORDING_GARBAGE_COLLECTED = 10
The recording was stopped because the Recording object was garbage collected.
The Recording object returned by start must be referenced until the recording is no longer needed. If it is not, the active recording will be stopped and this error will be produced. Once stop or close has been invoked, the recording object no longer needs to be referenced.
ERROR_SOURCE_INACTIVE
public static final int ERROR_SOURCE_INACTIVE = 4
The recording failed because the source becomes inactive and stops sending frames.
One case is that if camera is closed due to lifecycle stopped, the active recording will be finalized with this error, and the output will be generated, containing the frames produced before camera closing. Attempting to start a new recording will be finalized immediately if the source remains inactive and no output will be generated.
ERROR_UNKNOWN
public static final int ERROR_UNKNOWN = 1
An unknown error occurred.
The output file may or moy not be generated. Since the error is not determined, application should clean up the output file, such as deleting it.
Public methods
getCause
public @Nullable Throwable getCause()
Gets the error cause.
Returns the error cause if any, otherwise returns null.
Note that not all error types include an error cause. For some error types, the file may still be generated successfully with no error cause. For example, ERROR_FILE_SIZE_LIMIT_REACHED, ERROR_DURATION_LIMIT_REACHED and ERROR_SOURCE_INACTIVE.
getError
public int getError()
Gets the error type for a video recording.
Possible values are ERROR_NONE, ERROR_UNKNOWN, ERROR_FILE_SIZE_LIMIT_REACHED, ERROR_INSUFFICIENT_STORAGE, ERROR_INVALID_OUTPUT_OPTIONS, ERROR_ENCODING_FAILED, ERROR_RECORDER_ERROR, ERROR_NO_VALID_DATA and ERROR_SOURCE_INACTIVE.
getOutputResults
public @NonNull OutputResults getOutputResults()
Gets the OutputResults.
hasError
public boolean hasError()
Indicates whether an error occurred.
Returns false if getError returns ERROR_NONE, otherwise true.