Skip to content

api.md

Latest commit

 

History

History
721 lines (456 loc) · 21.5 KB

api.md

File metadata and controls

721 lines (456 loc) · 21.5 KB

NexPlayer API

Nexplayer methods

Player methods

Getters

Setters

Global Typedefs

Ads methods

Nexplayer methods

nexplayer.Setup(configObj)

Creates and initializes the player.

Type: instance method of Player

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.
adsParamsToEncode Array Array of strings specifying the parameters in the ad URL to be encoded.
adURL string Contains an object of DRM information. By default it's set to null.
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. This 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 subtitle files 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 Relic 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.

Parameters:

Param Type Description
div HTMLElement Player tag

nexplayer.PlayerEvents(event, callback)

Listens for player events.

Parameters:

Param Type Description
event string Event name
callback function Callback function

nexplayer.AdsEvents(event, callback)

Listens for ads events.

Parameters:

Param Type Description
event string Event name
callback function Callback function

Player methods

player.init(NexPlayerConfig)

Initializes the player with the config Object given.

player.play()

Plays the video when it is paused.

player.pause()

Pauses the video when it is playing.

player.seek(value)

Seeks the video to the value given.

player.Environment()

Returns which browser, platform and device type are set.

player.DefaultConfig()

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

player.destroy()

Destroys the player

Getters

player.getAudioStreams() ⇒ Array.< AudioStream >

Gets the available audio streams.

Returns: An Array - which contains the available audio streams.

player.getCurrentAudioTrack() ⇒ AudioTrack

Gets the audio track currently in use.

Returns: AudioTrack - The current audio track.

player.getCurrentSubtitle()

Gets the current subtitle info.

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).

Returns: number - the current time of the video.

player.getCurrentTrack() ⇒ Track

Gets the current track information.

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).

Returns: number - the duration of the video.

#### player.getQualityLevels() ⇒ Array

Gets the video quality levels array.

Returns: Array - quality levels array info

player.getSubtitles()

Gets all the avaliable subtitle tracks info.

Returns: Array of subtitles - the subtitle tracks of the video.

player.getThumbnailAt() ⇒ Promise

Returns a thumbnail loading promise in a specific time.

Returns: Promise - Thumbnail loading promise in a specific time.

player.getThumbnails() ⇒ Array < Frame >

Returns the loaded thumbnails.

Returns: Array < Frame > - The loaded thumbnails.

player.getTracks() ⇒ Array.< Track >

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

Returns:: Array.< Track > - all the tracks available.

player.getURL()

Returns the current video URL.

Returns: String

player.getVersion()

Returns the current version of the player.

Returns: String

player.getPlayerDiv()

Returns the video container.

Returns: HTMLDivElement

player.getPlayerContainerDiv()

Returns the player container.

Returns: HTMLDivElement

player.getAdInstance()

Returns the AdInstance Object.

Returns: Object

player.getVolume()

Returns the current volume of the Player.

Returns: number

player.getMute()

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

Returns: boolean

player.getLogger()

Returns the logger of the Player.

Returns: Object

player.isCurrentAssetAd()

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

player.isCurrentAssetMuted()

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

player.isSeeking()

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

Setters

player.setAudio(streamID)

Sets the current audio stream.

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

player.setCurrentTrack(trackID)

Sets the current track.

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

player.setCurrentSubtitle(subID)

Sets the current subtitle.

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

Global typedefs

AudioStream : Object

Properties:

Name Type Description
id number id of the stream.
language string language of the stream.
name string name of the stream.

Player.NexPlayerDRMOptions : Object

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

Properties:

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

Player.Captions : Object

Properties:

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

Player.Thumbnails : Object

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

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

nexplayer.AdInstance().play()

Play the ad when it is paused.

nexplayer.AdInstance().pause()

Pause the ad when it is playing.

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.

nexplayer.AdInstance().isAdPlaying()

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

nexplayer.AdInstance().skip()

Skip the current ad if possible.

nexplayer.AdInstance().checkInitialAds()

Check whether there ads

nexplayer.AdInstance().getAdType() ⇒ string

Get the current Ad type.

Returns: String - The current ad type.

nexplayer.AdInstance().getAdTitle() ⇒ string

Get the Ad title.

Returns: String - The current ad title.

nexplayer.AdInstance().getAdDuration() ⇒ number

Get the Ad duration.

Returns: number - The current ad duration.

nexplayer.AdInstance().getAdRemainingTime() ⇒ number

Get the Ad remaining time.

Returns: number - The ad remaining time.

nexplayer.AdInstance().getMute() ⇒ boolean

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

Returns: boolean - True if the video is muted or false if not.

nexplayer.AdInstance().getVolume() ⇒ number

Get the Ad volume.

Returns: number - The ad volume.

nexplayer.AdInstance().getAdBreaks() ⇒ Object

Returns the break points when ads will trigger

Returns: Object - The break points when ads will trigger

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

Please note that if you want to listen to events that happen at the start of the player initialization (e.g. "playercreated" or "adpodsinfo" event when ads are provided), the listeners must be added before calling the initialization method of the player. Example: 

    var player = new nexplayer.NexPlayer();

    // Adds a listener for the playing event
    nexplayer.PlayerEvents("playing", function(e) {
        console.log("playing", e);
    });

    // Adds a listener for the aderror event
    nexplayer.AdsEvents("aderror", function(e) {
        console.log("aderror", e);
    });

    player.init({
        key: 'ENTER YOUR LICENSE KEY HERE',
        div: document.getElementById("player"),
        src: 'https://livesim.dashif.org/dash/vod/testpic_2s/multi_subs.mpd',
        autoplay: true,
    });

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 lauched when the player is ready to play.
  • buffering: Event lauched when the player is buffering.
  • 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.
  • videoProgressTime: Event is fired when the (5%, 15%, 25%, 50%, 75%, 85%, 95%) of the video's duration has been reached, it returns a string with the percentage in the detail.progressTime, property of the event's payload.
  • ended: Event launched when the stream has been finished.
  • newsubtitlesdataloaded: Event launched when new captions are loaded.
  • ccnewdata: Event launched when new cues of the closed 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, contains 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);
    });