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 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 LoadingStrategy` | `DEFAULT_LOADING_STRATEGY` | Default loading strategy for thumbnails.
    `static String` | `INTENT_THUMBNAILS_DATA` | Deprecated. in favour of `SdkConsts.INTENT_SIDELOADED_TRACKS_ARRAYLIST` and `SideloadedTrack.ThumbnailBuilder`.
    `static int` | `PRESTO_DEFAULT_THUMBNAIL_VIEW` | Id for the default `DefaultThumbnailView`
    `static LoadingStrategy` | `SEQUENTIAL_LOADING_STRATEGY` | Sequential loading strategy.
    `static int` | `THUMBNAIL_INDEX_CLOSEST` | When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the closest thumbnail.
    `static int` | `THUMBNAIL_INDEX_CURRENT` | When used in `DefaultThumbnailView.show(long, DefaultThumbnailView.Callback, int)` will render the current thumbnail.
    `static 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

    All Methods Static Methods Instance Methods Concrete Methods
    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`.
    `String` | `getId()` |
    `static int` | `getThumbnailLoadThreads()` | Returns the number of Threads that will be used to load image-based 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 Detail

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

    - #### 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 Detail

    - #### 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 Detail

    - #### 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