Unified API thumbnail support

To test this feature and view the example code, please see the Unified API Example Code Quick Start guide.

This feature lets users capture DASH-IF and I-Frame thumbnails and display them as a position preview when sliding through the seek bar.

The following API is used to show/hide thumbnails on an existing IOTVUPIPlayer instance.

JAVA

  /**
   * Configure the player to use / not use thumbnails.
   *
   * @param xDisplayThumbnails boolean to decide whether to display thumbnails or not
   *                           <br>{@code true} Display thumbnail content
   *                           <br>{@code false} Do not displa thumbnails
   *
   * @remark If set to {@code true}, the thumbnail will be rendered based on the
   * {@link OTVUPIPlayer#setThumbnailStyle thumbnailStyle} and the
   * {@link OTVUPIPlayer#setThumbnailPosition thumbnailPosition} properties.
   */
  void setDisplayThumbnail(boolean xDisplayThumbnails);

  /**
   * Specify the position for which to present a thumbnail.
   *
   * @param xPositionSeconds the position in the stream for which to display the thumbnail
   *
   * @remark If a thumbnail is required for a given position and there is none available for
   * rendering, a blank or black canvas would be rendered.
   */
  void setThumbnailPosition(int xPositionSeconds);

  /**
   * Specify location, size and borders of a requested thumbnail to be rendered.
   *
   * @param xX the number of pixels from the left to the left border of the thumbnail
   * @param xY the number of pixels from the top to the top border of the thumbnail
   * @param xWidth the width of the thumbnail rectangle in pixels
   * @param xHeight the height of the thumbnail rectangle in pixels
   * @param xBorderWidth the thickness of the border in pixels
   * @param xBorderColor the sRGB colour (packed in a 32-bit integer) of the border
   *
   */
  void setThumbnailStyle(int xX, int xY, int xWidth, int xHeight, int xBorderWidth, int xBorderColor);

Providing a zero value to either width or height in setThumbnailStyle() will reset the style to default values.
The thumbnail stream provides the default size or a value of 320,180 if unable to get the stream thumbnail size.

It can be assisted by the following event arriving at an implementation of IOTVUPIEventListener (for which a reference is passed during Player creation).

JAVA

  /**
   * Indicates the stream being played contains preview thumbnails
   *
   * The event {@link #onThumbnailAvailable} will be triggered as soon as the player detects any
   * existing compatible thumbnails in the source requested to be played. This is triggered only
   * once for a new content request. This is required for the App to decide setting up of
   * {@link IOTVUPIPlayer#setDisplayThumbnail displayThumbnail}
   */
  void onThumbnailAvailable();

onThumbnailAvailable() only indicates thumbnails exist in the stream. For some streams, it takes the player longer to extract the thumbnails and prepare them for viewing. This callback is useful for the app to decide whether to ask for thumbnails to be displayed or not; however, no thumbnail would be shown if setDisplayThumbnail() is called, and the thumbnails were not prepared.

The example below shows when to call the setThumbnailStyle and setThumbnailPosition. Using the onProgressChanged event from a seek bar listener:

JAVA

     
	/**
	* this is a part of the SeekBar.OnSeekBarChangeListener(). whenever the scrollbar is touched or progress is changed this method is called
    * @param bar the Seekbar that is having its progress changed
    * @param progress the progress across the bar defaulted between 0 to 100 as a percentage. 
    * @param fromuser Boolean representing a user seek event or not
	*/
	public void onProgressChanged(SeekBar bar, int progress, boolean fromuser) {
        if (mIOTVUPIPlayer == null) {
          return;
        }

        // mDuration should be set using the OTVUPIEventListener's onLoad event
        long newPosition;
        //conver progress of seekbar to position in milliseconds
        newPosition = (mDuration * progress) / 1000L;

        mIOTVUPIPlayer.setDisplayPosition(newPosition);

        // this gets the center position for the seekbars thumb. useful for centering a thumbnail on
        int thumbCenter = (width * progress) / bar.getMax() + bar.getThumb().getBounds().width() / 2;
        // add all previous views from the left hand side of the sceen to the seekbar to this xPos to get the exact position on screen
        int xPos = thumbCenter + viewsToLeftWidth;
        // add all views below the bar to this yPos so that thumbnails appear above the seekbar.
        int yPos = bar.getHeight() + bar.getPaddingTop() + bar.getPaddingBottom() + viewsBelowHeight;
        updateView(xPos, yPos);

     }

     ...

     private void updateView(int xPos, int yPos) {
       mThumbnailXPos = xPos;
       mThumbnailYPos = mVideoContainerView.getHeight() - yPos;
       mIOTVUPIPlayer.setThumbnailStyle(mThumbnailXPos,mThumbnailYPos,mThumbnailWidth,mThumbnailHeight,mThumbnailBorderWidth,mThumbnailColor);
     }