Skip to content

abr.md

Latest commit

 

History

History
122 lines (95 loc) · 6.29 KB

abr.md

File metadata and controls

122 lines (95 loc) · 6.29 KB
Raw

Adaptive Bitrate (ABR)

Overview

The playback quality during play-out of a stream is determined by the ABR algorithm. On starting play-out of a stream, the ABR strategy determines which quality to prefer, while during play-out the network's bandwidth is monitored to select an optimal quality.

More information on ABR can be found on our THEOplayer website and demo page.

In this document we will outline how to affect the ABR algorithm, setting a preferred quality or set of qualities and subscribe to related events.

ABR Configuration

The ABR Configuration determines which initial quality the player will download, depending on the chosen strategy, as well as various parameters of the playback buffer.

 const onPlayerReady = (player: THEOplayer) => {
  player.abr.strategy = ABRStrategyType.quality;
  player.abr.targetBuffer = 20;
  player.abr.bufferLookbackWindow = 30;
  player.abr.maxBufferLength = 30;
}

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>
Property Description Supported Platforms
strategy The adaptive bitrate strategy. Possible values are 'performance', 'quality', 'bandwidth' or a ABRStrategyConfiguration object. Default is bandwidth. Android/Web/iOS*
targetBuffer The amount that the player should buffer ahead of the current playback position, in seconds. Default is 20s. Android/Web/iOS
bufferLookbackWindow The amount of data which the player should keep in its buffer before the current playback position, in seconds. Default is 30s. Web
maxBufferLength The maximum length of the player's buffer, in seconds. Web
preferredPeakBitRate A preferred upper limit on the bandwidth of the video to be downloaded, in bits per second. Defaults to 0, which indicates there is no limit. iOS
preferredMaximumResolution A preferred upper limit on the resolution of the video to be downloaded. (0,0) (the default) removes the cap. Android & iOS

* On native iOS/tvOS, strategy will only work with THEOlive and Millicast streams, and will not have any effect for other types of streams.

When specifying the strategy, apart from the values 'performance', 'quality', 'bandwidth', an ABRStrategyConfiguration object can be set with an estimate for the initial bitrate value (in bits per second):

const strategyConfig: ABRStrategyConfiguration = {
  type: ABRStrategyType.bandwidth,
  metadata: {
    'bitrate': 1200000
  }
}
player.abr.strategy = strategyConfig;

To cap the resolution of the variant the player downloads, set preferredMaximumResolution to a Resolution ({width, height}). Pass (0, 0) to remove the cap.

player.abr.preferredMaximumResolution = { width: 1280, height: 720 };

Setting Target Video Quality

By default, the ABR algorithm will choose, depending on the available bandwidth, from all the video qualities that are available in the manifest or playlist.

It is possible to set a specific quality, or subset of qualities, that should be retained as a source set by passing the uid to the targetVideoQuality property on the THEOplayer API.

const selectedVideoQuality: number | number[] | undefined = [33, 34, 35]
player.targetVideoQuality = selectedVideoQuality;

Subscribing to track events

The onMediaTrackListEvent and onMediaTrackEvent callback properties on THEOplayerView provide a way to perform actions when the track list is modified, or when a track's current quality changes:

Event name Event Supported Platforms
onMediaTrackListEvent when a media track list event occurs, for trackType with value Audio or Video, and event type with values AddTrack, RemoveTrack or ChangeTrack. Android & Web
onMediaTrackEvent when a media track event occurs, for trackType with value Audio or Video, and event type, which currently is only ActiveQualityChanged. Android & Web

Setting a preferred video quality across period switches and discontinuities

Subscribing to the AddTrack event on onMediaTrackListEvent for video tracks makes it possible set a fixed preferred video quality, even when a stream's track list changes due to a DASH period switch or an HLS discontinuity (for example during an ad break).

const onMediaTrackListEvent = (event: MediaTrackListEvent) => {
  const {subType, trackType} = event;
  if (trackType === MediaTrackType.VIDEO && subType === TrackListEventType.ADD_TRACK) {
    const {qualities, activeQuality: currentActiveQuality} = event.track;

    // Try to set a preferreed quality
    const targetQuality = qualities.find(q => q.bandwidth === preferredBandwidth);
    if (targetQuality) {
      const {uid} = targetQuality;
      this.player.targetVideoQuality = uid;
    }
  }
};

const onPlayerReady = (player: THEOplayer) => {
  this.player = player;
  this.player.addEventListener(PlayerEventType.MEDIA_TRACK_LIST, onMediaTrackListEvent)
}

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>