更新记录

1.1.0（2026-09-16） 下载此版本

本版相对 1.0.0（已上架）的唯一主题：传统 uni-app vue2 工程可用。 1.0.0 上架时机早于本项工作（其线上平台表中 Vue2 仍为 -），故独立发版。

Vue2 工程支持验证通过（含 4 个 vue2 专属坑的修复）

在传统 uni-app vue2 工程里完成真机验证：App 启动、组件挂载、融合文字/头像、mode 0 音频、 无音轨素材自动 remux、帧数与比例全部正常。过程中修掉 4 个只在 vue2 复现的问题：

1. main.js 与 vueVersion 必须匹配：vue2 要用 App.mpType='app' + new Vue({...App})； 用 Vue3 的 createSSRApp 会报 Cannot set properties of undefined (setting 'query') （框架挂 $mp 的 mixin 未注册所致，排查过程见 TROUBLESHOOTING 附·A）；
2. 事件回调别取页面生命周期名：onReady 等会被 vue2 编译器从 methods 摘走 ⇒ 报 Page "xxx" does not have a method "onReady"；demo 统一改为 vap* 前缀；
3. 方法名不能与 data 键同名（Method "xxx" has already been defined as a data property）—— 已加静态检查 check-demo-page.sh 兜住；
4. :style 对象对原生组件在 vue2 下不生效：<canvas> 的尺寸改为字符串 style， 并给 .vap-canvas 加 width/height:100% 兜底（宿主已有确定宽高）。

1.0.0（2026-09-16） 下载此版本

功能

• 合并原 axen-vap-h5 与 axen-vap-mp 为统一组件（条件编译分流）。
• H5：vap-web（WebGL）引擎（static/vap.min.js 随包分发）。
• 微信小程序：自研引擎（wx.createVideoDecoder + Canvas2D，r 通道遮罩合成）。
• 支持透明度渲染、融合元素（头像/昵称/图片/文字）、循环、完整事件回调。
• uni-app x 项目请使用 axen-vap-x（五端付费版）。

微信端：新增音频（所有素材统一 mode 0 + MediaAudioPlayer）

• 此前微信端完全没有音频实现（common/*.js 里 MediaAudioPlayer / createInnerAudioContext 出现 0 次，readme 也把 mute 标注为「静音（H5）」）—— vapx.mp4 的音轨被直接丢掉。
• 现在所有素材统一走 mode 0 + MediaAudioPlayer（与付费版 axen-vap-x 同一链路）： 音频由系统播放，同时作为帧推进的主时钟（音画天然同步）；有音轨素材因此出声； mute=true 时音量置 0 但仍播放（它是主时钟，停掉就没有帧了）。
• 不做模式分流（重要，防回退）：本版曾按「扫描到无音轨 → 分流 mode 1 + fps 门控」实现， 这恰恰是付费版明确否决并记录防回退的方案（其 changelog「被否决的中间方案」： 该方案在 Node 状态机 8 例全绿，真机仍 78/80）。无音轨素材在 mode 0 / mode 1 下 都会丢流尾 1~2 帧，而 mode 1 还额外失去音频时钟的节奏精度 —— 分流没有收益。已统一为 mode 0。
• 音轨探测（common/mp4-audio.js：最小扫 moov → trak → mdia → hdlr 的 handler_type 是否为 soun， 不解码、不解析 mdat）保留，但仅用于诊断日志（也是将来接 remux 的挂点）； 同一路径只探测一次。已用官方素材实测：demo.mp4 → 无音轨 ✓、vapx.mp4 → 有音轨 ✓。
• 已知限制：无音轨素材可能少 1~2 帧尾帧（VideoDecoder 在流尾 EOS 会吞掉硬解管道最后帧）。 付费版用原地 remux 加静音 AAC 轨解决（实测 80/80、240/240），免费版暂未移植。
• 兜底：mode 0 若 900ms 内一帧都取不到 → 回退 mode 1（画面正常、无声音），仅"保命"用。
• 起播判据修正：一帧都没拿到时绝不再判定"播放结束"（否则 mode 0 起播的几百毫秒会被误判成播完 → 上层立刻关闭覆盖层，表现为「画面没出来」）；改为 3s 仍无帧才报错；已播过帧后 600ms 无新帧才收尾。

日志默认静默 + 演示页清理 + 素材缓存改稳定路径

• 日志默认静默：新增 common/vap-log.js 统一出口，默认不打印（付费版做法：其发布产物里 vapLog 是空实现）。打开方式：uni.$vapDebug = true 或 VapLog.setDebug(true)； warn/error 始终输出。此前排查用的十几行 console.log 会直接刷给买家，现已收敛。
• 演示页清理：删掉调试期加的「微信端音频」开关按钮（组件默认已是 mode 0，无需演示切换）； 顶部显式 uni.$vapDebug = true —— demo 保留详细日志，买家工程保持安静。
• 素材缓存改稳定路径：微信端把下载的素材落到 USER_DATA_PATH/vap-cache/src/（稳定文件名）。 此前 wx.downloadFile 每次给的临时文件名都不同 → 组件 remux 出的 .sil.mp4 随之换名 → 每次播放都要重新下载 + remux，vap-cache 里还会攒下多份伴生文件。 「清空素材缓存」按钮会删掉整个 vap-cache（含 src/），一键复位。

微信端：素材不做比例适配（换素材就变形）+ 演示页写死了文字样式

• 比例适配：合成器此前把素材 rgbFrame 直接拉伸铺满画布 —— 竖版素材（672×1504）之后再播 横版素材（736×576）会明显变形（真机反馈："点了全屏进房动效以后再播透明动画就变形了"）。 现新增 scaleType 属性（默认 aspectFit，与付费版 axen-vap-x 同名属性同默认值）： aspectFit 等比装进画布留透明边 / aspectFill 等比铺满超出裁掉 / scaleToFill 拉伸铺满。 适配放在绘制阶段（与付费版一致），所以画布尺寸保持稳定（= 容器），换素材不再引起重排。 新增 scripts/sim-mp-aspect.mjs 逐模式校验适配数学（5 例：两种素材 × 三种模式）。
• 演示页不再写死文字样式：demo 的 FULL_MIX 曾写死 color:'#FFFFFF', fontSize:32, fontWeight:'bold'， 于是"字体是白的、还被裁" —— 素材 vapc 配置里本来有自己的颜色/字号，引擎还按元素矩形自适应字号 （正是为了避免裁切）。现在演示只传值不传样式；组件支持传对象覆盖样式（本实现的扩展）， 但示例不该覆盖，页面源码里留了注释与示例。

微信端：音频起不来 —— MediaAudioPlayer 的方法都是 Promise，我同步调用了

• 官方文档（MediaAudioPlayer）： · 属性只有 volume（0~1），没有 paused / currentTime / duration； · start() / addAudioSource(VideoDecoder) / removeAudioSource / stop / destroy 都返回 Promise。
• 两个后果：
  1. 我此前写的"音频自检"读 paused/currentTime 判"是否在播" —— 无效判据（必然读到 undefined）， 据此得出了错误结论，已删除；
  2. 真正的 bug：addAudioSource(decoder) 是异步的，我紧接着同步调用 ap.start()， 播放器可能在音源挂上之前就启动了 ⇒ 完全没有声音；而 mode 0 的帧由音频时钟推进， 时钟不走 ⇒ 帧只能慢慢滴 —— 真机日志里刷屏的 render behind, dropping frame N (late ~220ms) 正是这个症状。
• 修复：改成 Promise 链，并带顺序兜底 —— 先试 addAudioSource → start，失败则自动换 start → addAudioSource，两条都有明确日志： · 成功：[axen-vap] 音频播放器已启动（顺序=…），volume=1 · 都失败：打印拒绝原因（errMsg），并说明"该素材/该基础库下没有声音，画面不受影响"。

微信端：无音轨素材 remux 出静音音轨（对齐付费版链路）

• 定位到一个更根本的前提：付费版"素材统一 mode 0"能成立，是因为它先给无音轨素材补了音轨。 官方 demo.mp4 没有音轨时，mode 0 缺音频时钟、且把纯视频解码器挂给 MediaAudioPlayer 本就不成立 —— 实测表现就是「画面不出来」。
• 现在播放前对无音轨素材做原地 remux（新增 common/mp4-remux.js，纯字节数学无依赖）： 在 moov 里插一条静音 AAC trak（44.1kHz mono，时长对齐视频），视频样本一个字节都不动： mdat 在末尾（faststart，官方素材即如此）→ 扩展现有 mdat；否则 → 在 EOF 追加一个新 mdat； moov 变长后逐条修正视频 stco（+Δ）、更新 mvhd.next_track_ID。 产物 = 原路径 + ".sil.mp4" 伴生文件，按路径缓存（复用第二次 0ms）。
• 字节级验收（与付费版同一套标准）：
  • demo.mp4（80 帧 / faststart）：video 80/80 framemd5 逐帧一致、audio aac 44100 mono 138 帧、 全量解码零错误、vapc box 原样保留；
  • vapx.mp4 去音轨（240 帧 / 非 faststart）：240/240 逐帧一致、audio 517 帧、同样零错误；
  • 耗时（node）：17ms / 35ms —— 早期"逐字节 push 进 JS 数组"的写法是 62/139ms 且内存抖动大， 已改为先量长度、预分配 Uint8Array、set() 拷贝。
• 失败即放弃并回退 mode 1（非 mp4 / co64 / 结构异常 / 读写失败），不引入新风险。
• 新增 mpAudio 属性（默认 false）：默认仍走画面最稳的 mode 1；打开后走 mode 0 + remux 的完整链路（即付费版行为）。待真机确认后再决定是否把默认改成 true。

不支持的平台改为明确报错（不再静默）+ 补齐平台声明与 PLATFORMS.md

• 组件此前在 App 原生 / nvue / 其它小程序上什么都不渲染也不报错（只有 H5、MP-WEIXIN 两个模板分支）， 在 App 项目里装了只会看到一片空白，容易被当成"插件坏了"。 现在 mounted 里加了 #ifndef H5 / #ifndef MP-WEIXIN 守卫：打 console.error 并 @error（code: 3），把"不支持"这件事明确交出去。
• package.json 的 uni_modules.platforms 由只声明 web/mp-weixin，补齐为显式声明： app(android/ios/harmony)=n、nvue=n、vue2=n / vue3=y、其余小程序一律 n —— 市场页面不再让买家误以为 App 可用。
• 新增 PLATFORMS.md（readme 之前引用了它，但免费版里并不存在 → 断链）： 给出完整平台矩阵、不支持的原因（App 需原生 SDK 集成；其它小程序拿不到逐帧像素）、 以及"想在 App 上用就用 axen-vap-x"。

微信端：动画不是全屏

• 根因：模板 canvas 没有 CSS 尺寸 → 微信端 <canvas> 默认 300×150 → 画布按它渲染。
• 修复：.vap-canvas 补 width/height: 100%；尺寸兜底链改为 「props → 量到的尺寸 → 系统窗口尺寸」（量到 0 或正好 300×150 时直接用 wx.getWindowInfo()）， 即使父链百分比没生效也保证全屏；dpr 上限压到 2（合成器每帧按画布缓冲干活，全屏 + dpr3 ≈3M 像素/帧）。

融合元素点击 @click（H5 + 微信两端统一）

• 由组件统一做命中检测：画布把素材 rgbFrame 区域拉伸铺满显示区 → 点击点反推回素材坐标 → 与「当前帧」的元素矩形 frame=[x,y,w,h] 求交（vap-config.getFrameObjs 取最近关键帧， 与渲染同一套语义）→ 命中取 z 最大者 → 回传其 srcTag（如 [sImg1]）。 只有调用方真的传了该元素（ext / mixData）才会命中，与渲染时「没传就跳过」一致。
• H5：容器 @click + canvas 的 getBoundingClientRect() 换算；微信：canvas @click + boundingClientRect 换算（detail.x/y 是页面坐标）。

文字样式可运行时覆盖

• ext / mixData 的文字项现在可传对象 { txt, color, fontSize, textAlign, fontWeight }， 覆盖 vapc 配置里的样式（语义对齐付费版 mixData）。 此前只支持字符串 → 配置里的字号/颜色改不了，表现为「传了 color/fontSize 没生效」。

H5：播放中途关闭 → 再次起播没有声音（引擎静音降级）

• 根因在引擎（vap.min.js）：play() 里有一段降级 —— 只要 play() 被拒就 静默把视频静音后继续播（动画照播、无声、不回调 error）：

  var t = this.video && this.video.play();
  t && t.then && t.catch(function (t) { e.video && (e.video.muted = !0, e.video.volume = 0, …) })

• 两个触发路径：
  1. precache: true 时引擎先 fetch 整个 mp4、再设 video.src，play() 打在还没有 src 的 video 上 → 必然被拒 → 每次播放都静音（已把 demo 的 precache 撤掉，并把副作用写进 readme）；
  2. 播放中途关闭：引擎 destroy() 只把 <video> 从 DOM 摘掉、不 pause → 那个脱离文档的 video 仍在后台出声、占着媒体会话 → 下次起播无声。
• 组件侧兜底（浏览器只在「起播」时校验自动播放策略，对已在播放的媒体解静音是允许的）：
  • _guardH5Audio() 持续盯住引擎注入的 <video>（它在 document.body 上、异步出现）， 挂 volumechange 监听 → 引擎任何时候把它静音都立刻解掉；
  • destroy() 先 pause() + 静音本实例的 video，再销毁引擎（引用提前抓住 —— DOM 摘掉就 query 不到了）；
  • 点击组件时也尝试解静音（用户手势，给 iOS 这类"每个媒体元素都要手势"的浏览器留一条恢复路径）；
  • mute 属性为 true 时完全不介入；排查日志每实例只打一条。

H5：卡顿与画布尺寸

• 画布尺寸按【容器尺寸 + 素材宽高比】contain（对齐付费版 web 实现）。旧实现直接拿容器尺寸当画布： 容器是全屏覆盖层时画布＝整个视口 —— 竖版素材在桌面窗口里要多渲染约 3.7 倍像素。
• canvas 不再被 CSS 拉伸到满容器（改 flex 居中、保持自身尺寸）：旧行为每帧合成一整屏的缩放纹理， 窗口越大越卡，素材还会变形。
• 容器补 width/height: 100%：旧实现容器没有高度 → 尺寸量到 0 → 走 || 375 兜底算出很小的画布， 且 flex 居中以 0 高为基准导致画布贴顶（去掉 CSS 拉伸后暴露出来的问题）。
• accurate 默认改为 true（引擎据此启用 requestVideoFrameCallback；关掉帧推进变粗会顿）。
• 默认不开 precache（见上面的静音降级）。

微信端：卡帧（时间基准漂移 + 每帧大块分配/拷贝）

• 时间基准漂移（体感最明显）：_tick 旧实现是「渲染完再固定等 1000/fps」， 真实帧周期 = 处理耗时 + 间隔 → 处理 30ms 时 240 帧素材（应 12.0s）实际 19.2s，越播越慢。 改为固定节拍（nextDue 每帧只加 interval）+ 落后 ≥1 个间隔就只消费不渲染 （VAP 每帧是独立 I420，丢渲染不影响后续帧；frameIndex 仍按真实帧号递增 → 融合元素关键帧查找依然正确）。 模拟：渲染 30ms/帧 → 12.0s 零丢帧；60ms → 12.0s 丢 40 帧；100ms → 12.0s 丢 120 帧。时长恒准。
• 每帧的大块分配/拷贝（GC 与 CPU 压力）：整帧 createImageData + data.set（≈6.6MB）、 遮罩与每个融合元素各自再一份、tmpCanvas 尺寸每帧重设（重建画布缓冲）、require() 写在每帧里、 objs.slice().sort() 每帧分配 —— 全部改为按尺寸复用 / 顶层 import / 按关键帧缓存排序结果。

微信端：解码器生命周期修复（2026-09-15）

• playerStop failed 不再刷屏：wx.createVideoDecoder() 的 stop()/remove() 返回 Promise， 失败时不同步抛出（同步 try/catch 抓不到）→ 未处理的 rejection 被小程序当运行时错误上报。 现统一 swallow() 显式 catch，且 stop() 与 remove() 都调用。
• start 失败后不再「越播越坏」：旧实现只回调 onError、不回收解码器实例，连续几次后新建解码器的 start() 会被一律拒绝（播放器彻底失效）。现在失败/异常统一 _release()。
• 停止/重播作废在途回调：新增世代号 _gen，避免播放器被卸载后旧回调继续往已释放的解码器上取帧/挂音频。
• start() 增补 Promise 形态处理：部分基础库版本只返回 Promise 而不回调 fail，此前会静默卡住。

H5 引擎分发与小程序端编译（2026-09-14，新建可运行 demo 时暴露）

• H5 引擎曾不进产物：vap.min.js 原放在 vap/ 下，非 static/ 目录的 js 不会被拷进产物 → dev 能跑、线上 404。现随 static/vap.min.js 分发，加载路径多候探测。
• H5 工厂取法修正：vap.min.js 是 UMD，挂到 window 的是命名空间对象 { canWebGL, default }， 真正工厂是 Vap.default；另：工厂创建即播放，autoplay=false 时改为显式 pause()。
• 小程序端编译不过：common/*.js 原为 CJS，而组件用 ESM import → 5 个文件统一转 ESM， 且 player.js 只在 #ifdef MP-WEIXIN 下 import（H5 不走自研引擎）。
• 新增 uni-vap-demo/ 工程内的可运行 demo（H5 + 微信两端），也是本插件的发布源目录 （HBuilderX 里对 uni_modules/axen-vap 右键「发布插件」）。

平台兼容性

uni-app(3.8.4)

uni-app x

axen-vap VAP 视频动画特效组件（H5 + 微信小程序 · 免费版）

传统 uni-app 项目的 VAP 动效组件：H5（vap-web / WebGL）+ 微信小程序（自研引擎：VideoDecoder 硬解 + Canvas2D，无 WebGL/WASM 依赖）。 uni-app x 项目请用付费五端版 axen-vap-x（App 原生三端 + H5 + 微信）。 为什么只有微信：11 家小程序中仅微信开放逐帧视频解码 API（wx.createVideoDecoder），其余平台 video 为黑盒。完整矩阵见 PLATFORMS.md。

支持平台（免费版只有两头）

Vue2 工程的两个注意点（uni-app 规则，非本插件问题，demo 已规避）

1. main.js 必须与 manifest.json 的 vueVersion 匹配：vue2 用 App.mpType='app' + new Vue({...App})； 若用 Vue3 的 createSSRApp，会报 Cannot set properties of undefined (setting 'query')（TROUBLESHOOTING 附·A）。
2. 事件回调别取页面生命周期名（onReady/onShow/onLoad/onError…），vue2 编译器会把它们从 methods 里摘走当生命周期用；也别与 data 键同名。统一加前缀（如 @ready="vapReady"）即可。

不支持的平台不会静默：组件会打 console.error 并 @error（code: 3）； uni_modules.platforms 里也把 app / nvue / 其它小程序显式标为不支持。 原因与完整矩阵见 PLATFORMS.md。

使用（easycom）

<template>
    <view style="width:750rpx;height:340rpx">
        <axen-vap
            :src="src"
            :config="config"
            :ext="ext"
            :loop="false"
            :autoplay="true"
            @started="onStarted"
            @ended=""
            @error="onError"
        />
    </view>
</template>

<script>
    export default {
        data() {
            return {
                src: '/static/demo.mp4',
                config: require('@/static/demo.json'),  // 或 JSON 字符串
                ext: {
                    imgUser: '/static/user.png',   // 融合头像（键=srcTag去方括号）
                    textUser: '星河Momo'           // 融合昵称
                }
            }
        }
    }
</script>

引擎分发（重要）

• H5 引擎 vap.min.js 必须随 static/ 目录分发（构建后落在 uni_modules/axen-vap/static/vap.min.js）： 非 static/ 目录下的 js 不会进产物，写成其它路径在 dev 能跑、线上必然 404。
• 小程序端为自研引擎（common/*.js，ESM 模块），无需额外文件。

运行示例

本插件所在工程 uni-vap-demo/ 就是可运行 demo（H5 + 微信小程序）：

# HBuilderX 打开 vap-plugin/axen-vap，然后：
#   运行 → 运行到浏览器 → Chrome
#   运行 → 运行到小程序模拟器 → 微信开发者工具（勾选「不校验合法域名」）

属性

事件

@ready @mounted（H5 实例）@started @frame（{index}）@ended/@finish @error @destroy @click（{tag}）

@click（点击融合元素）H5 与微信两端都支持：命中检测按「当前帧的元素矩形」在组件内完成 （画布把素材 rgbFrame 拉伸铺满显示区，点击点反推回素材坐标后与矩形求交，命中取最上层， 回传该元素的 srcTag，如 [sImg1]）。只有调用方真的传了该元素（ext / mixData）才会命中， 与渲染时「没传就跳过」的规则一致。被覆盖层挡住的场景请参照 demo：点击覆盖层关闭、点元素上报 tag。

声音（两端都支持）

• 模式不分流：所有素材统一 mode 0 + MediaAudioPlayer（付费版 axen-vap-x 的做法）。 「探测到无音轨就分流 mode 1 + fps 门控」是被否决的方案 —— 无音轨素材在两种模式下都会丢 流尾 1~2 帧（真机实测 demo.mp4 稳定 78/80），而 mode 1 还额外失去音频时钟的节奏精度， 分流没有收益、只会制造两端差异。
• 组件仍会扫一遍 mp4 的 box（moov/trak/mdia/hdlr 的 handler_type 是否为 soun， 见 common/mp4-audio.js）—— 仅用于诊断日志，不作为模式选择的依据；同一路径只探测一次。
• 无音轨素材（如官方 demo.mp4）：mpAudio=true 时会在播放前原地 remux 出一条静音 AAC 轨， 产物为 原路径 + ".sil.mp4" 伴生文件（按路径缓存，重播直接用伴生文件），之后与有音轨素材 完全同链路 —— 这样 mode 0 才有音频时钟把流尾帧完整 flush 出来（否则 demo.mp4 会稳定少 1~2 帧）。 实现见 common/mp4-remux.js：纯字节数学无依赖，视频样本一个字节都不动， remux 失败即放弃并回退 mode 1。
• 兜底：若 mode 0 在该设备/素材上完全取不到帧，900ms 后回退 mode 1（画面正常、无声音）—— 这是"保命"路径，不是常规路径。
• 取帧节拍（照付费版 axen-vap-x 的参考实现）：mode 0 固定 8ms 轮询 + 按 pkPts 去重 （pts 未变即不是新帧，不渲染），帧节奏由音频时钟决定，绝不丢帧；mode 1 解码尽快、 按 vapc fps 定时上屏。收尾以 vapc 的总帧数（info.f）为主判据。
• @finish 的 totalFrameCount 上报的是素材总帧数（info.f）——注意组件逐帧回调的 index 是 0 基序号（第 1 帧 index=0），自行展示时需 +1，否则 240 帧的素材会显示成 239。
• common/mp4-remux.js 已完成字节级验收：ffprobe 全量解码零错误、视频流 framemd5 逐帧一致、 vapc box 原样保留；覆盖 faststart 与非 faststart 两种布局、80 帧与 240 帧两种素材。

日志

组件默认静默（与付费版 axen-vap-x 一致 —— 它的发布产物里 vapLog 就是空实现）。 排查问题时两种打开方式，都不用改插件源码：

• 页面里设置 uni.$vapDebug = true（任意位置，设置之后开始的播放即生效）；
• 或调用统一出口 VapLog.setDebug(true)（common/vap-log.js 的默认导出）。

warn / error 始终输出（真正的问题不该被静默）： 素材 remux 失败、音频挂载失败、融合图片加载失败、播放提前结束等都会照常提示。

本仓库的 demo 工程默认打开了详细日志（pages/index/index.vue 顶部一行），便于对照排查； 买家的正式工程不需要那行。

⚠️ 事件回调别取页面生命周期名：@ready="onReady" 这类命名在 uni-app vue2 工程里会踩坑 —— vue2 编译器把 onReady/onShow/onLoad/onError 等名字从 methods 里摘走当页面生命周期用， 于是组件 emit 时页面找不到该方法，报 Page "pages/xxx" does not have a method "onReady"。 统一加前缀（如 @ready="vapReady"）即可绕开。

方法（ref）

play() pause() stop() setTime(s)（H5）on(type,cb)（H5）destroy()

平台说明

微信端注意事项

• 主包 2MB 限制：mp4 素材建议放服务器，运行时 uni.downloadFile。
• srcTag 与融合键对应：[imgUser] → ext 的 imgUser。

许可证

• H5 内核：腾讯 VAP web 版（MIT）— LICENSE-tencent-vap.txt
• 微信端引擎：自研（算法蓝本源自官方 MIT 源码的 Canvas2D 翻译）