API Reference
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

Network API

Network request interception and configuration

HttpHeaders

Interface

Indexable

[fieldName: string]: string

The key of the object is the name of the HTTP header and the value its string content.

HttpRequest

Interface

Properties

body?

optional body?: HttpRequestBody

Request body to send to the server (optional).

credentials

credentials: "omit" | "same-origin" | "include"

The credentials property as used in the fetch API and mapped to the XmlHttpRequest as follows:

'include' ... withCredentials = true
'omit'    ... withCredentials = false

headers

headers: HttpHeaders

Headers of this request

method

method: HttpRequestMethod

HTTP method of the request

responseType

responseType: HttpResponseType

Type we expect the body to be.

url

url: string

URL of the request

HttpRequestBody

Type

HttpRequestBody = ArrayBuffer | ArrayBufferView | Blob | FormData | string | Document | URLSearchParams

Allowed types of the body

HttpRequestMethod

Enum

Allowed HTTP request method

Enumeration Members

GET

GET: "GET"

HEAD

HEAD: "HEAD"

PATCH

PATCH: "PATCH"

POST

POST: "POST"

HttpRequestType

Enum

Values the HttpRequestType property can have in the network API config callbacks.

Enumeration Members

DRM_CERTIFICATE_FAIRPLAY

DRM_CERTIFICATE_FAIRPLAY: "drm/certificate/fairplay"

DRM_LICENSE_CLEARKEY

DRM_LICENSE_CLEARKEY: "drm/license/clearkey"

DRM_LICENSE_FAIRPLAY

DRM_LICENSE_FAIRPLAY: "drm/license/fairplay"

DRM_LICENSE_PLAYREADY

DRM_LICENSE_PLAYREADY: "drm/license/playready"

DRM_LICENSE_PRIMETIME

DRM_LICENSE_PRIMETIME: "drm/license/primetime"

DRM_LICENSE_TVKEY

DRM_LICENSE_TVKEY: "drm/license/tvkey"

DRM_LICENSE_WIDEVINE

DRM_LICENSE_WIDEVINE: "drm/license/widevine"

HLS_INTERSTITIALS_ASSET_LIST

HLS_INTERSTITIALS_ASSET_LIST: "hls/interstitials/asset-list"

KEY_HLS_AES

KEY_HLS_AES: "key/hls/aes"

MANIFEST_ADS

MANIFEST_ADS: "manifest/ads"

MANIFEST_DASH

MANIFEST_DASH: "manifest/dash"

MANIFEST_HLS_MASTER

MANIFEST_HLS_MASTER: "manifest/hls/master"

MANIFEST_HLS_VARIANT

MANIFEST_HLS_VARIANT: "manifest/hls/variant"

MANIFEST_SMOOTH

MANIFEST_SMOOTH: "manifest/smooth"

MANIFEST_STEERING

MANIFEST_STEERING: "manifest/steering"

MEDIA_AUDIO

MEDIA_AUDIO: "media/audio"

MEDIA_SEGMENTINDEX

MEDIA_SEGMENTINDEX: "media/segmentindex"

MEDIA_SUBTITLES

MEDIA_SUBTITLES: "media/subtitles"

MEDIA_THUMBNAILS

MEDIA_THUMBNAILS: "media/thumbnails"

MEDIA_VIDEO

MEDIA_VIDEO: "media/video"

TIME_SYNC

TIME_SYNC: "time/sync"

UNKNOWN

UNKNOWN: "unknown"

WEBRTC_SDP_ANSWER

WEBRTC_SDP_ANSWER: "webrtc/sdp/answer"

WEBRTC_SDP_OFFER

WEBRTC_SDP_OFFER: "webrtc/sdp/offer"

WEBRTC_SDP_REQUEST

WEBRTC_SDP_REQUEST: "webrtc/sdp/request"

HttpResponse

Interface

Type Parameters

ResponseBody

ResponseBody extends HttpResponseBody

Properties

body?

optional body?: ResponseBody

Body of the response with type defined by responseType (optional).

elapsedTime?

optional elapsedTime?: number

The elapsed time in seconds since this request was opened.

headers

headers: HttpHeaders

Headers of the response.

length?

optional length?: number

Amount of bytes of the response body (optional).

request

request: HttpRequest

Corresponding request object of this response

status

status: number

HTTP status code

statusText

statusText: string

Status text provided by the server or default value if not present in response.

timeToFirstByte?

optional timeToFirstByte?: number

The time-to-first-byte for this request in seconds.

url

url: string

URL of the actual request. May differ from url when redirects have happened.

HttpResponseBody

Type

HttpResponseBody = string | ArrayBuffer | Blob | Object | Document | Stream<StreamDataType>

Possible types of body

HttpResponseTiming

Interface

Properties

doneTimestamp?

optional doneTimestamp?: number

The timestamp at which the request was finished.

headersReceivedTimestamp?

optional headersReceivedTimestamp?: number

The timestamp at which the headers where received.

openedTimestamp?

optional openedTimestamp?: number

The timestamp at which the request was opened.

progressTimestamp?

optional progressTimestamp?: number

The timestamp of the current progress event.

sendTimestamp?

optional sendTimestamp?: number

The time at which the request was initially sent.

HttpResponseType

Enum

Enumeration Members

ARRAYBUFFER

ARRAYBUFFER: "arraybuffer"

BLOB

BLOB: "blob"

DOCUMENT

DOCUMENT: "document"

JSON

JSON: "json"

TEXT

TEXT: "text"

NetworkConfig

Interface

The network API gives the ability to influence network requests. It enables preprocessing requests, processing
responses or influencing the retry behavior.

Since

7.4

Properties

defaultRequestTimeout?

optional defaultRequestTimeout?: number

Default timeout for network requests in seconds. Can be overridden for specific request types using the requestTimeout property.

Default: 20

Since: 8.245.0

preprocessHttpRequest?

optional preprocessHttpRequest?: (type, request) => Promise<HttpRequest>

Can be used to change request parameters before a request is made.

This will not be called before a retryHttpRequest.

Example:

network: {
  preprocessHttpRequest: function(type, request) {
    if (type === bitmovin.player.HttpRequestType.DRM_LICENSE_WIDEVINE) {
      // withCredentials = true
      request.credentials = 'include';
      // custom headers
      request.headers['customdata'] = 'AUTHENTICATION-XML';
    } else if (type === bitmovin.player.HttpRequestType.MEDIA_VIDEO ||
      type === bitmovin.player.HttpRequestType.MEDIA_AUDIO) {

      // async call of custom API and add token to media URLs
      return customApiCall.then(function(data) {
        request.url += '?token=' + data.token;
        return request;
      });
    }
    return Promise.resolve(request);
  }
}

Parameters

type

HttpRequestType

String type of the request to be made.

request

HttpRequest

Configuration object of the request.

Returns

Promise<HttpRequest>

The request can be canceled with Promise.reject() or
data can be retrieved asynchronously before processing the request properties.

preprocessHttpResponse?

optional preprocessHttpResponse?: <T>(type, response) => Promise<HttpResponse<T>>

Can be used to the access or change properties of the response before it gets into the player.

Example:

network: {
  preprocessHttpResponse: function(type, response) {
    if (type === bitmovin.player.HttpRequestType.DRM_LICENSE_WIDEVINE) {
      drmHeaders = response.headers;
    }
  }
}

Type Parameters

T

T extends HttpResponseBody

Parameters

type

HttpRequestType

String type of the request to be made.

response

HttpResponse<T>

Contains all important fields of the response.

Returns

Promise<HttpResponse<T>>

The response that shall go back into the player.

requestApi?

optional requestApi?: NetworkRequestApi

Specifies which Browser API should be used to perform network requests.

Default is XHR.

Since: 8.149.0

requestTimeout?

optional requestTimeout?: Partial<Record<HttpRequestType, number>>

Timeout for specific request types in seconds. Overrides the default timeout configured in defaultRequestTimeout for the given request types.

Example:

network: {
  requestTimeout: {
    [HttpRequestType.MANIFEST_DASH]: 10,
    [HttpRequestType.MEDIA_VIDEO]: 5,
    [HttpRequestType.MEDIA_AUDIO]: 5,
  }
}

Since: 8.245.0

retryHttpRequest?

optional retryHttpRequest?: <T>(type, response, retry) => Promise<HttpRequest>

Is called when a request is failed. Will override the default retry behavior.

Example:

network: {
  retryHttpRequest: function(type, response) {
    // delay the retry by 1 second
    return new Promise(function(resolve) {
      setTimeout(function() {
        resolve(response.request);
      }, 1000);
    });
  }
}

Type Parameters

T

T extends HttpResponseBody

Parameters

type

HttpRequestType

String type of the request to be made.

response

HttpResponse<T>

Response of the failed request.

retry

number

Amount of retries

Returns

Promise<HttpRequest>

The request that shall be used on the retry.

sendHttpRequest?

optional sendHttpRequest?: <T>(type, request) => RequestController<T>

Can be used to provide a custom implementation to download requested files.
When null or undefined is returned for a certain request, the default implementation is used.

Example:

network: {
  sendHttpRequest: function(type, request) {
    return {
      getResponse: function() {
        // get data from somewhere else
        var response = {
          request: request,
          url: request.url,
          headers: {},
          status: 200,
          statusText: 'OK',
          body: 'my message',
        }
        return Promise.resolve(response);
      },
      setProgressListener: function() {},
      cancel: function() {},
    }
  }
}

Type Parameters

T

T extends HttpResponseBody

Parameters

type

HttpRequestType

String type of the request to be made.

request

HttpRequest

Configuration object of the request.

Returns

RequestController<T>

The custom implementation of the RequestController.

Since: 7.7

NetworkRequestApi

Enum

Enumeration Members

Fetch

Fetch: "fetch"

Fetch API

If configured, fetch will only be used if the fetch and AbortController APIs are supported by the browser.
Otherwise, the player will fall back to using XHR. Fetch API on MDN

XHR

XHR: "xhr"

XMLHttpRequest API XMLHttpRequest on MDN

RequestController

Interface

This interface can be returned by sendHttpRequest if a custom
network request implementation should be provided. The default implementation of the
player uses XMLHttpRequest.

Type Parameters

T

T extends HttpResponseBody

Methods

cancel()

cancel(): void

Is called by the player if it wants to cancel the current request (e.g. on seek)

Returns

void

getResponse()

getResponse(): Promise<HttpResponse<T>>

Returns a Promise that resolves with the actual HttpResponse in case of a 2xx Success HTTP status code. For all other HTTP status codes, the Promise should reject
with the HttpResponse.

Returns

Promise<HttpResponse<T>>

setProgressListener()

setProgressListener(listener): void

Provides the data transfer progress to the player (if available).

Parameters

listener

(requestProgress) => void

Returns

void

RequestProgress

Interface

Properties

elapsedTime?

optional elapsedTime?: number

loadedBytes

loadedBytes: number

representationBitrate?

optional representationBitrate?: number

responseTiming?

optional responseTiming?: HttpResponseTiming

segmentDuration?

optional segmentDuration?: number

totalBytes?

optional totalBytes?: number

url?

optional url?: string

ResponseStatusMap

Interface

A map of [[HttpRequestType]] to HTTP status codes.
For the included request types, requests will not be retried if they return those codes.

The key must be a string belonging to [[HttpRequestType]]

Since

8.4

Example:

disable_retry_for_response_status: {
  [HttpRequestType.MANIFEST_DASH]: [ 401 ]
}

Indexable

[name: string]: number[]

StreamResponse

Interface

Type Parameters

T

T

Properties

done

done: boolean

value?

optional value?: T

DownloadedData

Interface

Data describing a downloaded segment of a representation.

Extended by

Properties

bitrate

bitrate: number

The bitrate of the representation.

id

id: string

The id of the representation.

isAuto

isAuto: boolean

True if the player’s logic automatically selects the best representation (default),
or false if a fixed representation is currently chosen.

DownloadedAudioData

Interface

Data describing a downloaded audio segment of an audio representation.

Extends

Properties

bitrate

bitrate: number

The bitrate of the representation.

Inherited from

DownloadedData.bitrate

id

id: string

The id of the representation.

Inherited from

DownloadedData.id

isAuto

isAuto: boolean

True if the player’s logic automatically selects the best representation (default),
or false if a fixed representation is currently chosen.

Inherited from

DownloadedData.isAuto

DownloadedVideoData

Interface

Data describing a downloaded video segment of a video representation.

Extends

Properties

bitrate

bitrate: number

The bitrate of the representation.

Inherited from

DownloadedData.bitrate

height

height: number

The height of the video representation.

id

id: string

The id of the representation.

Inherited from

DownloadedData.id

isAuto

isAuto: boolean

True if the player’s logic automatically selects the best representation (default),
or false if a fixed representation is currently chosen.

Inherited from

DownloadedData.isAuto

width

width: number

The width of the video representation.

QueryParameters

Interface

A map of query parameter names to values.

Example:

const query_parameters = {
  name: 'value',
  'another-name': 'another-value',
  // Empty values are allowed
  name3: '',
  // Names without values are also allowed
  name4: null,
}

The resulting query string of the example will be name=value&another-name=another-value&name3=&name4.

Indexable

[name: string]: string

SegmentInfo

Interface

Information about a given segment.

Properties

duration?

optional duration?: number

Duration of the segment.

startTime?

optional startTime?: number

Playback time of the beginning of the segment.

url

url: string

The full URL of the described segment.

SegmentMap

Interface

Maps MIME types to SegmentInfos.

Indexable

[mimeType: string]: SegmentQualityMap

SegmentQualityMap

Interface

Maps audio and video quality IDs (id) to a list of SegmentInfos.

Indexable

[qualityID: string]: SegmentInfo[]

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?