TransformationException

@UnstableApi
public final class TransformationException extends Exception

java.lang.Object
   ↳ kotlin.Throwable
     ↳ java.lang.Exception
       ↳ androidx.media3.transformer.TransformationException

Summary

Nested types
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(open = true, value = )
public annotation TransformationException.ErrorCode

Error codes that identify causes of Transformer errors.

Constants
static final int

Caused by an audio processing failure.
static final int

Caused by a decoder initialization failure.
static final int

Caused by a failure while trying to decode media samples.
static final int

Caused by trying to decode content whose format is not supported.
static final int

Caused by an encoder initialization failure.
static final int

Caused by a failure while trying to encode media samples.
static final int

Caused by trying to encode content whose format is not supported. *

static final int

Caused by a failed runtime check.
static final int

Caused by an HTTP server returning an unexpected HTTP response status code.
static final int

Caused by the AssetLoader trying to access cleartext HTTP traffic (meaning http:// rather than https://) when the app's Network Security Configuration does not permit it.
static final int

Caused by a non-existent file.
static final int

Caused by a server returning a resource with an invalid "Content-Type" HTTP header value.
static final int

Caused by a network connection failure.
static final int

Caused by a network timeout, meaning the server is taking too long to fulfill a request.
static final int

Caused by lack of permission to perform an IO operation.
static final int

Caused by reading data out of the data bound.
static final int

Caused by an Input/Output error which could not be identified.
static final int

Caused by a failure while muxing media samples.
static final int

Caused by an error whose cause could not be identified.
static final int

Caused by a video frame processing failure.

Public fields
final int

An error code which identifies the cause of the transformation failure.
final long

The value of elapsedRealtime when this exception was created.

Public methods
static TransformationException
createForAssetLoader(Throwable cause, int errorCode)

Creates an instance for an AssetLoader related exception.
static TransformationException

Creates an instance for an audio processing related exception.
static TransformationException
createForCodec(
    Throwable cause,
    @TransformationException.ErrorCode int errorCode,
    boolean isVideo,
    boolean isDecoder,
    String details
)

Creates an instance for a Codec related exception.
static TransformationException
createForCodec(
    Throwable cause,
    @TransformationException.ErrorCode int errorCode,
    boolean isVideo,
    boolean isDecoder,
    Format format
)

Creates an instance for a Codec related exception.
static TransformationException

Creates an instance for an unexpected exception.
boolean

Returns whether the error data associated to this exception equals the error data associated to other.
String

Equivalent to TransformationException.getErrorCodeName(this.errorCode).
static String

Returns the name of a given errorCode.

Inherited methods
From java.lang.Throwable
synchronized final void
synchronized Throwable
synchronized Throwable
String
String
StackTraceElement[]
synchronized final Throwable[]
synchronized Throwable
void
void
setStackTrace(StackTraceElement[] stackTrace)
String

Constants

ERROR_CODE_AUDIO_PROCESSING_FAILED

public static final int ERROR_CODE_AUDIO_PROCESSING_FAILED = 6001

Caused by an audio processing failure.

ERROR_CODE_DECODER_INIT_FAILED

public static final int ERROR_CODE_DECODER_INIT_FAILED = 3001

Caused by a decoder initialization failure.

ERROR_CODE_DECODING_FAILED

public static final int ERROR_CODE_DECODING_FAILED = 3002

Caused by a failure while trying to decode media samples.

ERROR_CODE_DECODING_FORMAT_UNSUPPORTED

public static final int ERROR_CODE_DECODING_FORMAT_UNSUPPORTED = 3003

Caused by trying to decode content whose format is not supported.

ERROR_CODE_ENCODER_INIT_FAILED

public static final int ERROR_CODE_ENCODER_INIT_FAILED = 4001

Caused by an encoder initialization failure.

ERROR_CODE_ENCODING_FAILED

public static final int ERROR_CODE_ENCODING_FAILED = 4002

Caused by a failure while trying to encode media samples.

ERROR_CODE_ENCODING_FORMAT_UNSUPPORTED

public static final int ERROR_CODE_ENCODING_FORMAT_UNSUPPORTED = 4003

Caused by trying to encode content whose format is not supported. *

Supported output formats are limited by the encoders available.

ERROR_CODE_FAILED_RUNTIME_CHECK

public static final int ERROR_CODE_FAILED_RUNTIME_CHECK = 1001

Caused by a failed runtime check.

This can happen when transformer reaches an invalid state.

ERROR_CODE_IO_BAD_HTTP_STATUS

public static final int ERROR_CODE_IO_BAD_HTTP_STATUS = 2004

Caused by an HTTP server returning an unexpected HTTP response status code.

ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED

public static final int ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED = 2007

Caused by the AssetLoader trying to access cleartext HTTP traffic (meaning http:// rather than https://) when the app's Network Security Configuration does not permit it.

ERROR_CODE_IO_FILE_NOT_FOUND

public static final int ERROR_CODE_IO_FILE_NOT_FOUND = 2005

Caused by a non-existent file.

ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE

public static final int ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE = 2003

Caused by a server returning a resource with an invalid "Content-Type" HTTP header value.

For example, this can happen when the AssetLoader is expecting a piece of media, but the server returns a paywall HTML page, with content type "text/html".

ERROR_CODE_IO_NETWORK_CONNECTION_FAILED

public static final int ERROR_CODE_IO_NETWORK_CONNECTION_FAILED = 2001

Caused by a network connection failure.

The following is a non-exhaustive list of possible reasons:

  • There is no network connectivity.
  • The URL's domain is misspelled or does not exist.
  • The target host is unreachable.
  • The server unexpectedly closes the connection.

ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT

public static final int ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT = 2002

Caused by a network timeout, meaning the server is taking too long to fulfill a request.

ERROR_CODE_IO_NO_PERMISSION

public static final int ERROR_CODE_IO_NO_PERMISSION = 2006

Caused by lack of permission to perform an IO operation. For example, lack of permission to access internet or external storage.

ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE

public static final int ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE = 2008

Caused by reading data out of the data bound.

ERROR_CODE_IO_UNSPECIFIED

public static final int ERROR_CODE_IO_UNSPECIFIED = 2000

Caused by an Input/Output error which could not be identified.

ERROR_CODE_MUXING_FAILED

public static final int ERROR_CODE_MUXING_FAILED = 7001

Caused by a failure while muxing media samples.

ERROR_CODE_UNSPECIFIED

public static final int ERROR_CODE_UNSPECIFIED = 1000

Caused by an error whose cause could not be identified.

ERROR_CODE_VIDEO_FRAME_PROCESSING_FAILED

public static final int ERROR_CODE_VIDEO_FRAME_PROCESSING_FAILED = 5001

Caused by a video frame processing failure.

Public fields

errorCode

@TransformationException.ErrorCode
public final int errorCode

An error code which identifies the cause of the transformation failure.

timestampMs

public final long timestampMs

The value of elapsedRealtime when this exception was created.

Public methods

createForAssetLoader

public static TransformationException createForAssetLoader(Throwable cause, int errorCode)

Creates an instance for an AssetLoader related exception.

Parameters
Throwable cause

The cause of the failure.
int errorCode

See errorCode.
Returns
TransformationException

The created instance.

createForAudioProcessing

public static TransformationException createForAudioProcessing(
    Throwable cause,
    AudioProcessor.AudioFormat audioFormat
)

Creates an instance for an audio processing related exception.

Parameters
Throwable cause

The cause of the failure.
AudioProcessor.AudioFormat audioFormat

The AudioFormat used.
Returns
TransformationException

The created instance.

createForCodec

public static TransformationException createForCodec(
    Throwable cause,
    @TransformationException.ErrorCode int errorCode,
    boolean isVideo,
    boolean isDecoder,
    String details
)

Creates an instance for a Codec related exception.

Parameters
Throwable cause

The cause of the failure.
@TransformationException.ErrorCode int errorCode

See errorCode.
boolean isVideo

Whether the Codec is configured for video.
boolean isDecoder

Whether the exception is created for a decoder.
String details

The details associated with this exception.
Returns
TransformationException

The created instance.

createForCodec

public static TransformationException createForCodec(
    Throwable cause,
    @TransformationException.ErrorCode int errorCode,
    boolean isVideo,
    boolean isDecoder,
    Format format
)

Creates an instance for a Codec related exception.

This method should be used when the cause occurs before the Codec is initialized.

Parameters
Throwable cause

The cause of the failure.
@TransformationException.ErrorCode int errorCode

See errorCode.
boolean isVideo

Whether the Codec is configured for video.
boolean isDecoder

Whether the exception is created for a decoder.
Format format

The Format used for configuring the Codec.
Returns
TransformationException

The created instance.

createForUnexpected

public static TransformationException createForUnexpected(Exception cause)

Creates an instance for an unexpected exception.

If the exception is a runtime exception, error code ERROR_CODE_FAILED_RUNTIME_CHECK is used. Otherwise, the created instance has error code ERROR_CODE_UNSPECIFIED.

Parameters
Exception cause

The cause of the failure.
Returns
TransformationException

The created instance.

errorInfoEquals

public boolean errorInfoEquals(@Nullable TransformationException other)

Returns whether the error data associated to this exception equals the error data associated to other.

Note that this method does not compare the exceptions' stack traces.

getErrorCodeName

public String getErrorCodeName()

Equivalent to TransformationException.getErrorCodeName(this.errorCode).

getErrorCodeName

public static String getErrorCodeName(@TransformationException.ErrorCode int errorCode)

Returns the name of a given errorCode.