OpenTV Player SDK for Browsers Integration
Introduction
This guide describes how to instantiate and use the OpenTV Player SDK for Browsers and provides guidance on using the features of the player. The SDK includes complete code examples to demonstrate the basic and advanced features.
Player hosting and configuration
-
The hosted video must be configured to allow cross-origin resource sharing (CORS) if not hosted on the same origin such as a different domain or subdomain.
-
The OpenTV Player SDK for Browsers uses cryptographic functions provided by the browser. Some browsers might inhibit this functionality if not running over HTTPS. You are recommended to only deploy OpenTV Player SDK for Browsers over HTTPS.
-
A licence will be required to use the player, see Player Licensing for details.
Creating a simple player
The player can be integrated by hosting a few lines of HTML on an HTTP server. This file (and the linked JS and CSS files) must be hosted on a web server for this to work.
For development and testing purposes, hosting on localhost is satisfactory.
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="dist/opy-sdk-browser.css">
<script src="dist/opy-sdk-browser-all-debug.js"></script>
</head>
<body>
<video class="video-js vjs-default-skin vjs-16-9" id="videoPlayer" controls crossorigin="anonymous">
</video>
<script>
document.addEventListener("DOMContentLoaded", function initializeRefApp() {
let playerInstance = otvplayer(
"videoPlayer",
// options
{},
// loaded callback
function loadedCallback() {
// Initialise the toolkit plugin (if not initialised by the player options)
playerInstance.otvtoolkit();
source = {
src: streamUrl,
type: "application/dash+xml"
};
playerInstance.src(source);
});
});
</script>
</body>
</html>
Code extracts
Important parts of this example are explained in the following sections.
Include the OpenTV Player SDK for Browsers
The player is distributed as two files:
opy-sdk-browser.cssopy-sdk-browser-all.js
Include the following in the page <head>:
<link rel="stylesheet" href="../../dist/opy-sdk-browser.css">
<script src="../../dist/opy-sdk-browser-all-debug.js"></script>
Change the path as required to point to your distribution folder.
Adding an HTML5 video tag
Add a <video> tag to the page <body>:
<video class="video-js vjs-default-skin vjs-16-9" id="videoPlayer" controls crossorigin="anonymous">
</video>
The id attribute is mandatory, and must be unique on the page. The player code uses it to identify the <video> tag to attach the player to.
The class attribute contains two classes:
video-jsapplies styles that are required byvideo.js(the industry standard technology on which the player is built).vjs-default-skinapplies the default skin to the HTML controls. It can be removed or overridden to apply your own design to the controls.
Create the player
Add code to create an instance of OpenTV Player and attach it to the <video> tag after the document is loaded. The sample above does this by using a listener to listen for the DOMContentLoaded event:
let playerInstance = otvplayer(
"videoPlayer",
// options
{},
// loaded callback
function loadedCallback() {
...
}
);
This takes three parameters:
- The
idof the<video>tag to attach the player to (which you added to the<video>tag above) - An
optionsobject. This can be used to set up theotvtoolkitplugin (see below). In this example, no setup is required so the options object is empty. - A callback that will be executed when the player is initialised and ready to play.
Initialise the otvtoolkit plugin
Within the callback, initialise the otvtoolkit plugin:
playerInstance.otvtoolkit();
The otvtoolkit plugin is an essential part of the OpenTV Player SDK for Browsers and is used to provide advanced player features. You must call to initialise the plugin when the player is ready.
Set the player source
Still within the callback, specify the video source URL:
source = {
src: streamUrl,
type: "application/dash+xml"
};
playerInstance.src(source);
A player source is an object containing:
src– the URL of the video sourcetype– the content's MIME type
Once you pass this object to the player's src() function, the video will start to play.
For HLS streams in Apple's Safari browser use:
type: "application/x-mpegURL".
Extending the simple example to include advanced features
Live stream support
In order to display the progress bar for seeking within the seekable range during live stream playback, you need to set the liveui attribute to true.
let playerInstance = otvplayer(
"videoPlayer",
// options
{
plugins: {
otvtoolkit: {}
},
liveui: true
}
);
Error handling during initialisaion
There may be a failure during player initialization which results in the player object not being returned. Since there is no object instance to attach listeners onto, no errors can be caught.
To deal with this the otvtoolkit allows for a creationFailureCallback property on its plugin options. In the event of an error during initialisation, this will be called with an error object passed in as the only parameter.
The error object will have a name and a message property that can be used to determine the nature of the error.
let playerInstance = otvplayer(
"videoPlayer",
// options
{
plugins: {
otvtoolkit: {
creationFailureCallback: onCreationFailureCallback
}
}
},
// loaded callback
function loadedCallback() {
...
}
);
function onCreationFailureCallback(creationError) {
console.error(creationError.name + ": " + creationError.message);
}
An invalid videoID being passed to the player, otvplayer will generate a TypeException, for an invalid plugin or plugin component, otvplayer will generate a ReferenceException.
Configuring the otvtoolkit plugin for DRM
To enable DRM, add the appropriate parameters to the options object. These will vary for SSP and Conax integrations:
var drmSystem = null;
if (
window.navigator.userAgent.indexOf("Safari") !== -1 &&
window.navigator.userAgent.indexOf("Chrome") === -1
) {
if (fairPlayMode === undefined || fairPlayMode === "nagra-ssp-fps") {
drmSystem = {
system: "nagra-ssp-fps",
config: {
tenantId: myTenantId,
licenceServer: fairplayLicenceServerUrl
}
};
} else if (fairPlayMode === "nagra-conax-fps") {
drmSystem = {
system: "nagra-conax-fps",
config: {
portalURL: conaxPortalUrl,
certificatesURL: conaxCertificateUrl,
licenceServer: conaxLicenceServerUrl
}
};
}
} else {
drmSystem = {
system: "nagra-ssp",
config: {
mode: "token",
tenantId: myTenantId,
licenceServer: sspLicenceServerUrl
}
};
}
Then initialise the otvtoolkit as follows:
let playerInstance = otvplayer(
"videoPlayer",
// options
{
plugins: {
otvtoolkit: {
drm: drmSystem
}
}
},
// loaded callback
function loadedCallback() {
...
}
);
The drm section of the otvtoolkit plugin contains the name of the DRM system (in this case, nagra-ssp, nagra-ssp-fps or nagra-conax) and a system-specific configuration object.
Because the
otvtoolkitplugin is configured by the options object, you do not need to initialise the toolkit inloadedCallback().
Adding DRM to the source
The above example configures the player for the “token” mode of operation for the “nagra-ssp” DRM system. In this mode, a token must be added to the source object:
source = {
src: streamUrl,
type: "application/dash+xml",
token: streamToken
};
The token is an opaque, base64-encoded structure that identifies the content (and its key) to the DRM system.
Adding thumbnail preview
The OpenTV Player SDK for Browsers can be configured to display preview thumbnails when the mouse pointer hovers over the seek/progress bar. To enable this feature, pass the URL of a WebVTT thumbnail resource to the otvtoolkit:
playerInstance.otvtoolkit().addThumbnailPreview(thumbnailWebvttUrl);
Thumbnail preview must be added after setting the player source.
Use low resolution thumbnails, as thumbnail rendering can adversely affect video playback.
Simple sample page with SSP DRM and thumbnail preview
The following code sample combines DRM and thumbnail preview with the example at the top:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="../../dist/opy-sdk-browser.css">
<script src="../../dist/opy-sdk-browser-all-debug.js"></script>
</head>
<body>
<video class="video-js vjs-default-skin vjs-16-9" id="videoPlayer" controls crossorigin="anonymous">
</video>
<script>
document.addEventListener("DOMContentLoaded", function initializeRefApp() {
let playerInstance = otvplayer(
"videoPlayer",
// options
{
plugins: {
otvtoolkit: {
drm: {
system: "nagra-ssp",
config: {
mode: "token",
tenantId: myTenantId,
licenceServer: myLicenceUrl,
}
}
}
}
},
// loaded callback
function loadedCallback() {
// No need to initialise the toolkit plugin, as it's initialised by the player options
source = {
src: streamUrl,
type: "application/dash+xml",
token: streamToken
};
playerInstance.src(source);
// Optional: Add thumbnail preview AFTER setting source
playerInstance.otvtoolkit().addThumbnailPreview(thumbnailWebvttUrl);
});
});
</script>
</body>
</html>
Picture-in-Picture
Picture-in-Picture mode moves the player to a fixed position in the bottom right corner of the page. Once the feature is enabled, it can be initiated by the corresponding button on the control bar or, by default, it is automatically initiated when 50% of the player is vertically scrolled out of the viewport.
By default, this feature is disabled. The following code can be used to enable the automatic scroll-based initiation:
playerInstance.otvtoolkit().enablePiP();
Chapter Navigation
See Chapters for a brief description of how the chapters feature may be used to aid navigation within a video.