Unified API bitrate and resolution capping

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

This feature uses the following API to apply capping on an existing IOTVUPIPlayer instance.

JAVA

/**
 * Sets the playback resolution capping to the maximum width and height provided
 * @param xMaxResolution resolution of the content that the player needs to cap (width, height)
 */
void setMaxResolution(Pair<Integer, Integer> xMaxResolution);

/**
 * gets the currently selected Resolution limit. returning 0 means uncapped
 * @return The maximum player Resolution (width, height)
 */
Pair<Integer, Integer> getMaxResolution();

/**
 * Sets the playback bandwidth capping to the maximum bitrate provided
 * @param xMaxBitrate bitrate of the content that the player needs to cap (in bits/second)
 */
void setMaxBitrate(int xMaxBitrate);

/**
 * gets the currently selected bitrate limit. returns 0 for uncapped
 * @return The maximum player bitrate
 */
int getMaxBitrate();

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

JAVA

  /**
   * Gets called to provide details of content's available bitrates
   * @param xBitrates array of bitrates (each bitrate in bits per second)
   */
  void onBitratesAvailable(@Nullable int[] xBitrates);

  /**
   * Gets called on change in selected content's bitrate
   * @param xBitrate bitrate (in bits per second)
   */
  void onSelectedBitrateChanged(int xBitrate);

  /**
   * Gets called on change in selected content's resolution
   * @param xResolution resolution (width, height)
   */
  void onDownloadResolutionChanged(Pair<Integer, Integer> xResolution);

Special cases

All resolution and bitrate capping values passed to the player should be greater than zero (except for resetting capping).

Negative bitrate capping values are ignored.
Zero bitrate capping values reset capping to uncapped.
If a bitrate capping value less than the lowest available in the stream is set, the player will play with the lowest bitrate.
Resolution capping is applied separately on the width (first parameter) and height (second).
Setting a zero or negative value on a resolution parameter resets capping to uncapped.
If a resolution capping value set is less than the lowest available in the stream, the player will play with the lowest available resolution.
If both resolution and bitrate capping are applied simultaneously (not recommended), the strongest capping of the two will apply.
Re-apply capping every time the source is set (zapping).

When changing capping settings during playback, the changes will apply only to newly downloaded segments, not to content already in the Player's buffers. Depending on the size of the buffers, the effect would be noticeable only after a few more seconds of playback.