Thumbnail previews

To test this feature and view the example code, please see the Android SDK 5 Example Code Quick Start guide.

This feature enables you to capture thumbnails from DASH VOD streams and display them as a position preview when sliding through the seek bar.

Thumbnails have to be advertised in the DASH manifest as per DASH-IF Interoperability Points 4.3. Please refer to chapter 6.2.6 Tiles of thumbnail images for the details.

Example code

The operation is instigated by the application providing the OTVVideoView instance with a thumbnail listener before providing it with the stream’s URL. The existence of this listener instigates the preparation of thumbnails upon providing the stream URL. The thumbnails are prepared asynchronously so that playback start time is not compromised. This also means that the VOD streams would not be available at the very beginning of playback. The SDK notifies the application of the thumbnail preparation state through the provided listener and, once prepared, will provide the application with a thumbnail view to display.

Preparation time (the time it takes from the start of playback until thumbnails are available for preview) depends on the number of thumbnails and their size (bandwidth). This could take a fraction of a second for short content with few thumbnails to a few seconds for long-duration content with a high density of thumbnails.

Prepare a listener in the application.

JAVA

    private IOTVThumbnailListener mThumbnailListener = new IOTVThumbnailListener() {
      @Override
      public void noThumbnails() {
        // Info: No thumbnails for the given stream
      }

      @Override
      public void preparing() {
        // Info: Got a DASH manifest with thumbnails. Preparing thumbnails
      }

      @Override
      public void prepared(OTVThumbnailView xView) {
        // Thumbnails are prepared and the thumbnail view is provided as a parameter
        // Note: this callback is NOT called on the UI thread.
      }

      @Override
      public void error(int reason) {
        // Failed to fetch thumbnails for some reason
        // The reason parameter represents one of the OTVThumbnailError integer constants
      }
    };

Just before setting the video path of the stream to play, provide the OTVVideoView instance with the thumbnail listener

JAVA

    mOTVVideoView.setThumbnailListener(mThumbnailListener);
    // ...
    mOTVVideoView.setVideoPath(STREAM_URI);

The OTVThumbnailView instance provided in the prepared() callback is used to display all thumbnails. The application needs to update the view with the correct image by specifying the desired time. The SDK will match the position (in milliseconds) with the correct thumbnail image.

JAVA

thumbnailView.seekTime(positionMs);

The example code implements a simple seek bar in a ThumbnailMediaController class which demonstrates the usage of the thumbnail view provided in the prepared() callback.

Additional features

Setting thumbnail bandwidth

Thumbnail bandwidth is defined in the IOP document as the thumbnail size in bits divided by its duration. In some streams, the DASH manifest provides thumbnails in multiple bandwidths.

Thumbnail preparation time and the memory requirements increase with the bandwidth. As an entire set of thumbnails (List<OTVThumbnail> thumbnails) is stored in the device’s memory during playback, selecting a set of high bandwidth thumbnails, especially with long-content VOD, can use up much of the application’s usable memory. If available memory is exhausted, the SDK will send an ‘out of memory’ error to the thumbnail listener and discard the entire set of thumbnails.

The application can specify its preferred thumbnail bandwidth. The SDK will select from the available bandwidths in the stream the thumbnails with the bandwidth closest to the preferred one. If no bandwidth is specified, the lowest bandwidth will be selected.

The preferred bandwidth is passed as an extra parameter when setting the thumbnail listener.

JAVA

mOTVVideoView.setThumbnailListener(mThumbnailListener, 20000);
// ...
mOTVVideoView.setVideoPath(STREAM_URI);

Direct access to thumbnail images and their start-time

If you do not want to display the OTVThumbnailView instance and want to implement a thumbnail view of your own, you can still have access to the list of images (and their start time) through the provided OTVThumbnailView instance, which contains a list of OTVThumbnail elements. Each element consists of the start-time (in milliseconds) and a byte array representing an image bitmap.

JAVA

// Extract the thumbnail list from the view
List<OTVThumbnail> thumbnails = thumbnailView.getThumbnails();
for (OTVThumbnail thumbnail : thumbnails) {
  // Extract start-time and bitmap image from an OTVThumbnail instance
  long startTime = thumbnail.getStartTime();
  byte[] imageData = thumbnail.getImageData();
  Bitmap thumbnailBitmap = BitmapFactory.decodeByteArray(imageData, 0, imageData.length);
}