Nexplayer methods
- Setup(configObj)
- ChangeSource({src: newSrc, drm: newDrm})
- UnMount(player)
- IsReady()
- AdsEvents()
- RemoveAdsEvents()
- decodeData(data)
- getVersion()
Player methods and objects
- play()
- pause()
- destroy(UnMount(player))
- load(url, startTime, externalSubtitles)
- reload()
- on(callbackType, functionToBeCalled)
- off(callbackType, functionToBeCalled)
- enableABR()
- addTrackerData()
- removeTrackerData()
- trickPlay(value)
- setVolume(value)
Navigation
- downFocus()
- downSubtitle()
- focusOnButtonBar()
- focusOnPlaybackBar()
- upFocus()
- upSubtitle()
- seek(value)
- seekRange()
- seekLive()
Player state
- isControlBarOpen() ⇒ boolean
- isCurrentAssetAd() ⇒ boolean
- isCurrentAssetMuted() ⇒ boolean
- isLanguageMenuOpen() ⇒ boolean
- isLive() ⇒ boolean
- isPlayBackBarFocused() ⇒ boolean
Toggle
Getters
- getAudioStreams() ⇒ Array<AudioStream>
- getBandwidthEstimate() ⇒ number
- getCurrentContentType() ⇒ string
- getCurrentSegmentContainer() ⇒ Object
- getCurrentAudioStream() ⇒ AudioStream
- getCurrentSubtitle() ⇒ number
- getCurrentTime() ⇒ number
- getCurrentTrack() ⇒ Track
- getDroppedFrames() ⇒ number
- getDuration() ⇒ number
- getMediaElement() ⇒ HTMLVideoElement
- getPlaybackRate() ⇒ number
- getProtocol() ⇒ number
- getQualityLevels() ⇒ array
- getSubtitles() ⇒ array
- getThumbnailAt() ⇒ Promise
- getThumbnails() ⇒ Array<Frame>
- getTracks() ⇒ Array<Track>
- getURL() ⇒ string
- getVersion() ⇒ string [Deprecated]
- getAvailabilityStartTime() ⇒ number
- getPublishTime() ⇒ number
- getTimeShiftBufferDepth() ⇒ number
Setters
- setAudioStream(streamID)
- setCurrentTrack(trackID)
- setSpeed(speed)
- setSubtitle(subID)
- setTrack(qualityLevel)
Static enums
- NexProtocol: enum
- NexEvent: enum
- THUMB_TYPE: enum
Global Typedefs
- AudioStream : object
- Error : object
- Frame : object
- NexDRMInformation : object
- NexHeaders : object
- Track : object
Ads methods and objects
- play()
- pause()
- skipAd()
- getAdCurrentTime() ⇒ number
- getAdDescription() ⇒ string
- getAdDuration() ⇒ number
- getAdPaused() ⇒ boolean
- getAdRemainingTime() ⇒ number
- getAdTitle() ⇒ string
- getIsSkippableAd() ⇒ boolean
- getMute() ⇒ boolean
- getVolume() ⇒ number
- getAdErrorMessage() ⇒ string
- getAdVastErrorCode() ⇒ number
- getAdErrorType() ⇒ string
- setMute(state)
- setVolume(value)
Creates and initializes the player.
Set NexPlayer settings using the configuration object as described in NexPlayer Configuration section.
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. |
| Param | Type | Description |
|---|---|---|
| addRequestFilter | Function |
Sets a function that receives the DRM request as a parameter and changes its Headers. |
| adsLoadTimeout | number |
Determines the time the player waits for the ad to start. Parameter for IMA. |
| adsMode | string |
Determines the ad library: 'ima', 'pal', 'dai' or 'default'. Note that 'dai' needs a [daiConfig] object to work, while 'ima' and 'pal' require a VAST string. |
| adsParamsToEncode | Array |
Specifies the name of the VAST ad URL parameters to encode. |
| autoplay | boolean |
Determines if the video must start playing or paused. True by default. |
| bitrateConfig | Object |
Determines whether the video will start playing at the bitrate you set by default. The tracks that the ABR will be able to select are the ones between minBitrate and maxBitrate. |
| callbackForLogger | Function |
Function to be called when the logger shows a message. |
| callbackForReturn | Function |
Sets a callback to be executed when the corresponding button is clicked. |
| callbackForSubtitles | Function |
Sets a callback to be executed when the corresponding subtitle is loaded. |
| callbacksWithPlayers | Function |
Used for retrieving the nexplayer instance and video element. This is necessary for getting the instance and use the NexPlayer API. |
| cast | boolean |
Determines if the cast will be enabled or not. |
| daiConfig | Object |
Used to initialize the DAI stream. |
| debug | boolean |
Determines if log information is showed. By default is set to true. |
| defaultLanguage | string |
Determines which is the default audio language. |
| disableKeyEvents | boolean |
Determines if the keyboard keys can be used to control the video. |
| drm | Object |
Contains an object of DRM information. By default it’s set to null. |
| enableVpaid | boolean |
If it is set to true the player can execute VPAID ads, otherwise, the player will play other media that is available in the ad. In case no other media files are included in the ad an error will be fired. |
| externalSubtitles | Array <externalSubtitle> |
Used to provide subtitle files as external subtitles. |
| hideControlBarOnStart | boolean |
Determines if the control bar will hide when the video starts. |
| hideUITime | boolean |
Determines if the time will be hidden in the UI. |
| improveStartUp | boolean |
Determines whether the video has to start at the lowest bitrate or not. |
| logosrc | string |
Company URL logo. |
| mutedAtStart | boolean |
Determines if the video will start playing muted or not. False by default. |
| pageUrl | string |
Adds a parameter to the ad request to keep track of the domain that sent the request. For targeting purposes. More info . Parameter for IMA. |
| preferredAudioCodec | Array |
This property can be used to give priority to a specific audio codec. |
| poster | string |
Video poster URL. |
| reinitializeAfterAds | boolean |
[Deprecated] Used to avoid errors related to ads on PS5, please set it to true on this platform. False by default. |
| resumePosition | number |
Determines the position where the video will start playing. |
| retryParameters | Object <retrySettings> |
Determines the retry parameters for DRM, manifest, and streaming requests. |
| showAdsUI | boolean |
Determines if the UI for ads is hidden or not. |
| showingFullUI | boolean |
Determines if the UI is hidden or not. |
| ssaiMediaTailor | Object |
Configuration object for setting AWS MediaTailor endpoint and use SSAI. |
| staticThumbnails | Object |
Thumbnail properties: VTT URL, image URL and a callback which returns an error object. |
| startFullScreen | boolean |
Determines if the video will start on full screen. |
| startingBufferLength | number |
Determines the starting buffer length. |
| subtitle | string |
Subtitle name of the video. |
| title | string |
Video name. |
| trailer | boolean |
Determines if a stream should be considered as a trailer. |
| useDefaultControls | boolean |
Determines if the TV controller will be able to be used to navigate in the UI. |
| useDynamicThumbnails | boolean |
Determines if dynamic thumbnails are used. By default this values is set to false. |
| 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. |
Change the URL stream of the video. It is possible to set a new URL with new DRM config if necessary.
Parameters: configObj is an object which values could be:
| Param | Type | Description |
|---|---|---|
| src | string |
URL of the video to be played. |
| drm | NexDRMInformation | Contains an object of DRM information. |
Unmounts the player and its dependencies. In order to properly clear the player this method must be called after destroying the very same player. Check more details here.
Parameters:
| Param | Type | Description |
|---|---|---|
| player | HTMLElement |
Player tag |
Fetches the player mount/unmount status. If true, it can be mounted again.
Returns: boolean - Whether the player is ready to be mounted or not.
nexplayer.AdsEvents("adEvent", function () {})
Add a listener for the specified ad event.
nexplayer.RemoveAdsEvents("adEvent", function () {})
Remove a listener for the specified ad event which has been previously registered.
Decodes an ArrayBuffer and converts it into a string. END OF TEXT (\u0003) and NULL (\u0000) unicode characters are cleaned.
Param:
- data is the ArrayBuffer to decode.
Returns: decoded and cleaned string or null if the parameter provided is not an ArrayBuffer.
Retrieve the current version of the player.
Returns: string - identify the version of the player.
Play the video.
Pause the video.
Loads a manifest starting it at the given position. Note that if the video has DRM, the player will try to use the DRM license of the old video.
Parameters:
| Param | Type | Description |
|---|---|---|
| url | string |
Manifest URL |
| startTime | number |
Starting time of the video |
| externalSubtitles | [{src: string, language: string, callback: function},…] |
Optional. External subtitles of the video |
Reloads the player with the same video and current time. This function may help to recover from errors.
Destroys the player. This method returns a promise which must call to UnMount as soon as it is resolved. This way, the player will be completely destroyed and new instances could be created afterwards. The UnMount method must be called from the ‘nexplayer’ instance and needs the HTMLDivElement used to create the player in order to remove it.
Add a listener of an event.
Parameters:
| Param | Type | Description |
|---|---|---|
| callbackType | NexEvent |
Event to listen for |
| functionToBeCalled | Function |
Function called on each event |
Remove a listener of an event.
Parameters:
| Param | Type | Description |
|---|---|---|
| callbackType | NexEvent |
Event to listen for |
| functionToBeCalled | Function |
Function called on each event |
Enable the ABR to change automatically between tracks.
Adds custom data into New Relic's tracker if initialized.
Parameters:
| Param | Type | Description |
|---|---|---|
| key | string |
Data variable name |
| value | any |
Data value |
Removes custom data from New Rellic's tracker if initialized.
Parameters:
| Param | Type | Description |
|---|---|---|
| key | string |
Data variable name |
Sets the trick play value. A value bigger than 1 will move the seek time forward. A value negative will move it backward. Setting trick play value to 1 will end trick play and seek to the calculated seek time. This seek time results from the provided value which will increase the time to seek depending on how much time the trickplay is executed. Then, it will trigger an event trickPlayStarted when the value is changed, a trickPlayTimeUpdate event will be thrown every time the seek time changes, and trickPlayEnded event when the trick play stops. Use player.play(), player.stop() or player.seek() will finish the trick play.
| Param | Type | Description |
|---|---|---|
| value | Number | number of times per second to update the seek time. |
Sets the new volume of the video. The value must be a number between 0 and 1.
| Param | Type | Description |
|---|---|---|
| value | Number | New volume of the video. |
Focuses the element of the UI situated directly below the element currently focused.
Changes the current subtitles to the previous one in the subtitle track playlist.
Changes the focus to the play/pause button.
Changes the focus to the video's seekbar.
Focuses the element of the UI situated directly above the element currently focused.
Changes the current subtitles to the following one in the subtitle track playlist.
Set the currentTime property of the attached video element. (if isUTC is true, the seek value will be in a different format than the currentTime of the video element).
| Param | Type | Description |
|---|---|---|
| value | number |
value in seconds that the player will seek to. |
//Non-live video
player.seek(120) // It seeks into minute 2:00 in the video (120 secs), must be a positive number ranging from 0 to the full duration of the video in seconds
//Live video
player.seek(-120) // It jumps back 2 minutes (120 secs) from the current live time, must be a negative number ranging from minus {the DVR window size} to 0When using a live stream, the parameter’s value of the seek() method is a number that is added or subtracted to the current time of the video. Therefore, if the value provided plus the video’s current time is greater than the seek range end value the player will seek to the live point. When providing a negative value, it will be subtracted to the video’s current time so the player will seek range.
In order to use the seek() method, you must ensure that the value used is between the end and start value returned by the seekRange() method, in seconds.
- A value greater than the end seekRange value will seek to live.
- A value lower than the start seekRange will seek to the start value of the range.
// "player" is the player instance
// "videoElem" is the HTMLVideoElement
var timeToSeek = player.seekRange().start - videoElem.currentTime;
player.seek(timeToSeek);Returns an object, with start and ending times the player can seek to.
Returns: object - {start: "number" , end: "number"}
Jump to the livestream current time from the current position (if isUTC is true, the seek value will be in a different format than the currentTime of the video element). Only works in livestream.
Returns: boolean - true if the bar is showing, false otherwise.
Indicates whether the current asset playing is an ad or not
Returns: boolean - true if the current asset is an ad, false otherwise.
Indicates whether the ad or the main content is muted or not.
Returns: boolean - true if the current asset is muted, false otherwise.
Returns: boolean - true if the Language/Subtitle menu is showing, false otherwise.
Returns: boolean - true if the video is live, false otherwise.
Returns: boolean - true if the seek bar of the video is currently focused, false otherwise.
Shows or hides the bottom bar.
Opens or closes the language menu.
Toggle the video playback between the play and pause states.
Enables toggle between full screen and window.
Get the available audio streams.
AudioStream:
| Property | Type | Description |
|---|---|---|
| id | number |
of the audio to be played. |
| language | string |
contains a string with the languages audio available (by default it is empty). |
| name | string |
contains a string with the names of audio files available (by default it is empty). |
| label | string |
contains information about the label tag inside the manifest. Empty if not specified. |
Returns: Array<AudioStream> - the list of the available audio streams.
Returns the current bandwidth available in bytes.
Returns: number - information about the bandwidth estimate.
Get the current audio and video segment type.
This object contains the following information:
| Property | Type | Description |
|---|---|---|
| audio | String |
Audio segment container (for ts segments, this value will be null as this type of segment contains the video and audio in the same segment.) |
| video | String |
Video segment container |
Returns: Object - Current audio and video segment container type.
Get the audio stream currently in use.
AudioStream:
| Property | Type | Description |
|---|---|---|
| id | number |
of the audio to be played. |
| language | string |
that contains a string with languages audio stream currently in use (by default it is empty). |
| name | string |
that contains a string with name of audio stream currently in use (by default it is empty). |
| label | string |
contains information about the label tag inside the manifest. Empty if not specified. |
Returns: Array<TrackInfo> - information about the current audio track.
Returns the the type of the current asset (“ad”, “mainContent” or “none”)
Returns: string - information about the current audio track.
Retrieves the number id of the current subtitle. If the returned value is -1, no subtitle is selected.
Returns: number - id of the current subtitle.
Returns the current time of the video element.
Returns: number - the current time of the video in seconds.
Get the current track information.
Track:
| Property | Type | Description |
|---|---|---|
| width | number |
that contains a number with the width of the current track. |
| height | number |
that contains a number with the height of the current track. |
| bitrate | number |
that contains a number with the bitrate of the current track. |
| id | number |
of the current track. |
Returns Array<TrackInfo> - information about the current video track.
Returns the number of frames dropped. 0 is returned if not available or no frames were dropped.
Returns: number - the number of frames dropped.
Returns the video duration.
Returns: number - the duration of the video.
Returns the player's video element.
Returns: HTMLVideoElement- video element playing the stream.
Returns the video's playback rate.
Returns number - video's playback rate.
Returns the stream's protocol ID, the number correspond to the NexProtocol enum values.
Returns number - the protocol of video to be played.
Get an array of video quality levels.
This array contains the following information:
| Param | Type | Description |
|---|---|---|
| id | number |
of this track. |
| width | number |
that contains a number with the width of this track. |
| height | number |
that contains a number with the height of this track. |
| bitrate | number |
that contains a number with the bitrate of this track. |
Returns: array - contains all video quality levels.
Get the video subtitles info.
The returned array contains objects with the following properties:
| Property | Type | Description |
|---|---|---|
| id | number |
is the identifier of each subtitle. It can be used to select the subtitle. |
| language | string |
that contains a string with subtitle stream (by default it is empty). |
Returns: Array - all the subtitles availables in the stream.
Get the thumbnail at a specific video time.
Returns: Promise - waits for a specific thumbnail to load.
Get all the available thumbnails.
Each array's element contains the next information:
| Name | Type | Description |
|---|---|---|
| f | canvas |
Thumbnail canvas instance. |
| w | number |
Width. |
| h | number |
Height. |
| st | number |
Thumbnail starting time. |
| ft | number |
Thumbnail ending time. |
Returns: Array< Frame > - all the avaliable thumbnails.
Get all the available video tracks (different qualities).
Each array's element contains the next information:
| Param | Type | Description |
|---|---|---|
| id | number |
of all tracks. |
| width | number |
that contains a number with the width of all tracks. |
| height | number |
that contains a number with the height of all tracks. |
| bitrate | number |
that contains a number with the bitrate of all tracks. |
Returns: Array< Track > - all the available video tracks and its different levels of quality.
Returns the current stream's URL.
Returns: string - stream URL.
The method getVersion() is deprecated, please use nexplayer.getVersion() instead.
Returns: string - identify the version of the player.
The presentation's start time in seconds.
Returns: number.
Specifies the wall-clock time when the MPD was generated and published at the origin server. This method is not supported for HLS streams and the return value is null.
Returns: number.
Gets the presentation's segment availability duration.
Returns: number.
Set the current audio stream.
| Param | Type | Description |
|---|---|---|
| streamID | number |
is the identifier of the audio stream to be selected. |
Set the current track.
Parameters:
| Param | Type | Description |
|---|---|---|
| trackID | number |
is the identifier of the audio stream to be selected. |
Set the video playback speed.
Parameters:
| Param | Type | Description |
|---|---|---|
| speed | number |
speed value. |
Set the video subtitles. Use -1 for deactivating the subtitles.
Parameters:
| Param | Type | Description |
|---|---|---|
| index | number |
index of the subtitles list. |
Set the video quality level.
Parameters:
| Param | Type | Description |
|---|---|---|
| qualityLevel | number |
index of the track to be selected. |
Properties:
| Name | Type | Default |
|---|---|---|
| HLS | number |
0 |
| DASH | number |
1 |
| UNKNOWN | number |
3 |
Properties:
| Name | Type | Default | Explanation |
|---|---|---|---|
| Track_Change | number |
0 |
Fired when the player changes the current track. |
| Fragment_Loading_Completed | number |
1 |
Fired when a new fragment has been loaded. |
| Buffering | number |
2 |
Fired when the buffer state changes. Check payload for state. |
| Error | number |
3 |
Fired when an error occurs. Returns an object with the information of the error. The object contains an array with the data (not all errors include data), and the name. |
| Stall_Detected | number |
5 |
Fired when a stall is detected. |
Properties:
| Name | Type | Default |
|---|---|---|
| STATIC_THUMBNAILS | number |
0 |
| DYNAMIC_THUMBNAILS | number |
1 |
Properties:
| Name | Type | Description |
|---|---|---|
| id | number |
id of the stream. |
| language | string |
language of the stream. |
| name | string |
name of the stream. |
| label | string |
contains information about the label tag inside the manifest. Empty if not specified. |
Properties:
| Name | Type | Description |
|---|---|---|
| code | number |
Error code. |
| message | string or Object |
Error detailed message. In case the message is an Object, it will represent the request's response statusText parsed into an Object. |
| src | string |
Source link causing the error. |
| type | string |
File type causing the error. "Manifest" and "Image" are the possible values. Manifest indicates that the error has happened at the level of the thumbnails file e.g. the URL of the thumbnails files does not exist (error 404). Image indicates that the error has ocurred at the level of a thumbnail image e.g the URL of a thumbnail image, which is specified inside the thumbnails manifest, does not exist (error 404). |
Possible error codes:
Manifest:
404: Manifest not found
420: Manifest load error
422: Empty manifest | No thumbnails found
Other error codes come directly from the status code of the request's response.
Image:
420: Image not loaded
422: Invalid image
Properties:
| Name | Type | Description |
|---|---|---|
| f | canvas |
Thumbnail canvas instance. |
| w | number |
Width. |
| h | number |
Height. |
| st | number |
Thumbnail starting time. |
| ft | number |
Thumbnail ending time. |
Properties:
| Name | Type | Description |
|---|---|---|
| NexDRMType | string |
NexDRMType of the video. |
| NexDRMKey | string |
NexDRMKey of the video. |
| NexHeaders | Array.<NexHeaders> |
NexHeaders of the video. |
Properties:
| Name | Type | Description |
|---|---|---|
| FieldName | string |
of the HTTPHeaders. |
| FieldValue | string |
of the HTTPHeaders. |
Properties:
| Name | Type | Description |
|---|---|---|
| width | number |
width of the video. |
| height | number |
height of the video. |
| bitrate | number |
bitrate of the video. |
| id | number |
id of the video. |
Properties:
| Name | Type | Description |
|---|---|---|
| baseURL | string |
Base URL for Video and Ads. |
| playbackURL | string |
Video URL to be attached to the baseURL. |
| adsParams | Object |
Contains "Params: string" this is the Ad URL to be attached to the baseURL. |
Properties:
| Name | Type | Description |
|---|---|---|
| minBitrate | num |
The player should ignore any bitrate profiles in the manifest under this value, and never play them. |
| startingBitrate | num |
The bitrate the player will try to start playing. |
| maxBitrate | num |
The player should ignore any bitrate profiles in the manifest above this value, and never play them. |
Properties:
| Name | Type | Description |
|---|---|---|
| src | String |
Subtitles file URL |
| language | String |
Subtitle language identifier |
| callback | Function |
Error callback |
Type: global typedef
Properties:
| Name | Type | Description |
|---|---|---|
| drm | Object <retryConfig> |
Subtitles file URL |
| streaming | Object <retryConfig> |
Subtitles file URL |
| manifest | Object <retryConfig> |
Subtitles file URL |
Type: global typedef
Properties:
| Name | Type | Description |
|---|---|---|
| timeout | number |
Timeout in ms, after which the player aborts. |
| stallTimeout | number |
Stall timeout in ms, after which the player aborts. |
| connectionTimeout | number |
Connection timeout in ms, after which the player aborts. |
| maxTries | number |
The maximum number of requests before player fails. |
| retryDelay | number |
The base delay in ms between retries. |
Type: global typedef
Properties:
| Name | Type | Description |
|---|---|---|
| ASSET_KEY | string |
Identifier of the live content that wants to be played. More info. Live streams only. |
| CONTENT_SOURCE_ID | number |
Unique identifier for the publisher content, from a CMS. VOD only. |
| VIDEO_ID | string |
Identifier for the video content source. VOD only. |
Play the ad
Pause the current ad.
This method only has an effect if the ad on stage is a skippable ad and can be skipped (e.g. getIsSkippableAd returns true, we can skip the ad)
Get the current time ad.
Returns: Number - the current time ad to be played.
Get the available description ad.
Returns: String - the description ad to be played.
Get the available duration ad.
Returns: Number - the duration ad to be played.
Get stating if the ad on stage is paused or not
Returns: boolean - true if the ad on stage is paused false if it is not.
Get the remaining time ad.
Returns: Number - the remaining time ad to be played.
Get the available title ad.
Returns: String - the title ad to be played.
Returns whether the ad can be skipped or not.
Returns: boolean - true if the video can be skip. false if it is not.
Get the mute state of an ad depending on what is on stage.
Returns: boolean - true if the ad can is mute. false if it is not.
Get the volume of ad depending on what is on stage.
Returns: number - is a number between 0 and 1. -1 is returned if this value is not available.
Returns the error message for the current ad error.
Returns: string - The error message for the current error.
Returns the VAST error code for the current ad error.
Returns: number - The VAST error code for the current error. -1 is returned if this value is not available.
Returns the detected ad error type for the current ad error.
Returns: string - The detected ad error type, possible values: 'adLoadError', 'adPlayError' or '' (if unknown error type).
Set value should be a Boolean. True for muting and false for unmuting.
Set value should be a Number between 0 (minimum volume) and 1 (maximum volume).
NexPlayer offers more advanced options to control the playback. This section contains several examples of how to use these features.
An instance of the player and the video element will be accessible once NexPlayer™ is configured and loaded. The 'callbacksForPlayer' option should be set. The defined function will be called when the player is considered ready. Once the callback is received, the playback can be controlled with the NexPlayer™ instance and the associated video element.
var callBackWithPlayers = function (nexplayerInstance, videoElement) {
// Eg. seeking to 30 sec from outside the predefined UI could be done like this
nexplayerInstance.seek(30);
}
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
callbacksForPlayer: callBackWithPlayers
});We strongly recommend calling the APIs after the player is ready.
If you want to reuse the same div for different videos, the container div must be unmounted properly. The way this is done has changed recently, now the following command must be used:
player.destroy().then(nexplayer.UnMount(document.getElementById('player')));In the case of using an await procedure to unmount the player, it is convenient to ensure that the Setup is called after the UnMount method is finished. This can be done via the IsReady method that returns a boolean value which indicates whether the player can be mounted or not. The recommended way to do this is via events, which are the following:
- mounted
- unmounted
When "unmounted" is triggered after calling UnMount, the player is ready to be initialized again. This means that creating a listener on this event and calling the Setup from there will always mount the player properly. The "mounted" event just notifies that the player has started the initialization. The listener must be added on the player HTML tag, usually called "player". For example, for the "unmounted" event, it would look like this:
document.getElementById('player').addEventListener("unmounted", function() {/* Do something here */});Digital rights management (DRM) is a set of access control technologies for restricting the use of proprietary hardware and copyrighted works.
?> Most of the DRMs available won't work without using HTTPS with a certificate. For development purposes, a tool like ngrok can be used to test DRM-protected links. NexPlayer supports several DRM technologies:
| MODELS | DASH+PlayReady | DASH+Widevine | HLS+Widevine | HLS+Playready |
|---|---|---|---|---|
| Samsung Tizen
2017-2018+ models |
✔ | ✔ | ✔ | ✔ |
| Samsung Tizen
2015-2016 models |
❌ | ℹ | ℹ | ✔ |
| LG WebOS 4.0+ | ✔ | ✔ | ✔ | ✔ |
| LG WebOS 3.0 | ❌ | ✔ | ✔ | ✔ |
?> Widevine Classic was supported in these models, but it has been deprecated by Google. It is no longer supported on Samsung TVs due to maintenance issues
?> For using Playready on Tizen the security level must be 2000, the clients version less than 3.0 and WRMHEADER version of 4.0.0.0. or lower.
- In Xbox the security level must be 150 on dev kit.
- In LG devices capabilities and restrictions in the following link.
- In PS5, it should be setup in the configuration as below:
nexplayer.Setup({
...
configuration: {
drm: {
advanced: {
'com.microsoft.playready': {
distinctiveIdentifierRequired: true,
},
}
},
},
});| FEATURE | PLAYREADY | WIDEVINE |
|---|---|---|
| Encrypted key | ✔ | ✔ |
| Separate encryption key server | ✔ | ✔ |
| Hardware DRM | ✔ | ✔ |
| Custom Headers | ✔ | ✔ |
?> For Tizen, DRM is supported from 2017 device models and higher
?> For WebOS, DRM is supported from WebOS 3.0 and higher
A DRM powered by Google. It can be set by entering the information into the DRM array:
var nexDRMInformationWidevine = {
NexDRMType:'com.widevine.alpha',
NexDRMKey: 'DRM key URL',
NexHeaders:[{FieldName: 'Optional field name', //Optional
FieldValue: 'Optional field value'}] //Optional
};
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
drm: [nexDRMInformationWidevine]
});?> Please note that the HTTP headers (NexHeaders) are optional, and might depend on the implementation of the Widevine server used.
A DRM powered by Microsoft. It can be used by entering the information into the DRM array:
var nexDRMInformationPlayReady = {
NexDRMType:'com.microsoft.playready',
NexDRMKey: 'DRM key URL',
NexHeaders:[{FieldName: 'Optional field name', //Optional
FieldValue: 'Optional field value'}]}; //Optional
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
drm: [nexDRMInformationPlayReady]
});?> Please note that the HTTP headers (NexHeaders) are optional, and might depend on the implementation of the PlayReady server used.
The Common Encryption Scheme (CENC) specifies the standard to enable decryption of the same file using different DRM systems. It allows the same CENC-encrypted content to be decrypted and played by any client device that interfaces with a DRM system that can serve the associated CENC key information.
For example, Widevine and PlayReady can be used with the same DASH manifest and chunk files:
// Widevine
var nexDRMInformationWidevine = {NexDRMType:'com.widevine.alpha',
NexDRMKey: 'DRM key URL',
NexHeaders:[{FieldName: 'Optional field name', //Optional
FieldValue: 'Optional field value'}]}; //Optional
// PlayReady
var nexDRMInformationPlayReady = {NexDRMType:'com.microsoft.playready',
NexDRMKey: 'DRM key URL',
NexHeaders:[{FieldName: 'Optional field name', //Optional
FieldValue: 'Optional field value'}]}; //Optional
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
drm: [nexDRMInformationWidevine, nexDRMInformationPlayReady]
});NexPlayer stopped the support for AES.
Custom headers can be included in each HTTP petition, even without the use of DRM, to include extra information for the server.
This information can be passed in the DRM array:
drmCustomHeaders = {NexHeaders:[{FieldName: 'Optional field name', FieldValue: 'Optional field value'}]};
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
drm: [drmCustomHeaders]
});?> Please note that this method is not as secure as other DRMs.
Custom headers are supported with HLS and DASH.
If you are migrating from AVPlay to our player, in order to configurate the DRM header, it could be helpful to take a look at this information.
The way to introduce a header in AVPlay is like the following example (different way from our player):
DRM_NAME: {
name: 'DRM NAME',
url: 'REPLACE THIS WITH YOUR MEDIA URL',
licenseServer: 'REPLACE THIS WITH YOUR LICENSE SERVER URL',
customData: 'REPLACE THIS WITH YOUR CUSTOM DATA'
};To enter the same configuration in our player it should be done like this (PlayReady used as example):
var nexDRMInformationPlayReady = {
NexDRMType: 'DRM NAME (e.g. com.microsoft.playready)',
NexDRMKey: 'REPLACE THIS WITH YOUR LICENSE SERVER URL',
NexHeaders:[{FieldName: 'X-AxDRM-Message' FieldValue:'REPLACE THIS WITH YOUR CUSTOM DATA'}]
};
src: 'REPLACE THIS WITH YOUR MEDIA URL',FieldName should be specified (if you don’t know this field, please enter 'X-AxDRM-Message') and as FieldValue should be included the wanted custom data.
NexPlayer supports the VAST, VPAID, and VMAP ad formats.
IMA and PAL libraries can be used for ad playback as well as NexPlayer's own solution.
You can insert any pre/mid/post roll ad by setting up the ad links as below:
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
vast: 'VAST / VPAID / VMAP link',
adsMode: 'pal / ima / default',
});Sample VAST links can be found on the Google Website.
DAI libraries can be used for ad playback, as well as the NexPlayer solution itself.
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
daiConfig: {
ASSET_KEY : 'KEY',
CONTENT_SOURCE_ID : 'ID',
VIDEO_ID : 'ID',
},
adsMode: 'dai / default',
});Get started Google Website.
In order to use IMA, DAI or PAL, a script must be provided in the index, which are the following respectively:
<!-- IMA -->
<script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
<!-- Currently, only IMA 3 is supported -->
<!-- DAI -->
<script src="https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
<!-- PAL -->
<script src="https://nex360.s3.amazonaws.com/PAL/pal.js" ></script>The following methods should be queried after the adstarted event has fired for accurate data with nexplayer.AdInstance()
getAdTitle() ⇒ StringRepresents the VAST AdTitle tag.getAdDescription() ⇒ StringRepresents the VAST Description tag.getAdDuration() ⇒ NumberRepresents the duration of the selected linear creative in milliseconds. Returns -1 if this value is not available.getAdCurrentTime() ⇒ NumberRepresents the current timestamp in the selected linear creative in milliseconds. Returns -1 if this value is not available.getAdRemainingTime() ⇒ NumberRepresents the current time remaining in the selected linear creative in milliseconds. Returns -1 if this value is not available.getIsSkippableAd() ⇒ BooleanStates if the loaded linear ad is a VAST skippable ad - can be queried when adloaded event fires.getVolume() ⇒ NumberRepresents the volume level in the ad.getAdErrorMessage() ⇒ StringRepresents the error message of the current ad error.getAdVastErrorCode() ⇒ NumberRepresents the VAST error code of the current ad error.getAdErrorType() ⇒ StringRepresents the error type of the current ad error.getMute() ⇒ booleanIndicates if the ad is mute.
nexplayer.AdsEvents('adstarted', function(e){
console.log("Time: ", nexplayer.AdInstance().getAdRemainingTime());
});setVolume()Set a number in order to indicate the volume level.setMute()Set true when you want to mute the ad, and false to unmute it.
nexplayer.AdsEvents('adstarted', function(e){
nexplayer.AdInstance().setVolume(0.5);
});addEventListener()Adds a listener to the ads video. The possible events to listen are the same as the HTML video element ones. Important: this method should be called inside the Setup's callback or after the player is initialized. Example of use:
var callBackForPlayers = function (nexplayerInstance, videoElement) {
nexplayer.AdInstance().addEventListener('playing', function() {
console.log("PLAYING --- ");
});
nexplayer.AdInstance().addEventListener('waiting', function() {
console.log("WAITING --- ");
});
}
...
nexplayer.Setup({
key: ...
callbacksForPlayer: callBackForPlayers
});References to the player instances are needed to register callbacks. There are two types of emitted events that can be listened to.
The video element emits the basic event, such as a change of the state of the video (pause/play/buffering), or informs that the current time of the video has changed.
The method addEventListener of the video element needs to be called with any of the available media events.
Some of the most important events are "playing", "pause", "waiting", "timeupdate", "seeking" and "seeked".
HTMLVideoElement.addEventListener("timeupdate", function() { console.log("The video playback has advanced to: "+videoElement.currentTime+", with the duration: "+videoElement.duration) }, true);We also have custom events to handle some different kind of video events.
HTMLVideoElement.addEventListener("customEvent", function(event) { console.log("Custom Event") });This event will be fired when a buffering event occurs and it specifies what type of buffering occurred (connection, seek, initial, background).
// Accessing the type of the buffer
var bufferType = event.detail;detail Contains a string indicating the type of buffering: connection, seek, initial or background.
HTMLVideoElement.addEventListener("bufferType", function(e) { console.log("Buffer Type", e) });Sent when a NexPlayer error is fired. The event parameter has the detail property that contains the error message:
// Accessing the error message
var errorMessage = event.detail;This event is fired when the state of player is changed. The event parameter for the callback function has a property called detail that stores the current state of the player:
// Accessing the current state of the player
var currentState = event.detail;detail type is String and can have the following values:
- Ready
- Buffering
- Playing
- Paused
- Ended
This event is fired when the 25% of the video's duration has been reached. The event parameter for the callback function has a property called detail that stores the time of the quartile:
// Accessing the time of the quartile
var firstQuartile = event.detail;detail type is number and returns the quartile time
HTMLVideoElement.addEventListener('videofirstquartile', function(e){
console.log("VIDEO FIRST QUARTILE -----> ", e);
});This event is fired when the 50% of the video's duration has been reached. The event parameter for the callback function has a property called detail that stores the time of the quartile:
// Accessing the time of the quartile
var midPoint = event.detail;detail type is number and returns the quartile time
HTMLVideoElement.addEventListener('videomidpoint', function(e){
console.log("VIDEO MID POINT -----> ", e);
});This event is fired when the 75% of the video's duration has been reached. The event parameter for the callback function has a property called detail that stores the time of the quartile:
// Accessing the time of the quartile
var thirdQuartile = event.detail;detail type is number and returns the quartile time
HTMLVideoElement.addEventListener('videothirdquartile', function(e){
console.log("VIDEO THIRD QUARTILE -----> ", e);
});This event is fired when the (5%, 15%, 25%, 50%, 75%, 85%, 95%) of the video's duration has been reached. The event parameter for the callback function has a property called detail that stores the percentage time:
detail type is string and returns the percentage time (5%, 15%, ...)
HTMLVideoElement.addEventListener('videoProgressTime', function(e){
console.log("VIDEO PROGRESS TIME -----> ", e.detail);
});This event is fired when the current video time is 60 or more seconds:
// Accessing the time when the event is triggered
var sixtysecondsin = event.detail;detail type is number and returns the quartile time
HTMLVideoElement.addEventListener('60secondsin', function(e){
console.log("60 SECONDS IN -----> ", e);
});This event is fired when the trick play value is changed:
// Accessing the time when the event is triggered
var trickPlayTime = event.detail;detail type is number and returns time when trick play started (currentTime when trick play value changed).
HTMLVideoElement.addEventListener('trickPlayStarted', function(e){
console.log("Trick play changed at time:", e.detail);
});This event is fired each time trick play time is changed (with a frequency of value times per second):
// Accessing the time when the event is triggered
var trickPlayTime = event.detail;detail type is number and returns the time where trick play is.
HTMLVideoElement.addEventListener('trickPlayTimeUpdate', function(e){
console.log("Trick play updated at time:", e.detail);
});This event is fired when trick play ends:
// Accessing the time when the event is triggered
var trickPlayTime = event.detail;detail type is number and returns the time where trick play is.
HTMLVideoElement.addEventListener('trickPlayEnded', function(e){
console.log("Trick play ended at time:", e.detail);
});This event just notifies that the player has started the initialization. The listener must be added on the player HTML tag, usually called “player”.
<div id="player_container">
<div id="player"></div>
</div>document.getElementById('player').addEventListener('mounted', function() {/* Do something here */});
nexplayer.Setup({
key: 'YOUR LICENSE KEY',
div: document.getElementById('player'),
...
})This event is triggered after calling "nexplayer.UnMount()", therefore it indicates that the player is ready to be initialized again.
<div id="player_container">
<div id="player"></div>
</div>document.getElementById('player').addEventListener('unmounted', function() {/* Do something here */});
nexplayer.Setup({
key: 'YOUR LICENSE KEY',
div: document.getElementById('player'),
...
})This event is triggered when all the subtitles are available.
HTMLVideoElement.addEventListener("subtitlesready", function (event) {
// The subtitles are ready to be used
console.log("Subtitles ready: ", nexplayerInstance.getSubtitles());
// At this point it is posibble to select any subtitle available
nexplayerInstance.setSubtitle(0);
});Advanced events such as a track change are available using the on method of NexPlayer.
nexplayerInstance.on(nexplayer.Player.NexEvent.Track_Change, function() { console.log("The current track has changed") });These events can be removed using the off method:
nexplayerInstance.off(eventId);We also have events to handle some different kind of ads events.
We have the next list of ad events available:
- adtagstartloading Note: This event is not triggered when using IMA.
- adloaded
- addurationchange
- adimpression
- adpaused
- adresumed
- adskipped
- adfirstquartile
- admidpoint
- adthirdquartile
- adcomplete
- adclick
- advolumemuted
- advolumechanged
- adclosed
- aderror
- addestroyed
var f = function() { console.log("this is an example") };
nexplayer.AdsEvents('event name', f);To remove the event, do the following:
nexplayer.RemoveAdsEvents('event name', f);- adstarted: Start an individual ad, contains the ad position in the block in the detail attribute.
- adblockstart: Contains the number of ads in the block in the detail attribute.
- adpodsinfo: Contains all ad pods information.
- adblockend: Event launched when an ad block (some ads in the same timestamp) ends.
nexplayer.AdsEvents('custom event name', function (e) {console.log("this is an example", e.detail)});;Advanced actions can be performed with a player instance. For the full action list, check NexPlayer API
HLS and DASH streams contain several video bitrates in order to adjust the quality based on the network conditions. Changes in bitrate are done automatically when ABR (Adaptive Bitrate) is enabled (default behavior).
The currently selected track can be obtained with the method getCurrentTrackof NexPlayer™. It returns all the track information.
nexplayerInstance.getCurrentTrack();All the available tracks can be obtained with the method getTracks of NexPlayer™.
nexplayerInstance.getTracks();Setting a fixed track can be achieved by calling the method setTrack of NexPlayer™.
// Sets the first track as the used one
nexplayerInstance.setTrack(nexplayerInstance.getTracks()[0].id);A change in the current track can be detected with the NexPlayer™ callbacks.
Information about the available subtitles can be retrieved with the textTracks attribute of the video element.
videoElement.textTracks;The active subtitles mode is set to showing. The currently selected subtitle can also be selected by setting the mode to showing. A subtitle can be deselected by setting the mode to hidden.
videoElement.textTracks[0].mode = "showing"; //0 -> the id of the textTrackInformation about the current audio can be retrieved with the method getCurrentAudioStream of NexPlayer™. It returns all the audio information for that stream.
nexplayerInstance.getCurrentAudioStream();All the available audio tracks can be retrieved with the method getAudioStreams of NexPlayer™.
nexplayerInstance.getAudioStreams();The currently used audio stream can be set with the method setAudioStream of NexPlayer™, passing one of the IDs of getAudioStreams.
// Sets the first audio stream as the used one
nexplayerInstance.setAudioStream(nexplayerInstance.getAudioStreams()[0].id);Seeking to a certain time can be achieved by calling the method seek of the NexPlayer™ and passing the desired number of seconds.
nexplayerInstance.seek(30);Only supported by platforms that actually allow picture in picture API.
var callBackWithPlayers = function (nexplayerInstance, videoElement) {
videoElement.requestPictureInPicture();
};
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
callbacksForPlayer: callBackWithPlayers
});This property is a function that receives the request as parameter , where the following properties can be changed:
| Property | Type |
|---|---|
| headers | Object.<string, string> |
| body | String |
var filter = function(request){
request.headers['FieldName'] = 'FieldValue';
};
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
callbacksForPlayer: 'YOUR CALLBACK VAR',
drm:['YOUR DRM'],
addRequestFilter: filter,
});This property gives priority to a specific audio codec.
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
callbacksForPlayer: 'YOUR CALLBACK VAR',
drm:['YOUR DRM'],
preferredAudioCodec: ['The priority codec as ac-3', 'mp4a.40.2'],
});This property gives priority to a specific video codec.
nexplayer.Setup({
key: 'REPLACE THIS WITH YOUR CUSTOMER KEY',
div: document.getElementById('player'),
src: 'VIDEO URL',
callbacksForPlayer: 'YOUR CALLBACK VAR',
drm:['YOUR DRM'],
preferredVideoCodec: ['The priority codec as H.265', 'avc1.4d481f'],
});This feature enables/disables autoplay. This can be configured in the player by adding the autoplay option:
{
div: document.getElementById('player'), // Mandatory
src: 'URL video', // Mandatory
autoplay: false
}?> Please note that the default value of the autoplay parameter is true, so the player will start without any user action.
This feature tells the player whether to start playback with the volume muted or not. This can be configured in the player by adding the mutedAtStart option:
{
div: document.getElementById('player'), // Mandatory
src: 'URL video', // Mandatory
mutedAtStart: true
}?> Please note that the default value of the mutedAtStart parameter is false, so the player will start unmuted if mutedAtStart is not set to true.
?> Please note that this feature is currently only available for live DASH streams and the backup manifests MUST have the same properties as the original one (codecs, container format, timestamps, etc.).
It's possible to set one or multiple backup manifests so the player can switch to them in case the original fails. That way, if the original manifest throws a server error, the player will try to use the backup manifests and, if at least one of them is available, the player will keep playing using that manifest without any buffering or pause.
To use it, add the property backupManifest to the setup configuration object. This property is an array of strings, each string being an URL of a manifest.
{
...
backupManifest: [
"https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd",
"https://this.is.an.example.com/manifest1/bbb_30fps.mpd",
"https://this.is.an.example.com/manifest2/bbb_30fps.mpd",
"https://this.is.an.example.com/manifest3/bbb_30fps.mpd"
],
...
}It's also possible to set the number of retries before the player decides it's impossible to keep playing.
{
...
retryParameters: {
streaming: {
maxTries: 6
},
manifest: {
maxTries: 6
}
}
...
}retryParameters.streaming.maxTries is the number of tries the player will try to fetch a segment before the stream fails, while retryParameters.manifest.maxTries is the number of tries before a manifest fails and the player tries a different one. The default value of each one is 2.
The nexplayer.js library is already minified, but to use even less space it's recommended to use gzip on the server where the library will be hosted. gzip is supported on the vast majority of servers.
The hosted versions in our CDN use gzip.
Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to let a user agent gain permission to access selected resources from a server on a different origin (domain) than the site currently in use.
This means that if a video is hosted in a different domain than the player, a header like Access-Control-Allow-Origin: httрs://foo.mycompany.com should be included in the response in order for it not to be blocked by the browser for security reasons. To allow all domains, set the header to Access-Control-Allow-Origin: *.
More information is available at MDN Web Docs.
When a specific version of the library is used, the URL of the hosted library should be upgraded. If the library is hosted on a custom server, replacing nexplayer.js is necessary. Here you can find the latest release.
Every new release of NexPlayer is backwards compatible.