DashJS中MediaPlayerAPI

DashMediaPlayerAPI

MediaPlayer

Members

<inner, constant> ELEMENT_NOT_ATTACHED_ERROR :string

在 dash.js 收到 HTML5 视频元素的引用之前调用函数时抛出的错误字符串

<inner, constant>MEDIA_PLAYER_NOT_INITIALIZED_ERROR :string

在 dash.js完全初始化之前调用函数时抛出的错误字符串。

<inner, constant> PLAYBACK_NOT_INITIALIZED_ERROR :string

在 dash.js 完全初始化之前调用函数时抛出的错误字符串

<inner, constant>SOURCE_NOT_ATTACHED_ERROR :string

在 dash.js 收到有效源流之前调用函数时抛出的错误字符串。

<inner, constant>STREAMING_NOT_INITIALIZED_ERROR :string

在 dash.js 完全初始化之前调用函数时抛出的错误字符串

Methods

addABRCustomRule(type, rulename, rule)

如果正在播放流，则添加自定义 ABR 规则规则将应用于下一个流

参数：

Name	类型	描述
type	string	规则类型（['qualitySwitchRules','abandonFragmentRules'] 之一）
rulename	string	规则名称（用于标识自定义规则）。如果添加了一条同名规则，则将更新现有规则
rule	object	规则对象实例

抛出： BAD_ARGUMENT_ERROR 如果使用无效参数调用。

addUTCTimingSource(schemeIdUri, value)

允许您为动态流的 UTC 实时边缘检测设置方案和服务器源。如果在清单中定义了 UTCTiming，它将优先于手动添加的任何时间源。

如果您已公开 Date 标头，请使用方法clearDefaultUTCTimingSources()。这将允许使用清单上的日期标头而不是时间服务器

参数：

Name	类型	默认值	描述
schemeIdUri	string	urn:mpeg💨utc:http-xsdate:2014	1. urn:mpeg💨utc:http-head:20142. urn:mpeg💨utc:http-xsdate:20143. urn:mpeg💨utc:http-iso:20144. urn:mpeg💨utc:direct:2014

一些引用早期 ISO23009-1 草案的规范在 URI 中错误地使用了 2012，而不是 2014。现在支持这些。

1. urn:mpeg💨utc:http-head:2012
2. urn:mpeg💨utc:http-xsdate:2012
3. urn:mpeg💨utc:http-iso:2012
4. urn:mpeg💨utc:direct:2012
   |
   |value |string |http😕/time.akamai.com/?iso&ms/li当前时间字符串 |
   时间源的路径。 |

attachProtectionController(value)

将覆盖 dash.js 保护控制器。

Name	类型	描述
value	ProtectionController	有效的保护控制器实例。

attachSource(urlOrManifest)

使用此方法将源 URL 设置为有效的 MPD 清单文件或先前下载并解析的清单对象。可选，还可以提供保护信息

Name	类型	描述
urlOrManifest	string	Object

抛出：

MEDIA_PLAYER_NOT_INITIALIZED_ERROR 如果在初始化函数之前调用

attachTTMLRenderingDiv(div)

使用此方法为 dash.js 附加一个 HTML5 div 以呈现丰富的 TTML 字幕。

Name	类型	描述
div	HTMLDivElemen	放置在视频元素之后的无样式 div。它将被设置为匹配视频大小和覆盖 z 顺序。

抛出：

ELEMENT_NOT_ATTACHED_ERROR 如果在 attachView 函数之前调用

attachView(element)

使用此方法附加一个 HTML5 VideoElement 以供 dash.js 操作。

Name	类型	描述
element	Object	已在 DOM（或等效存根）中定义HTMLMediaElement。

抛出：MEDIA_PLAYER_NOT_INITIALIZED_ERROR 如果在初始化函数之前调用

clearDefaultUTCTimingSources()

允许您清除存储的时间源数组。

使用示例：如果您已公开 Date 标头，则调用此方法将允许使用清单上的日期标头而不是时间服务器。

使用示例：调用此方法，假设清单上没有公开的日期标头，将默认返回使用二进制搜索来发现实时边缘

convertToTimeCode(value)

将秒转换为时间码（即 300 --&gt; 05:00）的实用方法。

destroy()

完全破坏媒体播放器并释放所有内存。

duration()

媒体播放的持续时间，以秒为单位。

抛出： PLAYBACK_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

返回：媒体的当前持续时间。对于动态流，这将返回 DVRWindow.end - DVRWindow.start

类型：数字

durationAsUTC()

使用此方法以绝对值形式获取当前持续时间，即自 UTC 1970

年1 月 1 日午夜以来的时间（以秒为单位）。注意 - 此属性仅对实时流有意义。

抛出：PLAYBACK_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

返回：当前持续时间作为 UTC 时间戳。

类型：数字

enableForcedTextStreaming(enable)

启用/禁用文本

启用破折号时，即使所有轨道都处于"隐藏"模式，也会继续下载和处理碎片化的文本轨道

Name	类型	描述
enable	Boolean	即使隐藏所有文本轨道，启用文本流也为 true。

enableText(enable)

启用/禁用文本

启用文本时，dash 将选择上一个选定的文本轨道

Name	类型	描述
enable	Boolean	true 启用文本，否则 false（与 setTextTrack(-1) 相同）

extend(parentNameString, childInstance, override)

此方法应用于扩展或替换内部 dash.js 对象。

有两种扩展 dash.js 的方法（由 override 参数决定）：

1. 如果您将 override 设置为 true ，则自定义对象中的任何公共方法或属性都将覆盖 dash.js 父对象的属性并将被使用，但仍会创建 dash.js 父模块。

2. 如果您将覆盖设置为 false，您的对象将完全替换 dash.js 对象。（注意：这就是第戎 Dash.js 1.x 中的情况）。 当您扩展时，您可以访问 this.context** 、 **this.factory 和 this.parent 以在您的自定义对象中操作。

3. this.context - 可用于为单例访问传递上下文。

4. this.factory - 可用于调用 factory.getSingletonInstance()。

5. this.parent - 是调用其他公共方法的父对象的引用。（如果您将覆盖设置为 false 或选项 2 进行扩展，则排除 this.parent） 您必须在调用 initialize 之前调用 extend

Name	类型	描述
parentNameString	string	父模块的名称
childInstance	Object	覆盖对象
override	Boolean	仅替换某些方法 (true) 或整个对象 (false)

formatUTC(time, locales, hour12, withDate)

将 UTC 时间戳值转换为有效时间和日期字符串的实用方法。

Name	类型	默认值	描述
time	number		要转换为日期和时间的 UTC 时间戳。
locales	string		区域标识符（即 en_US）。
hour12	Boolean		12 对 24 小时。对于 12 小时时间格式设置为 true。
withDate	Boolean	false	默认为假。设置为 true 以将当前日期附加到 UTC 时间格式。

getActiveStream()

此方法返回活动流

抛出：STREAMING_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

getAutoPlay()

当前自动播放状态。

getAverageThroughput(type)

返回在 ABR 逻辑中计算的平均吞吐量

getBitrateInfoListFor(type)

获取比特率信息列表

getBufferLength(type)

获取缓冲区长度

给定媒体类型的缓冲区长度，以秒为单位。有效的媒体 类型是"视频"、"音频"和"文本"。如果没有传入类型 ，则 返回视频、音频和文本缓冲区长度的最小值。如果请求的类型无效， 演示文稿不包含该类型，或者未传递任何参数 且演示文稿不包含任何有效媒体 类型的适配集，则返回 NaN

返回：给定媒体类型的缓冲区长度，以 秒为单位，或 NaN

getCurrentLiveLatency()

抛出： MEDIA_PLAYER_NOT_INITIALIZED_ERROR 如果在初始化函数之前调用

返回： 当前的实时流延迟（以秒为单位）。它是现在时间和播放头的时间位置之间的差异。

类型 ：数量 | NaN

getCurrentTrackFor(type)

抛出： STREAMING_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

返回： MediaInfo

类型 ：对象 | 空值

getDashAdapter()

返回 DashAdapter.js 模块。

getDashMetrics()

返回 DashMetrics.js 模块。您可以使用此模块访问存储在 dash.js 中的所有公共指标

getDebug()

使用此方法访问 dash.js 日志记录类。

getDVRSeekOffset(value)

此方法应仅用于具有有效 timeShiftBufferLength（DVR 窗口）的实时流。

注意-如果不需要原始偏移值（即媒体分析，跟踪等）可以考虑使用该seek()方法将计算此值，为您和设置视频元素的currentTime属性都在一个简单的调用。

返回：一个与 timeShiftBufferLength（DVR 窗口）内的可用范围相关的值。

类型：数字

Name	类型	描述
value	number	基于duration()方法的返回值的相对时间（以秒为单位）是预期的。

getDVRWindowSize()

timeShiftBufferLength（DVR 窗口），以秒为单位。

返回： 清单中定义的直播流的直播点后面的允许播放时间窗口。

类型 ：数字

getInitialMediaSettingsFor(type)

此方法返回用于选取初始轨道的媒体设置。

设置格式如下：

{

lang: langValue,

index: indexValue,

opinion: opinionValue,

audioChannelConfiguration: audioChannelConfigurationValue,

accessibility: accessibilityValue,

role: roleValue

}

抛出： MEDIA_PLAYER_NOT_INITIALIZED_ERROR 如果在初始化函数之前调用

类型 ：目的

参数：

Name	类型	描述
type	MediaType"video"	"audio"

getOfflineController()

检测是否包含 Offline 并返回 OfflineController.js 的实例

getPlaybackRate()

返回当前播放速率。

getProtectionController()

检测是否包含 Protection 并返回 ProtectionController.js 的实例

getQualityFor(type)

获取媒体类型视频、音频或图像的当前下载质量。对于视频和音频类型，

除非 autoSwitchBitrate 设置为 false，否则ABR规则会在每次新下载之前更新此值。对于"图像"

类型的缩略图，没有 ABR 算法并且质量是手动设置的。

Name	类型	描述
type	MediaType"video"	"audio"

抛出： STREAMING_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

返回： 质量指数，0对应最低码率

类型 :数字

getSettings()

获取在播放器上使用的当前设置对象。

返回： 正在使用的设置对象。

类型 :PlayerSettings

getSource()

返回通过调用 attachSource() 附加的源字符串或清单

抛出： SOURCE_NOT_ATTACHED_ERROR 如果在 attachSource 函数之前调用

类型 :字符串 | manifest

getStreamsFromManifest(manifest)

此方法返回给定清单中所有可用流的列表

Name	类型	描述
type	objecr

抛出： STREAMING_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

返回： 清单 StreamInfo

类型 :Array

getTopBitrateInfoFor(type)

获取最高质量的 BitrateInfo 检查门户限制和允许的最大值。

它在内部调用 getMaxAllowedIndexFor

Name	类型	描述
type	MediaType"video"	"audio"

抛出： STREAMING_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

类型 :比特率信息(BitrateInfo) | 空值(null)

getTracksFor(type)

此方法返回给定媒体类型的所有可用曲目的列表

Name	类型	描述
type	MediaType	"视频"、"音频"或"图像"（缩略图）

抛出： STREAMING_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用
返回： 清单 MediaInfo
类型 :Array

getTracksForTypeFromManifest(type, manifest, streamInfo)

此方法从给定清单返回给定媒体类型和流信息的所有可用轨道的列表

getTTMLRenderingDiv()

返回通过调用 attachTTMLRenderingDiv() 附加的 Div 实例

getVersion()

当前版本的 Dash.js

getVideoElement()

返回通过调用 attachView() 附加的 Video Element 的实例

getVolume()

返回当前音量，从 0.0（静音）到 1.0（最响）。

getXHRWithCredentialsForType(type)

获取特定请求 类型的XHR 请求上的 withCredentials是 true 还是 false

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

创建 MediaPlayer 后，您必须先调用 initialize，然后再调用其他任何内容。

这一规则有一个例外。 在调用 initialize 之前调用所有扩展是至关重要的。extend()

所有参数都是可选的，稍后有单独的方法来设置每个参数。

此方法中的参数只是为了方便起见，应该仅用于简单的播放器设置。

Name	类型	争论	描述
view	HTML5MediaElement	<可选>	用于设置视频元素的可选参数。 attachView()
source	string	<可选>	用于设置媒体源的可选参数。 attachSource()
AutoPlay	boolean	<可选>	用于设置自动播放的可选参数。 setAutoPlay()

isDynamic()

返回一个布尔值，指示媒体是否处于动态过程中。

isMuted()

一个布尔值，用于确定音频是否静音。

isPaused()

返回一个布尔值，指示视频元素是否已暂停。

isReady()

基于定义的视频元素和 MPD 源的 MediaPlayer 的就绪状态。

isSeeking()

返回一个布尔值，指示媒体是否正在寻找新位置。

isTextEnabled()

如果启用文本，则返回 true，否则返回 false

off(type, listener, scope)

使用 off 方法删除在 MediaPlayer.events 中找到的公共事件的侦听器。 MediaPlayerEvents

Name	类型	描述
type	string	MediaPlayerEvents
listener	function	事件触发时的回调方法。
scope	Object	侦听器的上下文，以便可以正确删除它。

on(type, listener, scope, options)

使用 on 方法侦听在 MediaPlayer.events 中找到的公共事件。

Name	类型	描述
type	string	MediaPlayerEvents
listener	function	事件触发时的回调方法。
scope	Object	侦听器的上下文，以便可以正确删除它。
options	Object	对象来定义各种选项，例如优先级和模式

pause()

此方法将在本机视频元素上调用暂停。

play()

play 方法启动由该attachSource()方法定义的媒体的播放。

此方法将调用原生视频元素上的播放。

provideThumbnail(time, callback)

在时间位置提供缩略图。这可以是异步的，因此您必须提供回调来检索缩略图信息

Name	类型	描述
time	number	基于duration()方法返回值的相对时间，以秒为单位
callback	function	检索给定时间位置的缩略图时提供的回调函数。如果没有缩略图表示或者它不包含给定时间位置的缩略图，缩略图对象为空。

registerCustomCapabilitiesFilter(filter)

注册自定义功能过滤器。这使应用程序能够过滤要使用的表示。 提供的回调函数应根据是否使用该表示返回一个布尔值。

过滤器按它们注册的顺序应用。

Name	类型	描述
filter	function	自定义功能过滤器回调

registerLicenseRequestFilter(filter)

注册许可请求过滤器。这使应用程序能够操纵/覆盖任何请求参数和/或请求数据。

提供的回调函数应返回一个承诺，一旦过滤过程完成，该承诺将被解决。过滤器按它们注册的顺序应用。

Name	类型	描述
filter	function	许可请求过滤器回调

registerLicenseResponseFilter(filter)

注册许可证响应过滤器。这使应用程序能够操作/覆盖响应数据。提供的回调函数应返回一个承诺，

一旦过滤过程完成，该承诺将被解析。过滤器按它们注册的顺序应用。

Name	类型	描述
filter	function	许可证响应过滤器回调

removeABRCustomRule(rulename)

删除自定义 ABR 规则

Name	类型	描述
rulename	string	要删除的规则的名称

removeAllABRCustomRule()

删除所有自定义规则

removeUTCTimingSource(schemeIdUri, value)

允许您删除 UTC 时间源。schemeIdUri 和 value 都需要匹配 Dash.vo.UTCTiming 属性，以便从数组中删除条目

抛出： BAD_ARGUMENT_ERROR 如果使用无效参数调用，则 schemeIdUri 和 value 不是字符串类型。

Name	类型	描述
schemeIdUri	string	看 addUTCTimingSource()
value	string	看 addUTCTimingSource()

reset()

将 MPD 源和视频元素设置为 null。您还可以通过 使用新的源文件调用 attachSource来重置 MediaPlayer 。

此调用不会破坏 MediaPlayer。要销毁 MediaPlayer 并释放其所有 内存，请调用 destroy()。

resetSettings()

将设置对象重置为默认值。

restoreDefaultUTCTimingSources()

允许您在调用后恢复默认时间源 clearDefaultUTCTimingSources()

默认值：

schemeIdUri: urn:mpeg💨utc:http-xsdate:2014

值：http://time.akamai.com/?iso&ms当前时间的时间字符串

retrieveManifest(url, callback)

允许应用程序检索清单。清单加载是异步的 ， 需要应用提供的回调函数

Name	类型	描述
url	string	url 清单 url
callback	function	检索清单时提供的回调函数

seek(value)

设置附加视频元素的 currentTime 属性。如果是带有timeShiftBufferLength的直播流，那么DVR窗口偏移量会自动计算。

抛出：

PLAYBACK_NOT_INITIALIZED_ERROR 如果在 initializePlayback 函数之前调用

BAD_ARGUMENT_ERROR 如果使用无效参数调用，不是数字类型或者是 NaN。

Name	类型	描述
value	number	基于duration()方法返回值的相对时间，以秒为单位

setAutoPlay(value)

设置为 false 以防止流在附加视图时自动播放。

抛出：

BAD_ARGUMENT_ERROR 如果使用无效参数调用，而不是布尔类型。

Name	类型	描述
value	布尔值	默认值true

setConfig( [config])

使用控制器配置媒体播放器。

setCurrentTrack(track)

setInitialMediaSettingsFor(type, value)

setMute(value)

使用此方法设置本机 Video Element 的静音状态。采用一个布尔值来确定音频是否静音。如果音频静音，则为 true，否则为 false。

setPlaybackRate(value)

使用此方法设置本机视频元素的播放速率。

setProtectionData(value)

设置设置保护模块 (DRM) 所需的保护数据。

必须在初始化 MediaPlayer 之前设置保护数据，或者在初始化之后，在触发 PROTECTION_CREATED 事件之前设置保护数据。

setQualityFor(type, value, forceReplace)

设置媒体类型的当前质量，而不是让 ABR Heuristics 自动选择它。

除非将 autoSwitchBitrate 设置为 false，否则此值将被 ABR 规则覆盖。

setTextTrack(idx)

使用此方法可以更改外部时间文本文件和碎片文本轨道的当前文本轨道。

使用此方法时无需在视频对象上设置轨道模式即可切换轨道。

setVolume(value)

表示音频音量的双精度值，从 0.0（静音）到 1.0（最响）。

setXHRWithCredentialsForType(type, value)

设置特定请求

类型的XHR 请求上的 withCredentials是 true 还是 false

time(streamId)

播放头的当前时间，以秒为单位。

如果不带参数调用，则返回的时间值是自第一个流的开始点以来经过的时间，或者如果它是实时流，则时间将基于duration()方法的返回值。

但是，如果提供了流 ID，则时间相对于该流的开始，如果清单中没有这样的流 ID，则时间为 null。

timeAsUTC()

使用此方法以绝对值形式获取当前播放头时间，即自 UTC 1970

年1 月 1 日午夜以来的时间（以秒为单位）。注意 - 此属性仅对实时流有意义。如果在 play() 开始之前调用，它将返回一个 NaN 值。

unregisterCustomCapabilitiesFilter(filter)

取消注册自定义功能过滤器。

unregisterLicenseRequestFilter(filter)

取消注册许可请求过滤器。

unregisterLicenseResponseFilter(filter)

取消注册许可证响应过滤器。

updatePortalSize()

更新视频元素大小变量

应在窗口调整大小（或任何其他时间调整播放器大小）时调用。全屏确实会触发窗口大小调整事件。

一旦 windowResizeEventCalled = true，abrController.checkPortalSize() 将使用元素大小变量而不是每次都查询 clientWidth。

updateSettings(settingsObj)

更新在播放器上使用的当前设置对象。任何未指定的内容都不会被修改。

此函数不会更新整个对象，只会更新传入对象中的属性。

这意味着 updateSettings({a: x}) 和 updateSettings({b: y}) 在功能上等同于

updateSettings({a: x, b: y})。如果再次需要默认值，@see resetSettings。