Universal Web Player SDK Version 3

Introduction

Welcome to the Anvato Web Player documentation. If you are a new user, start coding at Quick Start section with examples that will get you embedding in no time.

Embed options and configuration are discussed at Configuration Options. Common integration questions are answered at Integration section. Finally checkout the Plugins section for advanced use cases.

Quick Start

Embedding a video

Add the script tag <script src='//w3.cdn.anvato.net/player/prod/v3/scripts/anvload.js'></script>
Provide a player placeholder <div id="player"></div>
Call the init method with player configuration as shown below AnvatoPlayer("player").init({ url: "//mcp-download.storage.googleapis.com/anv-videos/variant/3697036.m3u8", title: "Sintel" });

The following is a live example:

<script src="//w3.cdn.anvato.net/player/prod/v3/scripts/anvload.js"></script>
<div id="player"></div>
<script> 
    AnvatoPlayer("player").init({
        url: "https://mcp-download.storage.googleapis.com/anv-videos/variant/3697036.m3u8", 
        width: "100%", 
        poster: "https://mcp-media.storage.googleapis.com/anv-iupl/5FA/ACA/5FAACA8FB2F3459C81F2CEF515615DAF", 
        title: "Sintel", 
        description: "Third Open Movie by Blender Foundation"
    });
</script>

Playing a playlist

If you have multiple videos, you can play them as a playlist. Providing an array of objects populated with video URLs in the playlist parameter is sufficient. AnvatoPlayer("player").init({ "playlist": [ { url: "URL_1" title: "TITLE_1", poster: "POSTER_1" }, { url: "URL_2" title: "TITLE_2", poster: "POSTER_2" }, { url: "URL_3" title: "TITLE_3", poster: "POSTER_3" }, ] });

<script src='//w3.cdn.anvato.net/player/prod/v3/scripts/anvload.js'></script>
<div id="player"></div>
<script> 
    AnvatoPlayer("player").init({ 
        playlist: [
            {
                url: "https://mcp-download.storage.googleapis.com/anv-videos/variant/3697596.m3u8",
                title: "Elephant`s Dream",
                poster: "https://mcp-media.storage.googleapis.com/anv-pvw/AF6/ABE/AF6ABE1D34FE42F3AAD5C72216AC41C7_7.jpg"
            },
            {
                url: "https://mcp-download.storage.googleapis.com/anv-videos/variant/3697658.m3u8",
                title: "Cosmos Laundromat",
                poster: "https://mcp-media.storage.googleapis.com/anv-pvw/F34/4C3/F344C330F8A147E4AA776B26550AD2EA_8.jpg"
            },
            {
                url: "https://mcp-download.storage.googleapis.com/anv-videos/variant/3697661.m3u8",
                title: "Caminandes 2",
                poster: "https://mcp-media.storage.googleapis.com/anv-pvw/B98/C0D/B98C0DBDD0404D56AD70119379477993_6.jpg"
            }
        ], 
        width: "100%"
    });
</script>

Configuration Options

Parameter	Type	Definition
url	String	External video url.
format	String	File format for the media asset (e.g. 'm3u8', 'mpd', 'mp4', 'mp3').
poster	String	Poster image URL (used in the absence of a default poster image or for overriding the one coming with the metadata)
live	Boolean	Live mode flag; needed while using external video url.
title	String	Used for overriding the existing title from metadata/specifying the title for external video url (applies to VOD only)
description	String	Used for overriding the existing description from metadata/specifying the description for external video url (applies to VOD only)
width	String	Player width in pixels or percent
height	String	Player height in pixels or percent
playlist	Array	Array of media info objects composed of `url` and additional parameters
volume	Number	Volume betwen 0 and 1
autoplay	Boolean	Autoplay mode
disableMutedAutoplay	Boolean	Used for disabling muted autoplay. When set to true while autoplay is enabled, the player will either autoplay with sound or not autoplay at all depending on what the browser allows. Default is false.
plugins	JSON	Contains the plugin parameters. Details are provided in Plugins section.
expectPreroll	Boolean	Used to prevent the player from starting the main content before a client-side preroll is loaded. Default is false.
expectPrerollTimeout	Number	Max number of seconds to wait for a client-side preroll before starting the main content. Only used when `expectPreroll` is true. Default is 5.
companions	Array of Objects	Used for registering companion containers with their width and height. Companion object format is given below.
logo	Object	Used for setting a logo overlay. Logo can be set using the API method: setLogo(). Logo object format is provided below.
share	Boolean	Used for disabling the share feature. Default is true.
shareLink	String	Used for overriding the share link detected by the player
clientSideAdTracking	Boolean	Used for pinging the tracking URL specified in VAST to demonstrate ad progress. Default value is true.
trackTimePeriod	Integer	Used for setting the TIME_UPDATED event period. This value must be to at least 1 (in second). TIME_UPDATED event will not be dispatched if this value is not set to a valid value.
control	Boolean	This flag is used for removing the player controls.
enablePictureInPicture	Boolean	This flag determines whether the player controls include a Picture-in-Picture button. Default value is false.
info	Boolean	This flag is used for removing the components providing info about the content such as title, description, poster image, etc.
360	Boolean	Used for enabling 360 view feature
recommendations	Boolean or Object	Used for enabling recommendation window. Providing true will use recommendations from MCP. Providing false will disable recommendations. To use custom recommendations, provide an object of the form `{ items: [...] }` where the `items` array has the same format as the `vList` argument in the Player.setRecommendations(vList) API function. The object may optionally include property `duration` to specify the default countdown in seconds. Default is false.
maxRecomPages	Number	Used to determine the maximum number of recommendation pages to show at the end of a playlist. Default is 3.
token	String	Used for activating the remote config and TVE services such as metadata lookup, schedule, geo station check and parental control.
styleNativeCaptions	Boolean	For videos that would normally use the browser's native caption settings and styling, setting this flag to true will cause the captions to use the Anvato player's caption settings and styles instead.
nativeHlsOnSafari	Boolean	Used for forcing native HTML5 video playback for HLS on Safari instead of Anvato's MSE player. Note that when this is true, the player is no longer able to track server-side ads. Default is false.
nativeHlsOnSafariForVod	Boolean	Similar to `nativeHlsOnSafari`, but only applies to VOD and not live streams. Default is false.
nativeHlsOnSafariForLive	Boolean	Similar to `nativeHlsOnSafari`, but only applies to live streams and not VOD. Default is false.
learnMore	Object	Used for styling the Learn More button displayed during DFP client-side ads on mobile devices. Learn More object format is provided below.
pauseOnClick	Boolean	Allows the user to pause the video when clicking on the video instead of the pause button specifically. Default is false.
liveDelayInSegments	Number	The number of segments from the live edge where the player will start playback for a live stream. For example, a value of 2 will have the player start playing from the second to last segment in the first live manifest. Default is 3.

Companion Object

AnvatoPlayer("p0").init({
    //...,
    companions: [
        {
            width: 160,
            height: 600,
            containers: [
                "companion-holder-1"
            ]
        }
    ]
});

Parameter	Type	Definiton
width	Number	The width of the companion placeholder
height	Number	The height of the companion placeholder
containers	Array	List of placeholder ids matching the width and height provided

Logo Object

AnvatoPlayer("p0").init({
    //...,
    logo: {
        url: "LOGO_URL",
        targetURL: "YOUR_TARGET_URL",
        location: "BR",
        margin: "3%",
        sizeFactor: 0.8
    }
});

Parameter	Type	Definiton
url	String	The logo URL
targetUrl	String	The target URL to be opened when the logo is clicked/tapped
location	String	"BR" for bottom right, "TR" for top right, "BL" for bottom left and "TL" for top left
margin	String	Margin to be calculated from the anchor point specified by `location`. Must be given in "px" or "%".
sizeFactor	Number	Used for resizing the logo. Default is 1 which sets the logo height to player height devided by 6.

Learn More Object

AnvatoPlayer("p0").init({
    //...,
    learnMore: {
        text: 'LEARN MORE',
        sizeFactor: 0.8,
        border: '0px solid #000',
        fontWeight: 600,
        //...,
    }
});

Parameter	Type	Definition
text	String	The text to display on the button.
sizeFactor	Number	Used for scaling the button font size. Default is 1.

You may also provide additional parameters that correspond to CSS styles.

Keyboard Controls

AnvatoPlayer('p0').init({
  keyMapping: {
    playPause: [75, 32], // k or Space
    rewind10Seconds: 74, // j
    rewind5Seconds: 37, // ArrowLeft
    fastForward5Seconds: 39, // ArrowRight
    fastForward10Seconds: 76, // l
    previousVideo: { // P (Shift + p)
      keyCode: 80,
      shiftKey: true,
    },
    nextVideo: { // N (Shift + n)
      keyCode: 78,
      shiftKey: true,
    },
    toggleFullscreen: 70, // f
    toggleMute: 77, // m
    volumeUp5Percent: 38, // ArrowUp
    volumeDown5Percent: 40, // ArrowDown
  }
});

Keyboard controls can be enabled for various player actions via the keyboardMapping config parameter. The parameter value should be an object whose keys are the player action names. The values are the keyCode values that trigger the player action.

In case any keyboard modifiers should also be pressed to trigger an action, the keyCode numeric value can be replaced by an object. The object should have a keyCode property with the numeric keyCode value, and the object may also have any of the following keyboard modifier properties set to true: altKey, ctrlKey, metaKey, shiftKey.

Additionally, the action can map to an array of keyCode values or objects in case multiple keys should map to the same player action.

Action Name	Description
playPause	Toggles between playing and pausing the video.
rewind10Seconds	Seeks backwards by 10 seconds.
rewind5Seconds	Seeks backwards by 5 seconds.
fastForward5Seconds	Seeks forwards by 5 seconds.
fastForward10Seconds	Seeks forwards by 10 seconds.
previousVideo	Plays the previous video in the playlist.
nextVideo	Plays the next video in the playlist.
toggleFullscreen	Toggles between entering and exiting fullscreen mode.
toggleMute	Toggles the volume level between muted and unmuted.
volumeUp5Percent	Increments the volume level by 0.05.
volumeDown5Percent	Decrements the volume level by 0.05.

There are various tools onlines that can help determine which keyCode corresponds to which key on the keyboard, such as this Keyboard Event Viewer.

The keyboard events will only trigger player actions if the player is focused (e.g. the user previously clicked on the player). This avoids unwanted behavior when multiple players are embedded on a single page.

An alternative to these keyboard configurations would be to listen to keyboard events on the application level and call the corresponding player API functions.

DRM Configuration

Widevine or PlayReady DRM configuration

AnvatoPlayer('p0').init({
  //...,
  drm: {
    servers: {
      'com.widevine.alpha': 'YOUR_LICENSE_SERVER_URL',
      'com.microsoft.playready': 'YOUR_LICENSE_SERVER_URL',
    }
  }
});

FairPlay DRM configuration

AnvatoPlayer('p0').init({
  //...,
  drm: {
    certificate: 'YOUR_BASE64_ENCODED_FAIRPLAY_CERTIFICATE',
    servers: {
      'com.apple.fps.1_0': 'YOUR_LICENSE_SERVER_URL'
    }
  }
});

The player supports playing DRM-protected content by passing the license server URL in the player configuration as shown in the sample code. For streams that use FairPlay DRM, the drm configuration includes the Base64 encoded FairPlay certificate as a parameter as well.

API Methods and Events

Accessing Player Instances

Each player instance can be accessed using the 'ready' callback function. This callback will be called once the instance is ready to accept API calls.

Using API Methods on Player Instances

AnvatoPlayer('p0').on('ready', function(playerInstance) {
  // Access API methods here
  // Either playerInstance or AnvatoPlayer('p0') can be used as a reference
  AnvatoPlayer('p0').play();
  AnvatoPlayer('p0').seekTo(90);
  AnvatoPlayer('p0').setVolume(.5);
  AnvatoPlayer('p0').getTitle(onResponse);
  AnvatoPlayer('p0').getDuration(onResponse);
});

function onResponse(result) {
  console.log('@onResponse result:', result);
}

API methods for which we do not need return values are called using the namespace, player instance name and method name.

API methods from which we are planning to retrieve a return value must be called using a callback function as the first argument. The referenced arguments of the API method must be given in an array if there are more than one arguments. One argument can be entered without array brackets.

Using API Events fired by Player Instances

A specific event can be listened using the on method. on method accepts both camel case form of the API events documented and uppercase form of them (for backwards compatibility).

Binding an event listener

AnvatoPlayer('p0').on('metadataLoaded', function(eventId, secondaryId, metadata, rawMetadata) {
  // use the arguments here
});

It is also possible to use the listener callback for listening to all events. All events are directed to the callback method provided by the SDK user by setting the listener callback of AnvatoPlayer singleton.

Unbinding a named event listener

A specific event listener can be turned off as long as it is not an anonymous function.

AnvatoPlayer('p0').on('userPause', onUserPaused);
AnvatoPlayer('p0').off('userPause', onUserPaused);

function onUserPaused() {
  console.log('this will not be called since its listener is turned off.');
}

Unbinding all event listeners for an event

In order to remove all listeners for a specific event unbindAll method can be used. This will even remove the anonymous listeners.

AnvatoPlayer('p0').unbindAll('userPause');

Event Sequence Live Demo

You can view the event progression as well as the common following use cases with this interactive tool

Loading the player behind an overlay/placeholder and displaying when the playback starts
Evaluating the proper player load and playback; replacing the player with an alternate content if some events are not received in a timely manner
Evaluating player load performance
Page level video analytics based on player events

API Functions

getTitle()

AnvatoPlayer('p0').getTitle(YOUR_CALLBACK_FUNCTION);

Provides the title of current item

Returns	Type
Video title	String

getDescription()

AnvatoPlayer('p0').getDescription(YOUR_CALLBACK_FUNCTION);

Provides the description of current item

Returns	Type
Video description	String

getDuration()

AnvatoPlayer('p0').getDuration(YOUR_CALLBACK_FUNCTION);

Provides the duration of current item

Returns	Type
Video duration	Number

getState()

AnvatoPlayer('p0').getState(YOUR_CALLBACK_FUNCTION);

Returns the player state

Returns	Type
Player state	(States provided in state diagram)

getEmbedCode()

AnvatoPlayer('p0').getEmbedCode(YOUR_CALLBACK_FUNCTION);

Provides the embed code (described in iframed embed option) for the current video item

Returns	Type
Embed code	String

getShareLink()

AnvatoPlayer('p0').getShareLink(YOUR_CALLBACK_FUNCTION);

Provides the share link for the current video item

Returns	Type
Share link	String

getBitrates()

AnvatoPlayer('p0').getBitrates(YOUR_CALLBACK_FUNCTION);

Provides available bitrates in kilobits per second

Returns	Type
Array of available bitrates in kilobits per second	Array

getCaptionLanguages()

AnvatoPlayer('p0').getCaptionLanguages(YOUR_CALLBACK_FUNCTION);

Provides available caption languages

Returns	Type
Array of available languages	Array

getCaptionStyle()

AnvatoPlayer('p0').getCaptionStyle(YOUR_CALLBACK_FUNCTION);

Provides the current caption style setting values

Returns	Type
Caption style settings	`CaptionStyleSettings`

getCurrentTime()

AnvatoPlayer('p0').getCurrentTime(YOUR_CALLBACK_FUNCTION);

Provides the current time/playhead time

Returns	Type
Current time in seconds	Number

getPlayerLanguages()

AnvatoPlayer('p0').getPlayerLanguages(YOUR_CALLBACK_FUNCTION);

Provides available player languages (for labels and notifications)

Returns	Type
Array of available languages	Array

getVolume()

AnvatoPlayer('p0').getVolume(YOUR_CALLBACK_FUNCTION);

Provides the player volume level

Returns	Type
Volume level between 0 and 1	Number

isFullscreen()

AnvatoPlayer('p0').isFullscreen(YOUR_CALLBACK_FUNCTION);

Gives player fullscreen mode

Returns	Type
True indicates fullscreen	Boolean

isPictureInPicture()

AnvatoPlayer('p0').isPictureInPicture(YOUR_CALLBACK_FUNCTION);

Provides player Picture-in-Picture mode

Returns	Type
True indicates Picture-in-Picture	Boolean

getPreviewState()

AnvatoPlayer('p0').getPreviewState(YOUR_CALLBACK_FUNCTION);

Provides preview state (available when Temp Pass is activated)

Returns	Type
Preview state either PASSIVE, LONG, SHORT or ENTITLEMENT	String

getViewStatus()

AnvatoPlayer('p0').getViewStatus(YOUR_CALLBACK_FUNCTION);

Used for getting the player’s viewability in the active window/tab (available for private beta clients)

Returns	Type
True for viewable, false for non-viewable	Boolean

getPlaylistIndex()

AnvatoPlayer('p0').getPlaylistIndex(YOUR_CALLBACK_FUNCTION);

Returns the index of the current playlist item

Returns	Type
Playlist item index	Number

setBitrate(bitrate)

AnvatoPlayer('p0').setBitrate(864);

Sets the video bitrate

Parameters:

Name	Type	Description
bitrate	number	Bitrate in kilobits per second

setCaption(language)

AnvatoPlayer('p0').setCaption('en');

Sets the caption language

Parameters:

Name	Type	Description
language	string	Caption language abbreviation - available with getCaptionLanguages() -

setCaptionStyle(style)

Sets caption style

Name	Type
style	`CaptionStyleSettings`

setPlayerLanguage(language)

AnvatoPlayer('p0').setPlayerLanguage('en');

Sets the player language (labels and notifications)

Parameters:

Name	Type	Description
language	String	Player language

setFullscreen(flag)

//This function must be called after a user interaction.
YOUR_BUTTON.onclick = function() {
    AnvatoPlayer('p0').setFullscreen(true);
};

Toggles on/off fullscreen mode. This method should be called based on a user interaction.

Parameters:

Name	Type	Description
flag	Boolean	True indicates fullscreen request, false indicates cancel fullscreen request

setPictureInPicture(flag)

YOUR_BUTTON.onclick = function() {
  AnvatoPlayer('p0').setPictureInPicture(true);
};

Toggles Picture-in-Picture mode. This method should be called based on a user interaction.

Parameters:

Name	Type	Description
flag	Boolean	True indicates Picture-in-Picture request, false indicates cancel Picture-in-Picture request

mute()

AnvatoPlayer('p0').mute();

Mutes the player

unmute()

AnvatoPlayer('p0').unmute();

Unmutes the player

setLogo(config)

Sets the player logo that will be displayed as an overlay

AnvatoPlayer('p0').setLogo({
  url: 'LOGO_URL_HERE',
  location: 'BR',
  margin: '5%',
  sizeFactor: .8
});

Name	Type	Description
config	Object	Object with keys: url, targetURL, location, margin, sizeFactor

showLogo()

Displays the player logo

AnvatoPlayer('p0').showLogo();

hideLogo()

Hides the player logo

AnvatoPlayer('p0').hideLogo();

setVolume(volume)

Sets the player volume

AnvatoPlayer('p0').setVolume(.5);

Parameters:

Name	Type	Description
volume	Number	Decimal number between 0 and 1

triggerUserInteraction()

AnvatoPlayer('p0').triggerUserInteraction();

Triggers user interaction which may be needed in preview flows.

play()

AnvatoPlayer('p0').play();

Plays the video content. Note that some browsers block programmatic play attempts for videos until the user manually initiates playback. As a result, this API method should not be used to autoplay videos. Instead pass in the autoplay embed parameter with the value true when initializing the player.

play(mediaInfo)

AnvatoPlayer('p0').play({
  url: 'https://mcp-download.storage.googleapis.com/anv-videos/variant/3697036.m3u8',
  format: 'm3u8',
  poster: 'https://mcp-media.storage.googleapis.com/anv-iupl/5FA/ACA/5FAACA8FB2F3459C81F2CEF515615DAF',
  title: 'Sintel',
  description: 'Third Open Movie by Blender Foundation'
});

Plays another video content associated with the accessKey. This API method is the recommended way for playing another video as opposed to reloading the player SDK.

Parameters:

Name	Type	Description
mediaInfo	Object	An object with id entry set to video id to be played

pause()

AnvatoPlayer('p0').pause();

Pauses the video content

destroy()

AnvatoPlayer('p0').destroy();

Destroys the player instance

seekTo(timeIndex)

Seeks to a given time index

AnvatoPlayer('p0').seekTo(9);

Parameters:

Name	Type	Description
timeIndex	Number	Seek position in seconds

catchLive()

Seeks to the edge of a live stream

AnvatoPlayer('p0').catchLive();

setRecommendations(vList)

Sets the list of video recommendations for the current video

var recommendations = [
  {
    url: 'https://mcp-download.storage.googleapis.com/anv-videos/variant/3697661.m3u8',
    format: 'm3u8',
    title: 'Caminandes 2',
    description: 'Gran Dillama - Blender Animated Short',
    image: 'https://mcp-media.storage.googleapis.com/anv-pvw/B98/C0D/B98C0DBDD0404D56AD70119379477993_6.jpg',
    duration: 146
  },
  {
    url: 'https://mcp-download.storage.googleapis.com/anv-videos/variant/3697658.m3u8',
    format: 'm3u8',
    title: 'Cosmos Laundromat',
    description: 'An in-development film project by the Blender Foundation',
    image: 'https://mcp-media.storage.googleapis.com/anv-pvw/B98/C0D/B98C0DBDD0404D56AD70119379477993_6.jpg',
    duration: 730,
  }
];
AnvatoPlayer('p0').setRecommendations(recommendations);

Parameters:

Name	Type	Description
vList	Array	A list of objects describing the metadata for each video recommendation. Each object must contain a video url and format ('m3u8', 'mp4', etc.). The objects should also contain a title, description, poster image URL, and video duration in seconds. Optionally, the objects may contain a live property stating whether the video is a live stream or not

changeProgram(eventId, eventMetadata)

Signals an event or program change for live programs

var eventMetadata = {
  title: 'NEW_EVENT_TITLE',
  description: 'NEW_EVENT_DESCRIPTION',
  rating: 'NEW_EVENT_RATING',
  derivedMetadata: {
    yourKey: 'YOUR_VALUE',
    anotherKey: 'ANOTHER_VALUE',
    // ...
  },
  // ...
}
AnvatoPlayer('p0').changeProgram('NEW_EVENT_ID', eventMetadata);

Parameters:

Name	Type	Description
eventId	String	The id of the new event
eventMetadata	Object	Metadata object with the program info as shown in the sample code. For more information about derived metadata, see the derived metadata section.

updateDerivedMetadata(derivedMetadata)

Updates the current derived metadata

AnvatoPlayer('p0').updateDerivedMetadata({
  yourKey: '',
  anotherKey: '',
  // ...
});

Parameters:

Name	Type	Description
derivedMetadata	Object	An object containing derived metadata key-value pairs

saveSnapshot()

Saves the current video frame as an image file

function onSnapshot(success) {
    if (success) {
        console.log('Saved');
    } else {
        console.log('Failed');
    }
}

// saves a snapshot with the default file name and configuration
AnvatoPlayer('p0').saveSnapshot(onSnapshot);

// saves snapshots with custom file names and inferred image types
AnvatoPlayer('p0').saveSnapshot(onSnapshot, 'snapshot.png');
AnvatoPlayer('p0').saveSnapshot(onSnapshot, 'snapshot.jpg');

// saves a snapshot with custom configuration
AnvatoPlayer('p0').saveSnapshot(onSnapshot, {
    filename: 'snapshot',
    type: 'image/jpeg',
    quality: 0.5
});

Parameters:

Name	Type	Description
onSnapshot	function	A callback function that is passed `true` if the snapshot succeeds or `false` if the snapshot fails
filename	string	The name of the image file

saveSnapshot() alternatively accepts the following parameters:

Name	Type	Description
onSnapshot	function	A callback function that is passed `true` if the snapshot succeeds or `false` if the snapshot fails
saveSnapshotConfig	Object	An object describing how the snapshot should be generated

The saveSnapshotConfig object has the following properties:

Property	Type	Description
filename	string	The name of the image file
type	string	The MIME type of the image file
quality	number	A number between 0 and 1 that specifies the compression level for lossy image formats

getSnapshot()

Gets the current video frame as an image Data URL

function onSnapshot(url) {
    if (url) {
        console.log(url);
    } else {
        console.log('Failed to take snapshot');
    }
}

// gets a snapshot with the default file name and configuration
AnvatoPlayer('p0').getSnapshot(onSnapshot);

// gets snapshots with MIME types inferred from image file names
AnvatoPlayer('p0').getSnapshot(onSnapshot, 'snapshot.png');
AnvatoPlayer('p0').getSnapshot(onSnapshot, 'snapshot.jpg');

// gets a snapshot with custom configuration
AnvatoPlayer('p0').getSnapshot(onSnapshot, {
    type: 'image/jpeg',
    quality: 0.5
});

Parameters:

Name	Type	Description
onSnapshot	function	A callback function that is passed the image Data URL if the snapshot succeeds or `false` if the snapshot fails
filename	string	A file name from which to infer the image type

getSnapshot() alternatively accepts the following parameters:

Name	Type	Description
onSnapshot	function	A callback function that is passed `true` if the snapshot succeeds or `false` if the snapshot fails
getSnapshotConfig	Object	An object describing how the snapshot should be generated

The getSnapshotConfig object has the following properties:

Property	Type	Description
filename	string	A file name from which to infer the image type
type	string	The MIME type of the image
quality	number	A number between 0 and 1 that specifies the compression level for lossy image formats

API Events

Event Format

{ sender: {player instance ID}, name: {event name}, time: {event time}, info: {event definition}, args: {array of arguments} }

Events are dispatched by the player instance using the following format. Sender value is available when IFRAMED JS embed option is utilized since this option supports multiple player instances.

Event List

Event Name	Event definition	Arguments
STATE_CHANGE	Player state has changed	Player state
CLIENT_BANDWIDTH	Client bandwidth estimated	Bandwidth in kilobits per second
FIRST_FRAME_READY	First frame is ready	None
PLAYING_START	Player started playing for the first time	Playback origin
TIME_UPDATED	Playhead updated while playing the video content (Only fired if trackTimePeriod is set in embed parameters)	video time (VOD) / time stamp (Live) in seconds live flag video id video title
VIDEO_STARTED	Video item started	video ID video title
VIDEO_FIRST_QUARTILE	Video playhead passed the first quartile	video ID video title
VIDEO_MID_POINT	Video playhead passed the midpoint	video ID video title
VIDEO_THIRD_QUARTILE	Video playhead passes the third quartile	video ID video title
VIDEO_COMPLETED	Video item completed	video ID video title
PLAYLIST_COMPLETED	All videos in playlist are completed	playlist ID
AD_STARTED	Ad content started	ad ID ad title ad provider Ad Detail (available for SSAI only)
AD_FIRST_QUARTILE	Ad content passed the first quartile	ad ID ad title ad provider
AD_MID_POINT	Ad content passed the mid point	ad ID ad title ad provider
AD_THIRD_QUARTILE	Ad content passed the third quartile	ad ID ad title ad provider
AD_COMPLETED	Ad content completed	ad ID ad title ad provider
ALL_ADS_COMPLETED	All ad videos completed	ad provider
AD_CLICKED	User clicked on the ad content	ad ID ad title ad provider
COMPANION_AVAILABLE	A companion is available for injection	payload type creative type width height payload
USER_INTERACTION	User has interacted with the player	interaction type Content type (“video” or “ad”) id (video id or ad id)
PREVIEW_STATUS	Preview state has changed	preview state preview/provider ID expiration time
PREVIEW_EXPIRED	Live preview has finished	preview state
PROGRAM_CHANGED	Live program has changed	event Id upid (another identifier used as a key for metadata lookup) metadata object with properties: title description rating mvpdAuthenticationNeeded tveCheckNeeded
NEXT_PROGRAM	Next program information has arrived	event Id upid (another identifier used as a key for metadata lookup) metadata object with properties: title description rating mvpdAuthenticationNeeded tveCheckNeeded
METADATA_LOADED	Program metadata has changed	event Id upid (another identifier used as a key for metadata lookup) metadata object with properties: title description rating ownerId tags categories
AUTHENTICATION_STATUS	Authentication status has changed	isAuthenticated authenticator
AUTHORIZATION_STATUS	Authorization status has changed	isAuthorized authorizer token error code (if failed)
HOMEZIP_DETECTED	User’s home zip detected	home zip
ENCRYPTED_HOMEZIP_DETECTED	User’s home zip detected	encrypted home zip
MAX_RATING_DETECTED	User’s allowed max rating detected	max rating
PROVIDER_LIST_SET	Provider list is available	Provider look-up table
PROVIDER_SELECTED	User selected a provider/previously selected provider has been set	provider ID
PICKER_REQUESTED	MVPD picker has been requested. (This event can be used as an opportunity to display custom MVPD picker dialogs if the default picker is disabled.)	None
PICKER_DISPLAYED	MVPD picker has been displayed	None
POPUP_BLOCKED	Browser has blocked the popup	None
POPUP_DISPLAYED	Browser has allowed the popup	None
GEOLOCATION_STATUS	User’s geolocation information updated	longitude latitude error code (if failed)
AD_IMMINENT	There will be an ad break in given seconds	startsIn (seconds)
SEGMENT_TYPE_CHANGED	Stream segment type has changed (applies to the ad stitched streams)	Segment type (“master”, “ad” or “slate”)
PROVIDER_IFRAME_INJECTED	Provider IFrame has been injected	Provider Id IFramed Login Placeholder Id
PROVIDER_IFRAME_REMOVED	Provider IFrame has been removed	IFramed Login Placeholder Id
VIEW_STATUS	The player is viewable in active window/tab (available for private beta clients)	isViewable (Boolean)
LOADER_READY	Loader is ready
SUBSCRIBER_AUTHORIZATION_STATUS	Subscriber authorization status has changed	authZ status
PLAYLIST_CHUNK_AVAILABLE	Playlist chunk is available	Array of playlist items
TIME_DELTA	Time difference between client and server detected	Difference between server time and browser time
CHROMECAST_STATUS	Chromecast status has changed	chromecast status
VERIFICATION_STATUS	Chromecast verification status has changed	verification satatus
PLAYER_ERROR	Player has thrown an error	Error information (Explained in Error Messages section)
USER_PLAY	User has started the playback	None
USER_RESUME	User has resumed the content	None
USER_GOLIVE	User has selected golive	None
USER_PAUSE	User has paused the playback	None
USER_MUTE	User has muted the audio	None
USER_UNMUTE	User has unmuted the audio	None
USER_SHARE	User has shared a content	None
USER_FORWARD_SEEK	User has seeked forwards	Current time target time
USER_BACKWARD_SEEK	User has seeked backwards	Current time target time
USER_FULLSCREEN	User has toggled on Fullscreen mode	None
USER_CANCEL_FULLSCREEN	User has toggled off Fullscreen mode	None
AD_BREAKS	Ad breaks detected in the content	Array of ad breaks
AD_BREAK_STARTED	Ad break has started	Ad break index Ad index
AD_BREAK_COMPLETED	Ad break has completed	Ad break index ad index
BUFFER_LIMIT_UPDATED	Buffer limit has been updated	Buffer limit
PRESENTATION_UPDATED	Current time, total time or content type has changed. For ads, time index and duration correspond to the ad break with the exception of client-side DFP ads where time index and duration correspond to the current ad.	time index duration presentation content type adIndex total ads in the ad break
BUFFER_START	Buffering has started	None
BUFFER_END	Buffering has completed	None
ID3	ID3 tag detected	Timed metadata payload publisher
POSTER_LOADED	Poster image has been loaded	None
COMPONENTS_INITIALIZED	Player UI components have been initialized	None
BITRATE_LIST_UPDATED	Bitrate list has been updated with available rendition bitrates	bitrateList resolutionMapping (from bitrate to resolution - WIDTHxHEIGHT in pixels if resolution is available in the manifest- )
BITRATE_CHANGED	Bitrate value has been updated	Current bitrate
BITRATE_CHANGE_IN_PROGRESS	There is a pending birate change	Target bitrate
TIME_DELTA	Time difference between client and server detected	time delta (msec)
MEDIA_URLS_SET	Published media URLs are available	Media URL objects array
BEFORE_VIDEO_LOAD	Player has notified the check point before video load	Video information object Embed configuration
PLAYLIST_ITEM_CHANGED	Playlist item index has been updated	playlist item index media Id
CAPTION_DETECTED	The player has detected closed captions	Array of available languages
AUTOPLAY_STATUS	The player's autoplay capability for the current video based on the browser's autoplay policy. The status value is `NONE` if there is no intent of autoplay, `BLOCKED` if the browser completely blocks autoplay, `MUTED` if muted autoplay is allowed, or `UNMUTED` if unmuted autoplay is allowed.	autoplay status

Playback Origins

Enum for playback origins exposed with PLAYING_START event

Properties

Name	Type	Default
INITIAL	`number`	`0`
PLAYLIST_MANUAL	`number`	`1`
PLAYLIST_AUTO_ADVANCE	`number`	`2`
RECOMMENDATION_MANUAL	`number`	`3`
RECOMMENDATION_AUTO_ADVANCE	`number`	`4`
PLAY_API_METHOD	`number`	`5`

Ad Detail

AdDetail : `Object`

AdDetail : Object
- .adIndex : number
- .totalAds : number
- .tracking : Object
  - .clickThrough : Array.<String>
  - .clickTracking : Array.<String>

AdDetail.adIndex : `number`

The ad index within the current ad break

AdDetail.totalAds : `number`

The total number of ads in the current ad break

AdDetail.tracking : `Object`

AdDetail.tracking : Object
- .clickThrough : Array.<String>
- .clickTracking : Array.<String>

tracking.clickThrough : `Array.<String>` | `null`

Click through URI for application layer rendering their own UI to display a page when user clicks on ad video

tracking.clickTracking : `Array.<String>` | `null`

Click tracking URIs for application layer rendering their own UI to track when the user clicks on the ad video

API Hooks

The following API hooks are triggered by certain player events. When an API hook is triggered, the player executes your callback function and uses the returned value before continuing.

NOTE: These API hooks should be registered before calling .init(...) on the player instance.

onBeforeVideoLoad

onBeforeVideoLoad

AnvatoPlayer('p0').on('beforeVideoLoad', function(mediaInfo, initConfig) {
  // mediaInfo.id can be used for identifying the asset
  // config can be modified based on mediaInfo.id
  return initConfig; // finally modified config is returned
});

SDK calls this hook before loading the media and ads. Application layer can modify the initConfig inside this hook and return modified initConfig (typically client-side ad settings are modified).

Parameters:

Name	Type	Description
mediaInfo	Object	Media info object in which media is identified with id entry. For external URLs id is populated with the md5 of the media url
initConfig	Object	Init configuration that is generated by merging application side and remote configuration. Plugins entry is often the point of interest for this hook

onBeforeSeek

onBeforeSeek

AnvatoPlayer('p0').on('beforeSeek', function(info) {
  var adBreakIndexToWatch = null;
  // info object can be used to determine which ad break
  // to watch before completing the seek. Set the
  // adBreakIndexToWatch variable to the desired
  // ad break index.
  return { watchAdBreakIndex: adBreakIndexToWatch };
});

SDK calls this hook when the user issues a seek but before the player completes the seek. Application layer can return an object that specifies whether the user should first watch an ad break before completing the seek.

Parameters:

Name	Type	Description
info	Object	Info object describing the seek and ad break information for the current video.

The info object contains the following properties:

seekFrom: Number - The current playhead time in seconds. This is the absolute playhead time that includes both the content and the stitched ad breaks.
seekTo: Number - The seek destination in seconds.
adBreaks: Array<Object> - An array containing information about the ad breaks for the current video. Each ad break info object contains the adBreakIndex, the start time index of the ad break in seconds, and the end time index of the ad break in seconds.

Returns	Type
An object with an optional `watchAdBreakIndex` property. Set this value to an ad break index value (0-indexed) to have the user watch that ad break before completing the seek. By default the player will complete the seek immediately.	Object

onBeforeAdBreak

onBeforeAdBreak

AnvatoPlayer('p0').on('beforeAdBreak', function(info) {
  var skipAdBreak = false;
  // info object can be used to determine whether the
  // player should skip the ad break or not. Set the
  // skipAdBreak variable to true in order to have the
  // player skip the ad break.
  return { skipAdBreak: skipAdBreak };
});

SDK calls this hook before each server-side ad break. Application layer can return an object that specifies whether the player should skip the ad break or not (for VOD assets only).

Parameters:

Name	Type	Description
info	Object	Info object describing the ad break information.

The info object contains the following properties:

currentTime: Number - The current playhead time in seconds. This is the absolute time index that includes both the content and the stitched ad breaks.
adBreakIndex: Number - The ad break index for the ad break that is about to play.
adBreaks: Array<Object> - An array containing information about the ad breaks for the current video. Each ad break info object contains the adBreakIndex, the start time index of the ad break in seconds, and the end time index of the ad break in seconds.

Returns	Type
An object with an optional `skipAdBreak` property. Set this value to true to have the player skip the ad break. By default the player will not skip the ad break.	Object

onBeforeBitrateMenuUpdated

onBeforeBitrateMenuUpdated

AnvatoPlayer('p0').onBeforeBitrateMenuUpdated = function(bitrateList, resolutionMapping) {
  var resolutionLabels = {};
  var resolutionLabel;
  var height;
  for (var bitrate in resolutionMapping) {
    if (!resolutionMapping.hasOwnProperty(bitrate)) {
      continue;
    }
    resolutionLabel = resolutionMapping[bitrate];
    resolutionLabel = resolutionLabel.split('x');
    if (resolutionLabel.length == 2) {
      height = resolutionLabel[1];
      resolutionLabel = height + 'p';
    }
    // showcasing 2 common customizations: friendly labels or picture height
    if (useFriendlyLabels) {
      resolutionLabels[bitrate] = getFriendlyLabel(height);
    } else {
      resolutionLabels[bitrate] = resolutionLabel;
    }
  }
  return resolutionLabels;
};

// helper method for converting height to friendly label
function getFriendlyLabel(height) {
  height = parseInt(height);
  if (height < 360) {
    return 'Low';
  } else if (height < 480) {
    return 'Medium';
  } else if (height < 720) {
    return 'High';
  } else if (height < 2160) {
    if (height == 720) {
      return 'HD 720';
    } else if (height == 1080) {
      return 'HD 1080';
    }
    return 'HD';
  } else if (height == 2160) {
    return '4K';
  }
}

SDK calls this hook before updating the bitrate list displayed with the quality button on control bar for default UI. SDK expects the application layer to return an object with each bitrate value given in the bitrateList as a key mapping to its custom label.

For custom UI this hook is called before calling setAvailableBitrates. And the returned custom label object is passed to the custom control bar instance using the third argument.

Parameters:

Name	Type	Description
bitrateList	Array	List of bitrates in kilobits per second unit
resolutionMapping	Object	Object with mapping from bitrate to resolution. Resolution is given as a string in the format of WIDTHxHEIGHT in pixel unit.

Returns	Type
Custom bitrate label mapping from bitrate to custom label.	Object

Type Definitions

CaptionStyleSettings

Name	Type
fontType	AnvatoPlayer.CaptionStyle.FontType
fontSize	Number
textColor	AnvatoPlayer.CaptionStyle.Color
textAlpha	AnvatoPlayer.CaptionStyle.PresetLevel
textAlign	AnvatoPlayer.CaptionStyle.TextAlign
bgColor	AnvatoPlayer.CaptionStyle.Color
bgAlpha	AnvatoPlayer.CaptionStyle.PresetLevel
textEdge	AnvatoPlayer.CaptionStyle.TextEdgeStyle
highlightColor	AnvatoPlayer.CaptionStyle.Color
highlightAlpha	AnvatoPlayer.CaptionStyle.PresetLevel
scale	Boolean
capitalize	Boolean
override	Boolean