Package com.castlabs.sdk.thumbs

# Interface ThumbnailProvider

All Known Subinterfaces:
  `StandaloneThumbnailProvider`

All Known Implementing Classes:
  `BaseThumbnailProvider`, `BifThumbnailProvider`, `JpgThumbnailProvider`, `VttThumbnailProvider`

public interface ThumbnailProvider
Implementations of this interface provide thumbnails for positions in the current track.

Since:
  4.0.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `ThumbnailProvider.Callback`
  Because loading Thumbnails is usually an asynchronous process, this callback interface needs to be implemented to receive the results when a thumbnail was requested.
  `static interface`
  `ThumbnailProvider.IndexRefreshListener`
  Listener which gets called every time the internal thumbnail index is refreshed.
  `static enum`
  `ThumbnailProvider.RequestQueuePosition`
  Defines where in the loading queue shall new thumbnail requests be placed.
  `static final class`
  `ThumbnailProvider.ThumbnailResult`
  The result provided by the Future returned when requesting a Thumbnail through one of the `getThumbnail(long, int, long)` or `getThumbnail(long, int, long)` APIs

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addIndexRefreshListener(ThumbnailProvider.IndexRefreshListener indexRefreshListener)`
  Add an `ThumbnailProvider.IndexRefreshListener`
  `void`
  `cancelPendingRequests()`
  Cancels any queued Thumbnail Requests.
  `boolean`
  `cancelRequests(long positionFromUs, long positionToUs)`
  Removes previously queued explicit requests (through the getThumbnail methods), whose requests positions' within the specified position range.
  `void`
  `destroy()`
  Free up all the resources, meaning this provider will not be used anymore
  `List<Long>`
  `getCuePointsList()`
  Gets cue-points list of the thumbnails, or null if not loaded yet.
  `DownloadableResource[]`
  `getDownloadableResources(String remoteManifestUrl, File basePath, Bundle bundle)`
  This methods is used to integrate a thumbnail provider with the downloader plugins and implementation can return an array of resources that should be fetched for offline playback.
  `default Future<ThumbnailProvider.ThumbnailResult>`
  `getThumbnail(long positionUs, int thumbnailIndex)`
  Load the exact thumbnail for the given position and return a `Future` linked to the operation.
  `Future<ThumbnailProvider.ThumbnailResult>`
  `getThumbnail(long positionUs, int thumbnailIndex, long positionToleranceUs)`
  Load the thumbnail for the given position and return a `Future` linked to the operation.
  `default void`
  `getThumbnail(long positionUs, ThumbnailProvider.Callback callback, int thumbnailIndex)`
  Load the exact thumbnail for the given position and return it through the provided callback.
  `void`
  `getThumbnail(long positionUs, ThumbnailProvider.Callback callback, int thumbnailIndex, long positionToleranceUs)`
  Load the thumbnail for the given position and return it through the provided callback.
  `Long`
  `getThumbnailPosition(long positionUs, int thumbnailIndex)`
  Gets the actual position of the thumbnail in micro seconds, or null if not loaded yet.
  `void`
  `removeIndexRefreshListener(ThumbnailProvider.IndexRefreshListener indexRefreshListener)`
  Remove an `ThumbnailProvider.IndexRefreshListener`
  `void`
  `setLoadingStrategy(LoadingStrategy loadingStrategy)`
  Updates the `LoadingStrategy` of this provider.
  `void`
  `setRequestQueuePosition(ThumbnailProvider.RequestQueuePosition queuePosition)`
  Set where in the loading queue shall new thumbnail requests be placed.

- ## Method Details

  - ### getThumbnail

    default void getThumbnail(long positionUs, ThumbnailProvider.Callback callback, @ThumbnailIndex int thumbnailIndex)
    Load the exact thumbnail for the given position and return it through the provided callback.

    Same as calling `getThumbnail(long, Callback, int, long)` with a tolerance of 0

    Parameters:
      `positionUs` - The position in microseconds
      `callback` - The callback that will be triggered once data are available
      `thumbnailIndex` - Position of the Thumbnail relative to its timestamp

  - ### getThumbnail

    default Future<ThumbnailProvider.ThumbnailResult> getThumbnail(long positionUs, @ThumbnailIndex int thumbnailIndex)
    Load the exact thumbnail for the given position and return a `Future` linked to the operation.

    Same as calling `getThumbnail(long, int, long)` with a tolerance of 0

    Parameters:
      `positionUs` - The position in microseconds
      `thumbnailIndex` - Position of the Thumbnail relative to its timestamp
    Returns:
      a Future identifying the request

  - ### getThumbnail

    Future<ThumbnailProvider.ThumbnailResult> getThumbnail(long positionUs, @ThumbnailIndex int thumbnailIndex, long positionToleranceUs)
    Load the thumbnail for the given position and return a `Future` linked to the operation.
    Parameters:
      `positionUs` - The position in microseconds
      `thumbnailIndex` - Position of the Thumbnail relative to its timestamp
      `positionToleranceUs` - Maximum tolerance time between the time of the requested thumbnail and a potentially already-loaded thumbnail in the index. If a matching nearby thumbnail with data is found, it will be returned immediately. Otherwise the requested thumbnail will be scheduled for fetching. If 0, the exact thumbnail will always be returned, loading it if necessary.
    Returns:
      a Future identifying the request

  - ### getThumbnail

    void getThumbnail(long positionUs, ThumbnailProvider.Callback callback, @ThumbnailIndex int thumbnailIndex, long positionToleranceUs)
    Load the thumbnail for the given position and return it through the provided callback.
    Parameters:
      `positionUs` - The position in microseconds
      `callback` - The callback that will be triggered once data are available
      `thumbnailIndex` - Position of the Thumbnail relative to its timestamp
      `positionToleranceUs` - Maximum tolerance time between the time of the requested thumbnail and a potentially already-loaded thumbnail in the index. If a matching nearby thumbnail with data is found, it will be returned immediately. Otherwise the requested thumbnail will be scheduled for fetching. If 0, the exact thumbnail will always be returned, loading it if necessary.

  - ### getCuePointsList

    @Nullable List<Long> getCuePointsList()
    Gets cue-points list of the thumbnails, or null if not loaded yet.
    Returns:
      The cue-points list

  - ### getThumbnailPosition

    @Nullable Long getThumbnailPosition(long positionUs, @ThumbnailIndex int thumbnailIndex)
    Gets the actual position of the thumbnail in micro seconds, or null if not loaded yet.
    Parameters:
      `positionUs` - The requested position
      `thumbnailIndex` - Position of the Thumbnail relative to its timestamp
    Returns:
      The actual position of the thumbnail

  - ### cancelRequests

    boolean cancelRequests(long positionFromUs, long positionToUs)
    Removes previously queued explicit requests (through the getThumbnail methods), whose requests positions' within the specified position range. If the request was issued with a `ThumbnailProvider.Callback` it will be invoked.

    Parameters:
      `positionFromUs` - minimum position for cancelling a request (inclusive)
      `positionToUs` - maximum position for cancelling a request (exclusive)
    Returns:
      whether at least one request has been cancelled by the method call

  - ### getDownloadableResources

    @Nullable DownloadableResource[] getDownloadableResources(String remoteManifestUrl, File basePath, Bundle bundle)
    This methods is used to integrate a thumbnail provider with the downloader plugins and implementation can return an array of resources that should be fetched for offline playback.
    Parameters:
      `remoteManifestUrl` - The manifest URL of the remote manifest that is the source of this download
      `basePath` - The base folder for this download
      `bundle` - The bundle that was used to start the initiate the download
    Returns:
      Array of downloadable resources or null

  - ### destroy

    void destroy()
    Free up all the resources, meaning this provider will not be used anymore

  - ### setLoadingStrategy

    void setLoadingStrategy(@NonNull LoadingStrategy loadingStrategy)
    Updates the `LoadingStrategy` of this provider. If thumbnails are already loading, this might not have an immediate effect.
    Parameters:
      `loadingStrategy` - the loading strategy to set

  - ### setRequestQueuePosition

    void setRequestQueuePosition(@NonNull ThumbnailProvider.RequestQueuePosition queuePosition)
    Set where in the loading queue shall new thumbnail requests be placed. Either front or back.
    Parameters:
      `queuePosition` - the position where to insert the upcoming thumbnail requests

  - ### cancelPendingRequests

    void cancelPendingRequests()
    Cancels any queued Thumbnail Requests. Requests currently processing won't be cancelled.

  - ### addIndexRefreshListener

    void addIndexRefreshListener(ThumbnailProvider.IndexRefreshListener indexRefreshListener)
    Add an `ThumbnailProvider.IndexRefreshListener`
    Parameters:
      `indexRefreshListener` - the listener

  - ### removeIndexRefreshListener

    void removeIndexRefreshListener(ThumbnailProvider.IndexRefreshListener indexRefreshListener)
    Remove an `ThumbnailProvider.IndexRefreshListener`
    Parameters:
      `indexRefreshListener` - the listener