Module: MediaPlayer

The MediaPlayer is the primary dash.js Module and a Facade to build your player around.
It will allow you access to all the important dash.js properties/methods via the public API and all the
events to build a robust DASH media player.

Source:

Members


<inner, constant> ELEMENT_NOT_ATTACHED_ERROR :string

error string thrown when a function is called before the dash.js has received a reference of an HTML5 video element

Type:
  • string
Source:

<inner, constant> MEDIA_PLAYER_NOT_INITIALIZED_ERROR :string

error string thrown when a function is called before the dash.js has been fully initialized.

Type:
  • string
Source:

<inner, constant> PLAYBACK_NOT_INITIALIZED_ERROR :string

error string thrown when a function is called before the dash.js has been fully initialized

Type:
  • string
Source:

<inner, constant> SOURCE_NOT_ATTACHED_ERROR :string

error string thrown when a function is called before the dash.js has received a valid source stream.

Type:
  • string
Source:

<inner, constant> STREAMING_NOT_INITIALIZED_ERROR :string

error string thrown when a function is called before the dash.js has been fully initialized

Type:
  • string
Source:

Methods


addABRCustomRule(type, rulename, rule)

Add a custom ABR Rule
Rule will be apply on next stream if a stream is being played

Parameters:
Name Type Description
type string

rule type (one of ['qualitySwitchRules','abandonFragmentRules'])

rulename string

name of rule (used to identify custom rule). If one rule of same name has been added, then existing rule will be updated

rule object

the rule object instance

Source:
Throws:

BAD_ARGUMENT_ERROR if called with invalid arguments.


addUTCTimingSource(schemeIdUri, value)

Allows you to set a scheme and server source for UTC live edge detection for dynamic streams. If UTCTiming is defined in the manifest, it will take precedence over any time source manually added.

If you have exposed the Date header, use the method clearDefaultUTCTimingSources(). This will allow the date header on the manifest to be used instead of a time server

Parameters:
Name Type Description
schemeIdUri string
  • urn:mpeg:dash:utc:http-head:2014
  • urn:mpeg:dash:utc:http-xsdate:2014
  • urn:mpeg:dash:utc:http-iso:2014
  • urn:mpeg:dash:utc:direct:2014

Some specs referencing early ISO23009-1 drafts incorrectly use 2012 in the URI, rather than 2014. support these for now.

  • urn:mpeg:dash:utc:http-head:2012
  • urn:mpeg:dash:utc:http-xsdate:2012
  • urn:mpeg:dash:utc:http-iso:2012
  • urn:mpeg:dash:utc:direct:2012
value string

Path to a time source.

Default Value:
    • schemeIdUri:urn:mpeg:dash:utc:http-xsdate:2014
    • value:http://time.akamai.com/?iso&ms/li>
Source:
See:

attachProtectionController(value)

Will override dash.js protection controller.

Parameters:
Name Type Description
value ProtectionController

valid protection controller instance.

Source:

attachSource(urlOrManifest)

Use this method to set a source URL to a valid MPD manifest file OR
a previously downloaded and parsed manifest object. Optionally, can
also provide protection information

Parameters:
Name Type Description
urlOrManifest string | Object

A URL to a valid MPD manifest file, or a
parsed manifest object.

Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function


attachTTMLRenderingDiv(div)

Use this method to attach an HTML5 div for dash.js to render rich TTML subtitles.

Parameters:
Name Type Description
div HTMLDivElement

An unstyled div placed after the video element. It will be styled to match the video size and overlay z-order.

Source:
Throws:

ELEMENT_NOT_ATTACHED_ERROR if called before attachView function


attachView(element)

Use this method to attach an HTML5 VideoElement for dash.js to operate upon.

Parameters:
Name Type Description
element Object

An HTMLMediaElement that has already been defined in the DOM (or equivalent stub).

Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function


clearDefaultUTCTimingSources()

Allows you to clear the stored array of time sources.

Example use: If you have exposed the Date header, calling this method will allow the date header on the manifest to be used instead of the time server.

Example use: Calling this method, assuming there is not an exposed date header on the manifest, will default back to using a binary search to discover the live edge

Source:
See:

convertToTimeCode(value)

A utility method which converts seconds into TimeCode (i.e. 300 --> 05:00).

Parameters:
Name Type Description
value number

A number in seconds to be converted into a formatted time code.

Source:
Returns:

A formatted time code string.

Type
string

destroy()

Completely destroys the media player and frees all memory.

Source:

duration()

Duration of the media's playback, in seconds.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

The current duration of the media. For a dynamic stream this will return DVRWindow.end - DVRWindow.start

Type
number

durationAsUTC()

Use this method to get the current duration as an absolute value, the time in seconds since midnight UTC, Jan 1 1970.
Note - this property only has meaning for live streams.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

The current duration as UTC timestamp.

Type
number

enableForcedTextStreaming(enable)

Enable/disable text
When enabling dash will keep downloading and process fragmented text tracks even if all tracks are in mode "hidden"

Parameters:
Name Type Description
enable boolean

true to enable text streaming even if all text tracks are hidden.

Source:

enableText(enable)

Enable/disable text
When enabling text, dash will choose the previous selected text track

Parameters:
Name Type Description
enable boolean

true to enable text, false otherwise (same as setTextTrack(-1))

Source:

extend(parentNameString, childInstance, override)

This method should be used to extend or replace internal dash.js objects.
There are two ways to extend dash.js (determined by the override argument):

  1. If you set override to true any public method or property in your custom object will override the dash.js parent object's property(ies) and will be used instead but the dash.js parent module will still be created.
  2. If you set override to false your object will completely replace the dash.js object. (Note: This is how it was in 1.x of Dash.js with Dijon).
When you extend you get access to this.context, this.factory and this.parent to operate with in your custom object.
  • this.context - can be used to pass context for singleton access.
  • this.factory - can be used to call factory.getSingletonInstance().
  • this.parent - is the reference of the parent object to call other public methods. (this.parent is excluded if you extend with override set to false or option 2)
You must call extend before you call initialize
Parameters:
Name Type Description
parentNameString string

name of parent module

childInstance Object

overriding object

override boolean

replace only some methods (true) or the whole object (false)

Source:
See:

formatUTC(time, locales, hour12, withDate)

A utility methods which converts UTC timestamp value into a valid time and date string.

Parameters:
Name Type Default Description
time number

UTC timestamp to be converted into date and time.

locales string

a region identifier (i.e. en_US).

hour12 boolean

12 vs 24 hour. Set to true for 12 hour time formatting.

withDate boolean false

default is false. Set to true to append current date to UTC time format.

Source:
Returns:

A formatted time and date string.

Type
string

getActiveStream()

This method returns the active stream

Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function


getAutoPlay()

Source:
Returns:

The current autoPlay state.

Type
boolean

getAverageThroughput(type)

Returns the average throughput computed in the ABR logic

Parameters:
Name Type Description
type MediaType
Source:
Returns:

value

Type
number

getBitrateInfoListFor(type)

Parameters:
Name Type Description
type MediaType
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:
Type
Array

getBufferLength(type)

The length of the buffer for a given media type, in seconds. Valid media
types are "video", "audio" and "text". If no type is passed
in, then the minimum of video, audio and text buffer length is
returned. NaN is returned if an invalid type is requested, the
presentation does not contain that type, or if no arguments are passed
and the presentation does not include any adaption sets of valid media
type.

Parameters:
Name Type Description
type MediaType

'video', 'audio' or 'text'

Source:
Returns:

The length of the buffer for the given media type, in
seconds, or NaN

Type
number

getCurrentLiveLatency()

Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function

Returns:

Current live stream latency in seconds. It is the difference between now time and time position at the playback head.

Type
number | NaN

getCurrentTrackFor(type)

Parameters:
Name Type Description
type MediaType
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

MediaInfo

Type
Object | null

getDashAdapter()

Returns the DashAdapter.js Module.

Source:
See:
Returns:
Type
Object

getDashMetrics()

Returns the DashMetrics.js Module. You use this Module to get access to all the public metrics
stored in dash.js

Source:
See:
Returns:
Type
Object

getDebug()

Use this method to access the dash.js logging class.

Source:
Returns:
Type
Debug

getDVRSeekOffset(value)

This method should only be used with a live stream that has a valid timeShiftBufferLength (DVR Window).
NOTE - If you do not need the raw offset value (i.e. media analytics, tracking, etc) consider using the seek() method
which will calculate this value for you and set the video element's currentTime property all in one simple call.

Parameters:
Name Type Description
value number

A relative time, in seconds, based on the return value of the duration() method is expected.

Source:
See:
Returns:

A value that is relative the available range within the timeShiftBufferLength (DVR Window).

Type
number

getDVRWindowSize()

The timeShiftBufferLength (DVR Window), in seconds.

Source:
Returns:

The window of allowable play time behind the live point of a live stream as defined in the manifest.

Type
number

getInitialMediaSettingsFor(type)

This method returns media settings that is used to pick the initial track. Format of the settings
is following:
{lang: langValue,
index: indexValue,
viewpoint: viewpointValue,
audioChannelConfiguration: audioChannelConfigurationValue,
accessibility: accessibilityValue,
role: roleValue}

Parameters:
Name Type Description
type MediaType
Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function

Returns:
Type
Object

getOfflineController()

Detects if Offline is included and returns an instance of OfflineController.js

Source:

getPlaybackRate()

Returns the current playback rate.

Source:
Returns:
Type
number

getProtectionController()

Detects if Protection is included and returns an instance of ProtectionController.js

Source:

getQualityFor(type)

Gets the current download quality for media type video, audio or images. For video and audio types the ABR
rules update this value before every new download unless autoSwitchBitrate is set to false. For 'image'
type, thumbnails, there is no ABR algorithm and quality is set manually.

Parameters:
Name Type Description
type MediaType

'video', 'audio' or 'image' (thumbnails)

Source:
See:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

the quality index, 0 corresponding to the lowest bitrate

Type
number

getSettings()

Get the current settings object being used on the player.

Source:
Returns:

The settings object being used.

Type
PlayerSettings

getSource()

Returns the source string or manifest that was attached by calling attachSource()

Source:
Throws:

SOURCE_NOT_ATTACHED_ERROR if called before attachSource function

Returns:
Type
string | manifest

getStreamsFromManifest(manifest)

This method returns the list of all available streams from a given manifest

Parameters:
Name Type Description
manifest Object
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

list of StreamInfo

Type
Array

getTopBitrateInfoFor(type)

Gets the top quality BitrateInfo checking portal limit and max allowed.
It calls getMaxAllowedIndexFor internally

Parameters:
Name Type Description
type MediaType

'video' or 'audio'

Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:
Type
BitrateInfo | null

getTracksFor(type)

This method returns the list of all available tracks for a given media type

Parameters:
Name Type Description
type MediaType
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

list of MediaInfo

Type
Array

getTracksForTypeFromManifest(type, manifest, streamInfo)

This method returns the list of all available tracks for a given media type and streamInfo from a given manifest

Parameters:
Name Type Description
type MediaType
manifest Object
streamInfo Object
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

list of MediaInfo

Type
Array

getTTMLRenderingDiv()

Returns instance of Div that was attached by calling attachTTMLRenderingDiv()

Source:
Returns:
Type
Object

getVersion()

Current version of Dash.js

Source:
Returns:

the current dash.js version string.

Type
string

getVideoElement()

Returns instance of Video Element that was attached by calling attachView()

Source:
Throws:

ELEMENT_NOT_ATTACHED_ERROR if called before attachView function

Returns:
Type
Object

getVolume()

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

Source:
Returns:
Type
number

getXHRWithCredentialsForType(type)

Gets whether withCredentials on XHR requests for a particular request
type is true or false

Parameters:
Name Type Description
type string

one of HTTPRequest.*_TYPE

Source:
Returns:
Type
boolean

initialize( [view] [, source] [, AutoPlay])

Upon creating the MediaPlayer you must call initialize before you call anything else.
There is one exception to this rule. It is crucial to call extend()
with all your extensions prior to calling initialize.

ALL arguments are optional and there are individual methods to set each argument later on.
The args in this method are just for convenience and should only be used for a simple player setup.

Parameters:
Name Type Argument Description
view HTML5MediaElement <optional>

Optional arg to set the video element. attachView()

source string <optional>

Optional arg to set the media source. attachSource()

AutoPlay boolean <optional>

Optional arg to set auto play. setAutoPlay()

Source:
See:

isDynamic()

Returns a Boolean that indicates whether the media is in the process of dynamic.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:
Type
boolean

isMuted()

A Boolean that determines whether audio is muted.

Source:
Returns:
Type
boolean

isPaused()

Returns a Boolean that indicates whether the Video Element is paused.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:
Type
boolean

isReady()

The ready state of the MediaPlayer based on both the video element and MPD source being defined.

Source:
See:
Returns:

The current ready state of the MediaPlayer

Type
boolean

isSeeking()

Returns a Boolean that indicates whether the media is in the process of seeking to a new position.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:
Type
boolean

isTextEnabled()

Return if text is enabled

Source:
Returns:

return true if text is enabled, false otherwise

Type
boolean

off(type, listener, scope)

Use the off method to remove listeners for public events found in MediaPlayer.events. MediaPlayerEvents

Parameters:
Name Type Description
type string

MediaPlayerEvents

listener function

callback method when the event fires.

scope Object

context of the listener so it can be removed properly.

Source:

on(type, listener, scope, options)

Use the on method to listen for public events found in MediaPlayer.events. MediaPlayerEvents

Parameters:
Name Type Description
type string

MediaPlayerEvents

listener function

callback method when the event fires.

scope Object

context of the listener so it can be removed properly.

options Object

object to define various options such as priority and mode

Source:

pause()

This method will call pause on the native Video Element.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function


play()

The play method initiates playback of the media defined by the attachSource() method.
This method will call play on the native Video Element.

Source:
See:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function


provideThumbnail(time, callback)

Provide the thumbnail at time position. This can be asynchronous, so you must provide a callback ro retrieve thumbnails informations

Parameters:
Name Type Description
time number

A relative time, in seconds, based on the return value of the duration() method is expected

callback function

A Callback function provided when retrieving thumbnail the given time position. Thumbnail object is null in case there are is not a thumbnails representation or
if it doesn't contain a thumbnail for the given time position.

Source:

registerCustomCapabilitiesFilter(filter)

Registers a custom capabilities filter. This enables application to filter representations to use.
The provided callback function shall return a boolean based on whether or not to use the representation.
The filters are applied in the order they are registered.

Parameters:
Name Type Description
filter function

the custom capabilities filter callback

Source:

registerLicenseRequestFilter(filter)

Registers a license request filter. This enables application to manipulate/overwrite any request parameter and/or request data.
The provided callback function shall return a promise that shall be resolved once the filter process is completed.
The filters are applied in the order they are registered.

Parameters:
Name Type Description
filter function

the license request filter callback

Source:

registerLicenseResponseFilter(filter)

Registers a license response filter. This enables application to manipulate/overwrite the response data
The provided callback function shall return a promise that shall be resolved once the filter process is completed.
The filters are applied in the order they are registered.

Parameters:
Name Type Description
filter function

the license response filter callback

Source:

removeABRCustomRule(rulename)

Remove a custom ABR Rule

Parameters:
Name Type Description
rulename string

name of the rule to be removed

Source:

removeAllABRCustomRule()

Remove all custom rules

Source:

removeUTCTimingSource(schemeIdUri, value)

Allows you to remove a UTC time source. Both schemeIdUri and value need to match the Dash.vo.UTCTiming properties in order for the entry to be removed from the array

Parameters:
Name Type Description
schemeIdUri string

see addUTCTimingSource()

value string

see addUTCTimingSource()

Source:
See:
Throws:

BAD_ARGUMENT_ERROR if called with invalid arguments, schemeIdUri and value are not string type.


reset()

Sets the MPD source and the video element to null. You can also reset the MediaPlayer by
calling attachSource with a new source file.

This call does not destroy the MediaPlayer. To destroy the MediaPlayer and free all of its
memory, call destroy().

Source:

resetSettings()

Resets the settings object back to the default.

Source:

restoreDefaultUTCTimingSources()

Allows you to restore the default time sources after calling clearDefaultUTCTimingSources()

Default Value:
    • schemeIdUri:urn:mpeg:dash:utc:http-xsdate:2014
    • value:http://time.akamai.com/?iso&ms
Source:
See:

retrieveManifest(url, callback)

Allows application to retrieve a manifest. Manifest loading is asynchro
nous and
requires the app-provided callback function

Parameters:
Name Type Description
url string

url the manifest url

callback function

A Callback function provided when retrieving manifests

Source:

seek(value)

Sets the currentTime property of the attached video element. If it is a live stream with a
timeShiftBufferLength, then the DVR window offset will be automatically calculated.

Parameters:
Name Type Description
value number

A relative time, in seconds, based on the return value of the duration() method is expected

Source:
See:
Throws:

setAutoPlay(value)

Set to false to prevent stream from auto-playing when the view is attached.

Parameters:
Name Type Description
value boolean
Default Value:
  • true
Source:
See:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, not boolean type.


setConfig( [config])

Configure media player with customs controllers. Helpful for tests

Parameters:
Name Type Argument Description
config object <optional>

controllers configuration

Source:

setCurrentTrack(track)

Parameters:
Name Type Description
track MediaInfo

instance of MediaInfo

Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function


setInitialMediaSettingsFor(type, value)

This method allows to set media settings that will be used to pick the initial track. Format of the settings
is following:

{lang: langValue (can be either a string or a regex to match),
index: indexValue,
viewpoint: viewpointValue,
audioChannelConfiguration: audioChannelConfigurationValue,
accessibility: accessibilityValue,
role: roleValue}

Parameters:
Name Type Description
type MediaType
value Object
Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function


setMute(value)

Use this method to set the native Video Element's muted state. Takes a Boolean that determines whether audio is muted. true if the audio is muted and false otherwise.

Parameters:
Name Type Description
value boolean
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, not boolean type.


setPlaybackRate(value)

Use this method to set the native Video Element's playback rate.

Parameters:
Name Type Description
value number
Source:

setProtectionData(value)

Sets Protection Data required to setup the Protection Module (DRM). Protection Data must
be set before initializing MediaPlayer or, once initialized, before PROTECTION_CREATED event is fired.

Parameters:
Name Type Description
value ProtectionDataSet

object containing
property names corresponding to key system name strings and associated
values being instances of.

Source:
See:

setQualityFor(type, value, forceReplace)

Sets the current quality for media type instead of letting the ABR Heuristics automatically selecting it.
This value will be overwritten by the ABR rules unless autoSwitchBitrate is set to false.

Parameters:
Name Type Default Description
type MediaType

'video', 'audio' or 'image'

value number

the quality index, 0 corresponding to the lowest bitrate

forceReplace boolean false

true if segments have to be replaced by segments of the new quality

Source:
See:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function


setTextTrack(idx)

Use this method to change the current text track for both external time text files and fragmented text tracks. There is no need to
set the track mode on the video object to switch a track when using this method.

Parameters:
Name Type Description
idx number

Index of track based on the order of the order the tracks are added Use -1 to disable all tracks. (turn captions off). Use module:MediaPlayer#dashjs.MediaPlayer.events.TEXT_TRACK_ADDED.

Source:
See:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function


setVolume(value)

A double indicating the audio volume, from 0.0 (silent) to 1.0 (loudest).

Parameters:
Name Type Description
value number
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, not number type, or is NaN or not between 0 and 1.


setXHRWithCredentialsForType(type, value)

Sets whether withCredentials on XHR requests for a particular request
type is true or false

Parameters:
Name Type Description
type string

one of HTTPRequest.*_TYPE

value boolean
Default Value:
  • false
Source:

time(streamId)

Current time of the playhead, in seconds.

If called with no arguments then the returned time value is time elapsed since the start point of the first stream, or if it is a live stream, then the time will be based on the return value of the duration() method.
However if a stream ID is supplied then time is relative to the start of that stream, or is null if there is no such stream id in the manifest.

Parameters:
Name Type Description
streamId string

The ID of a stream that the returned playhead time must be relative to the start of. If undefined, then playhead time is relative to the first stream.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

The current playhead time of the media, or null.

Type
number

timeAsUTC()

Use this method to get the current playhead time as an absolute value, the time in seconds since midnight UTC, Jan 1 1970.
Note - this property only has meaning for live streams. If called before play() has begun, it will return a value of NaN.

Source:
Throws:

PLAYBACK_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

The current playhead time as UTC timestamp.

Type
number

unregisterCustomCapabilitiesFilter(filter)

Unregisters a custom capabilities filter.

Parameters:
Name Type Description
filter function

the custom capabilities filter callback

Source:

unregisterLicenseRequestFilter(filter)

Unregisters a license request filter.

Parameters:
Name Type Description
filter function

the license request filter callback

Source:

unregisterLicenseResponseFilter(filter)

Unregisters a license response filter.

Parameters:
Name Type Description
filter function

the license response filter callback

Source:

updatePortalSize()

Update the video element size variables
Should be called on window resize (or any other time player is resized). Fullscreen does trigger a window resize event.

Once windowResizeEventCalled = true, abrController.checkPortalSize() will use element size variables rather than querying clientWidth every time.

Source:

updateSettings(settingsObj)

Update the current settings object being used on the player. Anything left unspecified is not modified.

This function does not update the entire object, only properties in the passed in object are updated.

This means that updateSettings({a: x}) and updateSettings({b: y}) are functionally equivalent to
updateSettings({a: x, b: y}). If the default values are required again, @seeresetSettings.

Parameters:
Name Type Description
settingsObj PlayerSettings

An object corresponding to the settings definition.

Source:
Example
player.updateSettings({
     streaming: {
         lowLatencyEnabled: false,
         abr: {
             maxBitrate: { audio: 100, video: 1000 }
         }
     }
 });