API Reference
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

Adaptation & ABR

Adaptive bitrate streaming configuration and API

AdaptationAPI

Interface

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

adaptationConfig

DynamicAdaptationConfig

the updated configuration

Returns

void

Since: 8.126.0

AdaptationConfig

Interface

Example:

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

Extends

Extended by

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) => 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;
      }
    },
  }
};

Parameters

data

AudioAdaptationData

An object carrying the suggested attribute, holding the suggested representation/quality
ID the player would select

Returns

string

A valid representation/quality ID which the player should use, based on your custom logic (either
data.suggested to switch to the player's suggested quality, or a id) getAvailableAudioQualities to get a list of all available audio qualities

onVideoAdaptation?

optional onVideoAdaptation?: (data) => 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:

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.

Parameters

data

VideoAdaptationData

An object carrying the suggested attribute, holding the suggested representation/quality
ID the player would select

Returns

string

A valid representation/quality ID which the player should use, based on your custom logic (either
data.suggested to switch to the player's suggested quality, or a id) getAvailableVideoQualities to get a list of all available video qualities

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

Enum

Enumeration Members

DOWNLOAD_PREDICTION

DOWNLOAD_PREDICTION: "v3"

Default adaptation logic. It uses a hybrid approach that combines buffer-based rules considering the
buffer fill state and fill rate with a prediction algorithm that estimates the download
time of segments. Downloads that exceed the expected download time may be canceled 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,"

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.

Since: 8.136.0

AdaptationPlatformConfig

Interface

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

Extends

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

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.

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) => 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;
      }
    },
  }
};

Parameters

data

AudioAdaptationData

An object carrying the suggested attribute, holding the suggested representation/quality
ID the player would select

Returns

string

A valid representation/quality ID which the player should use, based on your custom logic (either
data.suggested to switch to the player's suggested quality, or a id) getAvailableAudioQualities to get a list of all available audio qualities

Inherited from

AdaptationConfig.onAudioAdaptation

onVideoAdaptation?

optional onVideoAdaptation?: (data) => 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:

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.

Parameters

data

VideoAdaptationData

An object carrying the suggested attribute, holding the suggested representation/quality
ID the player would select

Returns

string

A valid representation/quality ID which the player should use, based on your custom logic (either
data.suggested to switch to the player's suggested quality, or a id) getAvailableVideoQualities to get a list of all available video qualities

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

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

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

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.

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

Interface

Extends

  • AdaptationData

Properties

isAd

isAd: boolean

Inherited from

AdaptationData.isAd

representations

representations: object[]

bandwidth

bandwidth: number

id

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

Interface

Parts of the AdaptationConfig which can be changed at runtime.

Extended by

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

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.

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

Interface

Extends

  • AdaptationData

Properties

isAd

isAd: boolean

Inherited from

AdaptationData.isAd

representations

representations: object[]

bandwidth

bandwidth: number

id

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

BitrateLimitationConfig

Interface

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

Interface

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

Enum

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.

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?