Package com.castlabs.android.player.exceptions

# Class CastlabsPlayerException

java.lang.Object
java.lang.Throwable
java.lang.Exception
com.castlabs.android.player.exceptions.CastlabsPlayerException

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `FilterException`

public class CastlabsPlayerException extends Exception
Exception that represents a player error and wraps the cause and an optional error code. This class provides detailed information about playback errors, including severity levels, error types, and additional error data.

See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static @interface`
  `CastlabsPlayerException.Severity`
  Defines the severity of an error.
  `static @interface`
  `CastlabsPlayerException.Type`
  Defines the type of an error.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CODE`
  Error code associated with the error
  `static final String`
  `HTTP_CODE`
  HTTP response code associated with the error
  `static final String`
  `MSG_MANIFEST_LOADING_FAILED`
  Message reported by exceptions of type `TYPE_MANIFEST_LOADING_FAILED`
  `static final String`
  `MSG_VIDEO_DECODER_INITIALIZATION`
  Message reported by exceptions of type `TYPE_VIDEO_DECODER_INITIALIZATION`
  `static final String`
  `PLAYLIST_CURRENT_ITEM_INDEX`
  Bundle key for the index of the item that was playing when the error occurred.
  `static final String`
  `PLAYLIST_FAILED_ITEM`
  Bundle key for the PlayerConfig of the failed item in the playlist.
  `static final String`
  `PLAYLIST_FAILED_ITEM_INDEX`
  Bundle key for the index of the failed item in the playlist.
  `static final String`
  `PLAYLIST_SIZE`
  Bundle key for the total number of items in the playlist.
  `static final String`
  `PLAYLIST_STATE`
  Bundle key for the playlist state as an `ArrayList` of `PlayerConfig` items.
  `static final String`
  `RESPONSE_BODY`
  Response body associated with the error
  `static final String`
  `SEVERITY`
  Severity level of the error
  `static final int`
  `SEVERITY_ERROR`
  Error severity.
  `static final int`
  `SEVERITY_INFO`
  Info severity.
  `static final int`
  `SEVERITY_WARNING`
  Warning severity.
  `static final String`
  `TRACK_TYPE`
  The value of the key is the track type, one of `PlayerController.VIDEO_RENDERER`, `PlayerController.AUDIO_RENDERER`, `PlayerController.TEXT_RENDERER` or `PlayerController.METADATA_RENDERER`
  `static final int`
  `TYPE_AD_ERROR`
  This error is raised when a general error occurs at initializing or during an Ad.
  `static final int`
  `TYPE_AD_REQUEST_UNSUPPORTED`
  Error raised when trying to play Ads but the current Player setup doesn't support it.
  `static final int`
  `TYPE_API_MISMATCH`
  This error is raised if a method is called that is not supported on the current API level.
  `static final int`
  `TYPE_AUDIO_DECODER_INITIALIZATION`
  Error raised when the audio decoder can not be initialized.
  `static final int`
  `TYPE_AUDIO_DECRYPTION_ERROR`
  Raised when an error occurs while decrypting audio data.
  `static final int`
  `TYPE_AUDIO_TRACK_INITIALIZATION`
  Error raised when the track can not be initialized.
  `static final int`
  `TYPE_AUDIO_UNSUPPORTED`
  This error is raised if all audio tracks are filtered out as unsupported.
  `static final int`
  `TYPE_AUDIO_WRITE_ERROR`
  Raised when an error occurs while writing to the audio track.
  `static final int`
  `TYPE_BEHIND_LIVE_WINDOW`
  Error raised when the current playback position is behind the live edge in a live stream.
  `static final int`
  `TYPE_CONNECTIVITY_GAINED_INFO`
  This exception is raised after the player lost connectivity (`TYPE_CONNECTIVITY_LOST_ERROR`), once connectivity was re-gained.
  `static final int`
  `TYPE_CONNECTIVITY_LOST_ERROR`
  This error is raised if an exception occurred while downloading playback and no network connectivity is available.
  `static final int`
  `TYPE_CSL_LIMIT_REACHED`
  Error raised when concurrent stream limiting reaches maximum clients
  `static final int`
  `TYPE_CSL_NETWORK_ERROR`
  Error raised when there's a network error with the concurrent stream limiting service
  `static final int`
  `TYPE_DATA_DOWLOAD_ERROR`
  This error is raised if an exception occurred while downloading data.
  `static final int`
  `TYPE_DNS_SERVER_ERROR`
  This error is raised when a DNS server error occurs.
  `static final int`
  `TYPE_DOWNLOAD_ERROR`
  This error is raised if an exception occurred while downloading playback data.
  `static final int`
  `TYPE_DOWNLOAD_WARNING`
  This error is raised if an exception occurred while downloading playback data.
  `static final int`
  `TYPE_DRM_EXCEPTION`
  This error is raised if an exception occurred while the player was communicating with DRM server to fetch a license.
  `static final int`
  `TYPE_DRM_KEY_DOWNLOAD_ERROR`
  This error is raised if a DRM key could not be fetched successfully.
  `static final int`
  `TYPE_DRM_PROVISION_ERROR`
  Error raised during device provisioning
  `static final int`
  `TYPE_DRMTODAY_EXCEPTION`
  This error is raised if an exception occurred while the player was communicating with DRMToday to fetch a license.
  `static final int`
  `TYPE_HDCP_CONNECTION_WARNING`
  This exception is raised after the player sees changes in HDCP connectivity.
  `static final int`
  `TYPE_INVALID_PLAYER_LICENSE`
  Error raised when the Castlabs player license is invalid or expired.
  `static final int`
  `TYPE_KEY_EXPIRED`
  This error is raised if a DRM key expires during playback.
  `static final int`
  `TYPE_MANIFEST_INVALID`
  This error happens when the player found a semantic issue with a Manifest.
  `static final int`
  `TYPE_MANIFEST_LOADING_FAILED`
  This error type is raised when loading the player manifest (i.e.
  `static final int`
  `TYPE_MANIFEST_PARSING_FAILED`
  This error type is raised when parsing the player manifest (i.e.
  `static final int`
  `TYPE_NO_PLAYABLE_CONTENT`
  Error raised when the applied filters were not able to find any viable content that can be displayed on the current device.
  `static final int`
  `TYPE_NO_RENDERER_FOUND`
  Error raised when no plugin was found that can be used to create a renderer to playback a given DRM and content combination.
  `static final int`
  `TYPE_PLAYBACK_ERROR`
  Error raised when the ExoPlayer reports a general playback error.
  `static final int`
  `TYPE_PLAYLIST_ITEM_PREFETCH_FAILED`
  Error raised when an item fails to load during prefetch (while another item is playing).
  `static final int`
  `TYPE_PLAYLIST_ITEM_TRANSITION_FAILED`
  Error raised when the player tries to transition to an item that failed to load.
  `static final int`
  `TYPE_SDK_INIT_ERROR`
  Error raised when the SDK could not be initialised successfully.
  `static final int`
  `TYPE_SDK_NOT_INITIALIZED`
  Error raised when the SDK was not initialized using one of `PlayerSDK.init(Context)` or `PlayerSDK.init(Context, LicenseLoader)`.
  `static final int`
  `TYPE_SECONDARY_DISPLAY`
  This error is raised if a secondary display is detected and the current configuration does not permit playback on that display.
  `static final int`
  `TYPE_TEXT_UNSUPPORTED`
  This error is raised if all text tracks are filtered out as unsupported.
  `static final int`
  `TYPE_TIME_OUT_ERROR`
  This error is raised when a timeout error occurs.
  `static final int`
  `TYPE_TUNNELING_ERROR`
  This error happens when tunneling mode can not be enabled on a device and the playback in non-tunneling mode continues.
  `static final int`
  `TYPE_UNKNOWN`
  Error raised with an unknown type
  `static final int`
  `TYPE_UNSUPPORTED_DRM`
  This error is raised if you are trying to use a DRM system that is not supported by the device.
  `static final int`
  `TYPE_USER_ID_NOT_PROVIDED`
  Error raised when the userID is mandatory and has not been provided.
  `static final int`
  `TYPE_VIDEO_BLOCKLIST_FAILED`
  This error is raised when video quality blocklisting fails as the current quality is the only video quality left for playback.
  `static final int`
  `TYPE_VIDEO_DECODER_INITIALIZATION`
  Raised when the video decoder can not be initialized.
  `static final int`
  `TYPE_VIDEO_DECRYPTION_ERROR`
  Raised when an error occurs while decrypting audio data.
  `static final int`
  `TYPE_VIDEO_UNSUPPORTED`
  This error is raised if all video tracks are filtered out as unsupported.
  `static final String`
  `URL`
  URL associated with the error

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CastlabsPlayerException(int severity, int type, String message)`
  Creates a new CastlabsPlayerException with the specified severity, type, and message.
  `CastlabsPlayerException(int severity, int type, String message, Throwable cause)`
  Creates a new CastlabsPlayerException with the specified severity, type, message, and cause.
  `CastlabsPlayerException(int severity, int type, String message, Throwable cause, String explicitCauseMessage)`
  Creates a new CastlabsPlayerException with the specified severity, type, message, cause, and explicit cause message.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static CastlabsPlayerException`
  `createError(int severity, String message, PlaylistException playlistException)`
  Creates a fatal exception for a download error.
  `static CastlabsPlayerException`
  `createError(int severity, String message, com.google.android.exoplayer2.upstream.HttpDataSource.HttpDataSourceException e)`
  Creates an error exception for an HTTP data source error.
  `static CastlabsPlayerException`
  `createError(int severity, String message, com.google.android.exoplayer2.upstream.HttpDataSource.InvalidResponseCodeException e)`
  Creates an error exception for an invalid HTTP response code.
  `static CastlabsPlayerException`
  `createFatal(DownloadException downloadException)`
  Creates a fatal exception for a download error.
  `static CastlabsPlayerException`
  `createFatal(com.google.android.exoplayer2.source.dash.DashPeriodNotFoundException exception)`
  Creates a fatal exception for a DASH period not found error.
  `static CastlabsPlayerException`
  `createFatal(com.google.android.exoplayer2.upstream.HttpDataSource.HttpDataSourceException exception, int type)`
  Creates a fatal exception for an HTTP data source error.
  `static CastlabsPlayerException`
  `createWarning(DownloadException downloadException)`
  Creates a warning exception for a download error.
  `String`
  `getCauseMessage()`
  Returns the cause message of this exception.
  `static String`
  `getDrmTodayTraceId(Throwable throwable)`
  Utility method to extract the DRMToday trace identifier from an exception's cause chain.
  `Bundle`
  `getErrorData()`
  Returns a `Bundle` with error-specific error data.
  `Integer`
  `getInteger(String key)`
  Returns the value for the given key out of the `errorData` Map.
  `int`
  `getSeverity()`
  Returns the severity of this issue.
  `String`
  `getString(String key)`
  Returns the value for the given key out of the `errorData` Map.
  `int`
  `getType()`
  Returns the type of this error.
  `void`
  `log()`
  Logs this exception using its severity to choose the log level
  `String`
  `toString()`
  `static String`
  `typeString(int type)`
  Translates an error type to a human readable string

  ### Methods inherited from class java.lang.Throwable

  `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### SEVERITY_INFO

    public static final int SEVERITY_INFO
    Info severity.
    See Also:
      - Constant Field Values

  - ### SEVERITY_WARNING

    public static final int SEVERITY_WARNING
    Warning severity.
    See Also:
      - Constant Field Values

  - ### SEVERITY_ERROR

    public static final int SEVERITY_ERROR
    Error severity.
    See Also:
      - Constant Field Values

  - ### TYPE_UNKNOWN

    public static final int TYPE_UNKNOWN
    Error raised with an unknown type
    See Also:
      - Constant Field Values

  - ### TYPE_AUDIO_TRACK_INITIALIZATION

    public static final int TYPE_AUDIO_TRACK_INITIALIZATION
    Error raised when the track can not be initialized. The cause of this error is a `AudioSink.InitializationException` that contains the audio track state reported by `AudioTrack.getState()`. This is reported as `SEVERITY_ERROR` since this means that no audio playback will be possible.
    See Also:
      - Constant Field Values

  - ### TYPE_AUDIO_DECODER_INITIALIZATION

    public static final int TYPE_AUDIO_DECODER_INITIALIZATION
    Error raised when the audio decoder can not be initialized. The cause of this error is a `MediaCodecRenderer.DecoderInitializationException`. This is reported as `SEVERITY_ERROR` since this means that no audio playback will be possible.
    See Also:
      - Constant Field Values

  - ### TYPE_AUDIO_WRITE_ERROR

    public static final int TYPE_AUDIO_WRITE_ERROR
    Raised when an error occurs while writing to the audio track. The cause of this error is a `AudioSink.WriteException` that exposes the `AudioSink.WriteException.errorCode` that is returned from `AudioTrack.write(byte[], int, int)` This is reported as `SEVERITY_WARNING` since it might be possible that audio playback will recover.
    See Also:
      - Constant Field Values

  - ### TYPE_AUDIO_DECRYPTION_ERROR

    public static final int TYPE_AUDIO_DECRYPTION_ERROR
    Raised when an error occurs while decrypting audio data. The cause of this error is a `MediaCodec.CryptoException` that exposes an error code using `MediaCodec.CryptoException.getErrorCode()`. The error code reported by the cause is one of `MediaCodec.CryptoException.ERROR_NO_KEY`, `MediaCodec.CryptoException.ERROR_INSUFFICIENT_OUTPUT_PROTECTION`, `MediaCodec.CryptoException.ERROR_KEY_EXPIRED`, `MediaCodec.CryptoException.ERROR_RESOURCE_BUSY`, or `MediaCodec.CryptoException.ERROR_SESSION_NOT_OPENED` This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_VIDEO_DECODER_INITIALIZATION

    public static final int TYPE_VIDEO_DECODER_INITIALIZATION
    Raised when the video decoder can not be initialized. The cause of this error is a `MediaCodecRenderer.DecoderInitializationException`. This is reported as `SEVERITY_ERROR` since this means that no video playback will be possible.
    See Also:
      - Constant Field Values

  - ### TYPE_VIDEO_DECRYPTION_ERROR

    public static final int TYPE_VIDEO_DECRYPTION_ERROR
    Raised when an error occurs while decrypting audio data. The cause of this error is a `MediaCodec.CryptoException` that exposes an error code using `MediaCodec.CryptoException.getErrorCode()`. The error code reported by the cause is one of `MediaCodec.CryptoException.ERROR_NO_KEY`, `MediaCodec.CryptoException.ERROR_INSUFFICIENT_OUTPUT_PROTECTION`, `MediaCodec.CryptoException.ERROR_KEY_EXPIRED`, `MediaCodec.CryptoException.ERROR_RESOURCE_BUSY`, or `MediaCodec.CryptoException.ERROR_SESSION_NOT_OPENED` This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_MANIFEST_LOADING_FAILED

    public static final int TYPE_MANIFEST_LOADING_FAILED
    This error type is raised when loading the player manifest (i.e. the DASH mpd, or the HLS playlist) failed. The cause of this error is an `IOException`. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_SDK_INIT_ERROR

    public static final int TYPE_SDK_INIT_ERROR
    Error raised when the SDK could not be initialised successfully. The cause of the error is a `Throwable`. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_NO_RENDERER_FOUND

    public static final int TYPE_NO_RENDERER_FOUND
    Error raised when no plugin was found that can be used to create a renderer to playback a given DRM and content combination. An error of this type will be raised for example if you are trying to playback a DASH stream using OMA-DRM but the OMA-Plugin was not loaded. It is possible also that this Exception is thrown if a Renderer has been temporarily disabled. A few use cases, such as performing background playback ,can disable a number of Renderers. This error has no cause attached to it. This is reported as `SEVERITY_WARNING`.
    See Also:
      - Constant Field Values

  - ### TYPE_NO_PLAYABLE_CONTENT

    public static final int TYPE_NO_PLAYABLE_CONTENT
    Error raised when the applied filters were not able to find any viable content that can be displayed on the current device. This can happen for example when you are trying to playback 4K video on a device that does not support it and 4K is the only representation found in the Manifest. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_PLAYBACK_ERROR

    public static final int TYPE_PLAYBACK_ERROR
    Error raised when the ExoPlayer reports a general playback error. The cause of this error is a `ExoPlaybackException`. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_API_MISMATCH

    public static final int TYPE_API_MISMATCH
    This error is raised if a method is called that is not supported on the current API level. This will for example be triggered if you try to use Widevine DRM on devices that do not support it. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_UNSUPPORTED_DRM

    public static final int TYPE_UNSUPPORTED_DRM
    This error is raised if you are trying to use a DRM system that is not supported by the device. The cause if this error is a `UnsupportedDrmException`. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_SDK_NOT_INITIALIZED

    public static final int TYPE_SDK_NOT_INITIALIZED
    Error raised when the SDK was not initialized using one of `PlayerSDK.init(Context)` or `PlayerSDK.init(Context, LicenseLoader)`. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_DRMTODAY_EXCEPTION

    public static final int TYPE_DRMTODAY_EXCEPTION
    This error is raised if an exception occurred while the player was communicating with DRMToday to fetch a license. The cause of this error is a `DrmTodayException`. Note that this error usually occurs during license acquisition and before any decryption errors are reported by the decoder. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_DOWNLOAD_ERROR

    public static final int TYPE_DOWNLOAD_ERROR
    This error is raised if an exception occurred while downloading playback data. The cause of this error is a `DownloadException` that you can use to identify the root cause and the id of the track that caused the error. This is reported as `SEVERITY_ERROR`
    See Also:
      - Constant Field Values

  - ### TYPE_SECONDARY_DISPLAY

    public static final int TYPE_SECONDARY_DISPLAY
    This error is raised if a secondary display is detected and the current configuration does not permit playback on that display. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_KEY_EXPIRED

    public static final int TYPE_KEY_EXPIRED
    This error is raised if a DRM key expires during playback. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_DRM_KEY_DOWNLOAD_ERROR

    public static final int TYPE_DRM_KEY_DOWNLOAD_ERROR
    This error is raised if a DRM key could not be fetched successfully. This is usually caused when offline lincenses are loaded. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_CONNECTIVITY_LOST_ERROR

    public static final int TYPE_CONNECTIVITY_LOST_ERROR
    This error is raised if an exception occurred while downloading playback and no network connectivity is available. This is reported as `SEVERITY_WARNING` and the player will automatically try to recover once connectivity is re-gained. This can be treated as in informative warning.
    See Also:
      - Constant Field Values

  - ### TYPE_CONNECTIVITY_GAINED_INFO

    public static final int TYPE_CONNECTIVITY_GAINED_INFO
    This exception is raised after the player lost connectivity (`TYPE_CONNECTIVITY_LOST_ERROR`), once connectivity was re-gained. This is reported as `SEVERITY_INFO` and can be treated as in informative message.
    See Also:
      - Constant Field Values

  - ### TYPE_BEHIND_LIVE_WINDOW

    public static final int TYPE_BEHIND_LIVE_WINDOW
    Error raised when the current playback position is behind the live edge in a live stream. The cause of this error is a `BehindLiveWindowException`. When this error is raised, the player is in a fatal state and you will need to restart/reopen the stream to continue playback at the live edge. Typically, this error is caused by loss of connectivity where the player is not able to keep updating the manifests to stay at the live edge or within the live window. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_INVALID_PLAYER_LICENSE

    public static final int TYPE_INVALID_PLAYER_LICENSE
    Error raised when the Castlabs player license is invalid or expired. Please contact support if you see this error unexpectedly. Note that if this error occurs, playback is prevented and the player will stop working. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_DATA_DOWLOAD_ERROR

    public static final int TYPE_DATA_DOWLOAD_ERROR
    This error is raised if an exception occurred while downloading data. The cause can be used to identify the root cause. In contrast to `TYPE_DOWNLOAD_ERROR` this type is raised for any download issues around non track specific data. This is reported as `SEVERITY_WARNING` since it depends on where and when this exception is raised. This type might contain the `URL` key in the `errorData` bundle.
    See Also:
      - Constant Field Values

  - ### TYPE_DRM_EXCEPTION

    public static final int TYPE_DRM_EXCEPTION
    This error is raised if an exception occurred while the player was communicating with DRM server to fetch a license. The cause of this error is a `DrmSession.DrmSessionException`. Note that this error usually occurs during license acquisition and before any decryption errors are reported by the decoder. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_AUDIO_UNSUPPORTED

    public static final int TYPE_AUDIO_UNSUPPORTED
    This error is raised if all audio tracks are filtered out as unsupported. It is reported as `SEVERITY_WARNING`
    See Also:
      - Constant Field Values

  - ### TYPE_VIDEO_UNSUPPORTED

    public static final int TYPE_VIDEO_UNSUPPORTED
    This error is raised if all video tracks are filtered out as unsupported. It is reported as `SEVERITY_WARNING`
    See Also:
      - Constant Field Values

  - ### TYPE_TEXT_UNSUPPORTED

    public static final int TYPE_TEXT_UNSUPPORTED
    This error is raised if all text tracks are filtered out as unsupported. It is reported as `SEVERITY_WARNING`
    See Also:
      - Constant Field Values

  - ### TYPE_USER_ID_NOT_PROVIDED

    public static final int TYPE_USER_ID_NOT_PROVIDED
    Error raised when the userID is mandatory and has not been provided. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_MANIFEST_PARSING_FAILED

    public static final int TYPE_MANIFEST_PARSING_FAILED
    This error type is raised when parsing the player manifest (i.e. the DASH mpd, or the HLS playlist) failed. The cause of this error is an `ParserException`. This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_AD_REQUEST_UNSUPPORTED

    public static final int TYPE_AD_REQUEST_UNSUPPORTED
    Error raised when trying to play Ads but the current Player setup doesn't support it. This is the case when using a `SingleControllerPlaylist` and informing `PlayerConfig.adRequest`. This is reported as `SEVERITY_WARNING`
    See Also:
      - Constant Field Values

  - ### TYPE_DRM_PROVISION_ERROR

    public static final int TYPE_DRM_PROVISION_ERROR
    Error raised during device provisioning This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_CSL_LIMIT_REACHED

    public static final int TYPE_CSL_LIMIT_REACHED
    Error raised when concurrent stream limiting reaches maximum clients This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_CSL_NETWORK_ERROR

    public static final int TYPE_CSL_NETWORK_ERROR
    Error raised when there's a network error with the concurrent stream limiting service This is reported as `SEVERITY_ERROR`.
    See Also:
      - Constant Field Values

  - ### TYPE_HDCP_CONNECTION_WARNING

    public static final int TYPE_HDCP_CONNECTION_WARNING
    This exception is raised after the player sees changes in HDCP connectivity. This is reported as `SEVERITY_INFO` and can be treated as in informative message.
    See Also:
      - Constant Field Values

  - ### TYPE_AD_ERROR

    public static final int TYPE_AD_ERROR
    This error is raised when a general error occurs at initializing or during an Ad.
    See Also:
      - Constant Field Values

  - ### TYPE_DNS_SERVER_ERROR

    public static final int TYPE_DNS_SERVER_ERROR
    This error is raised when a DNS server error occurs.
    See Also:
      - Constant Field Values

  - ### TYPE_TIME_OUT_ERROR

    public static final int TYPE_TIME_OUT_ERROR
    This error is raised when a timeout error occurs.
    See Also:
      - Constant Field Values

  - ### TYPE_MANIFEST_INVALID

    public static final int TYPE_MANIFEST_INVALID
    This error happens when the player found a semantic issue with a Manifest. This could be due to a change in between manifest updates deemed as illegal by the corresponding spec.
    See Also:
      - Constant Field Values

  - ### TYPE_TUNNELING_ERROR

    public static final int TYPE_TUNNELING_ERROR
    This error happens when tunneling mode can not be enabled on a device and the playback in non-tunneling mode continues. It is reported as `SEVERITY_WARNING` and can be treated as an informative message.
    See Also:
      - Constant Field Values

  - ### TYPE_VIDEO_BLOCKLIST_FAILED

    public static final int TYPE_VIDEO_BLOCKLIST_FAILED
    This error is raised when video quality blocklisting fails as the current quality is the only video quality left for playback. It is reported as `SEVERITY_WARNING`
    See Also:
      - Constant Field Values

  - ### TYPE_PLAYLIST_ITEM_PREFETCH_FAILED

    public static final int TYPE_PLAYLIST_ITEM_PREFETCH_FAILED
    Error raised when an item fails to load during prefetch (while another item is playing). This is a recoverable warning - the application can handle it and decide how to proceed.

    This is reported as `SEVERITY_WARNING`.

    See Also:
      - `PlaylistException`
      - Constant Field Values

  - ### TYPE_PLAYLIST_ITEM_TRANSITION_FAILED

    public static final int TYPE_PLAYLIST_ITEM_TRANSITION_FAILED
    Error raised when the player tries to transition to an item that failed to load. This occurs either when the application didn't handle the prefetch warning and the current item finishes playback, or when direct navigation (via `nextItem()`, `previousItem()`, or `playItem()`) targets an item that cannot be loaded.

    This is reported as `SEVERITY_ERROR` (fatal).

    The `error data bundle` exposes additional data accessible through the following keys:

    - `PLAYLIST_CURRENT_ITEM_INDEX`
    - `PLAYLIST_FAILED_ITEM_INDEX`
    - `PLAYLIST_FAILED_ITEM`
    - `PLAYLIST_SIZE`
    - `PLAYLIST_STATE`
    See Also:
      - `PlaylistException`
      - Constant Field Values

  - ### TYPE_DOWNLOAD_WARNING

    public static final int TYPE_DOWNLOAD_WARNING
    This error is raised if an exception occurred while downloading playback data. The cause of this error is a `DownloadException` that you can use to identify the root cause and the id of the track that caused the error. This is reported as `SEVERITY_WARNING`
    See Also:
      - Constant Field Values

  - ### MSG_MANIFEST_LOADING_FAILED

    public static final String MSG_MANIFEST_LOADING_FAILED
    Message reported by exceptions of type `TYPE_MANIFEST_LOADING_FAILED`
    See Also:
      - Constant Field Values

  - ### MSG_VIDEO_DECODER_INITIALIZATION

    public static final String MSG_VIDEO_DECODER_INITIALIZATION
    Message reported by exceptions of type `TYPE_VIDEO_DECODER_INITIALIZATION`
    See Also:
      - Constant Field Values

  - ### HTTP_CODE

    public static final String HTTP_CODE
    HTTP response code associated with the error
    See Also:
      - Constant Field Values

  - ### URL

    public static final String URL
    URL associated with the error
    See Also:
      - Constant Field Values

  - ### RESPONSE_BODY

    public static final String RESPONSE_BODY
    Response body associated with the error
    See Also:
      - Constant Field Values

  - ### SEVERITY

    public static final String SEVERITY
    Severity level of the error
    See Also:
      - Constant Field Values

  - ### CODE

    public static final String CODE
    Error code associated with the error
    See Also:
      - Constant Field Values

  - ### TRACK_TYPE

    public static final String TRACK_TYPE
    The value of the key is the track type, one of `PlayerController.VIDEO_RENDERER`, `PlayerController.AUDIO_RENDERER`, `PlayerController.TEXT_RENDERER` or `PlayerController.METADATA_RENDERER`
    See Also:
      - Constant Field Values

  - ### PLAYLIST_FAILED_ITEM_INDEX

    public static final String PLAYLIST_FAILED_ITEM_INDEX
    Bundle key for the index of the failed item in the playlist.
    See Also:
      - Constant Field Values

  - ### PLAYLIST_FAILED_ITEM

    public static final String PLAYLIST_FAILED_ITEM
    Bundle key for the PlayerConfig of the failed item in the playlist. The value is obtained through `Bundle.getParcelable(String)`.
    See Also:
      - Constant Field Values

  - ### PLAYLIST_CURRENT_ITEM_INDEX

    public static final String PLAYLIST_CURRENT_ITEM_INDEX
    Bundle key for the index of the item that was playing when the error occurred.
    See Also:
      - Constant Field Values

  - ### PLAYLIST_SIZE

    public static final String PLAYLIST_SIZE
    Bundle key for the total number of items in the playlist.
    See Also:
      - Constant Field Values

  - ### PLAYLIST_STATE

    public static final String PLAYLIST_STATE
    Bundle key for the playlist state as an `ArrayList` of `PlayerConfig` items. The value is obtained through `Bundle.getParcelableArrayList(String)`.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### CastlabsPlayerException

    public CastlabsPlayerException(int severity, int type, @Nullable String message)
    Creates a new CastlabsPlayerException with the specified severity, type, and message.
    Parameters:
      `severity` - The severity level of the error
      `type` - The type of error
      `message` - The error message

  - ### CastlabsPlayerException

    public CastlabsPlayerException(int severity, int type, @Nullable String message, @Nullable Throwable cause)
    Creates a new CastlabsPlayerException with the specified severity, type, message, and cause.
    Parameters:
      `severity` - The severity level of the error
      `type` - The type of error
      `message` - The error message
      `cause` - The cause of the error

  - ### CastlabsPlayerException

    public CastlabsPlayerException(int severity, int type, @Nullable String message, @Nullable Throwable cause, @Nullable String explicitCauseMessage)
    Creates a new CastlabsPlayerException with the specified severity, type, message, cause, and explicit cause message.
    Parameters:
      `severity` - The severity level of the error
      `type` - The type of error
      `message` - The error message
      `cause` - The cause of the error
      `explicitCauseMessage` - An explicit message describing the cause

- ## Method Details

  - ### getSeverity

    public int getSeverity()
    Returns the severity of this issue.
    Returns:
      The severity of this issue. One of `SEVERITY_INFO`, `SEVERITY_WARNING`, or `SEVERITY_ERROR`

  - ### getType

    public int getType()
    Returns the type of this error.
    Returns:
      the type of this error.

  - ### getCauseMessage

    public String getCauseMessage()
    Returns the cause message of this exception.
    Returns:
      message An explicitly set cause message if not `null` or the message of the lowest exception in the cause chain otherwise. May not be used in app UI elements.

  - ### getErrorData

    @NonNull public Bundle getErrorData()
    Returns a `Bundle` with error-specific error data. This data may be different for each error type.
    Returns:
      the Bundle with error data

  - ### getString

    @Nullable public String getString(String key)
    Returns the value for the given key out of the `errorData` Map. Note that this method will convert the requested data into String. Even if originally it was not.
    Parameters:
      `key` - the key for which to return the value.
    Returns:
      the value, or null if the key does not exist.

  - ### getInteger

    @Nullable public Integer getInteger(String key)
    Returns the value for the given key out of the `errorData` Map. Note that this method try to parse the requested data into an Integer. Even if originally it was not.
    Parameters:
      `key` - the key for which to return the value.
    Returns:
      the value, or null if the key does not exist.

  - ### createFatal

    @NonNull public static CastlabsPlayerException createFatal(com.google.android.exoplayer2.source.dash.DashPeriodNotFoundException exception)
    Creates a fatal exception for a DASH period not found error.
    Parameters:
      `exception` - The DashPeriodNotFoundException that caused the error
    Returns:
      A new CastlabsPlayerException instance

  - ### createFatal

    @NonNull public static CastlabsPlayerException createFatal(@NonNull DownloadException downloadException)
    Creates a fatal exception for a download error.
    Parameters:
      `downloadException` - The DownloadException that caused the error
    Returns:
      A new CastlabsPlayerException instance

  - ### createWarning

    @NonNull public static CastlabsPlayerException createWarning(@NonNull DownloadException downloadException)
    Creates a warning exception for a download error.
    Parameters:
      `downloadException` - The DownloadException that caused the error
    Returns:
      A new CastlabsPlayerException instance

  - ### createFatal

    public static CastlabsPlayerException createFatal(@NonNull com.google.android.exoplayer2.upstream.HttpDataSource.HttpDataSourceException exception, int type)
    Creates a fatal exception for an HTTP data source error.
    Parameters:
      `exception` - The HttpDataSourceException that caused the error
      `type` - The type of error
    Returns:
      A new CastlabsPlayerException instance

  - ### createError

    public static CastlabsPlayerException createError(int severity, String message, @NonNull PlaylistException playlistException)
    Creates a fatal exception for a download error.
    Parameters:
      `severity` - The severity level of the error
      `message` - The error message
      `playlistException` - The PlaylistException
    Returns:
      A new CastlabsPlayerException instance

  - ### createError

    public static CastlabsPlayerException createError(int severity, String message, com.google.android.exoplayer2.upstream.HttpDataSource.InvalidResponseCodeException e)
    Creates an error exception for an invalid HTTP response code.
    Parameters:
      `severity` - The severity level of the error
      `message` - The error message
      `e` - The InvalidResponseCodeException that caused the error
    Returns:
      A new CastlabsPlayerException instance

  - ### createError

    public static CastlabsPlayerException createError(int severity, String message, com.google.android.exoplayer2.upstream.HttpDataSource.HttpDataSourceException e)
    Creates an error exception for an HTTP data source error.
    Parameters:
      `severity` - The severity level of the error
      `message` - The error message
      `e` - The HttpDataSourceException that caused the error
    Returns:
      A new CastlabsPlayerException instance

  - ### getDrmTodayTraceId

    @Nullable public static String getDrmTodayTraceId(@Nullable Throwable throwable)
    Utility method to extract the DRMToday trace identifier from an exception's cause chain.

    This method traverses the entire cause chain of the provided throwable to find a `DrmTodayException` and returns its trace identifier if available. This is useful for debugging and correlating SDK failures with entries in the DRMtoday License Delivery portal.

    Example usage:

         playerController.addListener(new AbstractPlayerListener() {
             @Override
             public void onError(@NonNull CastlabsPlayerException error) {
                 String traceId = CastlabsPlayerException.getDrmTodayTraceId(error);
                 if (traceId != null) {
                     Log.e(TAG, "DrmToday trace id: " + traceId);
                 }
             }
         });

    Parameters:
      `throwable` - The exception to search for a DrmTodayException. May be null.
    Returns:
      The trace identifier from the DrmTodayException if found, null otherwise.
    See Also:
      - `DrmTodayException.getTraceId()`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Throwable`

  - ### log

    public void log()
    Logs this exception using its severity to choose the log level

  - ### typeString

    public static String typeString(int type)
    Translates an error type to a human readable string
    Parameters:
      `type` - the error type
    Returns:
      The string representation of the error type