Package com.castlabs.android

Class PlayerSDK

    • 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.

      • 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

      • 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

      • 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

      • 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.

      • 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

      • 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.

      • 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

      • 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.

      • licenseLoader

        public static LicenseLoader licenseLoader
        The license loader

    • 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

      • 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