更新记录

1.2.2(2026-11-16) 下载此版本

  • 修复打包后(非 dev)提示「播放内核未加载(mpegts 未加载)」:UMD 包被打包器按 CommonJS 处理,只走 module.exports 分支、没挂 window.mpegts
    • libs/mpegts.js 头部改为无条件多路赋值(module.exports / exports.mpegts / window.mpegts / globalThis.mpegts)
    • 已用 vm 实测两种环境:无 module 的 ESM 环境、有 module 的 CJS 环境,window.mpegts.createPlayer 均可用
  • 底部控制条图标从 emoji 字符(⏸ ▶ ⟳)改为纯 CSS 绘制 + 中文文字,避免 Android 渲染成彩色表情
  • 全屏按钮保留 ⛶ + 「全屏播放」文字;只把 emoji 变体字符(⏸ ▶ ⟳)换成 CSS 绘制 / 中文,⛶ 属于普通符号区不在此列

平台兼容性

uni-app(3.8.11)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
× √ √ √ √ × √ × ×
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × - × ×

yolo-player 多画面视频播放器

基于 mpegts.js 的 HTTP-FLV 直播播放组件。逻辑层只管给播放源和收事件,播放内核(libs/core.js)负责建 video + MSE、断流重连、低延迟追帧。

内核一套,两种承载:

端 承载方式 原因
App(Android) renderjs 逻辑层没有 DOM,必须在视图层操作
H5 $refs + $nextTick 逻辑层与视图层同线程,直接拿真实 DOM

支持 App-Android 与 H5(桌面浏览器)。 不支持 iOS:WKWebView 没有 MSE(iOS 17.1 起才有 ManagedMediaSource),iPhone 上播不了 FLV。 不支持小程序:没有 MSE。

安装

插件已放在 uni_modules/yolo-player,libs/mpegts.js(v1.8.0,UMD,未压缩)与 libs/core.js 随插件引入,无需 npm。

内置 mpegts.js 的补丁(升级时必看)

libs/mpegts.js 头部做过一处补丁。原始 UMD 是按环境三选一赋值:

"object" == typeof exports && "object" == typeof module
  ? module.exports = t()          // ← 打包器走这条,不会挂 window
  : ... : e.mpegts = t()

uni-app 打包(非 dev)时该文件被当成 CommonJS,只走 module.exports 分支,导致 window.mpegts 为 undefined,运行时提示「播放内核未加载」。补丁改成无条件多路赋值:

var a = t()
if (module.exports) module.exports = a
if (exports) exports.mpegts = a
if (window) window.mpegts = a
if (globalThis) globalThis.mpegts = a

升级 mpegts 版本时要重新打这个补丁,否则打包后又会拿不到内核。

用法

<template>
  <yolo-player
    :urls="urls"
    :cols="1"
    :muted="true"
    @ready="onReady"
    @error="onError"
    @tap="onTap"
  />
</template>

<script setup>
import { ref } from 'vue'

const urls = ref([
  { id: '100100014', url: 'http://10.11.159.105:8050/100100014.flv', name: '大门' }
])

function onReady(slot, item) {
  console.log('第', slot, '路起播', item)
}
function onError(slot, payload) {
  // 单路失败不影响其它路,组件内部已自动重连(指数退避,最多 10 次)
  console.warn('第', slot, '路异常', payload.msg)
}
function onTap(slot, item) {
  // 点某一路,常用于放大 / 切换主码流
}
</script>

容器必须有高度(组件是 height:100%),父级给 100vh 或固定高度。

Props

名称 类型 默认 说明
urls Array [] 播放源 [{ id, url, name }],url 必填
cols Number 1 宫格数 1/2/4/9,1 为单画面
mode String 'flv' 预留,目前仅 flv
autoplay Boolean true 自动起播
muted Boolean true 静音(App 端自动播放必须静音)
hasAudio Boolean false 流里含音轨时置 true,否则不解析音频
objectFit String 'contain' contain / cover / fill
gap Number 2 宫格间距 px
background String '#000000' 背景色
maxPlaying Number 4 同时拉流上限;0 不限。超出的画面显示「已暂停,点击播放」,点击即抢占播放资格
debug Boolean false 画面左上角显示「延迟 / 丢帧 / 重连」浮层

事件

名称 回调 说明
ready (slot, item) 某一路首帧出画
error (slot, payload) 某一路异常,payload.msg 为原因;组件内部已开始重连
tap (slot, item) 点击某一路(点未播放的画面会先抢占播放,不触发 tap)
state (payload) 全部状态变化(playing / error)
stats (list) 每秒回抛一次,[{ slot, url, latency, speed, dropped, retry, online }]

方法(通过 ref 调用)

名称 说明
reload() 销毁全部实例后重建(卡死、黑屏时用)
pause() 暂停全部:销毁实例并显示「已暂停」(页面 onHide 用)
resume() 恢复播放,重新拉最新流(比挂着 pause 更容易追平)

行为说明

  • 低延迟:关 enableStashBuffer、开 liveBufferLatencyChasing(最大延迟 1.6s,最小保留 0.3s),直播画面不会被缓冲越拖越远。
  • 自动重连:单路断流按 1.6 倍指数退避重连,最多 10 次;失败后在画面上显示「点击重试」。
  • 换源:urls 中某项 url 变化 → 只重建那一路,其它路不受影响(不白屏)。
  • 按需起播:同时拉流的路数不超过 maxPlaying,超出的槽位显示「已暂停,点击播放」;点击任意暂停的画面会把它提到活跃队首、踢掉最早激活的那一路。9 宫格用它才不会被解码器拖死。
  • 卡顿看门狗:每秒检查一次 currentTime,连续 3 秒不动即销毁重建(从最新 GOP 重拉),等效把延迟归零。两次强制重建至少间隔 5 秒,避免抖动。
  • 销毁:组件卸载 / urls 清空时统一 player.destroy() + 移除 DOM,避免 MSE 实例泄漏。

调试

  1. 画面一直停在「连接中…」→ 看 HBuilderX 控制台视图层日志(renderjs 的 console 打在视图层,不在逻辑层)。常见原因:流地址 CORS 被拦、流不是 FLV、设备 WebView 不支持 MSE(会直接显示「不支持 MSE 播放」)。
  2. 不要改成 import mpegts from './mpegts.js':mpegts.js 是 UMD 包,uni-app(Vite)下会报 The requested module ... does not provide an export named 'default'。core.js 里用的是「副作用导入 import './mpegts.js' + 取 window.mpegts」,这是 Vite 下加载 UMD 库的正确姿势,改回默认导入会立刻报错。

已知限制

  1. CORS:mpegts.js 用 XHR/fetch 拉流,服务端必须返回 Access-Control-Allow-Origin。若流地址是 302 跳转,跳转后的最终响应也要带 CORS 头,否则报网络错误。H5 端浏览器校验最严,必挂;App 端 webview 可能宽松些,但同样不确定。
  2. iOS 不支持:WKWebView 无 MSE(iOS < 17.1)。需要 iPhone 播放请改用服务端 HLS 转封装 + 原生 <video>,或上原生解码插件。
  3. 多路性能:4 路 1080p 在低端 Android 设备上会掉帧发热,建议平台提供子码流,宫格播子码流、单路放大切主码流。
  4. 组件只负责「给 url 就播」,取流地址、云台(PTZ)、录像回放等业务逻辑应留在项目里,保证插件可跨项目复用。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

网络(HTTP-FLV 拉流)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据,视频流仅在设备与你的流媒体服务器之间传输

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


本插件内置的 mpegts.js 遵循其原始 Apache-2.0 许可(https://github.com/xqq/mpegts.js)。

暂无用户评论。