Customer Sign In

upLynk

** Important Note **
The upLynk 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.

HTML5 AdaptivePlayer SDK

Overview

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 SDKhttp://storage.uplynk.com/clients/html5/{version}/uplynk-core.min.js

(Optional) upLynk Player User Interface

UI Stylesheethttp://storage.uplynk.com/clients/html5/{version}/plyr.min.css
UI Scripthttp://storage.uplynk.com/clients/html5/{version}/plyr.min.js

API

General Functions
createAdaptivePlayer(videoElement, optionsObject, callbackFunc)
Creates and configures an ActivePlayer instance.
Options Collection
debugtrue|false - enable debug information sent to the browser console
preferNativePlaybacktrue|false - if true, attempt to use native engine handling for playback
showThumbnailstrue|false - display thumbnail while seeking *upLynk UI
showAdBreakMarkerstrue|false - display ad break marker in the seek bar *upLynk UI
disableSeekDuringAdBreaktrue|false - prevent seeking during an Ad Break *upLynk UI
limitResolutionToViewSizetrue|false - prevent the player from loading a quality with higher resolution than the display surface

AdaptivePlayer Object

Methods
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
domainstringreturns the content source domain
numberOfRaysnumberreturn the number of qualities (rays)
sessionIdstringupLynk Playback Session ID (pbs)
availableBandwidthsint[]returns a numeric array of quality bitrates
availableResolutionsResolution[]returns an array of Resolution objects
availableMimeTypesstring[][]returns an array of string arrays. mime types per quality.
segmentMapSegmentMapreturns the content SegmentMap
adBreaksAdBreak[]array of AdBreak objects
durationfloatcontent duration in seconds
playlistTypestringreturns a string representing content type ("VOD" | "EVENT" | "LIVE")
supportsThumbnailsbooleanreturns a true/false indicating if thumbnails are available
versionstringreturns the version of the player
Event Callbacks
  • 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

Properties
startTimereturns the ad break start time in seconds
endTimereturns the ad break end time in seconds
durationreturns the ad break duration
numAdsreturns the number of ads in this ad break

Resolution Object

Properties
widthreturns the video width
heightreturns the video height

SegmentMap Object

Properties
adBreaksreturns an AdBreak[]
contentSegmentsreturns a Segment[]
lengthreturns the number of segments in the map

Segment Object

Properties
iduplynk Asset ID
indexnumeric index of segment in map
startTimesegment start time in seconds
endTimesegment end time in seconds
typesegment type ("CONTENT","AD")

LoadConfig Object

Properties
urlRequired string; the URL to play
fairplayCertificatePathOptional string; path to the Fairplay certificate. Inidcates that Fairplay should be used

Player Integration Examples

Includes
1
2
3
<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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
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);
}

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

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

Known Issues

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 Number Details
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.17012000RC3Initial 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.17010900RC2Initial 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.16122200RC1Initial Release Candidate 1