Player Configuration v5

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.

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 type="text/javascript" src="https://bitmovin-a.akamaihd.net/bitmovin-player/stable/5/bitdash.min.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 bitdash:

var player = bitdash('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

Mandatory. 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”

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. All options are available as documented in the DRM section.

options – An object specifying advanced source specific options.

  • manifestWithCredentials [new in v5.0] – Send credentials and cookies along with cross origin manifest (HLS and MPEG-DASH) requests. Must be supported by the server. Default is false.
  • withCredentials [new in v5.0] – Send credentials and cookies along with cross origin (HLS and MPEG-DASH) segment requests. Must be supported by the server. Default is false.
  • hlsManifestWithCredentials[new in v5.0] – Send credentials and cookies along with cross origin HLS manifest requests. Must be supported by the server. Default is false.
  • hlsWithCredentials [new in v5.0] – 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 [new in v4.3] [HTML5 only] – If set to true, this will keep the poster image visible during playback, e.g. for audio-only streams.

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

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'
  }, {
    url: 'http://path/to/webm',
    type: 'video/webm'
  }],
  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/'
    }
  }
}

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 [new in v4.1] – 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 [new in v4.1] – 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 &amp;&amp; drmTodayObj.status &amp;&amp; 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 &lt; 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 [new in v5.2] – 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).

customData [deprecated] – Adds customData ‘as is’ into the license acquisition request (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 [new in v4.1] – 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

[new in v4.1]

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

[new in v4.2]

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 [new in v5.2] – 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

[new in v4.1]

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 [new in v5.1] – 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 [new in v4.3] – 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 [new in v4.3] – – 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 [new in v5.1] — 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 [new in v5.1] — 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 [new in v5.1] — Sets an explicit response type for the license request. Default response type for this request is “text“, e.g. EZDRM requires “blob

EZDRM Specific Example (requires v5.1+):

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) + '&amp;' + session.contentId;
  },
  prepareContentId : function(contentId) {
    var pattern='skd://drmtoday?';
    var parameters;
    var idx;

    idx = contentId.indexOf(pattern);
    if (idx &gt; -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'
}

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.

preferredTech [new in v4.1] – 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.

controls – Whether controls are displayed or not. If no controls are displayed, this JavaScript API can be used to control the player. Can be true (default) or false.

autoHideControls – Can be used to disable auto-hiding the controls by setting this value to false. Default is true.

bufferingOverlay – Can be used to disable (i.e. never show) the overlay during buffering by setting this value to false. Default is true.

playOverlay – Can be used to disable (i.e. never show) the overlay in pause or stopped mode by setting this value to false. Default is true.

keyboard – Can be used to disable all keyboard commands by setting this value to false. Default is true.

mouse – Can be used to disable click (toggle play/pause) and double click (toggle fullscreen) mouse events by setting this value to false. Default is true.

ux – A short hand function to disable/enable controls, bufferingOverlay, playOverlay, subtitles, keyboard, and mouse. It is not possible to override this setting with one of the mentioned attributes.

subtitlesHidden – If set to true, active subtitles won’t be displayed, but still exposed in the onCueEnter and onCueExit events.

showErrors – Can be used enable/disable visible error messages. Default is true (enabled).

Style Example:

style : {
  width       : '100%',
  aspectratio : '16:9',
  controls    : true
}

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.

context_menu_entries – Custom context menu entries can be added. The value given to this option is an array of objects. Each object should have a name attribute, which is the string displayed in the context menu, and a url attribute, which is the link where the user gets redirected to if she clicks on the menu entry. The order of the entries is defined by the array, i.e. the first element in the array is the first element in the context menu.

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 [new in v4.1] – 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. 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,
  context_menu_entries: [
    {
      name : 'My Awesome Website',
      url  : 'http://my.awesome-website.com'
    }, {
      name : 'Another Link',
      url  : 'http://yet.another-link.net'
    }
  ],
  query_parameters : {
    key1: 'value1',
    key2: 'value2',
    mycustomname: 'another-value'
  }
}

Skin

A skin generated by our Skin Generator can be included by either putting the whole output skinning object of the generator in the skin object, or the URL to a JSON file which includes the output skinning object.

[new in v4.1]
The default bitmovin watermark can be disabled by setting the logo image to an empty string:

skin : { screenLogoImage : "" }

Example:

skin : 'http://www.example.com/my_custom_bitmovin_player_skin.json'

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, it is not necessary to use this option! This is only needed if one wants to create 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.

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 [new in v5.1] – 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 [new in v5.1] – The maximum bitrate in bits per second (bps) the player should start playback with. Has no effect if startupBitrate is used.

disableDownloadCancelling [new in v5.1] – 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).

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

[new in v4.1]

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.

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.

admessage – Defines a custom message that will be displayed to the user instead of the progress bar during ad playback. The predefined placeholder xx can be used to show the remaining seconds of the ad.

skipmessage [new in v5.1] – 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 xx 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 [new in v5.1] – 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.

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

VR and 360 Video

[new in v4.1]

The player can be used to playback VR and omnidirectional (360°) video. The related settings can be set in a deticated vr-section in the source part of the configuration object. Navigation can be performed via drag guestures 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.

The player offers different projection/rendering modes for various usage scenarios. The modes can be set within the config, or changed during runtime, using the button in the progress bar (next to the fullscreen symbol).

The specified default setting “off” shows a projection of the whole video. For 2D content on mobile and Desktop devices, “2D” (selectable in the settings window, as shown in the image above) is appropriate – for 3D content on these devices the “3D” option should be chosen. In the case of mobile, the built-in sensors can be used to navigate (look around). On desktop devices, keyboard controls (i.e. a,w,s,d), or the usage of a mouse is possible. For the use of VR devices like Oculus, or Samsung Gear VR, select the “Stereo 2D” or “Stereo 3D” option, depending on the content. In combination with the Oculus system, head tracking can be used as well, if supported in the browser (e.g. in FireFox Nightly with VR plugin).

Only progressive sources (mp4 files) are currently supported in Safari on iOS due to Apple’s limitations. In addition, the mp4 file needs to be hosted on the same domain as the website to get it to work on iOS.

startupMode – Specifies the mode at the startup of the playback. Allowed values are:

  • “off” – shows a projection of the whole video.
    [new in v5.2]: bitdash.VR.STARTUP_MODE.OFF
  • “2d” – for 2D content on mobile and desktop devices.
    [new in v5.2]: bitdash.VR.STARTUP_MODE.MONO_2D
  • “3d” – for 3D content on mobile and desktop devices.
    [new in v5.2]: bitdash.VR.STARTUP_MODE.MONO_3D
  • “stereo-2d” – for 2D content on VR devices, like Oculus Rift, or Samsung Gear VR.
    [new in v5.2]: bitdash.VR.STARTUP_MODE.STEREO_2D
  • “stereo-3d” – for 3D content on VR devices, like Oculus Rift, or Samsung Gear VR.
    [new in v5.2]: bitdash.VR.STARTUP_MODE.STEREO_3D

startPosition – Specifies the starting viewpoint, stated in degress.

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

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

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

source: {
  dash : 'http://path/to/mpd/file.mpd',
  vr: {
     startupMode       : bitdash.VR.STARTUP_MODE.MONO_2D,
     startPosition     : 180,
     initialRotation   : true,
     initialRotateRate : 0.025
  }
}

Location

This can be used to specify custom paths to bitdashplayer.swf, bitdashplayer.min.js, and bitdashplayer.min.css instead of having all files in the same folder.

html5 – Specifies the path, relative or absolute, to bitdashplayer.min.js, including the filename.

css – Specifies the path, relative or absolute, to bitdashplayer.min.css, including the filename.

flash – Specifies the path, relative or absolute, to bitdashplayer.swf, including the filename.

vr [new in v4.1] – Specifies the path, relative or absolute, to bitdash-vr.min.js, including the filename.

ctrls [new in v5.1] – Specifies the path, relative or absolute, to bitdash-controls.min.js, including the filename.

ctrls_css [new in v5.1] – Specifies the path, relative or absolute, to bitdash-controls.min.css, including the filename.

Example:

location : {
  html5 : 'MY_JS_FOLDER/bitdashplayer.min.js',
  css   : 'MY_CSS_FOLDER/bitdashplayer.min.css',
  flash : 'MY_FLASH_FOLDER/bitdashplayer.swf',
  vr    : 'MY_VR_FOLDER/bitdash-vr.min.js'
  ctrls : 'MY_JS_FOLDER/bitdash-controls.min.js',
  ctrls_css: 'MY_CSS_FOLDER/bitdash-controls.min.css'
}

Logs

[new in v4.1]

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).

Licensing

[new in v4.2]

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'
  },
  skin                      : "http://www.example.com/my_custom_bitmovin_player_skin.json"
}

Troubleshooting

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

  • CORS (for the HTML5 player) is enabled
  • a crossdomain.xml (for the Flash player) is placed

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