Documentation Class: MediaPlayer

new MediaPlayer()

The copyright in this software module is being made available under the BSD License, included below. This software module may be subject to other third party and/or contributor rights, including patent rights, and no such rights are granted under this license. The whole software resulting from the execution of this software module together with its external dependent software modules from dash.js project may be subject to Orange and/or other third party rights, including patent rights, and no such rights are granted under this license. Copyright (c) 2014, Orange All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. • Neither the name of the Orange nor the names of its contributors may be used to endorse or promote products derived from this software module without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Members

<static> dependencies

Packages declaration

<static> PUBLIC_EVENTS

ENUMS

<static> TRACKS_TYPE

Exposes the available tracks types used to manage tracks (language) switching.

Properties:

Name	Type	Default	Description
`AUDIO`		audio
`TEXT`		text

See:

Methods

addEventListener(type, listener, useCapture)

Registers a listener on the specified event. The possible event types are:

'error' (see error event specification)

'warning' (see warning event specification)

'manifestUrlUpdate' (see manifestUrlUpdate event specification)

'play_bitrate' (see play_bitrate event specification)

'download_bitrate' (see download_bitrate event specification)

'bufferLevel_updated' (see bufferLevel_updated event specification)

'state_changed' (see state_changed event specification)

Parameters:

Name	Type	Description
`type`	string	the event type for listen to, either any HTML video element event or player event.
`listener`	callback	the callback which is called when an event of the specified type occurs
`useCapture`	boolean	see HTML DOM addEventListener() method specification

addPlugin(plugin)

Adds a MediaPlayer plugin.

Parameters:

Name	Type	Description
`plugin`	object	the plugin instance

enableSubtitleExternDisplay(mode)

Enables or disables subtitles display in a div outside video player.

Parameters:

Name	Type	Description
`mode`	boolean	true if subtitles are displayed in a div outside video player

enableSubtitles(value)

Enable or disables subtitles processing.

Parameters:

Name	Type	Description
`value`	boolean	true to enable subtitles, false to disables subtitles processing (by default subtitles are disabled)

getAutoPlay() → {boolean}

Returns the autoplay state.

Returns:

the autoplay state

Type: boolean

getAutoSwitchQuality() → {boolean}

Returns the auto switch quality state.

Returns:

the auto switch quality state

Type: boolean

getBuildDate() → {string}

Returns the date at which this player has been built.

Returns:

the date at which this player has been built

Type: string

getDebug() → {object}

Returns the debug object.

Returns:

the debug object

Type: object

getDefaultAudioLang() → {string}

Gets the default audio language.

Returns:

lang - the default audio language based on ISO 3166-2

Type: string

getDefaultSubtitleLang() → {string}

Gets the default subtitle language.

Returns:

lang - the default subtitle language based on ISO 3166-2

Type: string

getDuration() → {number}

Returns the media duration.

Returns:

the media duration in seconds, Infinity for live content

Type: number

getDVRSeekOffset(value)

TBD

Parameters:

Name	Type	Description
`value`

Returns:

DVR seek offset

getDVRWindowSize() → {number}

Returns the DVR window size.

Returns:

the DVR window size in seconds

Type: number

getError() → {object}

Returns the Error object for the most recent error.

Returns:

the Error object for the most recent error, or null if there has not been an error

Type: object

getMetricsExt() → {object}

Returns the metrics extension object.

Returns:

the metrics extension object

Type: object

getMetricsFor(type) → {Array}

Returns the metrics for stream type.

Parameters:

Name	Type	Description
`type`	string	stream type, 'video' or 'audio'

Returns:

the metrics array for the selected type

Type: Array

getMute() → {boolean}

Returns the audio mute state.

Returns:

true if the audio is muted, false otherwise

Type: boolean

getPosition() → {number}

Returns the current playback time/position.

Returns:

the current playback time/position in seconds

Type: number

getQualityFor(type) → {number}

Returns the current quality for a stream type.

Parameters:

Name	Type	Description
`type`	string	stream type, 'video' or 'audio'

Returns:

the current quality level as an index of the quality (in bitrate ascending order)

Type: number

getScheduleWhilePaused() → {boolean}

Returns the buffering behaviour while the player is in pause.

Returns:

true if the player still buffers stream while in pause

Type: boolean

getSelectedTrack(type) → {Track}

Returns the selected track for the stream type.

Parameters:

Name	Type	Description
`type`	String	the stream type according to MediaPlayer.TRACKS_TYPE (see @link MediaPlayer#TRACKS_TYPE)

Returns:

the selected track

Type: Track

getTerminalId() → {string}

Returns the terminal ID.

Returns:

the terminal ID (--)

Type: string

getTracks(type) → {Array.<Track>}

Returns the list of available tracks for the stream type (as specified in the stream manifest). The tracks list can be retrieved once the video 'loadeddata' event has been fired.

Parameters:

Name	Type	Description
`type`	String	the stream type according to MediaPlayer.TRACKS_TYPE (see @link MediaPlayer#TRACKS_TYPE)

Returns:

the available tracks for the stream type

Type: Array.<Track>

getVersion() → {string}

Returns the version of the player.

Returns:

the version of the player

Type: string

getVersionDashJS() → {string}

Returns the version of dash.js from which this player has been built.

Returns:

the dash.js version

Type: string

getVersionFull() → {string}

Returns the full version of the player (including git tag).

Returns:

the version of the player including git tag

Type: string

getVideoBitrates() → {Array.<Number>}

Returns the list of available bitrates (as specified in the stream manifest).

Returns:

array of bitrate values

Type: Array.<Number>

getVideoModel() → {object}

Returns the video model object.

Returns:

the video model object

Type: object

getVolume() → {number}

Returns the audio volume level.

Returns:

the current audio volume level, from 0.0 (silent) to 1.0 (loudest)

Type: number

getWarning() → {object}

Returns the Warning object for the most recent warning.

Returns:

the Warning object for the most recent warning, or null if there has not been a warning

Type: object

init(video)

Initialize the player.

Parameters:

Name	Type	Description
`video`	Object	the HTML5 video element used to decode and render the media data

isLive() → {object}

Return the available DVR window range in case of live streams.

Returns:

range - the DVR window range

Type

object
range.start - the DVR window range start time

Type

number
range.end - the DVR window range end time

Type

number

isLive() → {boolean}

Returns true if the current stream is a live stream.

Returns:

true if current stream is a live stream, false otherwise

Type: boolean

isSubtitlesEnabled()

Returns the subtitles processing state.

load(stream)

Load/open a video stream.

Parameters:

Name Type Description

Name	Type	Description
`stream`	object	video stream properties object such url, startTime, prodData ... { url : "[manifest url]", startTime : [start time in seconds (optionnal)] protData : { // one entry for each key system ('com.microsoft.playready' or 'com.widevine.alpha') "[key_system_name]": { laURL: "[licenser url (optionnal)]", pssh: "[base64 pssh box (optionnal)]" cdmData: "[CDM data (optionnal)]" }, ... } ... }

stream

object

video stream properties object such url, startTime, prodData ...

            {
                url : "[manifest url]",
                startTime : [start time in seconds (optionnal)]
                protData : {
                    // one entry for each key system ('com.microsoft.playready' or 'com.widevine.alpha')
                    "[key_system_name]": {
                        laURL: "[licenser url (optionnal)]",
                        pssh: "[base64 pssh box (optionnal)]"
                        cdmData: "[CDM data (optionnal)]"
                    },
                    ...
               }
               ...
            }

pause()

Pauses the media playback.

play()

Plays/resumes playback of the media.

removeEventListener(type, listener)

Unregisters the listener previously registered with the addEventListener() method.

Parameters:

Name	Type	Description
`type`	string	the event type on which the listener was registered
`listener`	callback	the callback which was registered to the event type

See:

addEventListener

removePlugin(plugin)

Removes a MediaPlayer plugin.

Parameters:

Name	Type	Description
`plugin`	object \| string	the plugin instance (or name) to remove

reset(reason)

Stops and resets the player.

Parameters:

Name	Type	Description
`reason`	number	the reason for stopping the player. Possible values are: 0 : stop during streaming at user request 1 : stop when all streams are completed 2 : stop after an error

seek(time)

Seeks the media to the new time. For LIVE streams, this function can be used to perform seeks within the DVR window if available.

Parameters:

Name	Type	Description
`time`	number	the new time value in seconds

selectTrack(type, track)

Selects the track to be playbacked for the stream type.

Parameters:

Name	Type	Description
`type`	String	the stream type according to MediaPlayer.TRACKS_TYPE (see @link MediaPlayer#TRACKS_TYPE)
`track`	Track	the track to select

See:

getTracks

setAutoPlay(value)

Sets the autoplay state.

Parameters:

Name	Type	Description
`value`	boolean	true to activate autoplay, false to disable autoplay

setAutoSwitchQuality(value)

Sets the auto switch quality state.

Parameters:

Name	Type	Description
`value`	boolean	the new auto switch quality state

setConfig(params)

Sets player configuration parameters.

Parameters:

Name	Type	Description
`params`	PlayerParams	parameter(s) value(s) to set.

setDebug(value)

Enables or disables debug information in the browser console.

Parameters:

Name	Type	Description
`value`	boolean	true to enable debug information, false to disable

setDefaultAudioLang(lang)

Sets the default audio language. If the default language is available in the stream, the corresponding audio track is selected. Otherwise, the first declared audio track in the manifest is selected.

Parameters:

Name	Type	Description
`lang`	string	the default audio language based on ISO 3166-2

setDefaultSubtitleLang(lang)

Sets the default subtitle language. If the default language is available in the stream, the corresponding subtitle track is selected. Otherwise, the first declared subtitle track in the manifest is selected.

Parameters:

Name	Type	Description
`lang`	string	the default subtitle language based on ISO 3166-2

setInitialQualityFor(type, value)

Sets the initial quality to be downloaded for the given track type. This method has to be used before each call to load() method to set the initial quality. Otherwise, the initial quality is set according to previous bandwidth condition.

Parameters:

Name	Type	Description
`type`	string	the track type ('video' or 'audio')
`value`	number	the new initial quality index (starting from 0) to be downloaded

See:

setConfig to set quality boundaries

setMute(value)

Sets the audio mute state.

Parameters:

Name	Type	Description
`value`	boolean	true to mute audio, false otherwise

setQualityFor(type, value)

Selects the quality for a stream type.

Parameters:

Name	Type	Description
`type`	string	stream type, 'video' or 'audio'
`value`	number	the selected quality level as an index of the quality (in bitrate ascending order)

setScheduleWhilePaused(value)

Sets the buffering behaviour while player is in pause.

Parameters:

Name	Type	Description
`value`	boolean	true if the player has to buffer stream while in pause

setTrickModeSpeed() → {number}

Returns the current trick mode speed.

Returns:

the current trick mode speed

Type: number

setTrickModeSpeed(speed)

Sets the trick mode speed.

Parameters:

Name	Type	Description
`speed`	number	the new trick mode speed (0 corresponds to normal playback, i.e. playbackRate = 1)

setVolume(level)

Sets the audio volume level.

Parameters:

Name	Type	Description
`level`	number	the audio volume level, from 0.0 (silent) to 1.0 (loudest)

stop()

Stops the media playback and seek back to start of stream and media. Subsequently call to play() method will restart streaming and playing from beginning.

<inner> _onTimeupdate()

Usefull to dispatch event of quality changed

Events

bufferLevel_updated

The bufferLevel_updated event is fired when the buffer level changed.

Parameters:

Name Type Description

event

CustomEvent

the event

Properties

Name Type Description

detail

object

the event data

Properties

Name	Type	Description
`type`	string	the stream type ('audio' or 'video')
`level`	number	the buffer level (in seconds)

cueEnter

The cueEnter event is fired when a subtitle cue needs to be displayed.

Parameters:

Name Type Description

event

object

the event

Properties

Name Type Description

type object the event type ('cueEnter')

data

object

the event data

Properties

Name	Type	Description
`text`	object	the subtitle text
`style.backgroundColor`	string	the background color
`style.color`	string	the font color
`style.fontFamily`	string	the font family
`style.fontSize`	string	the font size

cueExit

The cueExit event is fired when a subtitle cue needs to be erased.

Parameters:

Name Type Description

event

object

the event

Properties

Name Type Description

type object the event type ('cueExit')

data

object

the event data

Properties

Name	Type	Description
`text`	object	the subtitle text
`style.backgroundColor`	string	the background color
`style.color`	string	the font color
`style.fontFamily`	string	the font family
`style.fontSize`	string	the font size

download_bitrate

The download_bitrate event is fired when the current downloaded bitrate has changed.

Parameters:

Name Type Description

event

CustomEvent

the event

Properties

Name Type Description

detail

object

the event data

Properties

Name	Type	Description
`type`	string	the stream type ('audio' or 'video')
`bitrate`	number	the new bitrate
`representationId`	string	the corresponding representation id (from manifest)
`time`	number	the current video time
`width`	number	in case of video stream, the video width of the representation
`height`	number	in case of video stream, the video height of the representation

error

The error event is fired when an error occurs. When the error event is fired, the application shall stop the player.

Parameters:

Name Type Description

event

object

the event

Properties

Name Type Description

type object the event type ('error')

data

object

the event data

Properties

Name	Type	Description
`code`	string	error code
`message`	string	error message
`data`	object	error additionnal data

manifestUrlUpdate

The manifestUrlUpdate event is fired when the URL of the manifest may have to be refreshed, since the player failed to download the manifest file (URL expiration for example). The application shall therefore provide an updated manifest URL by using the method refreshManifest

Parameters:

Name Type Description

event

object

the event

Properties

Name Type Description

type object the event type ('manifestUrlUpdate')

data

object

the event data

Properties

Name	Type	Description
`url`	object	the current manifest url

play_bitrate

The 'play_bitrate' event is fired when the current played bitrate has changed.

Parameters:

Name Type Description

event

CustomEvent

the event

Properties

Name Type Description

detail

object

the event data

Properties

Name	Type	Description
`type`	string	the stream type ('audio' or 'video')
`bitrate`	number	the new bitrate
`representationId`	string	the corresponding representation id (from manifest)
`time`	number	the current video time
`width`	number	in case of video stream, the video width of the representation
`height`	number	in case of video stream, the video height of the representation

state_changed

The state_changed event is fired when the player state changed.

Parameters:

Name Type Description

event

CustomEvent

the event

Properties

Name Type Description

detail

object

the event data

Properties

Name	Type	Description
`type`	string	the stream type ('audio' or 'video')
`state`	string	the current state ('stopped', 'buffering', 'seeking' or 'playing')

warning

The warning event is fired when a warning occurs.

Parameters:

Name Type Description

event

object

the event

Properties

Name Type Description

type object the event type ('warning')

data

object

the event data

Properties

Name	Type	Description
`code`	string	warning code
`message`	string	warning message
`data`	object	warning additionnal data