nexAPI.md

NexPlayer™ API

---

Overview

---

Nexplayer methods

• Setup(configObj)
• UnMount(div)
• PlayerEvents(event,callback)
• AdsEvents(event,callback)

Player methods

Miscellaneous

• init(configObj)
• play()
• pause()
• seek(value)
• Environment
• DefaultConfig
• destroy()

Getters

• getAudioStreams() ⇒ Array<AudioStream>
• getCurrentAudioTrack() ⇒ AudioTrack
• getCurrentSubtitle() ⇒ number
• getCurrentTime() ⇒ number
• getCurrentTrack() ⇒ Track
• getDuration() ⇒ number
• getQualityLevels() ⇒ Array
• getSubtitles() ⇒ Array
• getThumbnailAt() ⇒ Promise
• getThumbnails() ⇒ Array<Frame>
• getTracks() ⇒ Array<Track>
• getURL() ⇒ string
• getVersion() ⇒ string
• getPlayerDiv() ⇒ string
• getPlayerContainerDiv() ⇒ string
• getAdInstance() ⇒ string
• getVolume() ⇒ number
• getMute() ⇒ boolean
• getLogger() ⇒ Logger
• isCurrentAssetAd() ⇒ boolean
• isCurrentAssetMuted() ⇒ boolean
• isSeeking() ⇒ boolean

Setters

• setAudio(streamID)
• setCurrentTrack(trackID)
• setCurrentSubtitle(subID)
• setVolume(number)
• setMute(boolean)
• setLogger(logger)

Global Typedefs

• NexPlayerDRMOptions : object
• DRMCustomData : object
• Captions : object
• Thumbnails : object
• ICaptionsDisplayer : object

Ads methods

Miscellaneous

• play()
• pause()
• registerPlugin(ads)
• isAdPlaying()
• skip()
• checkInitialAds()

Getters

• getAdType() ⇒ string
• getAdTitle() ⇒ string
• getAdDuration() ⇒ number
• getAdRemainingTime() ⇒ number
• getMute() ⇒ boolean
• getVolume() ⇒ number
• getAdBreaks() ⇒ Object

Setters

• setMute(state)
• setVolume(value)

---

Nexplayer methods

---

nexplayer.Setup(configObj)

Creates and initializes the player.

Type: instance method of nexplayer
Parameters: configObj is an object which values could be:

Param	Type	Description
key	string	NexPlayer key to validate the playback.
div	HTMLDivElement	The div container of the player.
src	string	URL of the video to be played.
drm	NexPlayerDRMOptions	Contains an object of DRM information. By default it's set to null.
adURL	string	Contains an object of DRM information. By default it's set to null.
adsParamsToEncode	Array	Array of strings specifying the parameters in the ad URL to be encoded.
autoplay	boolean	Determines if the video must start playing or paused. True by default.
callbacksForPlayer	Function	Used for retrieving the NexPlayer instance and video element. This is necessary for getting the instance and use the NexPlayer API.
captionDisplayer	ICaptionsDisplayer	Used to provide a custom CaptionDisplayer. Tihs allows to implement the internal logic for the captions.
debug	boolean	Determines if log information is showed. By default is set to true.
externalSubtitles	Captions	Used to provide a WEBVTT file as external subtitles.
mutedAtStart	boolean	Determines if the video will start playing muted or not. False by default.
resumePosition	number	Determines the position where the video will start playing.
thumbnails	Thumbnails	Thumbnails to be shown. Static and dynamic thumbnails are supported.
trailer	boolean	Determines if a stream should be considered a trailer.
useNewRelicTracker	boolean	Determines if the New Relick tracker will be used.
vast	string	Advertisement url that is going to be played. VAST, VPAID, VMAP are supported.

nexplayer.UnMount(div)

Unmounts the player and its dependencies.

Type: instance method of nexplayer
Parameters:

Param	Type	Description
div	HTMLElement	Player tag

nexplayer.PlayerEvents(event, callback)

Listens for player events.

Type: instance method of nexplayer
Parameters:

Param	Type	Description
event	string	Event name
callback	function	Callback function

nexplayer.AdsEvents(event, callback)

Listens for ads events.

Type: instance method of nexplayer
Parameters:

Param	Type	Description
event	string	Event name
callback	function	Callback function

---

Player methods

---

Miscellaneous

---

player.init(configObj)

Initialize the player with the config object given.

Type: instance method of Player

player.play()

Plays the video when it is paused.

Type: instance method of Player

player.pause()

Pauses the video when it is playing.

Type: instance method of Player

player.seek(value)

Seek the video to the value given.

Type: instance method of Player

player.isSeeking()

Return a boolean, true if the player is seeking and false if not.

Type: instance method of Player

player.Environment()

Returns which browser, platform and device type are set.

Type: instance method of Player

player.DefaultConfig()

Sends the default configuration in case the parameters are not specified in the init.

Type: instance method of Player

player.destroy()

Destroy the player

Type: instance method of Player

---

Getters

---

player.getAudioStreams() ⇒ Array.< AudioStream >

Gets the available audio streams.

Type: instance method of Player
Returns: An Array - which contains the available audio streams.

player.getCurrentAudioTrack() ⇒ AudioTrack

Gets the audio track currently in use.

Type: instance method of Player
Returns: AudioTrack - The current audio track.

player.getCurrentSubtitle()

Gets the current subtitle info.

Type: instance method of Player
Returns: Current Subtitle - the current subtitle track (undefined if no subtitles are activated).

player.getCurrentTime() ⇒ number

Returns the currentTime taking into account isUTC (if isUTC is true, getCurrentTime's returned value will be different from the time of the video element).

Type: instance method of Player
Returns: number - the current time of the video.

player.getCurrentTrack() ⇒ Track

Gets the current track information.

Type: instance method of Player
Returns: Track - the current track.

player.getDuration() ⇒ number

Returns the duration taking into account isUTC (if isUTC is true, getDuration's returned value will be different from the duration of the video element).

Type: instance method of Player
Returns: number - the duration of the video.

##### player.getQualityLevels() ⇒ Array

Gets the video quality levels array.

Type: instance method of Player
Returns: Array - quality levels array info

player.getSubtitles()

Gets all the avaliable subtitle tracks info.

Type: instance method of Player
Returns: Array of subtitles - the subtitle tracks of the video.

player.getThumbnailAt() ⇒ Promise

Returns a thumbnail loading promise in a specific time.

Type: instance method of Player
Returns: Promise - Thumbnail loading promise in a specific time.

player.getThumbnails() ⇒ Array < Frame >

Returns the loaded thumbnails.

Type: instance method of Player
Returns: Array < Frame > - The loaded thumbnails.

player.getTracks() ⇒ Array.< Track >

Gets all of the videos avaliable tracks (different qualities).

Type: instance method of Player
Returns:: Array.< Track > - all the tracks available.

player.getURL()

Returns the current video URL.

Type: instance method of Player
Returns: String

player.getVersion()

Returns the current version of the player.

Type: instance method of Player
Returns: String

player.getPlayerDiv()

Returns the video container.

Type: instance method of Player
Returns: HTMLDivElement

player.getPlayerContainerDiv()

Returns the player container.

Type: instance method of Player
Returns: HTMLDivElement

player.getAdInstance()

Returns the AdInstance Object.

Type: instance method of Player
Returns: Object

player.getVolume()

Returns the current volume of the Player.

Type: instance method of Player
Returns: number

player.getMute()

Returns true if the video is muted and false if not.

Type: instance method of Player
Returns: boolean

player.getLogger()

Returns the logger of the Player.

Type: instance method of Player
Returns: Object

player.isCurrentAssetAd()

Returns a boolean, true if the current playing asset is an ad, false if not.

Type: instance method of Player

player.isCurrentAssetMuted()

Returns a boolean, true if the current playing asset is muted, false if not.

Type: instance method of Player

player.isSeeking()

Returns a boolean, true if the player is seeking and false if not.

Type: instance method of Player

---

Setters

---

player.setAudio(streamID)

Sets the current audio stream.

Type: instance method of Player

Param	Type	Description
streamID	number	ID of the audio stream to be used.

player.setCurrentTrack(trackID)

Sets the current track.

Type: instance method of Player

Param	Type	Description
trackID	number	ID of the track to be used.

player.setCurrentSubtitle(subID)

Sets the current subtitle.

Type: instance method of Player

Param	Type	Description
subID	number	ID of the subtitle to be used.

player.setVolume(value)

Set the volume of the video.

Param	Type	Description
value	number	The volume level to be used.

player.setMute(boolean)

Set mute or unmute to the video.

Param	Type	Description
boolean	boolean	If the video will be mute or unmute.

player.setLogger(logger)

Set logger to the video.

Param	Type	Description
logger	Object	The logger to be used.

---

Global typedefs

---

Player.NexPlayerDRMOptions : Object

Type: global typedef Properties:

Name	Type	Description
keySystem	string	DRM's keySystem type. I.E.: "com.widevine.alpha"
license	string	DRM's license.
customData	DRMCustomData	Used to indicate the custom headers necessary to request the license. Optional.

Player.DRMCustomData : Object

Type: global typedef Properties:

Name	Type	Description
fieldName	string	Header's name .
value	string	Value used in the DRM's request.

Player.Captions : Object

Type: global typedef Properties:

Name	Type	Description
src	string	Caption's URL.
language	string	Language of the captions. Use to identificate them.

Player.Thumbnails : Object

Type: global typedef Properties:

Name	Type	Description
canvas	HTMLCanvasElement	Canvas used to display the thumbnails.
urlVtt	string	VTT's URL.
urlImg	string	Image to extract thumbnails from.
chunkLimit	number	Number of thumbnails' chunks available at the same time.
chunkTotal	number	Number of thumbanils' chunks in total.

Player.ICaptionsDisplayer : Class

Type: global typedef Properties:

Name	Type	Description
_videoContainer	HTMLElement	Canvas used to display the thumbnails.
_captionsContainer	HTMLElement	VTT's URL.

Functions:

Name	Params	Returns	Description
init	cues: Array	void	Initializes the Caption Displayer.
destroy	None	void	Destroy the Caption Displayer.
reset	None	void	Resets the Caption Displayer.
setTextVisibility	visible: boolean	void	Shows/hides the captions.
updateCue	time: number	void	Called to update the current cues to display.
displayCuesCC	cuesCC:Map<string, Object>	void	Displays the CC cues passed. Object properties: "text", "position", and "rgba".

---

Ads methods

---

Miscellaneous

---

nexplayer.AdInstance().play()

Plays the ad when it is paused.

Type: instance method of nexplayer

nexplayer.AdInstance().pause()

Pauses the ad when it is playing.

Type: instance method of nexplayer

nexplayer.AdInstance().registerPlugin(ads)

ads is an Object that implements IAds interface, The users can pass their own implementation in case they want to use another advertisement library or a custom one.

Type: instance method of nexplayer

nexplayer.AdInstance().isAdPlaying()

Return a boolean, true if the ad is playing and false if not.

Type: instance method of nexplayer

nexplayer.AdInstance().skip()

Skip the current ad if possible.

Type: instance method of nexplayer

nexplayer.AdInstance().checkInitialAds()

Checks whether there ads

Type: instance method of nexplayer

---

Getters

---

nexplayer.AdInstance().getAdType() ⇒ string

Gets the current Ad type.

Type: instance method of nexplayer
Returns: String - The current ad type.

nexplayer.AdInstance().getAdTitle() ⇒ string

Gets the Ad title.

Type: instance method of nexplayer
Returns: String - The current ad title.

nexplayer.AdInstance().getAdDuration() ⇒ number

Gets the Ad duration.

Type: instance method of nexplayer
Returns: number - The current ad duration.

nexplayer.AdInstance().getAdRemainingTime() ⇒ number

Gets the Ad remaining time.

Type: instance method of nexplayer
Returns: number - The ad remaining time.

nexplayer.AdInstance().getMute() ⇒ boolean

Gets the true if the video is muted or false if not.

Type: instance method of nexplayer
Returns: boolean - True if the video is muted or false if not.

nexplayer.AdInstance().getVolume() ⇒ number

Gets the Ad volume.

Type: instance method of nexplayer
Returns: number - The ad volume.

nexplayer.AdInstance().getAdBreaks() ⇒ Object

Returns the break points when ads will trigger

Type: instance method of nexplayer
Returns: Object - The break points when ads will trigger

---

Setters

---

nexplayer.AdInstance().setMute(state)

Mutes or unmutes the ad.

Param	Type	Description
state	boolean	If the ad will be mute or unmute.

nexplayer.AdInstance().setVolume(value)

Set the volume of the ad.

Param	Type	Description
value	number	The volume level to be used.

---

Advanced usage

Events

Player Events

We have events to handle some different kind of player events. List of player events available:

• statechanged: Event is fired when the state of player is changed, contains in the detail attribute the different states of the player (Ready, Buffering, Playing, Paused, Ended)
• playercreating: Event lauched when the player is being created.
• playercreated: Event launched when the player has been created.
• playerdestroyed: Event launched when the player has been destroyed.
• play: Event launched when play is requested.
• playing: Event launched when the player is played.
• pause: Event launched when pause is requested.
• paused: Event launched when the player is paused.
• seeking: Returns a boolean. True when is seeking, false otherwise.
• seeked: Event launched when the stream has been seeked.
• stalled: Event launched when the stream has been stalled.
• hovering: Event launched when the cursor hovers over the seekbar.
• durationchange: Event launched when video duration is changed.
• timeupdate: Event launched when the video element duration changes.
• loadstart: Event launched when the player starts loading.
• loadeddata: Event launched when the manifest is loaded.
• canplay: Event launched when the player is ready to play.
• buffering: Event launched when the player is buffering.
• bufferType: Event launched indicating what type of buffering happened: "Connection", "Initial", "Seek" or "Background".
• videofirstquartile: Event is fired when the 25% of the video’s duration has been reached.
• videomidpoint: Event is fired when the 50% of the video’s duration has been reached.
• videothirdquartile: Event is fired when the 75% of the video’s duration has been reached.
• ended: Event launched when the stream has been finished.
• subtitlesdataloaded: Event launched when captions are loaded.
• newsubtitlesdataloaded: Event launched when new captions are loaded.
• ccnewdata: Event launched when new captions are received.
• thumbnaildata: Event launched when a thumbnail data is received.
• thumbnailloaded: Event launched when a thumbnail is loaded to the thumbnail array.
• thumbnailreply: Event launched when a thumbnail is provided to the canvas.

Example on how to listen for a player event:

    nexplayer.PlayerEvents("playing", function(e) {
        console.log("playing", e);
    });

Ads Events

We have events to handle some different kind of ads events. List of ad events available:

• adlibrarycreating: Creates a library with all ads when the player is started.
• adlibrarycreated: Event launched when the ads library is created.
• adlibrarydestroyed: Destroys the library with all ads when the player is started.
• adpodsinfo: Contains all ad pods information.
• adblockstarted: Contains the number of ads in the block in the detail attribute.
• adblockend: Event launched when an ad block (some ads in the same timestamp) ends.
• adstarted: Event launched when when the ad has started, contain the ad position in the block in the detail attribute.
• adtagstartloading: Event launched when the ad starts.
• adloaded: Event launched when the ad has been loaded.
• adcomplete: Event launched when the ad has ended.
• addestroyed: Event launched when the ad has been destroyed after ended.
• adpaused: Event launched when an ad is paused.
• adresumed: Event launched when an ad is resumed.
• adskipped: Event launched when an ad is skipped.
• adfirstquartile: Event is fired when the 25% of the ad’s duration has been reached.
• admidpoint: Event is fired when the 50% of the ad’s duration has been reached.
• adthirdquartile: Event is fired when the 75% of the ad’s duration has been reached.
• adimpression: Event launched when ad impression is sent to the server.
• aderror: Event launched when there is an error loading the ad.
• adpodcompleted: Event launched when an ad block has been completed.

    nexplayer.AdsEvents("aderror", function(e) {
        console.log("aderror", e);
    });