视频播放器调用方法
本页所有示例都对应本服务器已部署的实现:HLS 由 hls.js 播放,P2P 分片共享由 p2p-media-loader v4 提供。
1. 页面直达 URL
最简单的调用方式:把视频 id 拼到播放页。
https://<你的域名或 IP>/watch.html?id=<视频ID>
2. iframe 嵌入
播放页提供“复制 iframe 嵌入代码”按钮,也可以手写:
<iframe
src="https://<host>/embed.html?id=<视频ID>&p2p=1&autoplay=1&muted=1"
width="960" height="540"
style="border:0" allowfullscreen>
</iframe>
| 参数 | 默认 | 说明 |
|---|---|---|
id | — | 视频 ID(必填) |
p2p | 1 | 0 关闭 P2P,仅走 HTTP |
autoplay | 0 | 1 自动播放(受浏览器策略限制) |
muted | 1 | 0 不静音;自动播放时建议保持静音 |
3. JavaScript 组件 API
在页面中引入三个脚本后,用 WebRTCHLSPlayer.create() 创建播放器:
<script src="/js/vendor/hls.min.js"></script>
<script src="/js/vendor/p2p-media-loader-hlsjs.iife.min.js"></script>
<script src="/js/player.js"></script>
<div id="player"></div>
<script>
const player = WebRTCHLSPlayer.create('#player', {
src: '/media/<视频ID>/master.m3u8', // 必填
poster: '/media/<视频ID>/poster.jpg',
autoplay: false,
muted: false,
p2p: true, // 是否启用 P2P
swarmId: 'webrtc-hls:<视频ID>', // 同一视频的观众需一致
trackerUrl: WebRTCHLSPlayer.defaultTrackerUrl(), // 默认 /announce
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
// 回调(也可用 player.on('ready', fn) 注册)
onReady: (info) => console.log('P2P:', info.p2p),
onStats: (s) => console.log('节点', s.peers, 'P2P 占比', s.p2pRatio),
onError: (e) => console.error(e),
onPeer: (p) => console.log('peer', p.peerId, p.connected)
});
</script>
实例方法
| 方法 | 说明 |
|---|---|
play() / pause() | 播放 / 暂停 |
seek(seconds) | 跳转到指定秒数 |
setQuality(index) | 切换清晰度,-1 为自动 |
getLevels() | 返回 [{ index, height, bitrate, name }] |
getStats() | 返回 P2P 统计:peers / p2pBytes / httpBytes / uploadedBytes / p2pRatio |
getVideo() / getHls() | 获取原生 video / hls.js 实例,便于二次封装 |
isP2P() | 当前是否实际启用 P2P |
destroy() | 销毁播放器、断开所有 peer 连接 |
事件
| 事件 | 说明 |
|---|---|
ready | 播放器就绪,参数 { p2p, levels, native } |
levels / level | 码率列表就绪 / 当前清晰度变化 |
stats | P2P 流量统计变化 |
peer | peer 连接 / 断开 |
error | 播放错误 |
autoplay-blocked | 自动播放被浏览器拦截 |
4. 手动集成 hls.js + P2P 引擎
不使用本项目的 player.js 时,可以直接组合两个库:
<script src="/js/vendor/hls.min.js"></script>
<script src="/js/vendor/p2p-media-loader-hlsjs.iife.min.js"></script>
<script>
const HlsWithP2P = p2pml.hlsjs.HlsJsP2PEngine.injectMixin(Hls);
const hls = new HlsWithP2P({
p2p: {
core: {
announceTrackers: [WebRTCHLSPlayer.defaultTrackerUrl()],
rtcConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
swarmId: 'webrtc-hls:<视频ID>'
}
}
});
hls.loadSource('/media/<视频ID>/master.m3u8');
hls.attachMedia(document.querySelector('video'));
// 统计
const engine = hls.p2pEngine;
engine.addEventListener('onChunkDownloaded', (bytes, source) => {
console.log(source, bytes); // source: 'p2p' | 'http'
});
</script>
5. HLS 直链(通用播放器)
视频转码完成后,任何支持 HLS 的播放器都可以直接打开:
https://<host>/media/<视频ID>/master.m3u8
| 播放器 | 用法 |
|---|---|
| VLC | 媒体 → 打开网络串流,粘贴上面的 URL |
| mpv | mpv https://<host>/media/<id>/master.m3u8 |
| ffplay | ffplay https://<host>/media/<id>/master.m3u8 |
| Safari / iOS | 原生支持 HLS:<video src="..."> 即可(无 P2P) |
| video.js / Plyr / DPlayer | 配置 src 指向该 URL,并挂载 hls.js 技术 |
注意:直链方式不经过本项目的播放器,因此没有 P2P 加速,全部流量走服务器。
5.5 Range(字节范围)支持
转码时会保留原片,可直接用 Range 请求边下边播、拖动进度:
http://<host>/media/<视频ID>/source.mp4
# 200 + Accept-Ranges: bytes
curl -I http://<host>/media/<ID>/source.mp4
# 206 + Content-Range: bytes 0-1023/<size>
curl -r 0-1023 -o part.bin http://<host>/media/<ID>/source.mp4
# 越界返回 416
curl -r 999999999- http://<host>/media/<ID>/source.mp4
播放页的「用原片播放(Range)」等价于 /watch.html?id=<ID>&mode=mp4。
HLS 单文件 + EXT-X-BYTERANGE
上传时选择「单文件 + Range(EXT-X-BYTERANGE)」,每个码率生成一个 .ts,
播放列表用 #EXT-X-BYTERANGE:长度@偏移 描述分片;hls.js 按字节范围请求,
p2p-media-loader 也按 byteRange 在 peer 之间共享。两种模式可共存。
curl http://<host>/media/<ID>/720p/index.m3u8 | head
curl -r 0-99 -o chunk.bin http://<host>/media/<ID>/720p/media.ts
6. 服务端接口
| 接口 | 说明 |
|---|---|
GET /api/videos | 视频列表 |
GET /api/videos/:id | 视频详情(含 master / poster / renditions) |
POST /api/upload | 上传视频(Header x-upload-token;form 字段 file、title、mode=segments|single) |
DELETE /api/videos/:id | 删除视频(Header x-upload-token) |
GET /api/health | 健康检查 |
GET /api/p2p/stats | P2P 拓扑诊断:在线 swarm、节点数、WS 连接数 |
7. 常见问题
Network 面板里 /announce 一直显示 101 / 待处理(Pending)/ 0.0 kB?
这是正常现象。/announce 是 WebSocket 长连接,建立后状态会一直保持 Pending,
大小要等连接关闭才结算。判断 P2P 是否正常,请播放页看「信令:已连接」与「P2P 节点」,
或直接访问 /api/p2p/stats 查看 tracker 中的在线节点。
P2P 节点一直是 0?
同一视频需要至少两个观众同时在线才会建立 peer 连接。可以打开第二个标签页播放同一视频, 稍等 5–30 秒,两个页面都会出现 1 个节点;关闭一个标签页后节点数会减少。