HTML5+ Player User Guide

• HTML5+ Player User Guide
  • Introduction
  • HTML5+ player support
    • Prerequisites
    • OS and Browser support
    • DASH DRM support
    • HLS DRM support
    • Codec
    • Subtitle / Closed Caption
    • FCC compliance
    • Streaming protocol support
    • Analytics support
    • Chromecast support
    • Airplay support
    • Thumbnail preview as external VTT files
    • Low latency for DASH live streams
    • Poster tag
    • Resize and reposition of the image inside of poster tag
    • Google IMA Integration
      • Ad Playback
      • Ad Events
  • Product life cycle
• Installation and uninstallation
• Sample player features
• Logging system
  • Controlling VisualOn log in your application
  • Capturing VisualOn logs using the VisualOn sample player
• License Selection
  • Evaluation license
  • Production license
  • Web App license
• Recommendations for managing SDK updates
• Error code and API manual

Introduction

VisualOn HTML5+ Player offers the following benefits when deploying a content delivery solution:

• No plug-in installation

• Convenience and flexibility across platforms and devices

HTML5+ player support

Prerequisites

• MSE (Media Source Extensions™) is supported in your browser.

• EME (Encrypted Media Extensions) is supported for DRM type media.

OS and Browser support

Note：

1.  HTTPS streaming is required from Chrome 58 onwards.

•   MSE plus HTTP will always work if EME is not used.

•   EME plus HTTP will not work.

•   EME plus HTTPS will work which means MSE plus HTTPS is the only option here 
when EME is used. The old API requestMediaKeySystemAccess() is deprecated on insecure 
origins in the specification. The support will be removed in the future.

The non-HTTPS content will not render and the console will provide error reporting 
to that effect.                 
2.  IE10 and IE11 on Windows 7 do not have the MSE/EME API available. Consequently, 
it is technically not possible for any HTML5-based video player to playback DRM protected content 
on these browsers in Windows 7.
3.  DASH support is required Safari 10+ on Mac OS X.
4.  Only HLS is supported on Safari for iOS.
5.  DRM is not supported on Firefox for Android.

DASH DRM support

ClearKey is also supported for DASH on Chrome 35+, Firefox 47+, Android 4.3+.

HLS DRM support

Widevine DRM HLS version 2 specifies the new extensions which are meant to be used for HLS in CMAF and be compatible and consistent with Widevine DRM signaling for MPEG-DASH in CMAF. And this is now fully supported by HTML5+ player.

Codec

Only H264/AAC is supported.

Subtitle / Closed Caption

Note: 
1.  TTML is not supported in HTML5 for HLS.
2.  The attribute of CLOSED-CAPTION need define in HLS media playlist, otherwise, CEA-608/CEA-708
are not supported on safari for HLS. 

FCC compliance

Two APIs are supported in VisualOn HTML5+ player for FCC compliance. Refer to the sample code in API Reference Manual.zip file under the Doc directory in the installation package.

• setSubtitleStyles(subStyles) • getDefaultSubtitleStyles()

The objects below are supported for the APIs.

enable： Enable all subtitles properties or not.

previewSubtitleText： Set the preview text string.

fontBackgroundColor: Set font background color.

fontBackgroundOpacity: Set font background opacity.

FontColor: Set font color.

FontOpacity: Set font opacity.

FontFamily: Set font name.

FontEdgeType: Set font edge type.

FontEdgeColor: Set font edge color.

FontEdgeOpacity: Set font edge opacity.

FontSize: Set font size.

FontBold: Set font bold or not.

FontUnderline: Set font underline or not.

FontItalic: Set font italic or not.

WindowColor: Set window background color.

WindowOpacity: Set window background opacity.

BoundingBox: Set bounding box position.

FontHorzPosition: Set font horizontal position.

Note: FCC is not supported in VisualOn HTML5+ player for HLS on Safari.

Streaming protocol support

DASH and HLS are supported.

Analytics support

To enable Analytics Server Agent on VisualOn HTML5+ Player, please configure the assets.js as the introduction Sample player configurations. See the following sample code to configure the Analytics Server Agent status and CUID.

analytics: [
    {
        type: 'server',
        options: {
            cuid: 'visualon'// customer specified user ID for Analytics Agent
        }
    }
] 

The following events and attributes are supported:

Note 1: Analytics Server is limitedly supported in HTML5 on Safari for HLS. For Analytics Overlay, please refer to VisualOn_Analytics_Overlay.pdf

Note 2:
VisualOn Analytics and other VisualOn partners' analytics are enabled by default. 
It occupies a certain amount of bandwidth. Consequently, please turn it off in assets.js
for any special user cases like Low latency for example.

Chromecast support

Enabling the Chromecast to display the content to external device screen, tap the cast icon in the initial view, and select the Chromecast device from the list. If you want to change the source then click the “cast to” icon and select the source from the list. There are options for “cast tab” or “cast desktop” when “share your screen”.

While in casting, tab the casting icon, the VisualOn default customer media receiver is shown, which includes the basic playback control. Tab “STOP” to stop the casting.

Note: VisualOn HTML5+ player provides custom receiver SDK. 
If you want to set up your own server to host the receiver by using VisualOn receiver SDK
please refer https://developers.google.com/cast/docs/registration to register your cast 
application and get the application ID. 
The analytics data of Chromecast will be sent to your own server,
otherwise, to VisualOn default analytics server by using VisualOn default customer receiver 
which is hosted by VisualOn and the application ID is B5BCD208. 
The application ID is used with API calls from the sender application. 
The sample code below shows the steps to configure the application ID while initialization.

To enable Chromecast the init(config) must be called successfully. See the following sample code to configure the receiver media player.

     var playerConfig = {
        autoPlay: true,
        cast: {
            receiverAppId : 'B5BCD208'  //VisualOn default customer receiver
        }
    };
    player.init(playerConfig); 

Note: For Chrome 72 Chromecast, the HTML5+ player only works on the https links.

Airplay support

Enabling AirPlay to wirelessly stream video to external HDTV from Safari via AppleTV, tap Airplay after loading the stream in the player, and then select the AppleTV device from the list, the content will be streaming to the HDTV. While in Airplay streaming, the playback control bar is still displaying and working on VisualOn HTML5+ player, tab Airplay again or STOP playback to stop the Airplay streaming.

Note: Airplay only support for HLS on VisualOn HTML5+ player. The volume control is disabled from player control bar while in Airplay streaming mode.

Thumbnail preview as external VTT files

Thumbnail preview as external VTT files is supported to show an overlay preview images when set a new position on time slider. The overlay thumbnail is loaded to VisualOn player as external VTT files. The W3C VTT format is a basic, text format that combines timing and thumbnails. These thumbnails are stored in a basic image format, like JPG. Thumbnail preview also support multiple JPEG case. Multiple thumbs can be combined into a single sprite W3C Media Fragments are then used to map the individual thumbs to the correct times. The following API must be called to enable thumbnail preview for HTML5+ player: • findNearestThumbnail(pos) returns a thumbnailInfo object. Returns null if there is no thumbnail. See the following sample code to set the URI of WebVTT file in the sourceConfig object. Refer to the details in API Reference Manual.zip file under the Doc directory in the installation package.

   tracks: [{
          uri: 'http://path/to/thumbnail/vtt/url.vtt',
          type: 'thumbnails'
      }] 

Low latency for DASH live streams

Low latency allows users to easily build a high quality and low latency HD video transmission system for live streams playback.

The following platforms are supported with Low latency for DASH Live streams:

The following APIs are added:

lowLatencyMode startWithLowestLatency

For details usage, please refer to the API manual.

Poster tag

Enabled Custom Dimensions and Custom Metrics settings in Analytics server for VisualOn HTML5+ Player. The value needs to be set before playback with asset.js.You can add customized poster picture. The picture appears right after you click on the play button before the 1st frame shows up. Usage example:

source: {
poster: "https://sh.visualon.com/sites/default/files/tears_of_steel.png
https://sh.visualon.com/sites/default/files/tears_of_steel.png
",
links: [{
uri: "https://storage.googleapis.com/wvmedia/clear/h264/tears/tears_sd.mpd"
}]
}

Resize and reposition of the image inside of poster tag

Rsize and reposition of the image inside of poster tag by using key/value dict object. Please see the following Sample code:

source: {
poster: {
url: "poster_image_url",
width: "300px",
height: "10%",
top: "100px",
left: "20%"
},
links: [{
uri: "http://rdmedia.bbc.co.uk/dash/ondemand/testcard/1/client_manifest-audio.mpd"
}]
}

Under posterConfig there are “ width, height, top, left and sourceConfig parameters”. Please see the following descriptions for each parameter:

1. width: The width of the poster display area. This can be set to any CSS unit, (px, em, %, etc...) If this tag is empty, the poster width will default to the poster image's width.
2. height: The height of the poster display area. This can be set to any CSS unit, (px, em, %, etc...) If this tag is empty, the poster width will default to the poster image's height.
3. top: The position relative to the top border of the video div. This can be set to any CSS unit, (px, em, %, etc...) If this tag is empty, the top of the poster will default to the center of the video div.
4. left: The position relative to the left border of the video div. This can be set to any CSS unit, (px, em, %, etc...) If this tag is empty, the left side of the poster will default to the center of the video div.
5. sourceConfig: The poster info for this content. see: module:Player~posterConfig. The SDK will show the poster before the video content, or for the entire duration if the content is purely audio. Each source can have its own poster. Each individual poster can be declared in the same manor for different content links."

Google IMA Integration

Ad Playback

VisualOn HTML5+ player has natively integrated with Google IMA to support the playback of client-side stitched ad playback flow. The player inherits the Google IMA feature which is support VAST, VMAP and VPAID. It supports to show companion Ads as well. The Google IMA SDK is referred as follow:

<!-- google ads sdk -->
<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

Ad Events

Based on Google IMA tracking mechanism, VisualOn HTML5+ player provides the tracking Events as following:

Product life cycle

Product life cycle defines the time duration in which a given production released version of licensed technology is supported for maintenance. The VisualOn product life cycle starts at the first production release date, and general availability of the base release version ends 18 months afterwards. Maintenance support is not available for backport to released versions that have reached end of life cycle. Update or migration to a newer version of licensed technology is recommended prior to the end of life cycle.

Installation and uninstallation

Confirm with your system administrator about the location in your web server where the HTML5+ Player kit should be installed.

Note: For evaluation of VisualOn HTML5+ player on IE-11, Chrome and Firefox browsers it may be necessary to enable accessibility across domains (CROS) by installing add-ons, extensions or changing the browser security settings. Installing add-ons, extensions or changing the browser security settings is usually avoided by adjusting the server(s) settings.

• For Chrome, install the following extension will enable accessibility across domains: https://chrome.google.com/webstore/detail/allow-control-allow-origi/nlfbmbojpeacfghkpbjhddihlkkiljbi?hl=en
• For Firefox, installing the following add-on will enable accessibility across domains: https://addons.mozilla.org/en-US/firefox/addon/cors-everywhere/
• For IE-11, customizing the IE "miscellaneous" security settings for “Access data sources across domains" to Enable will enable accessibility across domains.More details about CORS are available here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS

Sample player features

1. Interface for selecting different sources: Select media sources, subtitle sources, and asset properties.
2. Set bitrate: The Sample Player application allows you to set the bitrate as needed (“Auto” by default). To set the bitrate, select the required bitrate from the Video list.
3. Playback controls: During playback, the Sample Player application provides a set of basic controls, including a Play/Pause button, a Stop button and a Mute button.
4. Asset property selections: When the media source includes multiple video tracks (also known as bitrate), audio tracks, or subtitles, the Sample Player application supports switching within various tracks during the playback.
5. Bitrate adaptation: When “Auto” is selected in the Select Bitrate list menu, the most suitable bitrate for the current network is selected.
6. DRM setting: manually set DRMs in Custom Asset menu to your DRM type
7. Sample player configurations: VisualOn HTML5+ player sample player supports to configure the settings by java script file asset.js under *<SDK_INSTALL_DIR>\SamplePlayer\sampleplayer\app.* This file allows you to configure the playback, analytics, logs, stream URI, DRMs and etc. In the configuration file, create voAvailableStreams for different types of the stream groups which allows you quick accessing the URI from the sample player webpage. Please refer to the sample code in Player API Reference Manual.zip file under the Doc directory in the installation package.

Logging system

Controlling VisualOn log in your application

VisualOn HTML5+ player log is generated via event mechanism. The application can get the log messages by listening to the VO_OSMP_CB_LOG_ADDED event. For example, the sample code of VisualOn sample player is: player.addEventListener( voPlayer.events.VO_OSMP_CB_LOG_ADDED, onLogAdded, $scope) ,If logsConfig is set to true, the VisualOn log will be showed in the browser's console.


Capturing VisualOn logs using the VisualOn sample player

1. Click the Show Log Window button.

2. Click the Turn On Log button at the bottom of the log window. Log messages are shown in the log window.

3. You can save the log file on a local device or upload the log file to a server that is hosting upload.php. See the SDK Tools/setuplogserver/ folder for more details about uploading a log file.

Note: The log file name and saving mechanism may differ across web browsers

License Selection

Evaluation license

The evaluation license is valid for 182 days from the date the build is created.

Production license

The production license has a domain check mechanism. Please contact your VisualOn contact and provide the list of your domains for the domain check white list of your production license.

Web App license

We have Web App license mechanism to check Web App ID for Tizen and webOS. Please provide your App ID to VisualOn support team for applying the production license.

Recommendations for managing SDK updates

1. main.js and asset.js are Sample Application files, voplayer.min.js is the player library file.

2. The HTML5 API is listed in module-Player.html, events are listed in modules.list.html (unzip the "Player API Reference Manual.zip" to see these files)

3. global.html contains our API change history for each version including API and Event usage changes, name changes, addition and removal, parameter changes

4. Please review the global.html file for each release.

If global.html indicates API and Event changes, it is possible that the application code needs to be updated.

If there are no changes in global.html, no further changes in the application is required, but it is a good practice to check changes in the VisualOn Sample Application files.

Error code and API manual

Please refer to the API Reference Manual in the /HTML5/Doc/Player API Reference Manual.zip for all the Events and API related topics.