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_LOW_LATENCY_MAX_DRIFT_BAD_ARGUMENT_ERROR :string

error string thrown when setLowLatencyMaxDriftBeforeSeeking function is called with an invalid value.

Type:
  • string
Source:

<inner, constant> PLAYBACK_LOW_LATENCY_MIN_DRIFT_BAD_ARGUMENT_ERROR :string

error string thrown when setLowLatencyMinDrift function is called with an invalid value.

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


attachVideoContainer(container)

Use this method to attach an HTML5 element that wraps the video element.

Parameters:
Name Type Description
container HTMLElement

The HTML5 element containing the video element.

Deprecated:
  • Yes
Source:

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

displayCaptionsOnTop(value)

This method serves to control captions z-index value. If 'true' is passed, the captions will have the highest z-index and be displayed on top of other html elements. Default value is 'false' (z-index is not set).

Parameters:
Name Type Description
value boolean
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.

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:

enableLastBitrateCaching(enable [, ttl])

Set to false if you would like to disable the last known bit rate from being stored during playback and used to set the initial bit rate for subsequent playback within the expiration window.

The default expiration is one hour, defined in milliseconds. If expired, the default initial bit rate (closest to 1000 kbps) will be used for that session and a new bit rate will be stored during that session.

Parameters:
Name Type Argument Description
enable boolean

Will toggle if feature is enabled. True to enable, False to disable.

ttl number <optional>

(Optional) A value defined in milliseconds representing how long to cache the bit rate for. Time to live.

Default Value:
  • enable = True, ttl = 360000 (1 hour)
Source:
Throws:

BAD_ARGUMENT_ERROR if called with invalid arguments, enable is not boolean type and, if defined, ttl is not a number or is NaN.


enableLastMediaSettingsCaching(enable [, ttl])

Set to false if you would like to disable the last known lang for audio (or camera angle for video) from being stored during playback and used to set the initial settings for subsequent playback within the expiration window.

The default expiration is one hour, defined in milliseconds. If expired, the default settings will be used for that session and a new settings will be stored during that session.

Parameters:
Name Type Argument Description
enable boolean

Will toggle if feature is enabled. True to enable, False to disable.

ttl number <optional>

(Optional) A value defined in milliseconds representing how long to cache the settings for. Time to live.

Default Value:
  • enable = True, ttl = 360000 (1 hour)
Source:
Throws:

BAD_ARGUMENT_ERROR if called with invalid arguments, enable is not boolean type and, if defined, ttl is not a number or is NaN.


enableManifestDateHeaderTimeSource(value)

Allows you to enable the use of the Date Header, if exposed with CORS, as a timing source for live edge detection. The use of the date header will happen only after the other timing source that take precedence fail or are omitted as described. clearDefaultUTCTimingSources()

Parameters:
Name Type Description
value boolean

true to enable

Default Value:
  • {boolean} True
Source:
See:
Throws:

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


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

getABRStrategy()

Returns the current ABR strategy being used.

Source:
See:
Returns:

"abrDynamic", "abrBola" or "abrThroughput"

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

getAutoSwitchQualityFor(type)

Parameters:
Name Type Description
type string

'audio' | 'video'

Source:
Returns:

Current state of adaptive bitrate switching

Type
boolean

getAverageThroughput(type)

Returns the average throughput computed in the ABR logic

Parameters:
Name Type Description
type string
Source:
Returns:

value

Type
number

getBandwidthSafetyFactor()

Returns the number of the current BandwidthSafetyFactor

Source:
See:
Returns:

value

Type
number

getBitrateInfoListFor(type)

Parameters:
Name Type Description
type string
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 "fragmentedText". If no type is passed in, then the minimum of video, audio and fragmentedText 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 string

the media type of the buffer

Source:
Returns:

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

Type
number

getBufferTimeAtTopQuality()

The time that the internal buffer target will be set to once playing the top quality. If there are multiple bitrates in your adaptation, and the media is playing at the highest bitrate, then we try to build a larger buffer at the top quality to increase stability and to maintain media quality.

Default Value:
  • 30 seconds.
Source:

getBufferTimeAtTopQualityLongForm()

The time that the internal buffer target will be set to once playing the top quality for long form content.

Default Value:
  • 60 seconds.
Source:
See:

getCatchUpPlaybackRate()

Returns the current catchup playback rate.

Source:
See:
Returns:
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 current time and time position at the playback head.

Type
number | NaN

getCurrentTrackFor(type)

Parameters:
Name Type Description
type string
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

MediaInfo

Type
Object | null

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.

Type
number

getFastSwitchEnabled()

Disabled by default. Will return the current state of Fast Switch.

Source:
See:
Returns:

Returns true if FastSwitch ABR is enabled.

Type
boolean

getInitialBitrateFor(type)

Parameters:
Name Type Description
type string
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

A value of the initial bitrate, kbps

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, viewpoint: viewpointValue, audioChannelConfiguration: audioChannelConfigurationValue, accessibility: accessibilityValue, role: roleValue}

Parameters:
Name Type Description
type string
Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function

Returns:
Type
Object

getInitialRepresentationRatioFor(type)

Parameters:
Name Type Description
type string
Source:
Returns:

A value of the initial Representation Ratio

Type
number

getJumpGaps()

Gets current status of jump gaps feature.

Source:
Returns:

The current jump gaps state.

Type
boolean

getLimitBitrateByPortal()

Source:

getLiveDelay()

Source:
See:
Returns:

Current live stream delay in seconds when previously set, or undefined

Type
number | undefined

getLowLatencyEnabled()

Returns if low latency mode is enabled. Disabled by default.

Source:
See:
Returns:

true - if enabled

Type
boolean

getLowLatencyMaxDriftBeforeSeeking()

Returns the maximum latency drift before applying a seek operation to reduce the latency.

Source:
See:
Returns:
Type
number

getLowLatencyMinDrift()

Returns the current latency minimum allowed drift.

Source:
See:
Returns:
Type
number

getManifestUpdateRetryInterval()

For live streams, get the interval-frequency in milliseconds at which dash.js will check if the current manifest is still processed before downloading the next manifest once the minimumUpdatePeriod time has expired.

Source:
See:
Returns:

Current retry delay for manifest update

Type
int

getMaxAllowedBitrateFor(type)

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

Source:
See:

getMaxAllowedRepresentationRatioFor(type)

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

Source:
See:
Returns:

The current representation ratio cap.

Type
number

getMetricsFor(type)

Parameters:
Name Type Description
type string
Source:
Returns:
Type
Object

getMinAllowedBitrateFor(type)

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

Source:
See:

getMovingAverageMethod()

Return the current moving average method used for smoothing throughput estimates.

Source:
See:
Returns:

Returns "slidingWindow" or "ewma".

Type
string

getPlaybackRate()

Returns the current playback rate.

Source:
Returns:
Type
number

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 setAutoSwitchQualityFor(type, false) is called. For 'image' type, thumbnails, there is no ABR algorithm and quality is set manually.

Parameters:
Name Type Description
type string

'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

getScheduleWhilePaused()

Returns a boolean of the current state of ScheduleWhilePaused.

Source:
See:
Returns:
Type
boolean

getSelectionModeForInitialTrack()

This method returns the track selection mode.

Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function

Returns:

mode

Type
string

getSmallGapLimit()

Time in seconds for a gap to be considered small.

Source:
Returns:

Current small gap limit

Type
boolean

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

getStableBufferTime()

The time that the internal buffer target will be set to post startup/seeks (NOT top quality).

When the time is set higher than the default you will have to wait longer to see automatic bitrate switches but will have a larger buffer which will increase stability.

Default Value:
  • 12 seconds.
Source:

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

getTextDefaultEnabled()

Get enabled default state.

Source:
Returns:

default enable state

Type
boolean

getTextDefaultLanguage()

Get default language for text.

Source:
Returns:

the default language if it has been set using setTextDefaultLanguage

Type
string

getThumbnail(time, callback)

Return the thumbnail at time position.

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

Source:
Returns:
  • Thumbnail for the given time position. It returns null in case there are is not a thumbnails representation or if it doesn't contain a thumbnail for the given time position.
Type
Thumbnail | null

getTopBitrateInfoFor(type)

Gets the top quality BitrateInfo checking portal limit and max allowed.

It calls getTopQualityIndexFor internally

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

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 string
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 string
manifest Object
streamInfo Object
Source:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function

Returns:

list of MediaInfo

Type
Array

getTrackSwitchModeFor(type)

This method returns the current track switch mode.

Parameters:
Name Type Description
type string
Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function

Returns:

mode

Type
string

getTTMLRenderingDiv()

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

Source:
Returns:
Type
Object

getUseDeadTimeLatencyForAbr()

Get the value of useDeadTimeLatency in AbrController. @see setUseDeadTimeLatencyForAbr

Source:
Returns:
Type
boolean

getUsePixelRatioInLimitBitrateByPortal()

Source:

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

keepProtectionMediaKeys( [value])

Set the value for the ProtectionController and MediaKeys life cycle. If true, the ProtectionController and then created MediaKeys and MediaKeySessions will be preserved during the MediaPlayer lifetime.

Parameters:
Name Type Argument Description
value boolean <optional>

True or false flag.

Source:
Throws:

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


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)

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.

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


preload()

Causes the player to begin streaming the media as set by the attachSource() method in preparation for playing. It specifically does not require a view to be attached with attachView() to begin preloading. When a view is attached after preloading, the buffered data is transferred to the attached mediaSource buffers.

Source:
See:
Throws:

SOURCE_NOT_ATTACHED_ERROR if called before attachSource function


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.

Calling this method is all that is necessary to destroy a MediaPlayer instance.

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:

setAbandonLoadTimeout(value)

A timeout value in seconds, which during the ABRController will block switch-up events. This will only take effect after an abandoned fragment event occurs.

Parameters:
Name Type Description
value int
Default Value:
  • 10 seconds
Source:
Throws:

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


setABRStrategy(value)

Sets the ABR strategy. Valid strategies are "abrDynamic", "abrBola" and "abrThroughput". The ABR strategy can also be changed during a streaming session. The call has no effect if an invalid method is passed.

The BOLA strategy chooses bitrate based on current buffer level, with higher bitrates for higher buffer levels. The Throughput strategy chooses bitrate based on the recent throughput history. The Dynamic strategy switches smoothly between BOLA and Throughput in real time, playing to the strengths of both.

Parameters:
Name Type Description
value string
Default Value:
  • "abrDynamic"
Source:

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.


setAutoSwitchQualityFor(type, value)

Set to false to switch off adaptive bitrate switching.

Parameters:
Name Type Description
type string

'audio' | 'video'

value boolean
Default Value:
  • true
Source:

setBandwidthSafetyFactor(value)

A percentage between 0.0 and 1 to reduce the measured throughput calculations. The default is 0.9. The lower the value the more conservative and restricted the measured throughput calculations will be. please use carefully. This will directly affect the ABR logic in dash.js

Parameters:
Name Type Description
value number
Source:
Throws:

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


setBufferAheadToKeep(value)

This value influences the buffer pruning logic. Allows you to modify the buffer ahead of current time position that is kept in source buffer in seconds.

0|--------|currentTime|-----bufferAheadToKeep----|----bufferToPrune-----------|end|
Parameters:
Name Type Description
value int
Default Value:
  • 80 seconds
Source:
Throws:

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


setBufferPruningInterval(value)

This value influences the buffer pruning logic. Allows you to modify the interval of pruning buffer in seconds.

Parameters:
Name Type Description
value int
Default Value:
  • 10 seconds
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, not a number type.


setBufferTimeAtTopQuality(value)

The time that the internal buffer target will be set to once playing the top quality. If there are multiple bitrates in your adaptation, and the media is playing at the highest bitrate, then we try to build a larger buffer at the top quality to increase stability and to maintain media quality.

Parameters:
Name Type Description
value int
Default Value:
  • 30 seconds.
Source:
Throws:

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


setBufferTimeAtTopQualityLongForm(value)

The time that the internal buffer target will be set to once playing the top quality for long form content.

Parameters:
Name Type Description
value int
Default Value:
  • 60 seconds.
Source:
See:
Throws:

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


setBufferToKeep(value)

This value influences the buffer pruning logic. Allows you to modify the buffer that is kept in source buffer in seconds.

0|-----------bufferToPrune-----------|-----bufferToKeep-----|currentTime|
Parameters:
Name Type Description
value int
Default Value:
  • 20 seconds
Source:
Throws:

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


setCacheLoadThresholdForType(type, value)

For a given media type, the threshold which defines if the response to a fragment request is coming from browser cache or not. Valid media types are "video", "audio"

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

value number

Threshold value in milliseconds.

Default Value:
  • 50 milliseconds for video fragment requests; 5 milliseconds for audio fragment requests.
Source:
Throws:

BAD_ARGUMENT_ERROR if called with invalid arguments, type not a string type and its value is not audio or video, value not number type.


setCatchUpPlaybackRate(value)

Use this method to set the maximum catch up rate, as a percentage, for low latency live streams. In low latency mode, when measured latency is higher/lower than the target one (setLiveDelay()), dash.js increases/decreases playback rate respectively up to (+/-) the percentage defined with this method until target is reached.

Valid values for catch up rate are in range 0-0.5 (0-50%). Set it to 0 to turn off live catch up feature.

Note: Catch-up mechanism is only applied when playing low latency live streams.

Parameters:
Name Type Description
value number

Percentage in which playback rate is increased/decreased when live catch up mechanism is activated.

Default Value:
  • {number} 0.5
Source:
See:
Throws:

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


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


setFastSwitchEnabled(value)

When enabled, after an ABR up-switch in quality, instead of requesting and appending the next fragment at the end of the current buffer range it is requested and appended closer to the current time When enabled, The maximum time to render a higher quality is current time + (1.5 * fragment duration).

Note, When ABR down-switch is detected, we appended the lower quality at the end of the buffer range to preserve the higher quality media for as long as possible.

If enabled, it should be noted there are a few cases when the client will not replace inside buffer range but rather just append at the end. 1. When the buffer level is less than one fragment duration 2. The client is in an Abandonment State due to recent fragment abandonment event.

Known issues:

  1. In IE11 with auto switching off, if a user switches to a quality they can not download in time the fragment may be appended in the same range as the playhead or even in the past, in IE11 it may cause a stutter or stall in playback.
Parameters:
Name Type Description
value boolean
Default Value:
  • {boolean} false
Source:
Throws:

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


setFragmentLoaderRetryAttempts(value)

Total number of retry attempts that will occur on a fragment load before it fails. Increase this value to a maximum in order to achieve an automatic playback resume in case of completely lost internet connection.

Note: This parameter is not taken into account when Low Latency Mode is enabled. For Low Latency Playback dash.js takes control and sets a number of retry attempts that ensures playback stability.

Parameters:
Name Type Description
value int
Default Value:
  • 3
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value is not number type.


setFragmentLoaderRetryInterval(value)

Time in milliseconds of which to reload a failed fragment load attempt.

Parameters:
Name Type Description
value int
Default Value:
  • 1000 milliseconds
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value is not number type.


setInitialBitrateFor(type, value)

Use this method to explicitly set the starting bitrate for audio | video

Parameters:
Name Type Description
type string
value number

A value of the initial bitrate, kbps

Source:

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, viewpoint: viewpointValue, audioChannelConfiguration: audioChannelConfigurationValue, accessibility: accessibilityValue, role: roleValue}

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

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function


setInitialRepresentationRatioFor(type, value)

Parameters:
Name Type Description
type string
value number

A value of the initial Representation Ratio

Source:

setJumpGaps(value)

Sets whether player should jump small gaps (discontinuities) in the buffer.

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

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


setLimitBitrateByPortal(value)

Sets whether to limit the representation used based on the size of the playback area

Parameters:
Name Type Description
value boolean
Source:

setLiveDelay(value)

Equivalent in seconds of setLiveDelayFragmentCount

Lowering this value will lower latency but may decrease the player's ability to build a stable buffer.

This value should be less than the manifest duration by a couple of segment durations to avoid playback issues

If set, this parameter will take precedence over setLiveDelayFragmentCount and manifest info

Parameters:
Name Type Description
value number

Represents how many seconds to delay the live stream.

Default Value:
  • undefined
Source:
See:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value, if defined, is not number type.


setLiveDelayFragmentCount(value)

Changing this value will lower or increase live stream latency. The detected segment duration will be multiplied by this value to define a time in seconds to delay a live stream from the live edge.

Lowering this value will lower latency but may decrease the player's ability to build a stable buffer.

Parameters:
Name Type Description
value number

Represents how many segment durations to delay the live stream.

Default Value:
  • 4
Source:
See:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value is not number type.


setLongFormContentDurationThreshold(value)

The threshold which defines if the media is considered long form content. This will directly affect the buffer targets when playing back at the top quality.

Parameters:
Name Type Description
value number
Default Value:
  • 600 seconds (10 minutes).
Source:
See:
Throws:

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


setLowLatencyEnabled(value)

Enables low latency mode for dynamic streams. If not specified, liveDelay is set to 3s of buffer. Browser compatibility (Check row 'ReadableStream response body'): https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

Parameters:
Name Type Description
value boolean
Source:
Throws:

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


setLowLatencyMaxDriftBeforeSeeking(value)

Use this method to set the maximum latency deviation allowed before dash.js to do a seeking to live position. In low latency mode, when the difference between the measured latency and the target one (setLiveDelay()), as an absolute number, is higher than the one sets with this method, then dash.js does a seek to live edge position minus the target live delay.

LowLatencyMaxDriftBeforeSeeking should be provided in seconds. If 0, then seeking operations won't be used for fixing latency deviations.

Note: Catch-up mechanism is only applied when playing low latency live streams.

Parameters:
Name Type Description
value number

Maximum difference between measured latency and the target one before using seek to fix drastically live latency deviations.

Default Value:
  • {number} 0
Source:
See:
Throws:

PLAYBACK_LOW_LATENCY_MAX_DRIFT_BAD_ARGUMENT_ERROR if called with an invalid argument


setLowLatencyMinDrift(value)

Use this method to set the minimum latency deviation allowed before activating catch-up mechanism. In low latency mode, when the difference between the measured latency and the target one (setLiveDelay()), as an absolute number, is higher than the one sets with this method, then dash.js increases/decreases playback rate until target latency is reached.

LowLatencyMinDrift should be provided in seconds, and it uses values between 0.0 and 0.5.

Note: Catch-up mechanism is only applied when playing low latency live streams.

Parameters:
Name Type Description
value number

Maximum difference between measured latency and the target one before applying playback rate modifications.

Default Value:
  • {number} 0.05
Source:
See:
Throws:

PLAYBACK_LOW_LATENCY_MIN_DRIFT_BAD_ARGUMENT_ERROR if called with an invalid argument


setManifestLoaderRetryAttempts(value)

Total number of retry attempts that will occur on a manifest load before it fails.

Parameters:
Name Type Description
value int
Default Value:
  • 4
Source:

setManifestLoaderRetryInterval(value)

Time in milliseconds of which to reload a failed manifest load attempt.

Parameters:
Name Type Description
value int
Default Value:
  • 1000 milliseconds
Source:

setManifestUpdateRetryInterval(value)

For live streams, set the interval-frequency in milliseconds at which dash.js will check if the current manifest is still processed before downloading the next manifest once the minimumUpdatePeriod time has expired.

Parameters:
Name Type Description
value int
Default Value:
  • 100
Source:
See:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value is not number type.


setMaxAllowedBitrateFor(type, value)

When switching multi-bitrate content (auto or manual mode) this property specifies the maximum bitrate allowed. If you set this property to a value lower than that currently playing, the switching engine will switch down to satisfy this requirement. If you set it to a value that is lower than the lowest bitrate, it will still play that lowest bitrate.

You can set or remove this bitrate cap at anytime before or during playback. To clear this setting you must use the API and set the value param to NaN.

This feature is typically used to reserve higher bitrates for playback only when the player is in large or full-screen format.

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

value number

Value in kbps representing the maximum bitrate allowed.

Source:

setMaxAllowedRepresentationRatioFor(type, value)

When switching multi-bitrate content (auto or manual mode) this property specifies the maximum representation allowed, as a proportion of the size of the representation set.

You can set or remove this cap at anytime before or during playback. To clear this setting you must use the API and set the value param to NaN.

If both this and maxAllowedBitrate are defined, maxAllowedBitrate is evaluated first, then maxAllowedRepresentation, i.e. the lowest value from executing these rules is used.

This feature is typically used to reserve higher representations for playback only when connected over a fast connection.

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

value number

number between 0 and 1, where 1 is allow all representations, and 0 is allow only the lowest.

Source:

setMinAllowedBitrateFor(type, value)

When switching multi-bitrate content (auto or manual mode) this property specifies the minimum bitrate allowed. If you set this property to a value higher than that currently playing, the switching engine will switch up to satisfy this requirement. If you set it to a value that is lower than the lowest bitrate, it will still play that lowest bitrate.

You can set or remove this bitrate limit at anytime before or during playback. To clear this setting you must use the API and set the value param to NaN.

This feature is used to force higher quality playback.

Parameters:
Name Type Description
type string

'video' or 'audio' are the type options.

value number

Value in kbps representing the minimum bitrate allowed.

Source:

setMovingAverageMethod(value)

Sets the moving average method used for smoothing throughput estimates. Valid methods are "slidingWindow" and "ewma". The call has no effect if an invalid method is passed.

The sliding window moving average method computes the average throughput using the last four segments downloaded. If the stream is live (as opposed to VOD), then only the last three segments are used. If wide variations in throughput are detected, the number of segments can be dynamically increased to avoid oscillations.

The exponentially weighted moving average (EWMA) method computes the average using exponential smoothing. Two separate estimates are maintained, a fast one with a three-second half life and a slow one with an eight-second half life. The throughput estimate at any time is the minimum of the fast and slow estimates. This allows a fast reaction to a bandwidth drop and prevents oscillations on bandwidth spikes.

Parameters:
Name Type Description
value string
Default Value:
  • {string} 'slidingWindow'
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value is not slidingWindow or ewma.


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 ProtectionData

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

Source:
See:

setQualityFor(type, value)

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 setAutoSwitchQualityFor(type, false) is called.

Parameters:
Name Type Description
type string

'video', 'audio' or 'image'

value number

the quality index, 0 corresponding to the lowest bitrate

Source:
See:
Throws:

STREAMING_NOT_INITIALIZED_ERROR if called before initializePlayback function


setScheduleWhilePaused(value)

Set to true if you would like dash.js to keep downloading fragments in the background when the video element is paused.

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

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


setSegmentOverlapToleranceTime(value)

The overlap tolerance time, at both the head and the tail of segments, considered when doing time to segment conversions.

This is used when calculating which of the loaded segments of a representation corresponds with a given time position. Its value is never used for calculating the segment index in seeking operations in which it assumes overlap time threshold is zero.

|-o-|--- segment X ----|-o-|
                       |-o-|---- segment X+1 -----|-o-|
                                                  |-o-|---- segment X+2 -----|-o-|
Parameters:
Name Type Description
value number
Default Value:
  • 0.05 seconds.
Source:
Throws:

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


setSelectionModeForInitialTrack(mode)

This method sets the selection mode for the initial track. This mode defines how the initial track will be selected if no initial media settings are set. If initial media settings are set this parameter will be ignored. Available options are:

MediaController.TRACK_SELECTION_MODE_HIGHEST_BITRATE this mode makes the player select the track with a highest bitrate. This mode is a default mode.

MediaController.TRACK_SELECTION_MODE_WIDEST_RANGE this mode makes the player select the track with a widest range of bitrates

Parameters:
Name Type Description
mode string
Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function


setSmallGapLimit(value)

Time in seconds for a gap to be considered small.

Parameters:
Name Type Description
value number
Default Value:
  • 0.8
Source:
Throws:

BAD_ARGUMENT_ERROR if called with an invalid argument, value is not number type.


setStableBufferTime(value)

The time that the internal buffer target will be set to post startup/seeks (NOT top quality).

When the time is set higher than the default you will have to wait longer to see automatic bitrate switches but will have a larger buffer which will increase stability.

Note: The value set for Stable Buffer Time is not considered when Low Latency Mode is enabled. When in Low Latency mode dash.js takes ownership of Stable Buffer Time value to minimize latency that comes from buffer filling process.

Parameters:
Name Type Description
value int
Default Value:
  • 12 seconds.
Source:
Throws:

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


setTextDefaultEnabled(enable)

Set enabled default state. This is used to enable/disable text when a file is loaded. During playback, use enableText to enable text for the file

Parameters:
Name Type Description
enable boolean

true to enable text, false otherwise

Source:

setTextDefaultLanguage(lang)

Set default language for text. If default language is not one of text tracks, dash will choose the first one.

Parameters:
Name Type Description
lang string

default language

Source:

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


setTrackSwitchModeFor(type, mode)

This method sets the current track switch mode. Available options are:

MediaController.TRACK_SWITCH_MODE_NEVER_REPLACE (used to forbid clearing the buffered data (prior to current playback position) after track switch. Defers to fastSwitchEnabled for placement of new data. Default for video)

MediaController.TRACK_SWITCH_MODE_ALWAYS_REPLACE (used to clear the buffered data (prior to current playback position) after track switch. Default for audio)

Parameters:
Name Type Description
type string
mode string
Source:
Throws:

MEDIA_PLAYER_NOT_INITIALIZED_ERROR if called before initialize function


setUseDeadTimeLatencyForAbr( [useDeadTimeLatency])

Set the value of useDeadTimeLatency in AbrController. If true, only the download portion will be considered part of the download bitrate and latency will be regarded as static. If false, the reciprocal of the whole transfer time will be used. Defaults to true.

Parameters:
Name Type Argument Description
useDeadTimeLatency boolean <optional>

True or false flag.

Source:

setUsePixelRatioInLimitBitrateByPortal(value)

Sets whether to take into account the device's pixel ratio when defining the portal dimensions. Useful on, for example, retina displays.

Parameters:
Name Type Description
value boolean
Default Value:
  • {boolean} false
Source:

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

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:

useDefaultABRRules(value)

Enable/disable builtin dashjs ABR rules

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

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


useSuggestedPresentationDelay(value)

Set to true if you would like to override the default live delay and honor the SuggestedPresentationDelay attribute in by the manifest.

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

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