flv.js 使用说明
flv.js 使用说明
flv.js 是一个纯 JavaScript 实现的 HTML5 FLV 视频播放器，由哔哩哔哩（Bilibili）开发。它允许在浏览器中直接播放 FLV 格式的视频流，而无需依赖 Flash 插件。flv.js 的核心原理是通过 Media Source Extensions (MSE) API 将 FLV 流解析并转封装为 Fragmented MP4 片段，然后注入到 HTML5 <video> 标签中，实现硬件加速播放。该库轻量高效，适用于点播和直播场景，但项目维护已较少，推荐对于 FLV 直播流考虑使用 mpegts.js 替代。
flv.js 支持 H.264 + AAC/MP3 编解码、HTTP FLV 低延迟直播、WebSocket FLV 直播等功能。以下是详细的使用说明，涵盖安装、基本用法、配置选项、注意事项等。
一、关键特性
- 支持格式：FLV 容器，支持 H.264 视频（Baseline、Main、High Profile，全支持 B 帧）和 AAC 音频（LC、HE、HEv2 Profile），部分支持 H.265（flv id == 12）和 PCM 音频。
- 传输协议：HTTP FLV 流、WebSocket FLV 流、多部分分段视频。
- 低延迟：支持设置缓冲区时长（可设为 0 实现低延迟，但网络抖动可能导致卡顿）。
- 硬件加速：浏览器原生加速，低开销。
- WASM 支持：智能丢帧避免花屏，适用于长时间播放。
- 兼容性：依赖 MSE API，不支持 iOS 和 Android 4.4.4 以下浏览器。
二、浏览器支持
flv.js 支持以下浏览器（需 MSE 支持）：
- Chrome（全支持）
- Firefox（全支持）
- Safari 10+（部分支持，直播可能有限制）
- IE11（MP3 音频不支持）
- Edge（类似 IE11）
不支持：iOS Safari、Android 低版本浏览器（需 Flash 或其他方案兼容）。
在代码中，先检查 flvjs.isSupported() 以确认浏览器兼容性。
三、安装
1. 通过 NPM 安装（推荐用于项目集成）
npm install --save flv.js- 对于中国大陆用户，推荐使用 cnpm 镜像加速安装。
- 安装后，可通过 ES6 模块导入：
import flvjs from 'flv.js';2. 通过 CDN 或直接下载
- 从 GitHub Releases 下载
flv.min.js（https://github.com/bilibili/flv.js/releases）。 - 或使用 CDN（如 unpkg）：
<script src="https://unpkg.com/flv.js@latest/dist/flv.min.js"></script>3. 构建（开发者）
- 克隆仓库：
git clone https://github.com/bilibili/flv.js.git - 安装依赖：
npm ci - 构建调试版：
npm run build:debug（输出到/dist） - 构建发布版：
npm run build（生成flv.min.js） - 开发模式：
npm run dev（监听文件变化，自动构建调试版）
四、基本用法
flv.js 的核心流程：检查支持 → 创建播放器 → 附加到 <video> 元素 → 加载并播放。
1. HTML 结构
<video id="videoElement" controls width="640" height="360"></video>
<script src="flv.min.js"></script> <!-- 或通过 NPM 导入 -->2. JavaScript 代码
简单点播播放示例
if (flvjs.isSupported()) {
var videoElement = document.getElementById('videoElement');
var flvPlayer = flvjs.createPlayer({
type: 'flv',
url: 'http://example.com/video.flv' // FLV 文件或流 URL
});
flvPlayer.attachMediaElement(videoElement); // 附加到 video 标签
flvPlayer.load(); // 加载媒体
flvPlayer.play(); // 开始播放
} else {
console.log('浏览器不支持 flv.js');
}Vue.js 示例（集成到 Vue 项目）
<template>
<video id="myVideo" controls></video>
</template>
<script>
import flvjs from 'flv.js';
export default {
methods: {
videoFlv(videoUrl) {
this.$nextTick(() => {
if (flvjs.isSupported()) {
let videoElement = document.getElementById("myVideo");
let flvPlayer = flvjs.createPlayer({
type: "flv",
url: videoUrl,
cors: true, // 跨域支持
hasAudio: true,
hasVideo: true,
isLive: false // 点播模式
});
flvPlayer.attachMediaElement(videoElement);
flvPlayer.load();
flvPlayer.play();
}
});
}
}
};
</script>- 调用：在 mounted 或方法中调用
this.videoFlv('http://your-flv-url.flv')。
直播流播放示例（HTTP FLV）
var flvPlayer = flvjs.createPlayer({
type: 'flv',
url: 'http://example.com/live.flv', // 直播流 URL
isLive: true // 直播模式
});
flvPlayer.attachMediaElement(videoElement);
flvPlayer.load();五、配置选项
创建播放器时，可传递配置对象。常见选项包括：
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | string | ‘flv’ | 媒体类型，必须为 ‘flv’。 |
url | string | – | FLV 文件或流 URL（HTTP 或 WebSocket）。 |
cors | boolean | false | 启用跨域资源共享（CORS）。 |
hasAudio | boolean | true | 是否包含音频。 |
hasVideo | boolean | true | 是否包含视频。 |
isLive | boolean | false | 是否为直播模式（影响缓冲和延迟）。 |
duration | number | – | 媒体总时长（秒），用于点播。 |
mediaDataSource | object | – | 高级：自定义媒体源，支持分段加载（multipart）。 |
config | object | {} | 高级配置，如 { enableWorker: true, enableStashBuffer: false }（启用 Worker 线程、禁用缓冲）。 |
示例高级配置（低延迟直播）：
var flvPlayer = flvjs.createPlayer({
type: 'flv',
url: 'ws://example.com/live.flv', // WebSocket 直播
isLive: true,
config: {
enableWorker: false, // 禁用 Worker 以降低延迟
stashInitialSize: 384, // 初始缓冲大小（KB）
fixAudioTimestampGap: true // 修复音频时间戳问题
}
});完整 API 文档：https://github.com/bilibili/flv.js/blob/master/docs/api.md
六、事件监听和控制
flv.js 提供事件回调和控制方法，与 HTML5 Video API 兼容。
1. 事件监听
flvPlayer.on(flvjs.Events.LOADED_METADATA, function() {
console.log('元数据加载完成');
});
flvPlayer.on(flvjs.Events.ERROR, function(errType, errDetail) {
console.log('播放错误:', errType, errDetail);
});
flvPlayer.on(flvjs.Events.MEDIA_INFO, function(mediaInfo) {
console.log('媒体信息:', mediaInfo);
});常见事件：
LOADED_METADATA：元数据加载。MEDIA_INFO：媒体信息（如分辨率、时长）。ERROR：错误处理（如网络错误、格式不支持）。STATISTICS_INFO：播放统计（如缓冲区、比特率）。
2. 控制方法
load()：重新加载媒体。play()：播放。pause()：暂停。unload()：卸载并销毁。destroy()：完全销毁播放器（释放资源）。detachMediaElement()：分离 video 元素。
示例：销毁播放器
// 组件卸载时
flvPlayer.pause();
flvPlayer.unload();
flvPlayer.detachMediaElement();
flvPlayer.destroy();七、注意事项
- 跨域问题（CORS）：
- 如果 FLV 资源在不同域，服务器需设置
Access-Control-Allow-Origin: *头。 - 配置中设置
cors: true，但服务器端必须支持。常见错误：No 'Access-Control-Allow-Origin' header。 - 解决方案：配置视频服务器（如 Nginx）添加 CORS 头，或使用代理。
- 直播兼容性：
- HTTP FLV 直播在某些浏览器（如 Safari）可能不支持，推荐 WebSocket。
- 低延迟设置：缓冲区设为 0，但易卡顿；测试网络稳定性。
- 性能优化：
- 启用 Worker：
enableWorker: true（多线程解码，但增加开销）。 - 丢帧机制：WASM 模式下自动丢帧避免花屏。
- 移动端：不支持 MSE 的设备需 fallback 到其他播放器（如 HLS）。
- 常见错误：
Non-FLV, Unsupported media type!：确保 URL 是 FLV 流；WebSocket 需正确格式。- H.265 支持有限：flv.js 部分支持 H.265（需最新版）。
- MP3 音频在 IE11/Edge 不工作。
- 兼容方案：
- 对于不支持的浏览器，使用
<video>的 HLS/MP4 fallback。 - 示例：
javascript if (!flvjs.isSupported()) { videoElement.src = 'video.mp4'; // 备选 MP4 videoElement.play(); }
- 调试：
- 使用调试版
flv.js（非 min.js），开启控制台日志。 - 检查 MSE 支持：
window.MediaSource && window.MediaSource.isTypeSupported('video/mp4; codecs="avc1.42E01E,mp4a.40.2"')。
八、多部分播放（Multipart）
flv.js 支持播放列表式分段视频：
- 配置
mediaDataSource.segments数组，每个段包含 URL 和时长。 - 详情：https://github.com/bilibili/flv.js/blob/master/docs/multipart.md
示例：
var mediaDataSource = {
type: 'flv',
segments: [
{ duration: 30, filesize: 1024000, url: 'part1.flv' },
{ duration: 30, filesize: 1024000, url: 'part2.flv' }
]
};
var flvPlayer = flvjs.createPlayer(mediaDataSource);九、资源与社区
- 官方仓库：https://github.com/bilibili/flv.js （包含 Issue 讨论，如跨域、H.265 支持）。
- 演示：http://bilibili.github.io/flv.js/
- 文档：API（https://github.com/bilibili/flv.js/blob/master/docs/api.md）、直播指南（https://github.com/bilibili/flv.js/blob/master/docs/livestream.md）、CORS（https://github.com/bilibili/flv.js/blob/master/docs/cors.md）。
- 许可：Apache License 2.0。
flv.js 适用于 Web 直播/点播项目，但鉴于维护状态，建议评估 mpegts.js 或 Video.js 等替代品。如果需要特定场景（如 Vue 集成或错误调试）的更多示例，请提供细节！