mpegts.js API

本文使用类似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中指定的 type字段创建播放器实例，可选的 config参数用于配置。

MediaDataSource

字段	类型	描述
type	string	媒体类型，可选值：'mse'、'mpegts'、'm2ts'、'flv'或 'mp4'
isLive?	boolean	指示数据源是否为直播流
cors?	boolean	是否启用跨域请求（CORS）
withCredentials?	boolean	是否携带cookie进行HTTP请求
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	为MediaSource启用独立线程
enableStashBuffer?	boolean	true	启用IO暂存缓冲区。设为false可实现直播流最低延迟，但网络抖动可能导致卡顿
stashInitialSize?	number	384KB	IO暂存缓冲区初始大小。合理设置可提升视频加载/seek速度
isLive?	boolean	false	同MediaDataSource中的 isLive，若已设置则忽略
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最小保留缓冲延迟（秒，同上）
liveSync?	boolean	false	通过调整播放速率追平直播延迟（需同时设置 isLive: true）
liveSyncMaxLatency?	number	1.2	最大可接受缓冲延迟（秒，仅在 isLive: true且 liveSync: true时生效）
liveSyncTargetLatency?	number	0.8	目标追平延迟（秒，同上）
liveSyncPlaybackRate?	number	1.2	追延迟时的播放速率（范围[1, 2]，同上）
lazyLoad?	boolean	true	当有足够数据时中止HTTP连接
lazyLoadMaxDuration?	number	3 * 60	为 lazyLoad保留的数据时长（秒）
lazyLoadRecoverDuration?	number	30	lazyLoad恢复时间边界（秒）
deferLoadAfterSourceOpen?	boolean	true	在MediaSource触发 sourceopen事件后加载（Chrome后台标签可能不触发该事件）
autoCleanupSourceBuffer	boolean	false	自动清理SourceBuffer
autoCleanupMaxBackwardDuration	number	3 * 60	当后向缓冲超过该值（秒）时自动清理
autoCleanupMinBackwardDuration	number	2 * 60	自动清理时保留的最小后向缓冲时长（秒）
fixAudioTimestampGap	boolean	true	检测到大音频时间戳间隙时填充静音帧避免音视频不同步
accurateSeek?	boolean	false	精确seek到任意帧（不限视频IDR帧，可能稍慢），支持Chrome>50、FireFox和Safari
seekType?	string	'range'	seek方式：'range'使用范围请求，'param'在URL中添加参数
seekParamStart?	string	'bstart'	seekType='param'时的起始参数名
seekParamEnd?	string	'bend'	seekType='param'时的结束参数名
rangeLoadZeroStart?	boolean	false	首次加载时发送 Range: bytes=0-
customSeekHandler?	object	undefined	自定义seek处理器
reuseRedirectedURL?	boolean	false	重用301/302重定向URL进行后续请求
referrerPolicy?	string	no-referrer-when-downgrade	使用FetchStreamLoader时的[引用策略][引用策略]
headers?	object	undefined	请求附加头信息

mpegts.isSupported()

function isSupported(): boolean;

返回 true表示当前浏览器支持基本播放功能。

mpegts.getFeatureList()

function getFeatureList(): FeatureList;

返回 FeatureList对象，包含以下详细信息：

FeatureList

字段	类型	描述
msePlayback	boolean	同 mpegts.isSupported()，表示基本播放是否可用
mseLivePlayback	boolean	是否支持HTTP MPEG2-TS/FLV直播流
mseH265Playback	boolean	是否支持H265 over 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

interface MSEPlayer extends Player {}

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

mpegts.NativePlayer

interface NativePlayer extends Player {}

浏览器原生播放器（HTMLVideoElement）的封装，实现 Player接口，适用于单部分MP4文件播放。

interface 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;
}

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	输入媒体数据源已完全缓冲至结束
RECOVERED_EARLY_EOF	缓冲时遇到意外网络EOF但已自动恢复
MEDIA_INFO	提供媒体技术信息（编解码器、码率等）
METADATA_ARRIVED	提供FLV文件（流）中的"onMetaData"元数据
SCRIPTDATA_ARRIVED	提供FLV文件（流）中的脚本数据（OnCuePoint/OnTextData）
TIMED_ID3_METADATA_ARRIVED	提供带时间戳的ID3元数据（stream_type=0x15）回调
PGS_SUBTITLE_ARRIVED	提供PGS字幕数据（stream_type=0x90）回调
SYNCHRONOUS_KLV_METADATA_ARRIVED	提供同步KLV元数据（stream_type=0x15）回调
ASYNCHRONOUS_KLV_METADATA_ARRIVED	提供异步KLV元数据（stream_type=0x06）回调
SMPTE2038_METADATA_ARRIVED	提供SMPTE2038元数据回调
SCTE35_METADATA_ARRIVED	提供SCTE35元数据（stream_type=0x86）回调
PES_PRIVATE_DATA_ARRIVED	提供ISO/IEC 13818-1 PES私有数据（stream_type=0x06）回调
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	mpegts.js不支持的输入媒体格式
MEDIA_CODEC_UNSUPPORTED	媒体流包含不支持的音视频编解码器

参考链接

• mpegts.js GitHub API文档