mpegts.js中文文档

本文件使用类似于 TypeScript 的定义来描述接口。

接口

mpegts.js 通过全局上下文中的 window 暴露的 mpegts 对象导出所有接口。
mpegts 对象也可以通过 require 或 ES6 的 import 来访问。

函数：

• mpegts.createPlayer()
• mpegts.isSupported()
• mpegts.getFeatureList()

类：

• mpegts.MSEPlayer
• mpegts.NativePlayer
• mpegts.LoggingControl

枚举：

• mpegts.Events
• mpegts.ErrorTypes
• mpegts.ErrorDetails

mpegts.createPlayer()

function createPlayer(mediaDataSource: MediaDataSource, config?: Config): Player;

根据 mediaDataSource 中指示的类型创建一个播放器实例，可选配置项为 config。

MediaDataSource

字段	类型	描述
type	string	指示媒体类型，如 'mse'、'mpegts'、'm2ts'、'flv' 或 'mp4'
isLive	boolean	是否为直播流
cors	boolean	是否为 HTTP 请求启用 CORS
withCredentials	boolean	是否在 HTTP 请求时携带 Cookie
hasAudio	boolean	是否包含音频轨道
hasVideo	boolean	是否包含视频轨道
duration	number	媒体总时长，以毫秒为单位
filesize	number	媒体文件的总大小，以字节为单位
url	string	媒体 URL，可以是 'https(s)' 或 'ws(s)' (WebSocket) 开头
segments	Array	可选字段，用于多部分回放，参见 MediaSegment

如果存在 segments 字段，转码器会将此 MediaDataSource 视作多部分源处理。
在这种模式下，MediaDataSource 结构中的 duration、filesize 和 url 字段会被忽略。

MediaSegment

字段	类型	描述
duration	number	必需字段，表示片段时长，以毫秒为单位
filesize	number	可选字段，表示片段文件大小，以字节为单位
url	string	必需字段，表示片段文件的 URL

Config

以下是配置选项的中文翻译，并以表格形式呈现：

字段	类型	默认值	描述
enableWorker?	boolean	false	启用分离线程（DedicatedWorker）进行转码
enableWorkerForMSE?	boolean	false	启用分离线程（DedicatedWorker）用于 MediaSource
enableStashBuffer?	boolean	true	启用 IO 缓存。如果需要实时（最小延迟）直播播放，则设置为 false，但网络抖动时可能会停滞。
stashInitialSize?	number	384KB	指示 IO 缓存初始大小，默认为 384KB。指定合适大小可以改善视频加载/搜索时间。
isLive?	boolean	false	与 MediaDataSource 中的 isLive 相同，若已在 MediaDataSource 结构中设置，则忽略此参数。
liveBufferLatencyChasing?	boolean	false	追赶由 HTMLMediaElement 内部缓冲区引起的直播流延迟。应同时将 isLive 设置为 true。
liveBufferLatencyChasingOnPaused?	boolean	false	即使 HTMLMediaElement 处于暂停状态，也追赶由内部缓冲区引起的直播流延迟。仅在 isLive: true 和 liveBufferLatencyChasing: true 时有效。
liveBufferLatencyMaxLatency?	number	1.5 秒	HTMLMediaElement 中可接受的最大缓冲延迟，单位秒。仅在 isLive: true 和 liveBufferLatencyChasing: true 时有效。
liveBufferLatencyMinRemain?	number	0.5 秒	HTMLMediaElement 中需保持的最小缓冲延迟，单位秒。仅在 isLive: true 和 liveBufferLatencyChasing: true 时有效。
liveSync?	boolean	false	通过改变播放速度来追赶由 HTMLMediaElement 内部缓冲区引起的直播流延迟。应同时将 isLive 设置为 true。
liveSyncMaxLatency?	number	1.2 秒	HTMLMediaElement 中可接受的最大缓冲延迟，单位秒。仅在 isLive: true 和 liveSync: true 时有效。
liveSyncTargetLatency?	number	0.8 秒	当延迟超过 liveSyncMaxLatency 时，HTMLMediaElement 中要追赶的目标延迟，单位秒。仅在 isLive: true 和 liveSync: true 时有效。
liveSyncPlaybackRate?	number	1.2	用于追赶延迟的播放速度，限制在 [1, 2] 之间。仅在 isLive: true 和 liveSync: true 时有效。
lazyLoad?	boolean	true	如果已有足够的数据供播放，则终止 HTTP 连接。
lazyLoadMaxDuration?	number	3 分钟	指示懒加载模式下应保留多少秒的数据。
lazyLoadRecoverDuration?	number	30 秒	指示懒加载恢复的时间边界，单位秒。
deferLoadAfterSourceOpen?	boolean	true	在 MediaSource 的 sourceopen 事件触发后开始加载。在 Chrome 中，后台打开的标签页可能直到切换到该标签页之前都不会触发 sourceopen 事件。
autoCleanupSourceBuffer	boolean	false	自动清理 SourceBuffer
autoCleanupMaxBackwardDuration	number	3 分钟	当向后的缓冲持续时间超过这个值（秒），自动清理 SourceBuffer。
autoCleanupMinBackwardDuration	number	2 分钟	自动清理时保留的向后缓冲持续时间，单位秒。
fixAudioTimestampGap	boolean	true	检测到大的音频时间戳间隔时，插入静音音频帧以避免音视频不同步。
accurateSeek?	boolean	false	精确查找任意帧，不限于视频 IDR 帧，但可能会稍慢。适用于 Chrome > 50, FireFox 和 Safari。
seekType?	string	'range'	使用范围请求进行查找，或使用 'param' 将参数添加到 URL 中以指示请求范围。
seekParamStart?	string	'bstart'	当 seekType = 'param' 时，表示查找起始参数名称。
seekParamEnd?	string	'bend'	当 seekType = 'param' 时，表示查找结束参数名称。
rangeLoadZeroStart?	boolean	false	如果使用范围查找，则首次加载发送 Range: bytes=0-。
customSeekHandler?	object	undefined	指定自定义查找处理器。
reuseRedirectedURL?	boolean	false	对于后续请求（如查找、重新连接等），重用 301/302 重定向的 URL。
referrerPolicy?	string	no-referrer-when-downgrade	使用 FetchStreamLoader 时的 Referrer Policy。
headers?	object	undefined	表示将添加到请求中的额外头信息。

请注意，带有问号的字段是可选的配置项。

mpegts.isSupported()

function isSupported(): boolean;

返回 true 如果浏览器支持基本的播放功能。

mpegts.getFeatureList()

function getFeatureList(): FeatureList;

返回一个包含以下细节的 FeatureList 对象：

字段	类型	描述
msePlayback	boolean	与 mpegts.isSupported()相同，指示浏览器是否支持基本的播放功能。
mseLivePlayback	boolean	指示 HTTP MPEG2-TS/FLV 直播流是否可以在您的浏览器上工作。
mseH265Playback	boolean	指示 H265 编码的 MPEG2-TS/FLV 流是否可以在您的浏览器上播放。
networkStreamIO	boolean	指示网络加载器是否正在流式传输。
networkLoaderName	string	指示网络加载器类型名称。
nativeMP4H264Playback	boolean	指示您的浏览器是否原生支持 H.264 编码的 MP4 视频文件。
nativeMP4H265Playback	boolean	指示您的浏览器是否原生支持 H.265 编码的 MP4 视频文件。
nativeWebmVP8Playback	boolean	指示您的浏览器是否原生支持 WebM VP8 视频文件。
nativeWebmVP9Playback	boolean	指示您的浏览器是否原生支持 WebM VP9 视频文件。

mpegts.MSEPlayer

实现了 Player 接口的 MSE 播放器，可以直接通过 new 操作符创建。

interface MSEPlayer extends Player {}

mpegts.NativePlayer

实现了 Player 接口的浏览器原生播放器（HTMLVideoElement）包装器，不使用 MediaSource src 属性。适用于单一部分 MP4 文件播放。

interface NativePlayer extends Player {}

Player (抽象接口)

interface Player {
  constructor(mediaDataSource: MediaDataSource, config?: Config): Player; 
  destroy(): void; 
  on(event: string, listener: Function): void;
  off(event: string, listener: Function): void;
  attachMediaElement(mediaElement: HTMLMediaElement): void;
  detachMediaElement(): void;
  load(): void;
  unload(): void;
  play(): Promise<void>;
  pause(): void;
  type: string;
  buffered: TimeRanges;
  duration: number;
  volume: number;
  muted: boolean;
  currentTime: number;
  mediaInfo: Object;
  statisticsInfo: Object;
}

    constructor(mediaDataSource: MediaDataSource, config?: Config): Player：这是播放器的构造函数，用于创建播放器实例，需要传入媒体数据源 MediaDataSource 和可选的配置 Config。
    destroy(): void：用于销毁播放器的方法。
    on(event: string, listener: Function): void：用于注册指定事件的监听函数。
    off(event: string, listener: Function): void：用于取消指定事件的监听函数。
    attachMediaElement(mediaElement: HTMLMediaElement): void：将播放器与指定的 HTML 媒体元素进行关联。
    detachMediaElement(): void：解除播放器与媒体元素的关联。
    load(): void：加载媒体资源。
    unload(): void：卸载媒体资源。
    play(): Promise<void>：开始播放，并返回一个 Promise 表示播放操作的结果。
    pause(): void：暂停播放。
    type: string：表示播放器的类型。
    buffered: TimeRanges：表示已缓冲的时间范围。
    duration: number：媒体的总时长。
    volume: number：音量大小。
    muted: boolean：是否静音。
    currentTime: number：当前播放时间。
    mediaInfo: Object：媒体的相关信息。
    statisticsInfo: Object：播放的统计信息。

mpegts.LoggingControl

一个全局接口，包含几个静态的 getter/setter 方法来设置 mpegts.js 日志的详细程度。

interface LoggingControl {
  forceGlobalTag: boolean;
  globalTag: string;
  enableAll: boolean;
  enableDebug: boolean;
  enableVerbose: boolean;
  enableInfo: boolean;
  enableWarn: boolean;
  enableError: boolean;
  getConfig(): Object;
  applyConfig(config: Object): void;
  addLogListener(listener: Function): void;
  removeLogListener(listener: Function): void;
}

mpegts.Events

一系列常量，可用于 Player.on() / Player.off()。它们需要带有 mpegts.Events 前缀。

事件	描述
ERROR	在播放期间由于任何原因发生错误时触发。
LOADING_COMPLETE	输入的 MediaDataSource已被完全缓冲至结束时触发。
RECOVERED_EARLY_EOF	在缓冲过程中发生了意外的网络 EOF（文件结束），但自动恢复时触发。
MEDIA_INFO	提供媒体的技术信息，例如视频/音频编解码器、比特率等。
METADATA_ARRIVED	提供 FLV 文件（流）中可能包含的元数据，带有 "onMetaData" 标记。
SCRIPTDATA_ARRIVED	提供 FLV 文件（流）中可能包含的脚本数据（OnCuePoint / OnTextData）。
TIMED_ID3_METADATA_ARRIVED	提供含有私有数据的定时 ID3 元数据包（stream_type=0x15）回调。
SYNCHRONOUS_KLV_METADATA_ARRIVED	提供同步 KLV 元数据包，包含私有数据（stream_type=0x15）回调。
ASYNCHRONOUS_KLV_METADATA_ARRIVED	提供异步 KLV 元数据包，包含私有数据（stream_type=0x06）回调。
SMPTE2038_METADATA_ARRIVED	提供含有私有数据的 SMPTE2038 元数据包回调。
SCTE35_METADATA_ARRIVED	提供含有部分（stream_type=0x86）的 SCTE35 元数据包回调。
PES_PRIVATE_DATA_ARRIVED	提供含有私有数据（stream_type=0x06）的 ISO/IEC 13818-1 PES 数据包。
STATISTICS_INFO	提供播放统计信息，如丢帧数、当前速度等。
DESTROYING	当播放器开始拆卸时触发。

mpegts.ErrorTypes

播放期间可能出现的错误。它们需要带有 mpegts.ErrorTypes 前缀。

错误	描述
NETWORK_ERROR	与网络相关的错误，例如无法连接到服务器、网络中断或请求超时等。
MEDIA_ERROR	与媒体文件本身相关的错误，包括格式不正确、解码问题等。
OTHER_ERROR	任何其他未指定的错误，不属于上述两类的错误情况。

mpegts.ErrorDetails

提供有关网络和媒体错误的更详细的解释。它们需要带有 mpegts.ErrorDetails 前缀。

错误	描述
NETWORK_EXCEPTION	与网络相关的其他问题；包含具体的错误信息。
NETWORK_STATUS_CODE_INVALID	与无效的 HTTP 状态码相关的问题，例如 403（禁止访问）、404（未找到）等。
NETWORK_TIMEOUT	与请求超时相关的问题。
NETWORK_UNRECOVERABLE_EARLY_EOF	与无法恢复的意外网络 EOF（文件结束）相关的问题。
MEDIA_MSE_ERROR	与 MediaSource相关的错误，如解码问题等。
MEDIA_FORMAT_ERROR	与媒体流中的任何无效参数相关的问题。
MEDIA_FORMAT_UNSUPPORTED	输入的 MediaDataSource格式不受 mpegts.js支持。
MEDIA_CODEC_UNSUPPORTED	媒体流中包含不受支持的视频/音频编解码器。