PlaybackException

public class PlaybackException extends Exception implements Bundleable

java.lang.Object
   ↳ kotlin.Throwable
     ↳ java.lang.Exception
       ↳ androidx.media3.common.PlaybackException
Known direct subclasses
ExoPlaybackException

Thrown when a non locally recoverable playback failure occurs.

Thrown when a non locally recoverable playback failure occurs.

Summary

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

Codes that identify causes of player errors.

Constants
static final Bundleable.Creator<PlaybackException>

This field is deprecated.

Use fromBundle instead.
static final int

Player implementations that want to surface custom errors can use error codes greater than this value, so as to avoid collision with other error codes defined in this class.
static final int

Caused by an AudioTrack initialization failure.
static final int

Caused by an AudioTrack write operation failure in offload mode.
static final int

Caused by an AudioTrack write operation failure in offload mode.
static final int

Caused by an AudioTrack write operation failure.
static final int

Caused by the loading position falling behind the sliding window of available live content.
static final int

Caused by a decoder initialization failure.
static final int

Caused by a decoder query 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 exceeds the capabilities of the device.
static final int

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

Caused by attempting to play incompatible DRM-protected content.
static final int

Caused by the device having revoked DRM privileges.
static final int

Caused by an operation being disallowed by a license policy.
static final int

Caused by a failure while trying to obtain a license.
static final int

Caused by an expired DRM license being loaded into an open DRM session.
static final int

Caused by a failure while provisioning the device.
static final int

Caused by a chosen DRM protection scheme not being supported by the device.
static final int

Caused by an error in the DRM system.
static final int

Caused by an unspecified error related to DRM protection.
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 player 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 parsing error associated with a media container format bitstream.
static final int

Caused by attempting to extract a file with an unsupported media container format, or an unsupported media container feature.
static final int

Caused by a parsing error associated with a media manifest.
static final int

Caused by an unsupported feature in a media manifest.
static final int

Caused by an unidentified error in a remote Player, which is a Player that runs on a different host or process.
static final int

Caused by a generic timeout.
static final int

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

Caused by a failure when processing a video frame.
static final int

Caused by a failure when initializing a VideoFrameProcessor.
static final int

Defines a minimum field ID value for subclasses to use when implementing toBundle and delegating to PlaybackException.

Public fields
final int

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

The value of elapsedRealtime when this exception was created.

Public constructors
@UnstableApi
PlaybackException(
    @Nullable String message,
    @Nullable Throwable cause,
    @PlaybackException.ErrorCode int errorCode
)

Creates an instance.

Protected constructors

Creates a new instance using the fields obtained from the given Bundle.
@UnstableApi
PlaybackException(
    @Nullable String message,
    @Nullable Throwable cause,
    @PlaybackException.ErrorCode int errorCode,
    long timestampMs
)

Creates a new instance using the given values.

Public methods
boolean

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

Restores a PlaybackException from a Bundle.
final String

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

Returns the name of a given errorCode.
Bundle

Returns a Bundle representing the information stored in this object.

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

CREATOR

@UnstableApi
public static final Bundleable.Creator<PlaybackException> CREATOR

Object that can create a PlaybackException from a Bundle.

CUSTOM_ERROR_CODE_BASE

public static final int CUSTOM_ERROR_CODE_BASE = 1000000

Player implementations that want to surface custom errors can use error codes greater than this value, so as to avoid collision with other error codes defined in this class.

ERROR_CODE_AUDIO_TRACK_INIT_FAILED

public static final int ERROR_CODE_AUDIO_TRACK_INIT_FAILED = 5001

Caused by an AudioTrack initialization failure.

ERROR_CODE_AUDIO_TRACK_OFFLOAD_INIT_FAILED

@UnstableApi
public static final int ERROR_CODE_AUDIO_TRACK_OFFLOAD_INIT_FAILED = 5004

Caused by an AudioTrack write operation failure in offload mode.

ERROR_CODE_AUDIO_TRACK_OFFLOAD_WRITE_FAILED

@UnstableApi
public static final int ERROR_CODE_AUDIO_TRACK_OFFLOAD_WRITE_FAILED = 5003

Caused by an AudioTrack write operation failure in offload mode.

ERROR_CODE_AUDIO_TRACK_WRITE_FAILED

public static final int ERROR_CODE_AUDIO_TRACK_WRITE_FAILED = 5002

Caused by an AudioTrack write operation failure.

ERROR_CODE_BEHIND_LIVE_WINDOW

public static final int ERROR_CODE_BEHIND_LIVE_WINDOW = 1002

Caused by the loading position falling behind the sliding window of available live content.

ERROR_CODE_DECODER_INIT_FAILED

public static final int ERROR_CODE_DECODER_INIT_FAILED = 4001

Caused by a decoder initialization failure.

ERROR_CODE_DECODER_QUERY_FAILED

public static final int ERROR_CODE_DECODER_QUERY_FAILED = 4002

Caused by a decoder query failure.

ERROR_CODE_DECODING_FAILED

public static final int ERROR_CODE_DECODING_FAILED = 4003

Caused by a failure while trying to decode media samples.

ERROR_CODE_DECODING_FORMAT_EXCEEDS_CAPABILITIES

public static final int ERROR_CODE_DECODING_FORMAT_EXCEEDS_CAPABILITIES = 4004

Caused by trying to decode content whose format exceeds the capabilities of the device.

ERROR_CODE_DECODING_FORMAT_UNSUPPORTED

public static final int ERROR_CODE_DECODING_FORMAT_UNSUPPORTED = 4005

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

ERROR_CODE_DRM_CONTENT_ERROR

public static final int ERROR_CODE_DRM_CONTENT_ERROR = 6003

Caused by attempting to play incompatible DRM-protected content.

For example, this can happen when attempting to play a DRM protected stream using a scheme (like Widevine) for which there is no corresponding license acquisition data (like a pssh box).

ERROR_CODE_DRM_DEVICE_REVOKED

public static final int ERROR_CODE_DRM_DEVICE_REVOKED = 6007

Caused by the device having revoked DRM privileges.

ERROR_CODE_DRM_DISALLOWED_OPERATION

public static final int ERROR_CODE_DRM_DISALLOWED_OPERATION = 6005

Caused by an operation being disallowed by a license policy.

ERROR_CODE_DRM_LICENSE_ACQUISITION_FAILED

public static final int ERROR_CODE_DRM_LICENSE_ACQUISITION_FAILED = 6004

Caused by a failure while trying to obtain a license.

ERROR_CODE_DRM_LICENSE_EXPIRED

public static final int ERROR_CODE_DRM_LICENSE_EXPIRED = 6008

Caused by an expired DRM license being loaded into an open DRM session.

ERROR_CODE_DRM_PROVISIONING_FAILED

public static final int ERROR_CODE_DRM_PROVISIONING_FAILED = 6002

Caused by a failure while provisioning the device.

ERROR_CODE_DRM_SCHEME_UNSUPPORTED

public static final int ERROR_CODE_DRM_SCHEME_UNSUPPORTED = 6001

Caused by a chosen DRM protection scheme not being supported by the device. Examples of DRM protection schemes are ClearKey and Widevine.

ERROR_CODE_DRM_SYSTEM_ERROR

public static final int ERROR_CODE_DRM_SYSTEM_ERROR = 6006

Caused by an error in the DRM system.

ERROR_CODE_DRM_UNSPECIFIED

public static final int ERROR_CODE_DRM_UNSPECIFIED = 6000

Caused by an unspecified error related to DRM protection.

ERROR_CODE_FAILED_RUNTIME_CHECK

public static final int ERROR_CODE_FAILED_RUNTIME_CHECK = 1004

Caused by a failed runtime check.

This can happen when the application fails to comply with the player's API requirements (for example, by passing invalid arguments), or when the player 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 player trying to access cleartext HTTP traffic (meaning http:// rather than https://) when the app's Network Security Configuration does not permit it.

See this corresponding troubleshooting topic.

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 player 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 (you can check this by querying getActiveNetwork).
  • 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_PARSING_CONTAINER_MALFORMED

public static final int ERROR_CODE_PARSING_CONTAINER_MALFORMED = 3001

Caused by a parsing error associated with a media container format bitstream.

ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED

public static final int ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED = 3003

Caused by attempting to extract a file with an unsupported media container format, or an unsupported media container feature.

ERROR_CODE_PARSING_MANIFEST_MALFORMED

public static final int ERROR_CODE_PARSING_MANIFEST_MALFORMED = 3002

Caused by a parsing error associated with a media manifest. Examples of a media manifest are a DASH or a SmoothStreaming manifest, or an HLS playlist.

ERROR_CODE_PARSING_MANIFEST_UNSUPPORTED

public static final int ERROR_CODE_PARSING_MANIFEST_UNSUPPORTED = 3004

Caused by an unsupported feature in a media manifest. Examples of a media manifest are a DASH or a SmoothStreaming manifest, or an HLS playlist.

ERROR_CODE_REMOTE_ERROR

public static final int ERROR_CODE_REMOTE_ERROR = 1001

Caused by an unidentified error in a remote Player, which is a Player that runs on a different host or process.

ERROR_CODE_TIMEOUT

public static final int ERROR_CODE_TIMEOUT = 1003

Caused by a generic timeout.

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

@UnstableApi
public static final int ERROR_CODE_VIDEO_FRAME_PROCESSING_FAILED = 7001

Caused by a failure when processing a video frame.

ERROR_CODE_VIDEO_FRAME_PROCESSOR_INIT_FAILED

@UnstableApi
public static final int ERROR_CODE_VIDEO_FRAME_PROCESSOR_INIT_FAILED = 7000

Caused by a failure when initializing a VideoFrameProcessor.

FIELD_CUSTOM_ID_BASE

@UnstableApi
protected static final int FIELD_CUSTOM_ID_BASE = 1000

Defines a minimum field ID value for subclasses to use when implementing toBundle and delegating to PlaybackException.

Subclasses should obtain their Bundle's field keys by applying a non-negative offset on this constant and passing the result to intToStringMaxRadix.

Public fields

errorCode

@PlaybackException.ErrorCode
public final int errorCode

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

timestampMs

public final long timestampMs

The value of elapsedRealtime when this exception was created.

Public constructors

PlaybackException

@UnstableApi
public PlaybackException(
    @Nullable String message,
    @Nullable Throwable cause,
    @PlaybackException.ErrorCode int errorCode
)

Creates an instance.

Parameters
@Nullable String message

See getMessage.
@Nullable Throwable cause

See getCause.
@PlaybackException.ErrorCode int errorCode

A number which identifies the cause of the error. May be one of the ErrorCodes.

Protected constructors

PlaybackException

@UnstableApi
protected PlaybackException(Bundle bundle)

Creates a new instance using the fields obtained from the given Bundle.

PlaybackException

@UnstableApi
protected PlaybackException(
    @Nullable String message,
    @Nullable Throwable cause,
    @PlaybackException.ErrorCode int errorCode,
    long timestampMs
)

Creates a new instance using the given values.

Public methods

errorInfoEquals

@CallSuper
public boolean errorInfoEquals(@Nullable PlaybackException 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' stacktraces.

fromBundle

@UnstableApi
public static PlaybackException fromBundle(Bundle bundle)

Restores a PlaybackException from a Bundle.

getErrorCodeName

public final String getErrorCodeName()

Equivalent to PlaybackException.getErrorCodeName(this.errorCode).

getErrorCodeName

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

Returns the name of a given errorCode.

toBundle

@UnstableApi
@CallSuper
public Bundle toBundle()

Returns a Bundle representing the information stored in this object.