Network API

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"

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

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: HttpRequestType, request: HttpRequest) => 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);
  }
}

Type declaration

▸ (type, request): Promise<HttpRequest>

Parameters

Returns

Promise<HttpRequest>

preprocessHttpResponse

• Optional preprocessHttpResponse: <T>(type: HttpRequestType, response: HttpResponse<T>) => 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 declaration

▸ <T>(type, response): Promise<HttpResponse<T>>

Type parameters

Parameters

Returns

Promise<HttpResponse<T>>

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: HttpRequestType, response: HttpResponse<T>, retry: number) => 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 declaration

▸ <T>(type, response, retry): Promise<HttpRequest>

Type parameters

Parameters

Returns

Promise<HttpRequest>

sendHttpRequest

• Optional sendHttpRequest: <T>(type: HttpRequestType, request: HttpRequest) => 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() {},
    }
  }
}

Since: 7.7

Type declaration

▸ <T>(type, request): RequestController<T>

Type parameters

Parameters

Returns

RequestController<T>

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

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

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

Properties

done

• done: boolean

value

• Optional value: T

DownloadedData

Interface

Data describing a downloaded segment of a representation.

Hierarchy

• DownloadedData

  ↳ DownloadedAudioData

  ↳ DownloadedVideoData

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.

Hierarchy

• DownloadedData

  ↳ DownloadedAudioData

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.

Hierarchy

• DownloadedData

  ↳ DownloadedVideoData

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[]