HTML5 AdaptivePlayer SDK

The Uplynk OSMF player/Flash SDK has been deprecated. It is recommended that all customers transition to the Uplynk HTML5 AdaptivePlayer. The documentation for the legacy Flash SDK and the flash-based web browser players are still available for reference.

This guide is provided to assist an integrator with the use of the Uplynk HTML5 AdaptivePlayer Javascript SDK which works in conjunction with the HTML5 <video> element to allow a consistent HLS viewing experience via an HTML5 compliant browser.

The Uplynk AdaptivePlayer SDK acts as a source component for the HTML5 <video> element, providing extended functionality in the form of metadata, captions, subtitles, and alternate audio tracks.

Browser Compatibility:

Chrome: 55
Firefox: 50
Safari: 10

Links

The below links are to be used by Uplynk integrators to include the Uplynk HTML5 AdaptivePlayer Javascript SDK. Details on how to use these links are referenced below. See the Change Log below for a list of available version numbers.

AdaptivePlayer SDK:

http://storage.uplynk.com/clients/html5/version/uplynk-core.min.js

(Optional) Uplynk player user interface CSS:

http://storage.uplynk.com/clients/html5/version/plyr.min.css

(Optional) Uplynk player user interface script:

http://storage.uplynk.com/clients/html5/version/plyr.min.js

API

Function	Description
createAdaptivePlayer(videoElement, optionsObject, callbackFunc)	Creates and configures an ActivePlayer instance

Options Collection	Description
debug	true\|false - enable debug information sent to the browser console
preferNativePlayback	true\|false - if true, attempt to use native engine handling for playback
showThumbnails	true\|false - display thumbnail while seeking *Uplynk UI
showAdBreakMarkers	true\|false - display ad break marker in the seek bar *Uplynk UI
disableSeekDuringAdBreak	true\|false - prevent seeking during an Ad Break *Uplynk UI
limitResolutionToViewSize	true\|false - prevent the player from loading a quality with higher resolution than the display surface

AdaptivePlayer Object

Methods	Description
load(url)	load the url string
load(loadConfig)	load using the loadConfig settings
destroy()	destroy the player object and release resources
canSeek()	returns boolean true/false depending on if the player allows seeking

Properties	Data Type	Description
domain	string	returns the content source domain
numberOfRays	number	return the number of qualities (rays)
sessionId	string	Uplynk playback session ID (pbs)
availableBandwidths	int[]	returns a numeric array of quality bitrates
availableResolutions	Resolution[]	returns an array of Resolution objects
availableMimeTypes	string[][]	returns an array of string arrays. mime types per quality.
segmentMap	SegmentMap	returns the content SegmentMap
adBreaks	AdBreak[]	array of AdBreak objects
duration	float	content duration in seconds
playlistType	string	returns a string representing content type ("VOD" \| "EVENT" \| "LIVE")
supportsThumbnails	boolean	returns a true/false indicating if thumbnails are available
version	string	returns the version of the player

Event Callbacks	Description
on(event,callbackFunction)	assign event handler to the player object
AdaptivePlayer.Event.SourceLoaded	indicates playback is ready and supporting metadata is available
AdaptivePlayer.Event.LoadError	an error with loading / preparing has occurred event.error = error message event.code = error code
AdaptivePlayer.Event.DrmError
AdaptivePlayer.Event.SegmentMapLoaded	indicates the segment information has been loaded and the integrator can request it via player.segmentMap
AdaptivePlayer.Event.LoadedAdBreaks	indicates the ad break information has been loaded and the integrator can request it via player.adBreaks
AdaptivePlayer.Event.ID3Tag	playhead has encountered an ID3 tag event.cue = TextTrackCue or VTTCue associated with the ID3 tag event.frame.type = ID3 Tag type event.frame.size = size of ID3 Tag event.frame.data = Uint8Array of byte
AdaptivePlayer.Event.TxxxID3Frame	playhead has encountered a Txxx ID3 tag event.cue = TextTrackCue or VTTCue associated with the Txxx ID3 tag event.frame.value = Txxx ID3 tag value event.frame.description = Txxx ID3 tag description
AdaptivePlayer.Event.PrivID3Frame	playhead has encountered a Priv ID3 tag event.cue = TextTrackCue or VTTCue associated with the Priv ID3 tag event.frame.owner = Prvi ID3 tag owner event.frame.data = Uint8Array of bytes
AdaptivePlayer.Event.TextID3Frame	playhead has encountered a Text ID3 tag event.cue = TextTrackCue or VTTCue associated with the Text ID3 tag event.frame.value = ID3 Text tag value
AdaptivePlayer.Event.SliceEntered	playhead has entered the next segment event.assetId = Uplynk Asset ID event.rayChar = quality indicator event.sliceIndex = sequence index
AdaptivePlayer.Event.AssetEntered	playhead has entered a new asset
AdaptivePlayer.Event.AssetExited	playhead has left an asset
AdaptivePlayer.Event.AdBreakEntered	playhead has entered an ad break
AdaptivePlayer.Event.AdBreakExited	playhead has left an ad break

AdBreak Object

Property	Description
startTime	returns the ad break start time in seconds
endTime	returns the ad break end time in seconds
duration	returns the ad break duration
numAds	returns the number of ads in this ad break

LoadConfig Object

Property	Description
url	Required string; the URL to play
fairplayCertificatePath	Optional string; path to the Fairplay certificate. Indicates that Fairplay should be used

Resolution Object

Property	Description
width	returns the video width
height	returns the video height

SegmentMap Object

Property	Description
adBreaks	returns an AdBreak[]
contentSegments	returns a Segment[]
length	returns the number of segments in the map

Segment Object

Property	Description
id	Uplynk Asset ID
index	numeric index of segment in map
startTime	segment start time in seconds
endTime	segment end time in seconds
type	segment type ("CONTENT","AD")

Player Integration Examples

Includes:

<script type="text/javascript" src="http://storage.uplynk.com/clients/html5/{version}/uplynk-core.min.js"></script>
<link rel="stylesheet" href="http://storage.uplynk.com/clients/html5/{version}/plyr.min.css" />
<script type="text/javascript" src="http://storage.uplynk.com/clients/html5/{version}/plyr.min.js"></script>

Player Setup:

var options = {
    debug: true,
    showThumbnails: true,
    showAdBreakMarkers: true,
    disableSeekDuringAdBreak: false,
    preferNativePlayback: false
}

var video = null;           // video tag reference
var player = null;          // uplynk adaptive player reference
var plyrUI = null;          // uplynk plyr ui reference
var contentUrl = null;      // target content URL


// uplynk player creation callback, used to attach event listeners 
// and UI handlers to the newly created player object
function onCreateAdaptivePlayerCallback(adaptivePlayer) {

  // check for error during creation
  if(!adaptivePlayer) {
    console.log('Error Creating Player');
    return;
  }

  // store new adaptive player reference  
  player = adaptivePlayer;

  // attach various event handlers
  player.on(AdaptivePlayer.Event.TxxxID3Frame, function(ev) {
    console.log(ev.frame.value);
  });
  player.on(AdaptivePlayer.Event.PrivID3Frame, function(ev) {
    console.log(ev.frame.owner + ", " + ev.frame.data.length + " bytes");
  });
  player.on(AdaptivePlayer.Event.SliceEntered, function(ev) {
    console.log(ev.assetId + ":" + ev.rayChar + ":" + ev.sliceIndex);
  });
  player.on(AdaptivePlayer.Event.AssetEntered, function(ev) {
    console.log("Asset Entered: " + ev.asset.asset);
  });
  player.on(AdaptivePlayer.Event.AdBreakEntered, function(ev) {
    console.log("Ad Break Entered: " + ev.adBreak.duration);
  });
  player.on(AdaptivePlayer.Event.SourceLoaded, function() {
    console.log("SourceLoaded:");
    console.log(player.segmentMap);
    console.log(player.availableResolutions);
    playContent();
  });  

  // create and configure player UI options
  plyrUI = plyr.setup(video, options)[0];

  // attach player UI to player object
  plyrUI.setAdaptivePlayer(player);

  // tell player to load content URL
  player.load(contentUrl);
}

function loadPlayer(url) {
  //if the video was already initialized, we need to "destroy" to 
  //prepare to play a new video.
  if (plyrUI !== null) { plyrUI.destroy(); }
  if (player !== null) { player.destroy(); }
  
  // get and store reference to the html <video> element
  video = document.getElementById("video");
  
  // store url for use after player is created and callback fired
  contentUrl = url;

  // create uplynk adaptive player
  createAdaptivePlayer(video, options, onCreateAdaptivePlayerCallback, url);
}

function playContent() {
  if(video == null) return;
  video.play();
}

function pauseContent() {
  if(video == null) return;
  video.pause();
}

Known Issues

Type	Description
Captions	608 Caption Channel 2-4 are not currently available
Captions	placement of some captions on Firefox may be outside of viewport
Logging	changing sources may interrupt debug output to the browser's console log

Change Log

Version	Details
02.00.18102200	Improve: DASH playback support. Change: Added optional URL parameter to the createAdaptivePlayer function. This URL parameter is required to take advantage of the improved DASH playback support. Syntax: createAdaptivePlayer(video, options, onCreateAdaptivePlayerCallback, url);
02.00.18061400	Fix: ID3 metadata with duration 0 was not being published Fix: Chrome on Android <7.1 failing to play Widevine content
02.00.18050400	Fix: CC608 roll-up captions could have characters transposed Fix: Android Chrome native playback wasn't playing back Fix: Fixed error logic when download error occurred on last slice Add: Initial support for live DASH playback
02.00.18032700	Fix: Scrubbing on Chrome on Android Fix: Audio sync issue Fix: Closed captions rendering too low Add: Support for captions in B-frame encoded assets Improve: Removed need for cookie data to playback DASH content Improve: DRM playback support for non-US viewers Improve: Better support for assets with audio gaps by inserting silent audio
02.00.18020701	Add: B-frame playback support Add: Non-minified .js files to dist Add: PlayReady DRM support
02.00.18012300	Fix: Track and slice load error callback Fix: Don't double count latency time in download stats Add: Fairplay DRM support for Safari Add: new LoadConfig object Improve: DASH MPD Parsing - Rays in separate AdaptationSets, and better template support
02.00.17101600	Fix: Detection of already-buffered data on seeking that would hang playback Fix: HTTP Strict Transport Security (HSTS) fix for IE11 Fix: Prevent switching to lowest ray when initiating a seek Fix: Firefox QuotaExceededError when seeking more than a human would Fix: The servertime URL was broken if playing with CDN url parameter Fix: Alt-audio tracks for Safari native playback
02.00.17092100	Add: Enable MacOS Picture-in-Picture support Fix: HTTP 304 responses foul up download metrics Fix: Check parity on 608 Caption data Fix: Fix for when assetInfo API fails
02.00.17082900	Fix: Improvements to download timeouts, playback getting outside the live window, and error handling
02.00.17080800	Fix: Switching audio tracks sometimes stops playback
02.00.17080700	Add: Support for ad click-thru's Add: Preview thumbnails for assets that were storage-switched Fix: Safari stops playback when selecting an alternate audio track Fix: Edge and IE have run-away downloads Fix: Player does not work on IOS 7 Safari Fix: AssetInfo returns incorrect isAd value for short assets Fix: A few fixes for more robust playback of imperfectly clipped/sliced assets
02.00.17042000	Fix: Could not have multiple players on the same page Fix: Servertime url was hardcoded
02.00.17021600	Add: Version property to AdaptivePlayer object Change: Changed signature of ID3Tag event object
02.00.17012000 RC3 - Initial Release Candidate 3	Add: API Option to limit playback quality by viewport dimensions Fix: Corrected the display of some special characters in captions Fix: UI - corrected placement of ad markers Fix: Alternate Audio selection failure on Live Streams
02.00.17010900 RC2 - Initial Release Candidate 2	Fix: Player set up failure on iOS Safari Fix: Prevent multiple CC channels from displaying at the same time Fix: Prevent captions from being rendered outside of display on FireFox Fix: Adjusted size of x-large captions to prevent text being clipped in Chrome Fix: Prevent AV sync drift on Safari Change: Safari 9 and lower will default to native player
02.00.16122200 RC1 - Initial Release Candidate 1