Package com.castlabs.android

## Class PlayerSDK

- java.lang.Object
- - com.castlabs.android.PlayerSDK

-     public final class PlayerSDK
      extends Object

  This class provides the required methods to initialize the castLabs SDK and register additional components and plugins. Note that before you can use the SDK in your application you have to call `init(Context)` or `init(Context, LicenseLoader)` to initialize the SDK.

  ## Global configuration

  The following application can be configured globally as static member of this class:

  - `SECURE_SURFACE_VIEW_DISABLED` to disable the usage of the secured surface view. See `SurfaceView.setSecure(boolean)`
  - `FORCE_UNSECURED_DECODER` enforces the usage of the unsecured video decoders
  Since:
    1.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `PlayerSDK.SystemStatusCallback` | Callback interface that can be used to detect rooted devices.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `AUDIO_CODEC_BUFFER_MODE` |
    `static boolean` | `CLIP_PERIODS` | Global parameter to enable or disable audio and video components clipping to their period duration (DASH-only).
    `static float` | `CODEC_WEIGHT_IMPL_HW` | The codec normalized weight for hardware implementation `1.0f` used for the default track selection.
    `static float` | `CODEC_WEIGHT_IMPL_SW` | The codec normalized weight for software implementation `0.5f` used for the default track selection.
    `static float` | `CODEC_WEIGHT_MIME_H264_HW` | The hardware codec H264 (AVC) normalized weight `0.5f` used for the default video track selection.
    `static float` | `CODEC_WEIGHT_MIME_H264_SW` | The software codec H264 (AVC) normalized weight `0.4f` used for the default video track selection.
    `static float` | `CODEC_WEIGHT_MIME_H265_HW` | The hardware codec H265 (HEVC) normalized weight `1.0f` used for the default video track selection.
    `static float` | `CODEC_WEIGHT_MIME_H265_SW` | The software codec H265 (HEVC) normalized weight `0.3f` used for the default video track selection.
    `static float` | `CODEC_WEIGHT_MIME_OTHER` | The normalized weight `0.2f` of the codec other than `CODEC_WEIGHT_MIME_H265_HW`, `CODEC_WEIGHT_MIME_H265_SW`, `CODEC_WEIGHT_MIME_H264_HW` and `CODEC_WEIGHT_MIME_H264_SW` normalized weight `0.5f` used for default video track selection.
    `static int` | `CONNECTIVITY_CHECK_PERIOD_MS` | Period in ms, used to poll the device's connectivity, when `ENABLE_CONNECTIVITY_CHECKS` is enabled
    `static ConnectivityCheck` | `CONNECTIVITY_CHECKER` | The default connectivity check that will be used at runtime to check for internet connectivity.
    `static int` | `CRASHLOG_AUTO_REPORT` | Configure the exception severity that will cause the `Crashlog.report(Throwable)` to be triggered automatically.
    `static NetworkConfiguration` | `DEFAULT_DOWNLOADER_NETWORK_CONFIGURATION` | The default network configuration used by the downloader for both manifests and segments
    `static com.google.android.exoplayer2.upstream.InternalSourceSelector.Factory` | `DEFAULT_INTERNAL_SOURCE_SELECTOR_FACTORY` | The default `InternalSourceSelector.Factory` used during CDN fallback e.g.
    `static KeyStore` | `DEFAULT_KEY_STORE` | The default key store that will be used to store and restore offline keys.
    `static int` | `DUMMY_SURFACE_MODE` | By default the player queries the device API version and internal API for support of the GL based dummy surface for faster and smoother transitions when the playback surface is attached/detached from the video codec.
    `static boolean` | `ENABLE_AD_SPEED_UP` | Default global value to enable or disable automatic setting of a speed to 1x when playing ads.
    `static boolean` | `ENABLE_AUDIO_CODEC_SYNC_INTERACTIONS_WITH_QUEUEING` |
    `static boolean` | `ENABLE_AUDIO_DECODER_FALLBACK` | If true (default), allows the player to fallback to other decoders if it failed to initialize the primary decoder.
    `static boolean` | `ENABLE_CDM_KEY_STATUS` | Key status change listener can be installed to CDM's starting API 23 and is used to get statuses of known key ids.
    `static boolean` | `ENABLE_CONNECTIVITY_CHECKS` | By default, the player will not automatically recover from loss of connectivity.
    `static boolean` | `ENABLE_DASH_EVENT_CALLBACK` | The default value to enable/disable internal handling of DASH event callbacks
    `static boolean` | `ENABLE_DRM_FALLBACK` | When multiple `Drm` systems are present on a device and one of them fails locally then the playback is automatically restarted and configured with another DRM type being available.
    `static boolean` | `ENABLE_DRM_PLACEHOLDER_SESSION` | The player selects unsecure codec when starting playing clear part of the content e.g.
    `static boolean` | `ENABLE_ERROR_RESPONSE_BODY` | If set to true, the body of the HTTP response will be returned in `CastlabsPlayerException.getErrorData()` when available.
    `static boolean` | `ENABLE_FATAL_RETRY_MIME_APPLICATION` | Indicates whether to consider as fatal errors the ones encountered while downloading segments with MimeType `MimeTypes.BASE_TYPE_APPLICATION`.
    `static boolean` | `ENABLE_MAX_REF_FRAME_WORKAROUND` | Enable a codec workaround that disables codec-reconfiguration on some devices.
    `static boolean` | `ENABLE_TEXT_WITH_NO_PREFERRED_LANGUAGE` | If set to `true` and text language specified by `SdkConsts.INTENT_PREFERRED_TEXT_LANGUAGE` does not match any of the available text tracks then the first available text track will still be enabled.
    `static boolean` | `ENABLE_TRICK_MODE_TRACK_SWITCH` | Deprecated. Use `TrickplayConfiguration.preferTrickPlayTracks` instead
    `static boolean` | `ENABLE_TRIGGER_MANIFEST_FALLBACK_MIME_APPLICATION` | Whether to trigger the alternative Manifest callback when an error occurs while downloading segments with MimeType `MimeTypes.BASE_TYPE_APPLICATION`.
    `static boolean` | `ENABLE_UNSECURE_DECODER_FALLBACK` | If true (default), allows the player to fallback to unsecure decoders if it failed to initialize the primary decoder.
    `static boolean` | `ENABLE_VIDEO_CODEC_SYNC_INTERACTIONS_WITH_QUEUEING` |
    `static boolean` | `ENABLE_VIDEO_DECODER_FALLBACK` | If true (default), allows the player to fallback to other decoders if it failed to initialize the primary decoder.
    `static boolean` | `ENABLE_WORKAROUND_EVERY_VIDEO_FRAME_IS_SYNC_FRAME` | Global parameter to enable or disable the workaround whether all video frames are marked as sync frames but should not be treated as sync frames except the very first in a segment (DASH-only)
    `static int` | `FAST_BITRATE_SWITCHING` | By default, the player queries the currently selected video codec if it supports fast adaptive bitrate switching (`SdkConsts.FAST_BITRATE_SWITCHING_AUTO`).
    `static boolean` | `FORCE_DRM_LICENSE_PREFETCH` | By default the player pre-fetches the license as soon as tracks are selected and segments are ready to be downloaded.
    `static boolean` | `FORCE_HDCP_EXCEPTION` | If set to true, the behavior of the sdk on HDMI disconnect/hdcp disconnects would be to throw a fatal exception to indicate a crypto error as well as an info exception to indicate HDMI disconnection.
    `static boolean` | `FORCE_IN_STREAM_DRM_INIT_DATA` | Global parameter whether to prefer DRM init data in segments over the manifest's data (DASH-only).
    `static boolean` | `FORCE_REOPEN_ON_HDCP_STATE_CHANGE` | Sets the behaviour when `FORCE_HDCP_EXCEPTION` is `false`, otherwise the option is ignored.
    `static boolean` | `FORCE_SINGLE_DRM_SESSION` | By default the player creates two DRM sessions, one for Audio, and one for Video.
    `static boolean` | `FORCE_UNSECURED_DECODER` | Disable the usage of the secure decoder pipeline.
    `static boolean` | `FORCE_VIDEO_CODEC_MAX_INPUT_SIZE_UNKNOWN` | By default the player will deduce the maximum input size that is used to configure the video codec via `MediaFormat` and the `MediaFormat.KEY_MAX_INPUT_SIZE` key.
    `static boolean` | `FORCE_WIDEVINE_L3` | Deprecated. use `DrmConfiguration.forceWidevineL3` instead, or `DrmTodayConfiguration.Builder.forceWidevineL3(boolean)` if using DrmTodayConfiguration.
    `static long` | `HDCP_EXCEPTION_TIMEOUT_MS` | This is the time in milliseconds to wait for DRM key to change its status from `KeyStatus.OutputNotAllowed` to `KeyStatus.Usable` before throwing an exception.
    `static long` | `HDMI_CONNECTION_DELAY_MS` | This is the time in milliseconds to delay the HDMI connection event.
    `static HttpDataSourceBuilder` | `HTTP_DATASOURCE_BUILDER` | The HTTP data source factory that is used to create http data sources.
    `static LicenseLoader` | `licenseLoader` | The license loader
    `static boolean` | `MERGE_VIDEO_TRACKS` | Global parameter to enable or disable the video merging option, default is `true`
    `static boolean` | `PAUSE_ON_HDMI_DISCONNECTED` | Default global value to enable or disable automatic playback pausing when HDMI is disconnected.
    `static int` | `PLAYBACK_HD_CONTENT` | The default setting for HD content filter.
    `static long` | `PLAYER_RELEASE_TIMEOUT_MS` | Timeout in milliseconds to release the underlying Player.
    `static float` | `PREFERENCE_CODEC_IMPL` | The preference of the codec implementation weight `100.0f`, compare to `PREFERENCE_CODEC_MIME`, `PREFERENCE_TRACK_TYPE` and `PREFERENCE_PIXEL_COUNT`.
    `static float` | `PREFERENCE_CODEC_MIME` | The preference of the codec mimes weight `20.0f`, compare to `PREFERENCE_CODEC_IMPL`, `PREFERENCE_TRACK_TYPE` and `PREFERENCE_PIXEL_COUNT`.
    `static float` | `PREFERENCE_PIXEL_COUNT` | The preference of the pixel count weight `10.0f`, compare to `PREFERENCE_CODEC_MIME`, `PREFERENCE_CODEC_IMPL` and `PREFERENCE_TRACK_TYPE`.
    `static float` | `PREFERENCE_TRACK_TYPE` | The preference of the track type weight `40.0f`, compare to `PREFERENCE_CODEC_MIME`, `PREFERENCE_CODEC_IMPL` and `PREFERENCE_PIXEL_COUNT`.
    `static boolean` | `PRESCAN_DASH_MANIFESTS` | Enable this options if you have to play DASH Manifests that are not spec conform and define AdaptationSets' before BaseURLs'.
    `static boolean` | `RESTORE_SPEED` | Default global value to enable or disable automatic restoring of a speed after playing ads.
    `static int` | `SECONDARY_DISPLAY` | Use this flag to configure handling of secondary displays.
    `static boolean` | `SECURE_SURFACE_VIEW_DISABLED` | Disable Secure SurfaceView
    `static long` | `SET_SURFACE_TIMEOUT_MS` | Timeout in milliseconds to set the player Surface.
    `static KeyStore` | `SSL_KEY_STORE` | The SSL key store used to verify certificates only in case the system default key store fails to verify them.
    `static SubtitlesPreviewBuilder` | `SUBTITLE_PREVIEW_BUILDER` | Static property that can be set (usually by plugins) to register a preview builder that is in turn used to create subtitle preview views.
    `static PlayerSDK.SystemStatusCallback` | `SYSTEM_STATUS_CALLBACK` | If specified, the callback implementation will be triggered on the main thread and inform about the current system status.
    `static TrackTypeProvider` | `TRACK_TYPE_PROVIDER` | The track type provider that will be used to define track group and tracks types and their weights.
    `static int` | `VIDEO_CODEC_BUFFER_MODE` |
    `static int` | `VIDEO_CODEC_FILTER` | The default global video codec filter used to configure the video codec filtering.
    `static VideoFilterConfiguration` | `VIDEO_FILTER` | The default global `VideoFilterConfiguration` to use in order to filter video qualities.
    `static Point` | `VIDEO_SIZE_FILTER` | Deprecated. Use `VIDEO_FILTER` instead.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `addLegacyDeviceScreenResolution​(String manufacturer, String model)` | Add a device for which its screen dimensions will be read using the legacy approach.
    `static Context` | `getContext()` | Access the globally configured application context used by the SDK.
    `static List<Downloadable>` | `getDownloadablePlugins()` |
    `static Collection<DrmLicenseManagerComponent>` | `getDrmLicenseManagerComponents()` |
    `static List<PlayerControllerPlugin>` | `getPlayerControllerPlugins()` |
    `static List<PlayerPlugin>` | `getPlayerPlugins()` |
    `static List<PlayerViewPlugin>` | `getPlayerViewPlugins()` |
    `static <T extends Plugin> T` | `getPlugin​(Class<T> pluginClass)` | Returns the instance of the registered plugin or null if no plugin was found
    `static Collection<Plugin>` | `getPlugins()` |
    `static List<TrackRendererPlugin>` | `getTrackRendererPlugins()` |
    `static String` | `getVersion()` | Exposes the SDK version
    `static void` | `init​(Context ctx)` | Initializes the SDK using the given context and the default `ManifestLicenseLoader` to find a meta-data entry with the key `castlabs-license` in your Applications Manifest.
    `static void` | `init​(Context ctx, LicenseLoader licenseLoader)` | Initializes the SDK using the given context and `LicenseLoader` to find and load a license file.
    `static void` | `init​(Context ctx, String license)` | Initializes the SDK using the given context and the license specified here.
    `static boolean` | `isPluginRegistered​(Drm drm)` | INTERNAL! This is an internal method and you will not need to call this method explicitly.
    `static void` | `register​(Downloadable plugin)` |
    `static void` | `register​(Drm drm)` | Register external Drm plugin to the sdk.
    `static void` | `register​(PlayerControllerPlugin plugin)` | Register a new `PlayerControllerPlugin`
    `static void` | `register​(PlayerPlugin plugin)` | Register a new player plugin
    `static void` | `register​(PlayerViewPlugin plugin)` | Register a new `PlayerViewPlugin`
    `static void` | `register​(TrackRendererPlugin plugin)` | Register a new track renderer plugin
    `static void` | `register​(Plugin plugin)` | Register a new plugin
    `static void` | `registerDrmLicenseManagerComponent​(DrmLicenseManagerComponent component)` | Register a new DrmLicenseManagerComponent
    `static void` | `waitForInitialization()` | INTERNAL method that will block until the SDK is fully initialized.

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

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

- - ### Field Detail

    - #### SECURE_SURFACE_VIEW_DISABLED

          public static boolean SECURE_SURFACE_VIEW_DISABLED

      Disable Secure SurfaceView

    - #### FORCE_UNSECURED_DECODER

          public static boolean FORCE_UNSECURED_DECODER

      Disable the usage of the secure decoder pipeline. Note that this will prevent playback of protected content on some devices.

    - #### FORCE_WIDEVINE_L3

          public static boolean FORCE_WIDEVINE_L3

      Deprecated.
      use `DrmConfiguration.forceWidevineL3` instead, or `DrmTodayConfiguration.Builder.forceWidevineL3(boolean)` if using DrmTodayConfiguration.
      If set to true, Widevine L3 will be enforces. Note that this will prevent playback of DRM content where the license requires L1 security.

      This flag can be set for certain devices that are known to have broken secure decoder implementation to allow Widevine protected content playback.

    - #### ENABLE_MAX_REF_FRAME_WORKAROUND

          public static boolean ENABLE_MAX_REF_FRAME_WORKAROUND

      Enable a codec workaround that disables codec-reconfiguration on some devices. The devices list currently covers Huawei P7 and P8-Lite as well as Qualcomm CPU. The workaround seems to be needed if the decoder is initialized with no B-Frame support and then switches to a track with B-Frames. In that case re-configuration is not sufficient and a full decoder reset is required.

      Please note that the same effect can be achieved bu setting `FAST_BITRATE_SWITCHING` to `SdkConsts.FAST_BITRATE_SWITCHING_DISABLED` in case there are other devices that need this workaround.

      More information can be found at https://github.com/google/ExoPlayer/issues/2416

    - #### SECONDARY_DISPLAY

          public static int SECONDARY_DISPLAY

      Use this flag to configure handling of secondary displays. Secondary displays are registered when an external HDMI display is connected (for phones and tablets) or screen mirriring is enabled. This is the default setting that will be used for all player instances. The default is `SdkConsts.SECONDARY_DISPLAY_ALLOW_UNPROTECTED_CONTENT | SdkConsts.SECONDARY_DISPLAY_ALLOW_SECURE_DISPLAY` which will always allow the usage of a secondary display for unprotected content and will allow a secondary display for protected content if the secondary display is considered secure (both flags `Display.FLAG_SECURE` and `Display.FLAG_SUPPORTS_PROTECTED_BUFFERS` are set to `true`). Note that this is the default setting that will be applied to all player instances, but you can use `PlayerController.setSecondaryDisplay(int)` to overwrite the default per player instance.

    - #### PLAYBACK_HD_CONTENT

          public static int PLAYBACK_HD_CONTENT

      The default setting for HD content filter. This is a bit field consisting of the values of `SdkConsts.ALLOW_HD_CLEAR_CONTENT`, `SdkConsts.ALLOW_HD_DRM_ROOT_OF_TRUST`, `SdkConsts.ALLOW_HD_DRM_SECURE_MEDIA_PATH`, `SdkConsts.ALLOW_HD_NEVER`, and `SdkConsts.ALLOW_HD_DRM_SOFTWARE`.

      The value here specifies under which circumstances HD representations are allowed and will not be filtered away. The default setting is: `SdkConsts.ALLOW_HD_CLEAR_CONTENT | SdkConsts.ALLOW_HD_DRM_SECURE_MEDIA_PATH`. This allows playback of HD content for unencrypted streams or for streams that are protected with a DRM that supports `SecurityLevel.SECURE_MEDIA_PATH`. This field holds the global default, but you can specify a content specific setting using the player controllers `PlayerController.setHdPlaybackEnabled(int)`

    - #### VIDEO_CODEC_FILTER

          public static int VIDEO_CODEC_FILTER

      The default global video codec filter used to configure the video codec filtering. This value should be one of `SdkConsts.VIDEO_CODEC_FILTER_NONE` or `SdkConsts.VIDEO_CODEC_FILTER_CAPS` The default one is `SdkConsts.VIDEO_CODEC_FILTER_NONE`. It is overwritten for single playback session by the value of the key `SdkConsts.INTENT_VIDEO_CODEC_FILTER` when the latter is set.

    - #### ENABLE_VIDEO_DECODER_FALLBACK

          public static boolean ENABLE_VIDEO_DECODER_FALLBACK

      If true (default), allows the player to fallback to other decoders if it failed to initialize the primary decoder. This can for instance happen if the primary decoder is a hardware implementation and is already blocked by another playback session. In that case, secondary decoders, i.e. software implementations, will be used if possible.

    - #### ENABLE_AUDIO_DECODER_FALLBACK

          public static boolean ENABLE_AUDIO_DECODER_FALLBACK

      If true (default), allows the player to fallback to other decoders if it failed to initialize the primary decoder. This can for instance happen if the primary decoder is a hardware implementation and is already blocked by another playback session. In that case, secondary decoders, i.e. software implementations, will be used if possible.

    - #### ENABLE_UNSECURE_DECODER_FALLBACK

          public static boolean ENABLE_UNSECURE_DECODER_FALLBACK

      If true (default), allows the player to fallback to unsecure decoders if it failed to initialize the primary decoder. This requires that the video decoder fallback is enabled.

    - #### VIDEO_CODEC_BUFFER_MODE

          public static int VIDEO_CODEC_BUFFER_MODE

    - #### AUDIO_CODEC_BUFFER_MODE

          public static int AUDIO_CODEC_BUFFER_MODE

    - #### ENABLE_VIDEO_CODEC_SYNC_INTERACTIONS_WITH_QUEUEING

          public static boolean ENABLE_VIDEO_CODEC_SYNC_INTERACTIONS_WITH_QUEUEING

    - #### ENABLE_AUDIO_CODEC_SYNC_INTERACTIONS_WITH_QUEUEING

          public static boolean ENABLE_AUDIO_CODEC_SYNC_INTERACTIONS_WITH_QUEUEING

    - #### PAUSE_ON_HDMI_DISCONNECTED

          public static boolean PAUSE_ON_HDMI_DISCONNECTED

      Default global value to enable or disable automatic playback pausing when HDMI is disconnected. Can be per playback specified with `SdkConsts.INTENT_PAUSE_ON_HDMI_DISCONNECTED` or `PlayerConfig.pauseOnHdmiDisconnected` Only for API higher or equal to 21

    - #### ENABLE_AD_SPEED_UP

          public static boolean ENABLE_AD_SPEED_UP

      Default global value to enable or disable automatic setting of a speed to 1x when playing ads. By default the ads will be played at 1x speed. The option can also be set for specific playback only with `SdkConsts.INTENT_ENABLE_AD_SPEED_UP` or `PlayerConfig.enableAdSpeedUp`

    - #### RESTORE_SPEED

          public static boolean RESTORE_SPEED

      Default global value to enable or disable automatic restoring of a speed after playing ads. By default the speed will be set to the one used before playing ads. The option can also be set for specific playback only with `SdkConsts.INTENT_RESTORE_SPEED` or `PlayerConfig.restoreSpeed`

    - #### VIDEO_SIZE_FILTER

          public static Point VIDEO_SIZE_FILTER

      Deprecated.
      Use `VIDEO_FILTER` instead.
      The default global pixel count filter used to configure the video size filtering. This value should be a valid `Point` (w x h) or one of `SdkConsts.VIDEO_SIZE_FILTER_AUTO`, `SdkConsts.VIDEO_SIZE_FILTER_NONE`. The default one is `SdkConsts.VIDEO_SIZE_FILTER_AUTO`. It is overwritten for single playback session by the value of the key `SdkConsts.INTENT_VIDEO_SIZE_FILTER` when the latter is set. Note When setting the value to other than `SdkConsts.VIDEO_SIZE_FILTER_AUTO` it is strongly recommended to set the `VIDEO_CODEC_FILTER` to `SdkConsts.VIDEO_CODEC_FILTER_CAPS` otherwise the video streams with high resolutions will be forced to play on devices that may not have support for it.

    - #### VIDEO_FILTER

          @NonNull
          public static VideoFilterConfiguration VIDEO_FILTER

      The default global `VideoFilterConfiguration` to use in order to filter video qualities. Applied to both ads and content tracks. Can be an instance of `VideoFilterConfiguration`, or one of `SdkConsts.VIDEO_FILTER_AUTO` or `SdkConsts.VIDEO_FILTER_NONE`. The default one is `SdkConsts.VIDEO_FILTER_AUTO`. It is overwritten for single playback session by the value of the key `SdkConsts.INTENT_VIDEO_FILTER` when the latter is set. Note When setting the value to other than `SdkConsts.VIDEO_FILTER_AUTO` it is strongly recommended to set the `VIDEO_CODEC_FILTER` to `SdkConsts.VIDEO_CODEC_FILTER_CAPS` otherwise the video streams with high resolutions will be forced to play on devices that may not have support for it.

    - #### MERGE_VIDEO_TRACKS

          public static boolean MERGE_VIDEO_TRACKS

      Global parameter to enable or disable the video merging option, default is `true`

    - #### ENABLE_TEXT_WITH_NO_PREFERRED_LANGUAGE

          public static boolean ENABLE_TEXT_WITH_NO_PREFERRED_LANGUAGE

      If set to `true` and text language specified by `SdkConsts.INTENT_PREFERRED_TEXT_LANGUAGE` does not match any of the available text tracks then the first available text track will still be enabled. This is the default behaviour.

    - #### ENABLE_DASH_EVENT_CALLBACK

          public static boolean ENABLE_DASH_EVENT_CALLBACK

      The default value to enable/disable internal handling of DASH event callbacks

    - #### ENABLE_WORKAROUND_EVERY_VIDEO_FRAME_IS_SYNC_FRAME

          public static boolean ENABLE_WORKAROUND_EVERY_VIDEO_FRAME_IS_SYNC_FRAME

      Global parameter to enable or disable the workaround whether all video frames are marked as sync frames but should not be treated as sync frames except the very first in a segment (DASH-only)

      Note: enable it only when needed, since it degrades the seek performance

    - #### CLIP_PERIODS

          public static boolean CLIP_PERIODS

      Global parameter to enable or disable audio and video components clipping to their period duration (DASH-only). Enable to clip un-aligned durations of audio and video components to their period duration. The default is true

    - #### FORCE_IN_STREAM_DRM_INIT_DATA

          public static boolean FORCE_IN_STREAM_DRM_INIT_DATA

      Global parameter whether to prefer DRM init data in segments over the manifest's data (DASH-only). The parameter can also be set for a single stream via `SdkConsts.INTENT_FORCE_IN_STREAM_DRM_INIT_DATA` or `PlayerConfig.forceInStreamDrmInitData` The default is false

    - #### DEFAULT_KEY_STORE

          public static KeyStore DEFAULT_KEY_STORE

      The default key store that will be used to store and restore offline keys. If no default is set when `init(Context)` is called, the `SharedPreferencesKeyStore` will be used.

    - #### SSL_KEY_STORE

          public static KeyStore SSL_KEY_STORE

      The SSL key store used to verify certificates only in case the system default key store fails to verify them. Thus, this is NOT a replacement of the system key store!

      Leave or set it to `null` when no custom verification is needed. Set it up when your certificate is not (yet) trusted by the system or the application is running on the older version of system without the needed CA.

      Note: The application shall take care of maintaining the custom key store and keeping it up-to-date.

      Note: There is a limitation of using custom `SSL_KEY_STORE` with enabled okhttp plugin as it brings a significant delay when opening a connection.

    - #### TRACK_TYPE_PROVIDER

          public static TrackTypeProvider TRACK_TYPE_PROVIDER

      The track type provider that will be used to define track group and tracks types and their weights. If it is not set when `init(Context)` is called, the `DefaultTrackTypeProvider` will be used

    - #### DEFAULT_DOWNLOADER_NETWORK_CONFIGURATION

          public static NetworkConfiguration DEFAULT_DOWNLOADER_NETWORK_CONFIGURATION

      The default network configuration used by the downloader for both manifests and segments

    - #### DEFAULT_INTERNAL_SOURCE_SELECTOR_FACTORY

          public static com.google.android.exoplayer2.upstream.InternalSourceSelector.Factory DEFAULT_INTERNAL_SOURCE_SELECTOR_FACTORY

      The default `InternalSourceSelector.Factory` used during CDN fallback e.g. DASH multi BaseUrl handling

    - #### PREFERENCE_CODEC_IMPL

          public static float PREFERENCE_CODEC_IMPL

      The preference of the codec implementation weight `100.0f`, compare to `PREFERENCE_CODEC_MIME`, `PREFERENCE_TRACK_TYPE` and `PREFERENCE_PIXEL_COUNT`. Used to define the priority of the codec implementations `CODEC_WEIGHT_IMPL_HW` or `CODEC_WEIGHT_IMPL_SW` over other weights

    - #### PREFERENCE_TRACK_TYPE

          public static float PREFERENCE_TRACK_TYPE

      The preference of the track type weight `40.0f`, compare to `PREFERENCE_CODEC_MIME`, `PREFERENCE_CODEC_IMPL` and `PREFERENCE_PIXEL_COUNT`. Used to define the priority of the track types see `TrackTypeProvider` over other weights

    - #### PREFERENCE_CODEC_MIME

          public static float PREFERENCE_CODEC_MIME

      The preference of the codec mimes weight `20.0f`, compare to `PREFERENCE_CODEC_IMPL`, `PREFERENCE_TRACK_TYPE` and `PREFERENCE_PIXEL_COUNT`. Used to define the priority of the codec mimes `CODEC_WEIGHT_MIME_H265_HW`, `CODEC_WEIGHT_MIME_H265_SW`, `CODEC_WEIGHT_MIME_H264_HW`, `CODEC_WEIGHT_MIME_H264_SW` or `CODEC_WEIGHT_MIME_OTHER` over other weights

    - #### PREFERENCE_PIXEL_COUNT

          public static float PREFERENCE_PIXEL_COUNT

      The preference of the pixel count weight `10.0f`, compare to `PREFERENCE_CODEC_MIME`, `PREFERENCE_CODEC_IMPL` and `PREFERENCE_TRACK_TYPE`. Used to define the priority of the pixel count values (width x height) over other weights

    - #### CODEC_WEIGHT_IMPL_HW

          public static float CODEC_WEIGHT_IMPL_HW

      The codec normalized weight for hardware implementation `1.0f` used for the default track selection.

    - #### CODEC_WEIGHT_IMPL_SW

          public static float CODEC_WEIGHT_IMPL_SW

      The codec normalized weight for software implementation `0.5f` used for the default track selection.

    - #### CODEC_WEIGHT_MIME_H265_HW

          public static float CODEC_WEIGHT_MIME_H265_HW

      The hardware codec H265 (HEVC) normalized weight `1.0f` used for the default video track selection.

    - #### CODEC_WEIGHT_MIME_H265_SW

          public static float CODEC_WEIGHT_MIME_H265_SW

      The software codec H265 (HEVC) normalized weight `0.3f` used for the default video track selection.

    - #### CODEC_WEIGHT_MIME_H264_HW

          public static float CODEC_WEIGHT_MIME_H264_HW

      The hardware codec H264 (AVC) normalized weight `0.5f` used for the default video track selection.

    - #### CODEC_WEIGHT_MIME_H264_SW

          public static float CODEC_WEIGHT_MIME_H264_SW

      The software codec H264 (AVC) normalized weight `0.4f` used for the default video track selection.

    - #### CODEC_WEIGHT_MIME_OTHER

          public static float CODEC_WEIGHT_MIME_OTHER

      The normalized weight `0.2f` of the codec other than `CODEC_WEIGHT_MIME_H265_HW`, `CODEC_WEIGHT_MIME_H265_SW`, `CODEC_WEIGHT_MIME_H264_HW` and `CODEC_WEIGHT_MIME_H264_SW` normalized weight `0.5f` used for default video track selection.

    - #### CRASHLOG_AUTO_REPORT

          public static int CRASHLOG_AUTO_REPORT

      Configure the exception severity that will cause the `Crashlog.report(Throwable)` to be triggered automatically. This should be one of `CastlabsPlayerException.SEVERITY_INFO`, `CastlabsPlayerException.SEVERITY_WARNING`, `CastlabsPlayerException.SEVERITY_ERROR`, or `-1` to disable all automated crash reports.

      By default errors with severity `CastlabsPlayerException.SEVERITY_INFO` or higher will be reported.

    - #### FAST_BITRATE_SWITCHING

          public static int FAST_BITRATE_SWITCHING

      By default, the player queries the currently selected video codec if it supports fast adaptive bitrate switching (`SdkConsts.FAST_BITRATE_SWITCHING_AUTO`). There are however devices where the codec reports an incorrect value. For these devices, you can force the setting to either `SdkConsts.FAST_BITRATE_SWITCHING_ENABLED` or `SdkConsts.FAST_BITRATE_SWITCHING_DISABLED`.

      Set this field to one of `SdkConsts.FAST_BITRATE_SWITCHING_AUTO` (default), `SdkConsts.FAST_BITRATE_SWITCHING_ENABLED`, or `SdkConsts.FAST_BITRATE_SWITCHING_DISABLED`.

    - #### ENABLE_TRICK_MODE_TRACK_SWITCH

          public static boolean ENABLE_TRICK_MODE_TRACK_SWITCH

      Deprecated.
      Use `TrickplayConfiguration.preferTrickPlayTracks` instead
      By default, the player will not switch to any trick mode tracks when the playback speed is changed and will stay on the current video track. Set the value to `true` to use the trick mode track when the latter is available

    - #### ENABLE_CONNECTIVITY_CHECKS

          public static boolean ENABLE_CONNECTIVITY_CHECKS

      By default, the player will not automatically recover from loss of connectivity. Setting this flag to `true` will enable automatic recovery in case the device will loose internet connectivity.
      See Also:
        `CONNECTIVITY_CHECKER`

    - #### CONNECTIVITY_CHECK_PERIOD_MS

          public static int CONNECTIVITY_CHECK_PERIOD_MS

      Period in ms, used to poll the device's connectivity, when `ENABLE_CONNECTIVITY_CHECKS` is enabled
      See Also:
        `CONNECTIVITY_CHECKER`

    - #### DUMMY_SURFACE_MODE

          public static int DUMMY_SURFACE_MODE

      By default the player queries the device API version and internal API for support of the GL based dummy surface for faster and smoother transitions when the playback surface is attached/detached from the video codec.

      This feature is used, for instance, when client side Ad insertion is enabled through the IMA plugin.

      On some devices though, the GL support for the dummy surface and is not properly implemented. In this case, this flag can be use to disable the auto detection mode and manually enable or disable the usage of the dummy surface by setting this flag to `SdkConsts.DUMMY_SURFACE_ENABLED` or `SdkConsts.DUMMY_SURFACE_DISABLED`.

      Please note that this flag is automatically adjusted during the initialization of the SDK based on the current device. If you intent to change the value if this flag, make sure you change it before the call to `init(Context)`.

    - #### PRESCAN_DASH_MANIFESTS

          public static boolean PRESCAN_DASH_MANIFESTS

      Enable this options if you have to play DASH Manifests that are not spec conform and define AdaptationSets' before BaseURLs'. The spec defines the entries in a Period in the Manifest as a sequence where the order matters and BaseURL entries should appear before other entries. Enabling this options causes the Manifest parser to pre-scan the Manifest for BaseURL entries. Note that this means the parser needs to scan the Manifest twice and you should only enable this if it is necessary.

    - #### HTTP_DATASOURCE_BUILDER

          @NonNull
          public static HttpDataSourceBuilder HTTP_DATASOURCE_BUILDER

      The HTTP data source factory that is used to create http data sources. Note that is us a public field because it is used by some plugins and extensions but you usually do not need to set this field manually!

    - #### SUBTITLE_PREVIEW_BUILDER

          @Nullable
          public static SubtitlesPreviewBuilder SUBTITLE_PREVIEW_BUILDER

      Static property that can be set (usually by plugins) to register a preview builder that is in turn used to create subtitle preview views.

    - #### CONNECTIVITY_CHECKER

          @Nullable
          public static ConnectivityCheck CONNECTIVITY_CHECKER

      The default connectivity check that will be used at runtime to check for internet connectivity.

    - #### FORCE_SINGLE_DRM_SESSION

          public static boolean FORCE_SINGLE_DRM_SESSION

      By default the player creates two DRM sessions, one for Audio, and one for Video. If you are certain that the DRM backend returns all required license keys with one request, you can use this flag to enforce only one DRM session.

    - #### FORCE_DRM_LICENSE_PREFETCH

          public static boolean FORCE_DRM_LICENSE_PREFETCH

      By default the player pre-fetches the license as soon as tracks are selected and segments are ready to be downloaded. This provides smooth period transitions with `PlayerController` and smooth items transitions with `SingleControllerPlaylist`. If disabled, then the license will only be acquired when needed for decryption by a renderer.

    - #### ENABLE_DRM_PLACEHOLDER_SESSION

          public static boolean ENABLE_DRM_PLACEHOLDER_SESSION

      The player selects unsecure codec when starting playing clear part of the content e.g. DASH period. Then, when the content is switched to the encrypted one, the unsecure codec is closed and is replaced with a secure one. The user may experience a black screen while the codec is changed. Note that the unsecure codec is selected even if the secure one is forced via player configuration. This flag when enabled, allows to select the secure codec even if the playback starts with content clear part. The default is Util.SDK_INT >= 23. The placeholder is disabled for older devices by default as not all the devices below API 23 may support DRM session sharing needed for placeholder to work correctly.

    - #### ENABLE_DRM_FALLBACK

          public static boolean ENABLE_DRM_FALLBACK

      When multiple `Drm` systems are present on a device and one of them fails locally then the playback is automatically restarted and configured with another DRM type being available. The fallback works with `DrmTodayConfiguration` only and when `DrmConfiguration.drm` is specified as `Drm.BestAvailable`. The fallback can be disabled by setting this flag to `false`. The most secure after the failed DRM is selected always during the fallback. Note that the video quality may degrade after the DRM fallback, consider for example OMA not allowing HD playback. Examples of possible DRM fallbacks: Widevine to PlayReady, Widevine to OMA, Widevine to PlayReady to OMA.

    - #### ENABLE_CDM_KEY_STATUS

          public static boolean ENABLE_CDM_KEY_STATUS

      Key status change listener can be installed to CDM's starting API 23 and is used to get statuses of known key ids. Can be overridden with true or false

    - #### FORCE_VIDEO_CODEC_MAX_INPUT_SIZE_UNKNOWN

          public static boolean FORCE_VIDEO_CODEC_MAX_INPUT_SIZE_UNKNOWN

      By default the player will deduce the maximum input size that is used to configure the video codec via `MediaFormat` and the `MediaFormat.KEY_MAX_INPUT_SIZE` key. On some devices, the internal buffer size might not be set correctly and will be to small. You can try to set this flag to true on such devices to work around this issue.

      Note it is generally advised to use this on targeted devices only where this actually works around in issue in the codec implementation.

      Since:
        4.1.6

    - #### ENABLE_FATAL_RETRY_MIME_APPLICATION

          public static boolean ENABLE_FATAL_RETRY_MIME_APPLICATION

      Indicates whether to consider as fatal errors the ones encountered while downloading segments with MimeType `MimeTypes.BASE_TYPE_APPLICATION`.

    - #### ENABLE_TRIGGER_MANIFEST_FALLBACK_MIME_APPLICATION

          public static boolean ENABLE_TRIGGER_MANIFEST_FALLBACK_MIME_APPLICATION

      Whether to trigger the alternative Manifest callback when an error occurs while downloading segments with MimeType `MimeTypes.BASE_TYPE_APPLICATION`.

    - #### SYSTEM_STATUS_CALLBACK

          public static PlayerSDK.SystemStatusCallback SYSTEM_STATUS_CALLBACK

      If specified, the callback implementation will be triggered on the main thread and inform about the current system status. Please note that this might happen multiple times.

      The system status is evaluated when the SDK is initialized so please make sure that you are setting this callback before you call `init(Context, String)`.

    - #### FORCE_HDCP_EXCEPTION

          public static boolean FORCE_HDCP_EXCEPTION

      If set to true, the behavior of the sdk on HDMI disconnect/hdcp disconnects would be to throw a fatal exception to indicate a crypto error as well as an info exception to indicate HDMI disconnection. The default behavior is for it be false where the SDK would only throw an exception with severity INFO to indicate HDMI/HDCP disconnect and pause till reconnection is achieved.

    - #### FORCE_REOPEN_ON_HDCP_STATE_CHANGE

          public static boolean FORCE_REOPEN_ON_HDCP_STATE_CHANGE

      Sets the behaviour when `FORCE_HDCP_EXCEPTION` is `false`, otherwise the option is ignored. If set to `true` then the playback will be closed and then re-opened when HDCP state allows playback, otherwise (default) the playback will not be closed but the video qualities not allowed for playback will be disabled.

    - #### HDCP_EXCEPTION_TIMEOUT_MS

          public static long HDCP_EXCEPTION_TIMEOUT_MS

      This is the time in milliseconds to wait for DRM key to change its status from `KeyStatus.OutputNotAllowed` to `KeyStatus.Usable` before throwing an exception. The timeout is needed when HDMI-display only device is turned on together with HDMI-display and playback starts shortly. It may be the case that HDCP session is not ready yet and needs some more time to complete its setup, so that the playback has to wait. After the timeout the playback will throw CryptoException assuming the output digital requirements can not be met on the current device. Set to {literal 0} to disable the timeout.

    - #### HDMI_CONNECTION_DELAY_MS

          public static long HDMI_CONNECTION_DELAY_MS

      This is the time in milliseconds to delay the HDMI connection event. The delay is what usually required for the device to setup HDCP session with external display. Devices with API >= 23 does not need this delay as they are operating within `HDCP_EXCEPTION_TIMEOUT_MS` timeout. For other devices this value is defaulted to 3000 ms. Therefore, when the player is re-opening the stream upon HDMI event then it will wait for the specified delay.

    - #### PLAYER_RELEASE_TIMEOUT_MS

          public static long PLAYER_RELEASE_TIMEOUT_MS

      Timeout in milliseconds to release the underlying Player.

    - #### SET_SURFACE_TIMEOUT_MS

          public static long SET_SURFACE_TIMEOUT_MS

      Timeout in milliseconds to set the player Surface.

    - #### licenseLoader

          public static LicenseLoader licenseLoader

      The license loader

    - #### ENABLE_ERROR_RESPONSE_BODY

          public static boolean ENABLE_ERROR_RESPONSE_BODY

      If set to true, the body of the HTTP response will be returned in `CastlabsPlayerException.getErrorData()` when available. The key to get it from the bundle is `CastlabsPlayerException.RESPONSE_BODY`

  - ### Method Detail

    - #### init

          public static void init​(@NonNull
                                  Context ctx)

      Initializes the SDK using the given context and the default `ManifestLicenseLoader` to find a meta-data entry with the key `castlabs-license` in your Applications Manifest.

      Please note that you need to `register(Plugin)` all plugins you want to use before you call this method.

      Note that in case the license key is invalid the SDK will not be initialized and the error will be sent via the `PlayerListener.onError(CastlabsPlayerException)`. The SDK however can still be tried to re-initialized with valid key if applicable.

      Parameters:
        `ctx` - The application context

    - #### init

          public static void init​(@NonNull
                                  Context ctx,
                                  String license)

      Initializes the SDK using the given context and the license specified here. Please note that you need to `register(Plugin)` all plugins you want to use before you call this method.

      Note that in case the license key is invalid the SDK will not be initialized and the error will be sent via the `PlayerListener.onError(CastlabsPlayerException)`. The SDK however can still be tried to re-initialized with valid key if applicable.

      Parameters:
        `ctx` - The application context
        `license` - The license key

    - #### init

          public static void init​(@NonNull
                                  Context ctx,
                                  @NonNull
                                  LicenseLoader licenseLoader)

      Initializes the SDK using the given context and `LicenseLoader` to find and load a license file. Please note that you need to `register(Plugin)` all plugins you want to use before you call this method.

      Note that in case the license key is invalid the SDK will not be initialized and the error will be sent via the `PlayerListener.onError(CastlabsPlayerException)`. The SDK however can still be tried to re-initialized with valid key if applicable.

      Parameters:
        `ctx` - the context
        `licenseLoader` - the license loader that will be used to load the license data

    - #### waitForInitialization

          public static void waitForInitialization()
                                            throws Throwable

      INTERNAL method that will block until the SDK is fully initialized. You usually do not need to call this method manually.
      Throws:
        `Throwable` - in case an error occurs during initialization

    - #### getContext

          public static Context getContext()

      Access the globally configured application context used by the SDK. A runtime exception is thrown if the SDK is not initialized.
      Returns:
        context the context used by the SDK
      Throws:
        `RuntimeException` - if the SDK is not yet initialized

    - #### register

          public static void register​(@NonNull
                                      TrackRendererPlugin plugin)

      Register a new track renderer plugin
      Parameters:
        `plugin` - the plugin

    - #### register

          public static void register​(@NonNull
                                      PlayerPlugin plugin)

      Register a new player plugin
      Parameters:
        `plugin` - the plugin

    - #### register

          public static void register​(@NonNull
                                      Downloadable plugin)

    - #### register

          public static void register​(@NonNull
                                      Drm drm)

      Register external Drm plugin to the sdk.
      Parameters:
        `drm` - drm to be registered

    - #### register

          public static void register​(@NonNull
                                      Plugin plugin)

      Register a new plugin
      Parameters:
        `plugin` - the plugin

    - #### registerDrmLicenseManagerComponent

          public static void registerDrmLicenseManagerComponent​(DrmLicenseManagerComponent component)

      Register a new DrmLicenseManagerComponent
      Parameters:
        `component` - the component

    - #### register

          public static void register​(@NonNull
                                      PlayerViewPlugin plugin)

      Register a new `PlayerViewPlugin`
      Parameters:
        `plugin` - The plugin
      Since:
        3.2.2

    - #### register

          public static void register​(@NonNull
                                      PlayerControllerPlugin plugin)

      Register a new `PlayerControllerPlugin`
      Parameters:
        `plugin` - The plugin
      Since:
        4.0.0

    - #### getPlugin

          @Nullable
          public static <T extends Plugin> T getPlugin​(Class<T> pluginClass)

      Returns the instance of the registered plugin or null if no plugin was found
      Type Parameters:
        `T` - The plugin class type
      Parameters:
        `pluginClass` - The plugin class
      Returns:
        Plugin the plugin instance

    - #### getTrackRendererPlugins

          public static List<TrackRendererPlugin> getTrackRendererPlugins()

      Returns:
        plugins the list of currently registered track renderer plugins

    - #### getPlayerPlugins

          public static List<PlayerPlugin> getPlayerPlugins()

      Returns:
        plugins the list of currently registered player plugins

    - #### getPlugins

          public static Collection<Plugin> getPlugins()

      Returns:
        plugins the list of currently registered plugins

    - #### getDrmLicenseManagerComponents

          public static Collection<DrmLicenseManagerComponent> getDrmLicenseManagerComponents()

      Returns:
        the list of currently registered DrmLicenseManagerComponents

    - #### getDownloadablePlugins

          public static List<Downloadable> getDownloadablePlugins()

      Returns:
        plugins The list of currently registered downloadable plugins

    - #### getPlayerViewPlugins

          public static List<PlayerViewPlugin> getPlayerViewPlugins()

      Returns:
        plugins The list of currently registered player-view plugins

    - #### getPlayerControllerPlugins

          public static List<PlayerControllerPlugin> getPlayerControllerPlugins()

      Returns:
        plugins The list of currently registered player-view plugins

    - #### isPluginRegistered

          public static boolean isPluginRegistered​(@NonNull
                                                   Drm drm)

      INTERNAL! This is an internal method and you will not need to call this method explicitly. If you are looking for an APU to get information about the support of a given DRM system, please take a look at `DrmUtils.isDrmSupported(Drm)`.
      Parameters:
        `drm` - The DRM system
      Returns:
        True if a plugin is registered that supports the given DRM type

    - #### getVersion

          @NonNull
          public static String getVersion()

      Exposes the SDK version
      Returns:
        The SDK version

    - #### addLegacyDeviceScreenResolution

          public static void addLegacyDeviceScreenResolution​(String manufacturer,
                                                             String model)

      Add a device for which its screen dimensions will be read using the legacy approach.

      It has been seen that on some STBs, the underlying new APIs are not reliable while the approach for Android versions < 25 results in the expected behaviour.

      Note that this method won't work with all devices, and it is specially likely not to work with devices running on API >=25.

      In case the legacy method is forced for a device, but no resolution is available through it, it will default to the standard behaviour.

      Parameters:
        `manufacturer` - manufacturer of the device, as found in `Build.MANUFACTURER`
        `model` - manufacturer of the device, as found in `Build.MODEL`