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 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. When setting the thumbnail listener, the preferred bandwidth is passed as an extra parameter.

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

Faster loading of DASH-IF thumbnails

The size and quantity of the thumbnail images affect preparation time. Until the prepared() callback is sent, no preview thumbnails are available for the application to display, and the prepared() callback is only sent when all thumbnails are downloaded and prepared. Depending on network conditions and the device, this could take several minutes for long assets with many large-size images. (To ensure playback quality is not affected, the CONNECT player intentionally does not speed up downloading any further). The CONNECT player provides an API to improve this by initially downloading fewer thumbnails before declaring thumbnails as prepared().

The way this is implemented is as follows:

1. The application instantiates the player with configuration (see (5.33.x) Advanced player configuration ) using setThumbnailsPerMinute(float xThumbnailsPerMinute).

2. The thumbnails-per-minute value specifies the initial spacing (a value of 0f means setting as default - 10% 'spacing').
   For example, if the stream provides a thumbnail every four seconds, there would be fifteen images to download every minute. If the application requests three thumbnails per minute, the player would initially only download a fifth of the thumbnails.

3. The player downloads only a partial subset of the thumbnail images and then notifies the application with prepared(). The subset of thumbnails is now available to use.

4. Unless keepThumbnailsSpaced is set to true, the player continues downloading the rest of the thumbnails in the background and adds them to the subset list until all thumbnails are downloaded.

5. If keepThumbnailsSpaced is set to true, only the 'spaced' thumbnails are downloaded. For Live and start-over streams, additional thumbnails would be added as time progresses, but only in 'spaced' mode.

For live and start-over streams, where new thumbnails are added upon manifest refresh events, the CONNECT Player will start downloading fresh thumbnails only after all thumbnails for the previous manifest are downloaded.

Controlling memory usage of thumbnail images.

The quantity and size of thumbnail images not only affects their preparation time as mentioned above, but may affect memory usage. Prepared thumbnails are kept in the device's memory rather than in its storage for quicker access. If there are many images, and if they are large in size, the device's memory might be exhausted.  The best way to avoid this is to make sure the streams' thumbnails are carefully prepared with memory usage in mind. The next line of defence would be to control the initial thumbnail spacing and setting keepThumbnailsSpaced to true. In addition to that, the application can configure the player to limit the usage of memory by the thumbnail images:

1. The application instantiates the player with configuration (see (5.33.x) Advanced player configuration ) using setThumbnailsMaximumMemory(float xThumbnailsMaximumMemoryMB). Setting this value to zero, or not calling this method means no upper limit is set (default).

2. When the player prepares the thumbnails, it will calculate and estimate the usage of memory by the thumbnail images (it will only take into account memory used directly by the images, no other overhead usage)

3. The memory used is increased as more thumbnails are extracted from the stream and prepared for preview.

4. If the calculated memory usage reaches the upper limit set in the configuration, parsing will stop, and an ERROR_THUMBNAILS_MAXIMUM_MEMORY_REACHED (4) error notification will be sent to the application via the listener.

   • If the error occurs before the prepared()notification is sent, no thumbnails would be available to preview.

   • If the error occurs after the prepared()notification is sent, the thumbnails already prepared will remain available.

5. Stopping playback clears all the player's resources, including the memory used by the thumbnails.

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.

// 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);
}