Package com.castlabs.sdk.thumbs

# Class ThumbsPlugin

java.lang.Object
com.castlabs.android.Plugin
com.castlabs.sdk.thumbs.ThumbsPlugin

public class ThumbsPlugin extends Plugin
This plugin can be registered with the player to add support for thumbnails in different formats.

The plugin module exposes two main interfaces, `ThumbnailLoader` to load raw images from a data source and `ThumbnailProvider` that handles the asynchronous delivery to a view.

The plugin expose a default `ThumbnailProvider` through `PlayerController.getComponent(Class)` if playback is started with an intent bundle, i.e. `PlayerController.open(Bundle)` is used to start playback. The provider assumes that you add an instance of `ThumbnailDataTrack` with the key `INTENT_THUMBNAILS_DATA` to the bundle. If that is the case the provider will be fully initialized and can be accessed through:

         ThumbnailProvider provider = playerController.getComponent(ThumbnailProvider.class);

The provider can then be used in a `View` to render thumbnail images. The plugin also provides `DefaultThumbnailView` as a default implementation. You can use that view to add it manually to you view hierarchy, but you can also register the plugin with the default view component enabled. In that case in instance of `DefaultThumbnailView` will automatically added to the `PlayerView` and will be initialized with the provider component. In that case you can access the component through `PlayerView.getComponent(Class)`, for example:

         ThumbnailViewComponent thumbsView = playerView.getComponent(ThumbnailViewComponent.class);

The view component exposes `ThumbsPlugin.ThumbnailViewComponent.show(long, DefaultThumbnailView.Callback)` and `ThumbsPlugin.ThumbnailViewComponent.hide()` to control thumbnail rendering.

Since:
  4.0.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ThumbsPlugin.DiskCacheMode`
  Disk cache mode controlling on-disk thumbnail caching behavior.
  `static class`
  `ThumbsPlugin.ThumbnailViewComponent`
  If you registered the plugin with the default view integration enabled, this component will be registered with the `PlayerView` and you can access it to trigger displaying thumbnails.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static boolean`
  `DEBUG`
  Flag to enable detailed logging of thumbnail loading
  `static final LoadingStrategy`
  `DEFAULT_LOADING_STRATEGY`
  Default loading strategy for thumbnails.
  `static final LoadingStrategy`
  `EMPTY_LOADING_STRATEGY`
  Empty loading strategy without any `LoadingStrategy.Wave`.
  `static final String`
  `INTENT_THUMBNAILS_DATA`
  Deprecated.
  in favour of `SdkConsts.INTENT_SIDELOADED_TRACKS_ARRAYLIST` and `SideloadedTrack.ThumbnailBuilder`.
  `static final int`
  `PRESTO_DEFAULT_THUMBNAIL_VIEW`
  Id for the default `DefaultThumbnailView`
  `static final LoadingStrategy`
  `SEQUENTIAL_LOADING_STRATEGY`
  Sequential loading strategy.
  `static final int`
  `THUMBNAIL_INDEX_CLOSEST`
  When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the closest thumbnail.
  `static final int`
  `THUMBNAIL_INDEX_CURRENT`
  When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the current thumbnail.
  `static final int`
  `THUMBNAIL_INDEX_NEXT`
  When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the next thumbnail.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ThumbsPlugin(boolean useDefaultView)`
  Create a new instance of this plugin.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ThumbnailProvider`
  `createProvider(PlayerController playerController, ThumbnailDataTrack thumbnailData, LoadingStrategy loadingStrategy, String manifestUrl)`
  Same as `createProvider(PlayerController, ThumbnailDataTrack, LoadingStrategy, String, ThumbnailLoader.Factory)` but with a default loader implementation.
  `static ThumbnailProvider`
  `createProvider(PlayerController playerController, ThumbnailDataTrack thumbnailData, LoadingStrategy loadingStrategy, String manifestUrl, com.castlabs.sdk.thumbs.ThumbnailLoader.Factory loaderFactory)`
  Create a thumbnail provider based on the `type`.
  `static ThumbsPlugin.DiskCacheMode`
  `getDiskCacheMode()`
  Returns the global disk cache mode for thumbnails.
  `String`
  `getId()`
  `static int`
  `getThumbnailLoadThreads()`
  Returns the number of Threads that will be used to load image-based Thumbnails.
  `static void`
  `setDiskCacheMode(ThumbsPlugin.DiskCacheMode mode)`
  Sets the global disk cache mode for thumbnails.
  `void`
  `setLoadingStrategy(LoadingStrategy loadingStrategy)`
  Sets the `LoadingStrategy` to use for loading thumbnails.
  `static void`
  `setThumbnailLoadThreads(int loadThreadCount)`
  Set the number of Threads that will be used to load image-based Thumbnails.

  ### Methods inherited from class com.castlabs.android.Plugin

  `init, onRemotePlay`

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

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

- ## Field Details

  - ### INTENT_THUMBNAILS_DATA

    public static final String INTENT_THUMBNAILS_DATA
    Deprecated.
    in favour of `SdkConsts.INTENT_SIDELOADED_TRACKS_ARRAYLIST` and `SideloadedTrack.ThumbnailBuilder`.
    Use this key to store `ThumbnailDataTrack` in an intent.
    See Also:
      - Constant Field Values

  - ### DEFAULT_LOADING_STRATEGY

    public static final LoadingStrategy DEFAULT_LOADING_STRATEGY
    Default loading strategy for thumbnails. Load will be triggered upon the first Thumbnail request. Defines 3 waves:
    1. 1 Minute: A thumbnail will be loaded for every minute of the content
    2. 15 Seconds: A thumbnail will be loaded for every 15 seconds of the content
    3. All thumbnails will be loaded

  - ### SEQUENTIAL_LOADING_STRATEGY

    public static final LoadingStrategy SEQUENTIAL_LOADING_STRATEGY
    Sequential loading strategy. Naive strategy which simply loads all thumbnails sequentially. Thumbnails will start to load immediately. Corresponds to the legacy behaviour before `LoadingStrategy` was introduced.

  - ### EMPTY_LOADING_STRATEGY

    public static final LoadingStrategy EMPTY_LOADING_STRATEGY
    Empty loading strategy without any `LoadingStrategy.Wave`. Use this strategy if you want to disable any precaching of thumbnails while still being able to load them on demand.

  - ### DEBUG

    public static boolean DEBUG
    Flag to enable detailed logging of thumbnail loading

  - ### PRESTO_DEFAULT_THUMBNAIL_VIEW

    @IdRes public static final int PRESTO_DEFAULT_THUMBNAIL_VIEW
    Id for the default `DefaultThumbnailView`

  - ### THUMBNAIL_INDEX_CURRENT

    public static final int THUMBNAIL_INDEX_CURRENT
    When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the current thumbnail. This corresponds to the thumbnail with the highest media time that is lower than the requested position.
    See Also:
      - Constant Field Values

  - ### THUMBNAIL_INDEX_NEXT

    public static final int THUMBNAIL_INDEX_NEXT
    When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the next thumbnail. This corresponds to the thumbnail with the lowest media time that is higher than the requested position.
    See Also:
      - Constant Field Values

  - ### THUMBNAIL_INDEX_CLOSEST

    public static final int THUMBNAIL_INDEX_CLOSEST
    When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the closest thumbnail. This corresponds to the thumbnail with the lowest difference between its media time and the requested position.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### ThumbsPlugin

    public ThumbsPlugin(boolean useDefaultView)
    Create a new instance of this plugin. You can specify if the default renderer view should be registered. If you want to use the default renderer view, see `ThumbsPlugin.ThumbnailViewComponent` for more information how to access and use the view.
    Parameters:
      `useDefaultView` - Register the default renderer view

- ## Method Details

  - ### getDiskCacheMode

    @NonNull public static ThumbsPlugin.DiskCacheMode getDiskCacheMode()
    Returns the global disk cache mode for thumbnails. Default is `ThumbsPlugin.DiskCacheMode.DISABLED`.
    Returns:
      The disk cache mode.

  - ### setDiskCacheMode

    public static void setDiskCacheMode(@NonNull ThumbsPlugin.DiskCacheMode mode)
    Sets the global disk cache mode for thumbnails. This affects how thumbnail loaders use on-disk caching and whether cleanup occurs on dispose.

    Parameters:
      `mode` - The disk cache mode. Default is `ThumbsPlugin.DiskCacheMode.DISABLED`.

  - ### setLoadingStrategy

    public void setLoadingStrategy(@NonNull LoadingStrategy loadingStrategy)
    Sets the `LoadingStrategy` to use for loading thumbnails. Applies for VTT, JPG and DASH embedded thumbnails.

    Can be later set at runtime, between playback sessions through `ThumbnailProvider.setLoadingStrategy(LoadingStrategy)`.

    Parameters:
      `loadingStrategy` - the strategy to use. Must be non null and contain at least one Wave.
    See Also:
      - `LoadingStrategy`

  - ### getId

    @NonNull public String getId()
    Specified by:
      `getId` in class `Plugin`

  - ### createProvider

    @Nullable public static ThumbnailProvider createProvider(@NonNull PlayerController playerController, @NonNull ThumbnailDataTrack thumbnailData, @NonNull LoadingStrategy loadingStrategy, @Nullable String manifestUrl)
    Same as `createProvider(PlayerController, ThumbnailDataTrack, LoadingStrategy, String, ThumbnailLoader.Factory)` but with a default loader implementation.
    Parameters:
      `playerController` - The player controller instance
      `thumbnailData` - The thumbnail data
      `loadingStrategy` - The thumbnail loading strategy
      `manifestUrl` - URL to the manifest that is used to infer the absolute URL to the thumbnails in case `url` is relative
    Returns:
      The provider
    Throws:
      `IllegalArgumentException` - in case the type of the thumbnail format is not specified and could not be inferred.

  - ### createProvider

    @Nullable public static ThumbnailProvider createProvider(@NonNull PlayerController playerController, @NonNull ThumbnailDataTrack thumbnailData, @NonNull LoadingStrategy loadingStrategy, @Nullable String manifestUrl, @Nullable com.castlabs.sdk.thumbs.ThumbnailLoader.Factory loaderFactory)
    Create a thumbnail provider based on the `type`. If the type is unknown, it will be inferred from the extension (i.e. .bif, .vtt, or .jpg of the URL. If the type could not be inferred, an exception is raised.
    Parameters:
      `playerController` - The player controller instance
      `thumbnailData` - The thumbnail data
      `loadingStrategy` - The thumbnail loading strategy
      `manifestUrl` - URL to the manifest that is used to infer the absolute URL to the thumbnails in case `url` is relative
      `loaderFactory` - The thumbnail loader factory. If `null` the default factory will be generated
    Returns:
      The provider
    Throws:
      `IllegalArgumentException` - in case the type of the thumbnail format is not specified and could not be inferred.

  - ### getThumbnailLoadThreads

    public static int getThumbnailLoadThreads()
    Returns the number of Threads that will be used to load image-based Thumbnails.
    Returns:
      the number of Threads that will be used for Thumbnail loading

  - ### setThumbnailLoadThreads

    public static void setThumbnailLoadThreads(int loadThreadCount)
    Set the number of Threads that will be used to load image-based Thumbnails.
    Parameters:
      `loadThreadCount` - number of Threads