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文档

目录CONTENT

mpegts.js 官方 API 中文文档