Adaptation & ABR

AdaptationAPI

Exposes the ability to interact with the adaptation logic after the player has been created.

Methods

getConfig

▸ getConfig(): DynamicAdaptationConfig

Returns the current DynamicAdaptationConfig which is a subset of properties of the AdaptationConfig that can be dynamically changed through the Adaptation API.

Returns

DynamicAdaptationConfig

setConfig

▸ setConfig(adaptationConfig): void

Allows updating certain properties of the AdaptationConfig dynamically after player creation.
DynamicAdaptationConfig defines the specific properties of AdaptationConfig that can be updated.

Parameters

Name	Type	Description
`adaptationConfig`	`DynamicAdaptationConfig`	the updated configuration

Returns

void

Since: 8.126.0

AdaptationConfig

Example:

adaptation : {
  desktop: {
    bitrates: {
      minSelectableAudioBitrate: '128kbps',
      maxSelectableAudioBitrate: '320kbps',
      minSelectableVideoBitrate: '900kbps',
      maxSelectableVideoBitrate: Infinity
    }
  },
  mobile: {
    bitrates: {
      minSelectableAudioBitrate: 0,
      maxSelectableAudioBitrate: '256000bps',
      minSelectableVideoBitrate: 0,
      maxSelectableVideoBitrate: '2.5mbps'
    }
  }
}

Hierarchy

DynamicAdaptationConfig

↳ AdaptationConfig

↳↳ AdaptationPlatformConfig

Properties

bitrates

• Optional bitrates: BitrateLimitationConfig

Lower and upper bitrate boundaries to limit qualities.

disableDownloadCancelling

• Optional disableDownloadCancelling: boolean

The player automatically cancels requests if it takes too long and retries in a lower quality (default, false).
This behavior can be disabled by setting this option to true.

exclude

• Optional exclude: boolean

Specifies whether qualities that must not be switched to should be removed when parsing the manifest or
not. Qualities which must not be switched to can be specified by bitrates or resolution.
Default is false.

limitToPlayerSize

• Optional limitToPlayerSize: boolean

Limits the automatically selected quality to the player size, so the player won't select quality
levels with a higher resolution than the video element. This is disabled (false) per default.

Inherited from

DynamicAdaptationConfig.limitToPlayerSize

logic

• Optional logic: AdaptationLogicType

Defines the type/version of adaptation logic to be used.
Default is DOWNLOAD_PREDICTION.

maxStartupBitrate

• Optional maxStartupBitrate: Bitrate

The maximum bitrate the player should start playback with.
Has no effect if startupBitrate is used.

onAudioAdaptation

• Optional onAudioAdaptation: (data: AudioAdaptationData) => string

A callback function to customize the player's adaptation logic that is called before the player tries to download
a new audio segment.

Example:

const conf = {
  ...
  adaptation: {
    desktop: {
      onAudioAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
    mobile: {
      onAudioAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
  }
};
``` [getAvailableAudioQualities](ref:web-sdk-player-api#getavailableaudioqualities) to get a list of all available audio qualities

#### Type declaration

▸ (`data`): `string`

##### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `data` | [`AudioAdaptationData`](ref:web-sdk-adaptation#audioadaptationdata) | An object carrying the <code>suggested</code> attribute, holding the suggested representation/quality ID the player would select |

##### Returns

`string`

---

### onVideoAdaptation

• `Optional` **onVideoAdaptation**: (`data`: [`VideoAdaptationData`](ref:web-sdk-adaptation#videoadaptationdata)) => `string`

A callback function to customize the player's adaptation logic that is called before the player tries to download
a new video segment.

Example:
```js
const conf = {
  ...
  adaptation: {
    desktop: {
      onVideoAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
    mobile: {
      onVideoAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
  }
};

To simply restrict video qualities to the current video player size, use limitToPlayerSize. getAvailableVideoQualities to get a list of all available video qualities

Type declaration

▸ (data): string

Parameters

Name	Type	Description
`data`	`VideoAdaptationData`	An object carrying the `suggested` attribute, holding the suggested representation/quality ID the player would select

Returns

string

preload

• Optional preload: boolean

Specifies whether the player preloads the content (default: true for VOD, false for live streams) or not.

qualityStabilityBalance

• Optional qualityStabilityBalance: number

Defines the balance between quality (i.e. bitrate) and stability in a range of [0, 1].
A value of 0 means that the player will aim to play the best possible quality, potentially at the cost of lower playback stability.
A value of 1 means that the player will aim for the highest stability with the least amount of stalls,
while potentially sacrificing quality.
This is only relevant when using the Low Latency adaptation logic.

Default is 0.5.

Inherited from

DynamicAdaptationConfig.qualityStabilityBalance

resolution

• Optional resolution: VideoSizeLimitationConfig

Lower and upper resolution boundaries. Use 0 for no limitation for minimum selectable width/height and
Infinity for no limitation for maximum selectable width/height.

Inherited from

DynamicAdaptationConfig.resolution

rttEstimationMethod

• Optional rttEstimationMethod: RttEstimationMethod

Defines what method shall be used to estimate the round-trip-time of the network based on the measured RTTs of
previous downloads. Possible values are WeightedAverage and
Median. The Median estimation method may perform better
on low-performance devices. Default value is WeightedAverage. Can only be used with the
'v3' logic.

startupBitrate

• Optional startupBitrate: Bitrate

The bitrate the player should start playback with. If this option doesn’t exist
in the configuration, the player will try to find the best startup bitrate automatically.

AdaptationLogicType

Enumeration Members

DOWNLOAD_PREDICTION

• DOWNLOAD_PREDICTION = "v3"

Default adaptation logic. It uses a hybrid approach that builds on top of the buffer-based rules of
AdaptationLogicType.BUFFER_FILL_RATE and adds a prediction algorithm that estimates the download
time of segments. Downloads that exceed the expected download time, may be cancelled to prevent stalls.

LOW_LATENCY

• LOW_LATENCY = "low-latency-v1"

Adaptation logic tailored to low-latency streaming of chunked CMAF live content.

Should only ever be used in combination with chunked_cmaf_streaming.

WISH

• WISH = "wish"

Based on the paper: M. Nguyen [et al.], "WISH: User-centric Bitrate Adaptation for HTTP Adaptive Streaming on
Mobile Devices,"

https://dx.doi.org/10.1109/MMSP53017.2021.9733605.

WISH employs a Weighted Sum model to achieve high QoE for video streaming, while allowing to express preferences
that allow to trade off data usage, stall events, and video quality.

wish_abr_params

Since: 8.136.0

AdaptationPlatformConfig

Adaptation configurations for different platforms. Most options are not applicable for the native
player technologies due to technical limitations.

Hierarchy

AdaptationConfig

↳ AdaptationPlatformConfig

Properties

bitrates

• Optional bitrates: BitrateLimitationConfig

Lower and upper bitrate boundaries to limit qualities.

Inherited from

AdaptationConfig.bitrates

desktop

• Optional desktop: AdaptationConfig

disableDownloadCancelling

• Optional disableDownloadCancelling: boolean

The player automatically cancels requests if it takes too long and retries in a lower quality (default, false).
This behavior can be disabled by setting this option to true.

Inherited from

AdaptationConfig.disableDownloadCancelling

exclude

• Optional exclude: boolean

Inherited from

AdaptationConfig.exclude

limitToPlayerSize

• Optional limitToPlayerSize: boolean

Limits the automatically selected quality to the player size, so the player won't select quality
levels with a higher resolution than the video element. This is disabled (false) per default.

Inherited from

AdaptationConfig.limitToPlayerSize

logic

• Optional logic: AdaptationLogicType

Defines the type/version of adaptation logic to be used.
Default is DOWNLOAD_PREDICTION.

Inherited from

AdaptationConfig.logic

maxStartupBitrate

• Optional maxStartupBitrate: Bitrate

The maximum bitrate the player should start playback with.
Has no effect if startupBitrate is used.

Inherited from

AdaptationConfig.maxStartupBitrate

mobile

• Optional mobile: AdaptationConfig

onAudioAdaptation

• Optional onAudioAdaptation: (data: AudioAdaptationData) => string

A callback function to customize the player's adaptation logic that is called before the player tries to download
a new audio segment.

Example:

const conf = {
  ...
  adaptation: {
    desktop: {
      onAudioAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
    mobile: {
      onAudioAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
  }
};
``` [getAvailableAudioQualities](ref:web-sdk-player-api#getavailableaudioqualities) to get a list of all available audio qualities

#### Type declaration

▸ (`data`): `string`

##### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `data` | [`AudioAdaptationData`](ref:web-sdk-adaptation#audioadaptationdata) | An object carrying the <code>suggested</code> attribute, holding the suggested representation/quality ID the player would select |

##### Returns

`string`

#### Inherited from

[AdaptationConfig](ref:web-sdk-adaptation#adaptationconfig).[onAudioAdaptation](ref:web-sdk-adaptation#onaudioadaptation)

---

### onVideoAdaptation

• `Optional` **onVideoAdaptation**: (`data`: [`VideoAdaptationData`](ref:web-sdk-adaptation#videoadaptationdata)) => `string`

A callback function to customize the player's adaptation logic that is called before the player tries to download
a new video segment.

Example:
```js
const conf = {
  ...
  adaptation: {
    desktop: {
      onVideoAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
    mobile: {
      onVideoAdaptation: (data) => {
        // Do your custom logic
        return newRepresentationId;
      }
    },
  }
};

To simply restrict video qualities to the current video player size, use limitToPlayerSize. getAvailableVideoQualities to get a list of all available video qualities

Type declaration

▸ (data): string

Parameters

Name	Type	Description
`data`	`VideoAdaptationData`	An object carrying the `suggested` attribute, holding the suggested representation/quality ID the player would select

Returns

string

Inherited from

AdaptationConfig.onVideoAdaptation

preload

• Optional preload: boolean

Specifies whether the player preloads the content (default: true for VOD, false for live streams) or not.

Inherited from

AdaptationConfig.preload

qualityStabilityBalance

• Optional qualityStabilityBalance: number

Default is 0.5.

Inherited from

AdaptationConfig.qualityStabilityBalance

resolution

• Optional resolution: VideoSizeLimitationConfig

Lower and upper resolution boundaries. Use 0 for no limitation for minimum selectable width/height and
Infinity for no limitation for maximum selectable width/height.

Inherited from

AdaptationConfig.resolution

rttEstimationMethod

• Optional rttEstimationMethod: RttEstimationMethod

Inherited from

AdaptationConfig.rttEstimationMethod

startupBitrate

• Optional startupBitrate: Bitrate

The bitrate the player should start playback with. If this option doesn’t exist
in the configuration, the player will try to find the best startup bitrate automatically.

Inherited from

AdaptationConfig.startupBitrate

AudioAdaptationData

Hierarchy

AdaptationData

↳ AudioAdaptationData

Properties

isAd

• isAd: boolean

Inherited from

AdaptationData.isAd

representations

• representations: { bandwidth: number ; id: string }[]

Inherited from

AdaptationData.representations

suggested

• suggested: string

The ID of the representation that the player selected, which is the same ID as returned through the
AudioQuality and VideoQuality objects from getAvailableAudioQualities and
getAvailableVideoQualities.

Inherited from

AdaptationData.suggested

DynamicAdaptationConfig

Parts of the AdaptationConfig which can be changed at runtime.

Hierarchy

DynamicAdaptationConfig

↳ AdaptationConfig

Properties

limitToPlayerSize

• Optional limitToPlayerSize: boolean

Limits the automatically selected quality to the player size, so the player won't select quality
levels with a higher resolution than the video element. This is disabled (false) per default.

qualityStabilityBalance

• Optional qualityStabilityBalance: number

Default is 0.5.

resolution

• Optional resolution: VideoSizeLimitationConfig

Lower and upper resolution boundaries. Use 0 for no limitation for minimum selectable width/height and
Infinity for no limitation for maximum selectable width/height.

VideoAdaptationData

Hierarchy

AdaptationData

↳ VideoAdaptationData

Properties

isAd

• isAd: boolean

Inherited from

AdaptationData.isAd

representations

• representations: { bandwidth: number ; id: string }[]

Inherited from

AdaptationData.representations

suggested

• suggested: string

Inherited from

AdaptationData.suggested

BitrateLimitationConfig

Properties

maxSelectableAudioBitrate

• Optional maxSelectableAudioBitrate: Bitrate

Upper bitrate boundary for audio qualities. All qualities above this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the exclude
flag is set to true.

If the audio quality with the lowest bitrate is higher than this value, that quality will still be allowed
for selection.

Can be set to Infinity for no limitation.

maxSelectableVideoBitrate

• Optional maxSelectableVideoBitrate: Bitrate

Upper bitrate boundary for video qualities. All qualities above this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the exclude
flag is set to true.

If the video quality with the lowest bitrate is higher than this value, that quality will still be allowed
for selection.

Can be set to Infinity for no limitation.

minSelectableAudioBitrate

• Optional minSelectableAudioBitrate: Bitrate

Lower bitrate boundary for audio qualities. All qualities below this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the exclude
flag is set to true.

If the audio quality with the highest bitrate is lower than this value, that quality will still be allowed
for selection.

Can be set to 0 for no limitation.

minSelectableVideoBitrate

• Optional minSelectableVideoBitrate: Bitrate

Lower bitrate boundaries for video qualities. All qualities below this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the exclude
flag is set to true.

If the video quality with the highest bitrate is lower than this value, that quality will still be allowed
for selection.

Can be set to 0 for no limitation.

VideoSizeLimitationConfig

Properties

maxSelectableVideoHeight

• Optional maxSelectableVideoHeight: number

Upper video height boundary for video qualities. All qualities above this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the
exclude flag is set to true.

If the video quality with the lowest video height is higher than this value, that quality will still be allowed
for selection.

Can be set to 0 for no limitation.

maxSelectableVideoWidth

• Optional maxSelectableVideoWidth: number

Upper video width boundary for video qualities. All qualities above this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the
exclude flag is set to true.

If the video quality with the lowest video width is higher than this value, that quality will still be allowed
for selection.

Can be set to 0 for no limitation.

minSelectableVideoHeight

• Optional minSelectableVideoHeight: number

Lower video height boundary for video qualities. All qualities below this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the
exclude flag is set to true.

If the video quality with the highest video height is lower than this value, that quality will still be allowed
for selection.

Can be set to 0 for no limitation.

minSelectableVideoWidth

• Optional minSelectableVideoWidth: number

Lower video width boundary for video qualities. All qualities below this threshold will not be selected by
the ABR logic. These qualities are still available for manual quality selection unless the
exclude flag is set to true.

If the video quality with the highest video width is lower than this value, that quality will still be allowed
for selection.

Can be set to 0 for no limitation.

RttEstimationMethod

Enumeration Members

Median

• Median = "median"

Uses the median of the round-trip-times measured for the previous downloads. May perform better
on low-performant devices.

WeightedAverage

• WeightedAverage = "weightedaverage"

Uses the weighted average of the round-trip-times measured for the previous downloads, with newest
samples having the highest weights.