Upgrade Bitmovin Player v5 to v6

Bitmovin Player v6 provides many new features and capabilities, but in order to enable them and also to prepare the player for new exciting features in the future a few breaking changes have been made to the player API.

Setup

Instead of including bitdash.min.js in the HTML page, bitmovinplayer.min.js needs to be included:

<script src="//bitmovin-a.akamaihd.net/bitmovin-player/<release-channel>/6/bitmovinplayer.min.js"></script>;

Where is either “stable”, “staging”, “beta”, or “dev”. More details can be found at the release channels overview.
Please find all available player versions and release channels in our backend application: https://app.bitmovin.com/player/embed

To create a player object, bitmovin.player(id) needs to be called instead of bitdash(id):

var player = bitmovin.player("player");
player.setup(conf)

VR/360

VR/360 support and especially the usability has been increased. Instead of providing the user all possible options in the settings menu, the type of content – 2D, 3D top and bottom, or the new 3D side by side – has to be specified in the player configuration using the new contentType attribute. The user gets a cardboard-like icon to toggle stereo view mode.

var conf = {
  ...
  source: {
    ...
    vr: {
      contentType: 'single' // "single", "tab" (for top-and-bottom 3D content) or "sbs" (for side-by-side 3D content)
    }
  }
};

There are two API calls in regards to VR/360, the first can be used to toggle the stereo mode:

player.setVRStereo(enableStereo)

The second call can be used to receive the status of the VR playback, as specified in the API documentation:

player.getVRStatus()

Ads

In addition to the new VPAID ads support, the existing API call to dynamically schedule ads, scheduleAd has been changed. The optional parameters have been moved into an object:

player.scheduleAd(manifestUrl, adType, [optional] {
  timeOffset: 'pre',
  skipOffset: 10,
  persistent: false, 
  adMessage: 'Ad can be skipped in xx seconds...', 
  skipMessage: 'Skip ad', 
  style: styleObject, 
  skin: skinObject
});

The client attribute, which specifies the ad type, has been moved into the ad objects in the schedule:

advertising: {
  schedule: {
    pre: {
      ...
      client: 'vast'
    }
  }
}

A new event is triggered when ad playback starts: onAdStarted. It has an object as parameter containing the following attributes:

{
     clickThroughUrl: clickThroughUrl,
     indexInQueue: idxInQueue,
     duration: duration,
     skipOffset: skipOffset,
     timeOffset: offsetString
}

More details can be found in the player documentation event description.

Another new event, onAdScheduled, is fired when a new ad is scheduled. The parameter is an object with numAds, the total number of ads currently scheduled.

onAdScheduled: {
  numAds: total number of parsed, playing or played ads (ads, whose manifests were not yet loaded, or that are unsupported are not counted)
}

The player’s built-in “skip ad” button can be disabled in the player configuration:

advertising: {
  ...
  hideSkipAdButton: true
}

Different than VAST 3 ads, VAST 2 ads can not be specified as skippable in the VAST manifest. Therefore, VAST 2 ads can now be marked as skippable, including the offset after which it can be skipped. This can be done using the skipOffset in the scheduleAd call or in the player configuration.

Player Configuration:

advertising: {
  ...
  tag: 'some-url',
  skipOffset: 10
}

Schedule Ad dynamically:

advertising: {
  schedule: {
    pre: {
      ...
      skipOffset: 10
    }
  }
}

Adaptation Logic

To influence/overwrite the built-in adaptation logic the new callback functions, which can be specified in the player configuration, should be used as the onVideoAdaptation and onAudioAdaptation events do not use a return type anymore.

Instead of the onVideoAdaptation event, use the onVideoAdaptation callback:

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

Instead of the onAudioAdaptation event, use the onAudioAdaptationcallback:

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

Errors and Warnings

Previous player versions sometimes fired an onError event even though the issue was not critical for playback. The existing errors have been re-considered and all non-critical errors, where continuing the playback is still possible have been removed. Instead, these issues might fire an onWarning event. It let’s you know that playback can be continued, but something happened (e.g. a subtitle sidecard file could not be loaded). The same parameter structure is used as for errors, but the code starts at 5000.

Others

The attribute name in the onSourceLoaded event’s parameter object has been renamed from newMpd to newManifest.
A mimeType attribute has been added to the onDownloadFinished event’s parameter object. In addition, a new onSegmentRequestFinished event has been added which is fired when the download of a segment has been finished.

The attributes in the tweaks object of the player configuration are now all in seconds (some used milliseconds in previous versions).

Back to Top
Simple Share Buttons