Player Configuration

This page shows how the Bitmovin player can be configured. Additionally, the Bitmovin player offers a JavaScript API, which we describe in our API section.

This page refers to version 7 and above of the Bitmovin Adaptive Streaming Player.

Setup

Just use the link to the CDN hosted player as provided in your Bitmovin Account to include the bitmovin player in your web page:

<script src="//bitmovin-a.akamaihd.net/bitmovin-player/stable/7/bitmovinplayer.js"></script>

The next step is to add and setup the player. Just pass the unique id of an HTML container element (like div) to bitmovin.player:

var player = bitmovin.player('player-wrapper');
player.setup(config);

If you are using module loaders, like systemjs, the player object is directly exported:

var bitmovinPlayer = require('...');
var player = bitmovinPlayer('player-wrapper');
player.setup(config);

player-wrapper is an example for any page-wide unique ID of an HTML element, usually a div element or another container, where the player will be inserted.

config is a JSON object holding the configuration for the player and will be explained in the following.

All entries are case sensitive and most are optional. Mandatory objects or attributes are labelled as such.

The config object can have the properties listed below. While key is a string, all others are objects.

Key

Mandatory. A personal key can be found in the bitmovin portal and should be specified here as string. Do not forget to enter all your domains (subdomains are included) in your account.

player-domains

Source

Contains information to the video source, e.g. dash, hls, progressive fallback.

dash – The URL to the MPEG-DASH manifest file (MPD, Media Presentation Description) for the video to play. The file has to be a valid MPD. MPEG-DASH content can easily and for free be generated using our encoding solution bitcodin.

hls – An URL to an HLS playlist file (M3U8). The file has to be a valid M3U8 playlist. HLS content can easily and for free be generated using our encoding solution bitcodin.

progressive – An Array of objects to video files, used for progressive download as fallback. Is only used when all other methods fail. Multiple progressive files can be used, e.g. .mp4 and .webm files to support as many browsers as possible.
Each object in the array should have two parameters:

  • url – The URL to the progressive video file
  • type – The MIME type of the video file, e.g. “video/mp4” or “video/webm”
  • bitrate – Can be used to specify which bitrate the a progressive source has. Providing multiple progressive sources with different bitrates allows the users to manually select qualities. Please note that no automatic quality switching will happen.
  • preferred – Sets the source/quality which the player will use per default. Should be set to true at only one object within the progressive array. If no element has set this attribute to true, the first object in the array will be used per default.
  • label – Specifies the label to be displayed in the quality selection in the player’s settings window.

poster – The URL to a preview image displayed until the video starts. Make sure JavaScript and Flash are allowed to access it, i.e. CORS (for the HTML5/JavaScript player) must be enabled and a crossdomain.xml has to be there if it’s not the same server as the website.

drm – The DRM object should be included into the source object. All options are available as documented in the DRM section.

title – A title of the video to be displayed in the player UI.

description – A description of the video to be displayed in the player UI.

options – An object specifying advanced source specific options.

  • manifestWithCredentials – Send credentials and cookies along with cross origin manifest (HLS and MPEG-DASH) requests. Must be supported by the server. Default is false.
  • withCredentials – Send credentials and cookies along with cross origin (HLS and MPEG-DASH) segment requests. Must be supported by the server. Default is false.
  • hlsManifestWithCredentials – Send credentials and cookies along with cross origin HLS manifest requests. Must be supported by the server. Default is false.
  • hlsWithCredentials – Send credentials and cookies along with cross origin HLS segment requests. Must be supported by the server. Default is false.
  • dashManifestWithCredentials – Send credentials and cookies along with cross origin MPEG-DASH manifest requests. Must be supported by the server. Default is false.
  • dashWithCredentials – Send credentials and cookies along with cross origin MPEG-DASH segment requests. Must be supported by the server. Default is false.
  • persistentPoster – If set to true, this will keep the poster image visible during playback, e.g. for audio-only streams.
  • startTime [new in v7.1] – Specify the time (in seconds) where the player should start the initial playback.

tracks – An array of objects with timed data.

  • file: The URL to the timed text file, i.e. WebVTT file
  • kind: The type of timed data. At the moment, “thumbnails” is the only supported kind

labeling – An object with callback functions to provide labels for audio tracks, qualities and subtitle tracks. The return value of a callback function should be string, which will be used as label.

labeling.dash – An object containing all callback labeling functions for DASH streams:

  • tracks: function(track) where the track object is { mimeType: string, lang: string }
  • qualities: function(quality) where the quality object is { id: string, mimeType: string, bitrate: number, qualityRanking: string, width: number, height: number, frameRate: number }
  • subtitles: function(subtitle) where the subtitle object is { id: string, kind: string (‘caption’|’subtitle’), lang: string, label: string }

labeling.hls – An object containing all callback labeling functions for HLS streams:

  • tracks: function(track) where the track object is { mimeType: string, lang: string }
  • qualities: function(quality) where the quality object is { id: string, mimeType: string, bitrate: number, width: number, height: number }
  • subtitles: function(subtitle) where the subtitle object is { id: string, kind: string (‘caption’|’subtitle’), lang: string, label: string }

Example:

source : {
  dash        : 'http://path/to/mpd/file.mpd',
  hls         : 'http://path/to/hls/playlist/file.m3u8',
  progressive : [{
    url: 'http://path/to/mp4',
    type: 'video/mp4',
    bitrate: 500000,
    label: 'Low'
  }, {
    url: 'http://path/to/another-mp4',
    type: 'video/mp4',
    bitrate: 1000000,
    label: 'Mid'
    preferred: true
  }, {
    url: 'http://path/to/another-mp4',
    type: 'video/mp4',
    bitrate: 2500000,
    label: 'High'
  }],
  poster      : 'images/poster.jpg',
  tracks      : [{
    file: 'http://path/to/thumbnail/vtt/file.vtt',
    kind: 'thumbnails'
  }],
  drm         : {
    widevine : {
      LA_URL: 'https://mywidevine.licenseserver.com/'
    },
    playready : {
      LA_URL : 'https://myplayready.licenseserver.com/'
    }
  },
  labeling: {
      hls: {
          qualities: function(quality) {
              return quality.height + 'p';
          }
      },
      dash: {
          qualities: function(quality) {
              return quality.height + 'p';
          }
      }
  }
}

DRM

The drm object should be included into the source object.

Only the options which are really used should be included.

Widevine Modular

Widevine Modular is supported in Chrome and Chromium-based browsers with Widevine CDM (e.g. Opera 15+).

An object itself, with the following parameters:

LA_URL – An URL to the Widevine license server for this content (mandatory for widevine).

withCredentials – Set to true to send credentials such as cookies or authorization headers along with the license requests. Default is false.

maxLicenseRequestRetries – Specifies how often a license request should be retried if was not successful (e.g. the license server was not reachable). Default is 1. 0 disables retries.

licenseRequestRetryDelay – Specifies how long in milliseconds should be waited before a license request should be retried.

headers – An array of objects which specify custom HTTP headers (optional). Each object should have two attributes:

  • name – The name of the HTTP header
  • value – The value of the HTTP header

BuyDRM/KeyOS Specific Example:

headers : [{
  name: 'customdata',
  value: 'AUTHENTICATION-XML'
}]

DRMtoday by castLabs Specific Example:

headers : [{
  name: 'dt-custom-data',
  value: 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA'
}]

prepareLicense – A function which gets the widevine license from the server. Is needed for custom widevine servers where not only the license itself is responded, but instead the license is e.g. wrapped in an JSON object.

DRMtoday by castLabs Specific Example:

prepareLicense : function(licenseObj) {
  var license = {license: licenseObj.license};
 
  try {
    var drmTodayObj = JSON.parse(String.fromCharCode.apply(null, licenseObj.license));
    if (drmTodayObj && drmTodayObj.status && drmTodayObj.license) {
      if (drmTodayObj.status === 'OK') {
        var str = window.atob(drmTodayObj.license);
        var bufView = new Uint8Array(new ArrayBuffer(str.length));
        for (var i = 0; i < str.length; i++) {
          bufView[i] = str.charCodeAt(i);
        }
        license.license = bufView;
      } else {
        // license not okay
      }
    } else {
      // no valid DRMtoday license
    }
  } catch (e) {
    // no valid DRMtoday license
  }
  return license;
};

prepareMessage – A function to prepare the license acquisition message which will be sent to the license acquisition server. As many DRM provider expect different, vendor-specific message, this can be done using this user-defined function (optional / depending on the DRM server). The parameter is the key message event object as given by the Widevine Content Decryption Module (CDM).

Default Implementation Example:

prepareMessage : function (keyMessage) {
  return keyMessage.message;
}

This will send just the actual key message as provided by the CDM to the license server.

Vualto Specific Example:

prepareMessage : function (keyMessage) {
  return JSON.stringify({
    token: VUALTO_TOKEN,
    drm_info: Array.apply(null, new Uint8Array(keyMessage.message)),
    kid: 'VUALTO_KID'
  });
}

This will send a JSON object to the license server. This object contains the Vualto-specific token (token), a pre-processed key message (drm_info), and the key ID (kid).

mediaKeySystemConfig – An object which allows to specify configuration options of the DRM key system, such as distinctiveIdentifier or persistentState (refer to MediaKeySystemConfiguration for more details). Please note that these settings need to be supported by the browser or playback will fail.

PlayReady

Microsoft PlayReady is supported in Edge and Internet Explorer 11 on Windows 8.1+.

LA_URL – An URL to the PlayReady license server for this content (optional).

withCredentials – Set to true to send credentials such as cookies or authorization headers along with the license requests. Default is false.

maxLicenseRequestRetries – Specifies how often a license request should be retried if was not successful (e.g. the license server was not reachable). Default is 1. 0 disables retries.

licenseRequestRetryDelay – Specifies how long in milliseconds should be waited before a license request should be retried.

headers – An array of objects which specify custom HTTP headers (optional). Each object should have two attributes:

  • name – The name of the HTTP header
  • value – The value of the HTTP header

DRMtoday by castLabs Specific Example:

headers : [
  {
    name: 'http-header-CustomData',
    value: 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA'
  }
]

Access

Adobe Access DRM is supported in the Flash fallback only.

LA_URL – The URL to the Adobe Access license server for this content. The URL should already include all necessary GET parameters.

authToken – The token required to authenticate on the Access license server.

PrimeTime

Adobe PrimeTime DRM is supported in Firefox 42+ on Windows only.

LA_URL – The URL to the Adobe PrimeTime license server for this content.

indivURL – The URL for individualization requests.

withCredentials – Set to true to send credentials such as cookies or authorization headers along with the license requests. Default is false.

headers – An array of objects which specify custom HTTP headers (optional). Each object should have two attributes:

  • name – The name of the HTTP header
  • value – The value of the HTTP header

mediaKeySystemConfig – An object which allows to specify configuration options of the DRM key system, such as distinctiveIdentifier or persistentState (refer to MediaKeySystemConfiguration for more details). Please note that these settings need to be supported by the browser or playback will fail.

Fairplay

Apple Fairplay DRM is supported in Safari on Mac OS X only.

LA_URL – The URL to the Fairplay license server for this content.

certificateURL – The URL to the Fairplay certificate of the license server.

headers – An array of objects which specify custom HTTP headers for the license request (optional). Each object should have two attributes:

  • name – The name of the HTTP header
  • value – The value of the HTTP header

certificateHeaders – An array of objects which specify custom HTTP headers for the certificate request (optional). Each object should have two attributes:

  • name – The name of the HTTP header
  • value – The value of the HTTP header

prepareMessage – A function to prepare the license acquisition message which will be sent to the license acquisition server (optional). As many DRM providers expect different, vendor-specific messages, this can be done using this user-defined function. The first parameter is the key message event object as given by the Fairplay Content Decryption Module (CDM), enhanced by the messageBase64Encoded attribute, which contains the key message encoded as base64 encoded string. The second parameter is the ssion object, enhanced by a contentId attribute.

prepareContentId – A function to prepare the contentId, which is sent to the Fairplay license server as request body (optional). As many DRM providers expect different, vendor-specific messages, this can be done using this user-defined function. The parameter is the URI extracted from the HLS manifset (m3u8) and the return value should be the contentID as string.

withCredentials – Set to true to send credentials such as cookies or authorization headers along with the license requests. Default is false.

prepareCertificate – A function to prepare the certificate before passing it into the browser. This is needed if the server response with anything else than the certificate, e.g. if the certificate is wrapped into a JSON object. The server response is passed as parameter “as is” and the return type is expected to be an ArrayBuffer.

prepareLicense – A function to prepare the license before passing it into the browser. This is needed if the server response with anything else than the license, e.g. if the license is wrapped into a JSON object. The server response is passed as parameter “as is” and the return type is expected to be a Base64-encoded string.

prepareLicenseAsync – Similar to prepareLicense, this callback can be used to prepare the license before passing it to the browser, but the license can be processed asynchronously. Please note that this function must return a promise and the parameter for the resolve function needs to be the Uint8Array, which is passed “as is” to the browser. Using this function prevents prepareLicense from being called.

useUint16InitData – A boolean flag to change between Uint8Array (default, value false) and Uint16Array initialization data. Depends on the fairplay license server, most use Uint8Array but e.g. EZDRM requires Uint16Array.

licenseResponseType – Sets an explicit response type for the license request. Default response type for this request is “text“, e.g. EZDRM requires “blob

getLicenseServerUrl – A callback function which gets the URI (without the “skd:” part) from the HLS manifest passed as parameter. The function needs to return a string which is used as LA_URL “as is”.

EZDRM Specific Example:

fairplay: {
  LA_URL: 'http://fps.ezdrm.com/api/licenses/YOUR-CONTENT-ID',
  certificateURL: 'YOUR-CERTIFICATE',
  prepareContentId: function(contentId) {
    var uri = contentId;
    var uriParts = uri.split('://', 1);
    var protocol = uriParts[0].slice(-3);
    uriParts = uri.split(';', 2);
    contentId = uriParts.length>1?uriParts[1]:'';
    return protocol.toLowerCase()=='skd'?contentId:'';
  },
  prepareLicenseAsync: function(ckc) {
    return new Promise(function(resolve, reject) {
      var reader = new FileReader();
      reader.addEventListener('loadend', function() {
        var array = new Uint8Array(reader.result);
        resolve(array);
      });
      reader.addEventListener('error', function() {
        reject(reader.error);
      });
      reader.readAsArrayBuffer(ckc);
    });
  },
  prepareMessage: function(event, session) {
    return new Blob([event.message], {type: 'application/octet-binary'});
  },
  headers: [{
    name: 'content-type',
    value: 'application/octet-stream'
  }],
  useUint16InitData: true,
  licenseResponseType: 'blob'
}

DRMtoday by castLabs Specific Example:

fairplay: {
  LA_URL: 'https://license-server-url-provided-by-drmtoday',
  certificateURL: 'https://certificate-url-provided-by-drmtoday',
  headers: [{
    name: 'dt-custom-data',
    value: 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA'
  }],
  prepareMessage : function(event, session) {
    return 'spc=' + encodeURIComponent(event.messageBase64Encoded) + '&' + session.contentId;
  },
  prepareContentId : function(contentId) {
    var pattern='skd://drmtoday?';
    var parameters;
    var idx;
 
    idx = contentId.indexOf(pattern);
    if (idx > -1) {
      parameters = contentId.substring(idx + pattern.length);
      parameters = parameters.replace(/assetid/gi, 'assetId');
      parameters = parameters.replace(/variantid/gi, 'variantId');
      return parameters;
    } else {
      return '';
    }
  }
}

Vualto Specific Example (requires Bitmovin Player 6.0+):

fairplay: {
  LA_URL: 'http://fairplay-license.drm.technology/license',
  certificateURL: 'http://fairplay-license.drm.technology/certificate',
  certificateHeaders: [{
    name: 'x-vudrm-token',
    value: arrayParams['token']
  }],
  headers: [{
    name: 'Content-Type',
    value: 'application/json'
  }],
  prepareMessage: function (keyMessageEvent, keySession) {
    return JSON.stringify({
      token: 'VUALTO_TOKEN',
      contentId: keySession.contentId,
      payload: keyMessageEvent.messageBase64Encoded
    });
  },
  prepareContentId: function(rawContentId) {
    var tmp = rawContentId.split('/');
    return tmp[tmp.length - 1];
  },
  prepareCertificate: function(cert) {
    return new Uint8Array(cert);
  },
  prepareLicense: function(license) {
    return new Uint8Array(license);
  },
  licenseResponseType: 'arraybuffer'
}

Clear Key

If no Hollywood-grade DRM is required, clear key can be an alternative. The player supports MPEG-CENC (Common Encryption) compatible AES-128 CTR encryption.

keys – An array of objects with kid (key ID (optional*)) and key, both in hex string format.

clearkey: {
  keys: [{
    kid: 'eb676abbcb345e96bbcf616630f1a3da',
    key: '100b6c20940f779a4589152b57d2dacb'
  }, {
    kid: 'fc787bccdb345e96bbcf61674102b4eb',
    key: '211c7d30940f779a4589152c68a1cfba'
  }]
}

* kid – this value is optional, if the same kid has been used for the whole content (every audio and video track of each representation). Otherwise, the player won’t know, which kid has to be used.

Playback

autoplay – Whether the player starts playing after setup or not. Can be true or false (default). Note that autoplay does not work on mobile devices and the bitmovin player therefore disables it automatically on these devices!

muted – Whether the sound is muted on startup or not. Can be true or false (default).

audioLanguage – Defines one (as string) or more (as array of strings) audio languages which should be used in the specified order on start up.

subtitleLanguage – Defines one (as string) or more (as array of strings) subtitle languages which should be used in the specified order on start up.

restoreUserSettings – Disables the save & restore behavior of user settings like volume, muted, selected language etc. if set to false. Default is false.

timeShift – Enables time shift / DVR for live streams. Default is true (enabled). If time shift is disabled (set to false), the timeline (scrub bar) will not be shown any more.

playsInline – Sets the playsinline/webkit-playsinline attribute on the video element if set to true. Can be used to prevent videos on iOS 10 to go into native fullscreen automatically when playback starts.

preferredTech – An array of objects to specify the player and streaming technology order to use. If the first is supported, this technologies are used. If not, the second is tried etc.
Player technologies:

  • html5 refers to the MediaSource Extension (MSE) based JavaScript player.
  • flash refers to the Flash fallback.
  • native refers to the browser’s native capabilities are being used, e.g. playing back HLS in Safari on iOS.

Currently supported combinations:

{ player: 'html5', streaming: 'dash'}
{ player: 'html5', streaming: 'hls'}
{ player: 'native', streaming: 'hls'}
{ player: 'flash', streaming: 'dash'}
{ player: 'flash', streaming: 'hls'}
{ player: 'native', streaming: 'progressive'}

Example:

preferredTech : [
  {
    player: 'html5',
    streaming: 'dash'
  }, {
    player: 'flash',
    streaming: 'hls'
  }
]

Playback Example:

playback : {
  autoplay         : false,
  muted            : false,
  audioLanguage    : ['en', 'es', 'de'],
  subtitleLanguage : 'en',
  preferredTech    : [{
    player: 'html5',
    streaming: 'dash'
  }, {
    player: 'flash',
    streaming: 'hls'
  }]
}

Style

width – The width of the player. Can have any value including the unit (e.g. px, %, em, vw) usable in CSS, e.g. 500px or 90%. Not more than two options of width, height, and aspect ratio should be given. Defaults to 100%.

height – The height of the player. Can have any value including the unit (e.g. px, %, em, vh) usable in CSS, e.g. 500px or 90%. Not more than two options of width, height, and aspect ratio should be given. If no height is given, it is calculated in respect of the width in a way that a 16:9 aspect ratio is given (default).

aspectratio – The aspect ratio of the player, e.g. 16:9, 16:10, 4:3. Not more than two options of width, height, and aspect ratio should be given. Defaults to 16:9.

ux – Can be used to disable the built-in UI. Default is true.

Style Example:

style : {
  width       : '100%',
  aspectratio : '16:9',
  ux          : false
}

Events

Is an object itself and enables to register callback functions for events. The this keyword will be set to the player object so that it is possible to directly call other API methods on it.

See the section JavaScript Documentation for a complete list of available events. All events can also be registered after setup, except for onReady and onError. onReady is fired when setup is complete and the player is ready to receive API calls and to play. onError is fired if something goes wrong during player setup or during playback. Therefore, if these events are registered after setup, they will never be fired.

Example:

events : {
  onReady : function(data) {
              console.log('version: ' + this.getVersion() + ', onReady Event data: ', data);
            },
  onPlay  : function(data) {
              // do awesome stuff
            },
  onError : function(data) {
              console.error('An error occurred:', data);
            }
}

Tweaks

Use these values only if you know what you are doing.

autoqualityswitching – Determines if the automatic quality switching is enabled on startup. Can be true (default) or false.

max_buffer_level – Changes the maximum buffer level in seconds. Default is 20 seconds.

search_real_end – If set to true, the mediaPresentationDuration (the total duration of the video) in the MPD is ignored and the video is played until no more segments are available. This enables playback of MPDs with a wrong mediaPresentationDuration. Default is false.

wmode – Set the wmode of the flash object if the flash fallback is used. Valid values are the strings direct, window, opaque, transparent (default), and gpu. Please refer to Flash OBJECT and EMBED tag attributes for more information.

hwdecoding – Enable/Disable hardware-supported video decoding. Enabling this might lead to decoding artefacts, but can improve performance. Default is false.

prevent_mpd_caching – DASH in Flash adds a timestamp as URL parameter to each MPD request to prevent caching, especially for MPD updates. This setting enables/disables the parameter. Default is true (timestamp is added).

query_parameters – Query parameters are added as GET parameters to all request URLs (e.g. manifest, media segments, subtitle files, …). Query_parameters should be an object with key value pairs, where the keys are used as parameter name and the values as parameter values. Please note that this does not work for Safari’s native HLS playback!
The example below would be translated into MY_REQUEST_URL?key1=value1&key2=value2&mycustomname=another-value:

query_parameters : {
  key1: 'value1',
  key2: 'value2',
  mycustomname: 'another-value'
}

Example:

tweaks : {
  autoqualityswitching : true,
  max_buffer_level     : 20,
  search_real_end      : false,
  query_parameters : {
    key1: 'value1',
    key2: 'value2',
    mycustomname: 'another-value'
  }
}

Skin

With the release of player version 7, we introduced an open-source user interface, based on TypeScript. It can be customized easily, as also shown in the according tutorial. For more detailed information on all available components, please have a look at our CSS class reference documentation.

Cast

enable – ChromeCast support is disabled per default. To enable it, set this attribute to true. Default is false.

application_id – The ChromeCast application ID retrieved from Google when a Cast receiver app is registered. To use ChromeCast with player version 6 an higher, it is not necessary to use this option. For versions pre v6, please use ‘121122A0’, or your dedicated ID, in case you want to use a custom ChromeCast receiver app.

message_namespace – A custom message namespace as defined in the Cast receiver app. To use ChromeCast, it is not necessary to use this option! This is only needed if one wants to create a custom ChromeCast receiver app.

receiverStylesheetUrl [new in v7.1] – A URL to a CSS file the Chromecast receiver app loads. Can be used to style the Chromecast receiver app.

Example:

cast : {
  enable                 : true,
  application_id         : 'A12B45C6',
  message_namespace      : 'urn:x-cast:my.custom.chromecast.namespace'
}

Adaptation

The adaptation logic can be influenced by this parameter. Lower and upper bitrate boundaries can be set for desktop and mobile separately. Only representations between minSelectableVideoBitrate (or minSelectableAudioBitrate) and maxSelectableVideoBitrate (or maxSelectableAudioBitrate) are chosen except there are no matching representations.

Values should be string with one of the following units:

  • mbps (megabits per second)
  • kbps (kilobits per second)
  • bps (bits per second)

Only the values 0 (no limitation for lower boundaries) and Infinity (no limitation for upper boundaries) are not required to be strings.

limitToPlayerSize – Limits the automatically selected quality to the player size, so the player won’t select quality levels with a higher resolution than itself has. Default value is false (disabled).

startupBitrate – The bitrate in bits per second (bps) 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.

maxStartupBitrate – The maximum bitrate in bits per second (bps) the player should start playback with. Has no effect if startupBitrate is used.

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

onVideoAdaptation – A callback function which is called before the player tries to download a new video segment. The function which is called with an object as parameter, which contains the suggested attribute. This holds the suggested representation/quality ID the player would select. The return value needs to be a valid representation/quality ID (as string), which the player should use, based on your custom logic.

var conf = {
  ...
  adaptation: {
    desktop: {
      onVideoAdaptation: function(param) {
        // Do your custom logic
        return newRepresentationId;
      }
    },
    mobile: {
      onVideoAdaptation: function(param) {
        // Do your custom logic
        return newRepresentationId;
      }
    },
  }
};

onAudioAdaptation – A callback function which is called before the player tries to download a new audio segment. The function which is called with an object as parameter, which contains the suggested attribute. This holds the suggested representation/quality ID the player would select. The return value needs to be a valid representation/quality ID (as string), which the player should use, based on your custom logic.

var conf = {
  ...
  adaptation: {
    desktop: {
      onAudioAdaptation: function(param) {
        // Do your custom logic
        return newRepresentationId;
      }
    },
    mobile: {
      onAudioAdaptation: function(param) {
        // Do your custom logic
        return newRepresentationId;
      }
    },
  }
};

Example:

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

Advertising – VAST, VPAID and IMA

Allows you to define which ads you want to display and when you want to display them. In order to play ads on your website, you need to specify an ad config.

client – Mandatory. Specifies which ad client to use, like e.g., VAST (‘vast’), VPAID (‘vpaid’) or Google IMA (‘ima’).

adCallOffset – Specifies the time in seconds, how much the VAST tag is loaded prior to the ad playback. By default the VAST tag is loaded at player startup.

onAdManifestLoaded – A callback function which is called when an ad manifest has been successfully loaded. The callback function may modify the ad manifest and return it. Callback parameters:

  • manifest: The parsed VAST manifest.

admessage – Defines a custom message that will be displayed to the user instead of the progress bar during ad playback. The predefined placeholders {remainingTime}, {playedTime} and {adDuration} can be used to show the remaining seconds, current time, and duration of the ad, respectively.

skipmessage – Defines a custom message that will be displayed to the user as a skip button. Skipmessage is an object with the following properties:

  • countdown – The message shown before the ad is skippable. The placeholder {remainingTime} can be used to show the remaining seconds before the ad can be skipped.
  • skip – The message shown after the countdown, when the ad can be skipped.

withCredentials – Specifies that cookies are send along with the ad request. The server needs to explicitly accept them for CORS requests, otherwise the request will fail.

tag – Defines the path to the ad manifest.

offset – Defines when the ad shall be played. Allowed values are:

  • ‘pre’: plays a pre-roll ad
  • ‘post’: plays a post-roll ad
  • fractional seconds: ’10’, ‘12.5’
  • percentage of the entire video duration: ‘25%’, ‘50%’
  • timecode [hh:mm:ss.mmm]: ’00:10:30.000’, ‘01:00:00.000’

schedule – Contains one or more ad breaks. Each ad break defines when an ad shall be played and must contain an offset and a tag property.

allowSeekingOverMidRollAds [new in v7.1] – If set to true, mid roll ads are only played during normal playback. Seeking to a time after the mid roll ads doesn’t trigger the ad playback.

Note: if the advertising object has the tag property, the specified ad will always be played as a pre-roll ad, even if an offset property is specified.

Example configurations

Simplest possible configuration to play a single pre-roll ad.

advertising: {
  client          : 'vast',
  tag             : 'http://your.ad.provider/manifest.xml'
}

Play a pre-roll and a mid-roll ad after 50% of the playback, and display This ad will end in xx seconds to the viewer:

advertising: {
  admessage: 'This ad will end in xx seconds',
  skipmessage: {
    countdown: 'Skip in xx seconds...',
    skip: 'SKIP'
  },
  schedule: {
    'pre-roll-ad': {
      client: 'vast',
      offset: 'pre',
      tag: 'http://your.ad.provider/pre-roll-ad-manifest.xml'
    },
    'mid-roll-ad': {
      client: 'vpaid',
      offset: '50%',
      tag: 'http://your.ad.provider/mid-roll-ad-manifest.xml'
    }
  }
}

VR and 360 Video

The player can be used to playback VR and omnidirectional (360°) video. The related settings can be set in a dedicated vr-section in the source part of the configuration object. Navigation can be performed via drag gestures with the mouse/finger, or the keyboard using W, A, S, and D. Also rotation based navigation is possible on devices with appropriate sensors in place.
For the use of VR devices like the Oculus, head tracking can be used as well, if supported in the browser (e.g. in FireFox Nightly with VR plugin).

The player needs to know the type of the VR/360 video, i.e. if it’s a single equirectangular video for 2D or two equirectangular videos for 3D content. In case of 3D content, there are two supported video types: top-and-bottom and side-by-side, which specify the position of the two videos.

Per default, the player shows the VR/360 video in non-stereo mode. The initial setting can be changed in the vr config using the “stereo” option or via the API using the setVRStereo(…) call. Further, a user can toggle stereo and non-stereo using the cardboard icon in the player UI.

Before iOS 10, only progressive sources (mp4 files) are currently supported in Safari on iOS due to Apple’s limitations, on iOS 10 and above also HLS can be used. In addition, the mp4 file or HLS stream needs to be hosted on the same domain as the website to get VR/360 playback to work on iOS.

contentType – Specifies the type of the VR/360 content. Allowed values are:

  • bitmovin.player.VR.CONTENT_TYPE.SINGLE (“single”) – A single equirectangular video typically used for 2D VR/360 content.
  • bitmovin.player.VR.CONTENT_TYPE.TAB (“tab”) – Two equirectangular videos for 3D content in top-and-bottom position.
  • bitmovin.player.VR.CONTENT_TYPE.SBS (“sbs”) – Two equirectangular videos for 3D content in side-by-side position.

stereo – Specifies if the video should start in stereo mode (true) or not (false, default)

startPosition – Specifies the starting viewpoint, stated in degrees.

initialRotation – Set to true, an automatic rotation across the entire video will be executed.

initialRotationRate – Specifies the automatic rotation speed of the projection, if initialRotation is active.

viewingWindow Specifies the angles the user can view around within the VR/360 video. Per default, the user has no limitations. This optional object can be used to limit the viewing window using the following attributes:

  • minYaw – Specifies how low the user can look. Valid values are from -90 to 90 (default: -90).
  • maxYaw – Specifies how high the user can look. Valid values are from -90 to 90 (default: 90).
  • minPitch – Specifies how far left the user can look. Valid values are from 0 to 360 (default: 0).
  • maxPitch – Specifies how far right the user can look. Valid values are from 0 to 360 (default: 360).

If no viewingWindow is specified, the following default object will be used:

{
        minYaw: 0,
        maxYaw: 360,
        minPitch: -90,
        maxPitch: 90
}

cardboard – Allows to set a cardboard config as string to adjust the VR/360 rendering to a specific cardboard device. The QR codes on cardboards contain short URLs, which lead to a long URL, e.g.: http://google.com/cardboard/cfg?p=CghSZWQgQnVsbBILUmVkIEJ1bGwgVlId7FE4PSWPwnU9KhAAAEhCAABIQgAASEIAAEhCWAA1KVwPPToICtcjPArXIzxQAGAC
The content of parameter p should be used as string:

{
        ...
        cardboard: 'CghSZWQgQnVsbBILUmVkIEJ1bGwgVlId7FE4PSWPwnU9KhAAAEhCAABIQgAASEIAAEhCWAA1KVwPPToICtcjPArXIzxQAGAC'
}

A possible configuration, with a default VR mode and initial rotation looks as follows:

source: {
  dash : 'http://path/to/mpd/file.mpd',
  vr: {
     contentType: bitmovin.player.VR.CONTENT_TYPE.SINGLE,
     startPosition: 180,
     initialRotation: true,
     initialRotateRate: 0.025
  }
}

Location

The location setting can be used to specify custom paths and naming for the Bitmovin Player Files. This can be handy, if one wants to separate different file types (e.g., JS and CSS) in different folders, or apply a dedicated prefix to the files.

flash – Specifies the path, relative or absolute, to the file containing the Flash based player. Default name: bitmovinplayer.swf

vr – Specifies the path, relative or absolute, to the file needed for VR and 360º video playback. Default name: bitmovinplayer-vr.js

ui – Specifies the path, relative or absolute, to the UI/skin. Default name: bitmovinplayer-ui.js

ui_css – Specifies the path, relative or absolute, to the style sheet of the UI/skin. Default name: bitmovinplayer-ui.css

Example:

location : {
  flash : 'MY_FLASH_FOLDER/my_bitmovinplayer.swf',
  vr    : 'MY_VR_FOLDER/my_bitmovinplayer-vr.js'
  ui .  : 'MY_JS_FOLDER/my_bitmovinplayer-ui.js',
  ui_css: 'MY_CSS_FOLDER/my_bitmovinplayer-ui.css'
}

Logs

Can be use to fine tune logging of the player.

bitmovin – Enable or disable the bitmovin credits in the browser’s console. Defaults to true (enable).

level – Sets the log level for debug output, warnings and errors sent to the browser console. Please note that especially DEBUG but also LOG level should not be used for production environments as this can decrease performance, especially for long-term playback, due to the amount of log messages.
Available values are:

  • bitmovin.player.LOGLEVEL.DEBUG
  • bitmovin.player.LOGLEVEL.LOG
  • bitmovin.player.LOGLEVEL.WARN (default)
  • bitmovin.player.LOGLEVEL.ERROR
  • bitmovin.player.LOGLEVEL.OFF

Licensing

delay – Can be used to set the delay (in milliseconds) until the licensing call is issued. Maximum value is 30000 (30 seconds).

Example Configuration

This is a sample configuration object:

{
  key                       : 'INSERTPROVIDEDKEYHERE',
  playback: {
    autoplay                : false,
    muted                   : false
  },
  source: {
    dash                    : 'http://path/to/mpd/file.mpd',
    hls                     : 'http://path/to/hls/playlist/file.m3u8',
    progressive             : [{
                                url: 'http://path/to/mp4',
                                type: 'video/mp4'
                              }, {
                                url: 'http://path/to/webm',
                                type: 'video/webm'
                              }],
    poster                  : 'images/poster.jpg',
    drm                     : {
      widevine              : {
        LA_URL              : 'https://mywidevine.licenseserver.com/'
      },
      playready             : {
        LA_URL              : 'https://myplayready.licenseserver.com/'
      },
      access                : {
        LA_URL              : 'https://myaccess.licenseserver.com/',
        authToken           : 'INSERT-YOUR-BASE64-ENCODED-AUTH-TOKEN'
      },
      primetime             : {
        LA_URL              : 'https://myprimetime.licenseserver.com/'
      },
      fairplay              : {
        LA_URL              : 'https://fairplay.licenseserver.com/',
        certificateURL      : 'https://fairplay.licenseserver.com/certificate-url'
      }
    }
  },
  style: {
    width                   : '90%',
    aspectratio             : '16/9',
    ux                      : true
  },
  events: {
    onReady                 : myFunc,
    onPlay                  : function() {
                                // do some awesome stuff
                              },
    onError                 : myErrorHandlingFunc
  },
  tweaks: {
    max_buffer_level        : 20
  },
  advertising: {
    client  : 'vast',
    tag     : 'http://your.ad.provider/manifest.xml'
  }
}

Troubleshooting

If the player is not loading an element, whether poster image, manifest, segments, etc. provided by another server, make sure that CORS is enabled on the server containing the element.

If things are unclear it’s always good to take a look at our frequently asked questions or at our tutorials. If you don’t see your question here, feel free to contact our support for direct help.

Back to Top
Simple Share Buttons