更新记录

1.0.1（2026-08-11）

• 首发 uni-app x FFmpeg UTS 插件
• 支持 execFFmpeg / execFFprobe / 进度与日志
• 内置 compressVideo / snapshot / trim / extractAudio 等 recipe
• Android 本地 AAR + Application ClassLoader 反射桥接

平台兼容性

uni-app

uni-app x(4.27)

x-ffmpeg

基于 FFmpegKit full（LGPL） 的 uni-app x UTS 音视频插件。

• Android：dev.ffmpegkit-maintained:ffmpeg-kit-full:8.1.7（官方 com.arthenica 已下架）
• iOS：CocoaPods ffmpeg-kit-ios-full 6.0
• 不含 x264/x265（避免 GPL）；压缩默认使用 h264_mediacodec / h264_videotoolbox

安装

将本目录放到工程 uni_modules/x-ffmpeg/。

1. Android AAR 已放在 utssdk/app-android/libs/ffmpeg-kit-full-8.1.7.aar（勿删）
2. config.json 声明 com.arthenica:smart-exception-java:0.2.1（不要再在 libs/ 放同名 jar，会 Duplicate class）
3. 必须制作自定义调试基座（本地 uni_modules UTS 插件没有「勾选插件」这一步，会自动打进基座）
4. 用自定义调试基座运行；标准基座会报 NoClassDefFoundError: FFmpegKitConfig
5. 若 ffmpeg=(empty) / jobId=-1：看 diagnose 是否缺 com.arthenica.smartexception —— 改依赖后需重制自定义基座

自定义基座怎么做（HBuilderX）— 必做且易错

工程里的 AAR 已经放好，本地 uni_modules 没有勾选框。

已确认的根因（真机反查）

1. 自定义基座 APK 已经包含 FFmpegKitConfig 与 libffmpegkit.so（与 unpackage/debug/android_debug.apk MD5 一致）
2. 差量调试会把插件加载为隔离 DexClassLoader（Android/data/.../www/uni_modules/x-ffmpeg/.../classes.dex），父加载器不是 App
3. 因此插件里直接 import com.arthenica.ffmpegkit.* / Class.forName 会 NoClassDefFoundError，即使基座 dex 里已有该类

当前修复

Android 实现改为经 Application ClassLoader 反射调用 FFmpegKit（FFmpegReflectBridge.kt）。
一般只需重新运行到自定义基座（差量编译），不必再打基座；若改了 config.json 依赖声明，再重制一次基座更稳妥。

操作

1. HBuilderX：运行到自定义调试基座
2. 打开 FFmpeg Demo，看 nativeReady=yes 且 ffmpeg 版本非空
3. 若仍为 NO，点刷新看 diagnose 日志（logcat tag：x-ffmpeg）

API

import {
  getVersion, getWorkDir, resolvePath, setLogEnabled,
  execFFmpeg, execFFprobe, cancel, isRunning, dispose,
  compressVideo, extractAudio, snapshot, trimVideo, remux, replaceAudio,
  probeMediaInfoJson, generateTestVideo
} from '@/uni_modules/x-ffmpeg'

核心

回调：onLog / onProgress / success / fail / complete（持续回调需 HBuilderX 4.27+ @UTSJS.keepAlive）。

Recipes

• compressVideo — 硬件 H.264 + AAC
• extractAudio / snapshot / trimVideo / remux / replaceAudio
• probeMediaInfoJson — JSON 媒体信息
• generateTestVideo — lavfi testsrc + sine（Demo 零素材）

示例

const out = getWorkDir() + '/demo.mp4'
generateTestVideo({
  output: out,
  durationSec: 2,
  success: (res) => {
    probeMediaInfoJson({
      input: out,
      success: (p) => { console.log(p.output) }
    })
  }
})

错误码

• 9020001 执行失败
• 9020002 已取消
• 9020003 参数无效
• 9020004 平台不支持
• 9020005 job 不存在

许可

插件代码可按项目约定分发；底层 FFmpegKit full 为 LGPL-3.0。详见 THIRD_PARTY.md。