flv.js API

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

接口

flv.js 通过全局上下文 window 中暴露的 flvjs 对象导出所有接口。

flvjs 对象也可以通过 require 或 ES6 import 访问。

函数:

• flvjs.createPlayer()
• flvjs.isSupported()
• flvjs.getFeatureList()

类:

• flvjs.FlvPlayer
• flvjs.NativePlayer
• flvjs.LoggingControl

枚举:

• flvjs.Events
• flvjs.ErrorTypes
• flvjs.ErrorDetails

flvjs.createPlayer()

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

根据 mediaDataSource 中指定的 type 字段创建播放器实例，可选的 config 参数。

MediaDataSource

字段	类型	描述
type	string	表示媒体类型，'flv' 或 'mp4'
isLive?	boolean	表示数据源是否为直播流
cors?	boolean	表示是否启用 CORS 进行 HTTP 请求
withCredentials?	boolean	表示是否在 HTTP 请求中使用 cookies
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	启用分离线程进行转码（目前不稳定）
enableStashBuffer?	boolean	true	启用 IO 缓存。如果需要实时（最小延迟）播放直播流，可以设置为 false，但在网络抖动时可能会卡顿。
stashInitialSize?	number	384KB	表示 IO 缓存的初始大小。默认值为 384KB。指定合适的大小可以改善视频加载/搜索时间。
isLive?	boolean	false	与MediaDataSource 中的 isLive 相同，如果在 MediaDataSource 结构中已设置，则忽略此字段。
lazyLoad?	boolean	true	如果有足够的数据进行播放，则中止 HTTP 连接。
lazyLoadMaxDuration?	number	3 * 60	表示 lazyLoad 保留数据的秒数。
lazyLoadRecoverDuration?	number	30	表示 lazyLoad 恢复时间边界，单位为秒。
deferLoadAfterSourceOpen?	boolean	true	在 MediaSource sourceopen 事件触发后加载。在 Chrome 中，后台打开的标签页可能不会触发 sourceopen 事件，直到切换到该标签页。
autoCleanupSourceBuffer	boolean	false	对 SourceBuffer 进行自动清理
autoCleanupMaxBackwardDuration	number	3 * 60	当向后缓冲区时长超过此值（单位为秒）时，对 SourceBuffer 进行自动清理
autoCleanupMinBackwardDuration	number	2 * 60	表示在进行自动清理时保留的向后缓冲区时长，单位为秒。
fixAudioTimestampGap	boolean	true	在检测到较大的音频时间戳间隙时填充静音音频帧，以避免音视频不同步。
accurateSeek?	boolean	false	精确搜索到任何帧，不限于视频 IDR 帧，但可能稍慢。适用于 Chrome > 50、FireFox 和 Safari。
seekType?	string	'range'	'range' 使用范围请求进行搜索，或 'param' 在 URL 中添加参数以指示请求范围。
seekParamStart?	string	'bstart'	表示 seekType = 'param' 时的搜索开始参数名称
seekParamEnd?	string	'bend'	表示 seekType = 'param' 时的搜索结束参数名称
rangeLoadZeroStart?	boolean	false	如果使用 Range 搜索，则在首次加载时发送 Range: bytes=0-
customSeekHandler?	object	undefined	表示自定义的搜索处理器
reuseRedirectedURL?	boolean	false	重用 301/302 重定向的 URL 进行后续请求，如搜索、重新连接等。
referrerPolicy?	string	no-referrer-when-downgrade	表示使用 FetchStreamLoader 时的[Referrer Policy][Referrer Policy]
headers?	object	undefined	表示将添加到请求中的额外头信息

flvjs.isSupported()

function isSupported(): boolean;

如果基本播放功能在您的浏览器上可以工作，则返回 true。

flvjs.getFeatureList()

function getFeatureList(): FeatureList;

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

FeatureList

字段	类型	描述
mseFlvPlayback	boolean	与 flvjs.isSupported() 相同，表示基本播放功能是否在您的浏览器上工作。
mseLiveFlvPlayback	boolean	表示 HTTP FLV 直播流是否在您的浏览器上工作。
networkStreamIO	boolean	表示网络加载器是否为流式传输。
networkLoaderName	string	表示网络加载器的类型名称。
nativeMP4H264Playback	boolean	表示您的浏览器是否原生支持 H.264 MP4 视频文件。
nativeWebmVP8Playback	boolean	表示您的浏览器是否原生支持 WebM VP8 视频文件。
nativeWebmVP9Playback	boolean	表示您的浏览器是否原生支持 WebM VP9 视频文件。

flvjs.FlvPlayer

interface FlvPlayer extends Player {}

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

flvjs.NativePlayer

interface NativePlayer extends Player {}

浏览器原生播放器（HTMLVideoElement）的包装器，没有 MediaSource src，实现了 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;
}

flvjs.LoggingControl

一个全局接口，包含几个静态的 getter/setter 来设置 flv.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;
}

flvjs.Events

一系列常量，可以与 Player.on() / Player.off() 一起使用。它们需要前缀 flvjs.Events。

事件	描述
ERROR	在播放过程中发生任何错误时触发
LOADING_COMPLETE	输入的 MediaDataSource 已完全缓冲到末尾时触发
RECOVERED_EARLY_EOF	在缓冲过程中发生意外的网络 EOF 但已自动恢复时触发
MEDIA_INFO	提供媒体的技术信息，如视频/音频编解码器、比特率等。
METADATA_ARRIVED	提供 FLV 文件（流）可以包含的元数据，带有 "onMetaData" 标记。
SCRIPTDATA_ARRIVED	提供 FLV 文件（流）可以包含的脚本数据（OnCuePoint / OnTextData）。
STATISTICS_INFO	提供播放统计信息，如丢帧、当前速度等。

flvjs.ErrorTypes

播放过程中可能出现的错误。它们需要前缀 flvjs.ErrorTypes。

错误	描述
NETWORK_ERROR	与网络相关的错误
MEDIA_ERROR	与媒体相关的错误（格式错误、解码问题等）
OTHER_ERROR	任何其他未指定的错误

flvjs.ErrorDetails

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

错误	描述
NETWORK_EXCEPTION	与网络相关的任何其他问题；包含 message
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 格式不受 flv.js 支持
MEDIA_CODEC_UNSUPPORTED	媒体流包含不受支持的视频/音频编解码器

参考链接

• flv.js GitHub API文档