更新记录

1.0.3（2026-08-06）

• 清理插件发布目录中的外部方案调研和内部审计资料，客户文档仅保留接入说明、真实能力和平台边界。
• 完善发布检查，禁止内部验收报告、外部产品对比信息和误导性平台支持声明进入插件市场包。
• 补充横版市场封面素材，并保持 Android 已支持、iOS/HarmonyOS 尚未开放的真实宣传口径。

1.0.2（2026-08-06）

• 修复 Android FFmpeg 在部分 ABI 转译模拟器中出现 MediaCodec 丢弃全部视频缓冲、命令仍以 exitCode=0 结束时误回调成功的问题；显式视频输出现在必须反查到可读视频轨，否则返回明确失败。
• 修正 Android H264/H265 能力判断：当内置 FFmpeg 二进制 ABI 与系统首选 ABI 不一致时，不再把仅能创建 MediaCodec 对象误报为可用编码能力，并在能力说明中返回 ABI 兼容状态。
• 增强 Android FFmpeg manifest 读取：系统首选 ABI 没有对应资源时会继续读取实际随插件发布的 ABI manifest，避免诊断字段为空。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-video-editor

lizhao-video-editor 是面向 uni-app / uni-app x 的视频编辑 UTS 插件，目标能力包括视频裁剪 UI、无界面压缩、FFmpeg 命令、FFprobe 命令、视频宽高/时长、视频取帧、取消任务和缓存清理。

插件已提供稳定的 UTS 接口、错误码、平台入口、示例页和发布守卫。Android 已先打通“本地/授权视频 -> 读取宽高时长 -> 真实 FFprobe -> 提取帧图到插件缓存 -> 原生裁剪 UI 预览/时间轴/比例确认 -> 无 UI 时间裁剪输出 MP4 -> FFmpeg 画面区域裁剪 -> compressVideo codec=copy 全量/时间段兼容输出 -> H264/H265 硬编码压缩预检 -> FFmpeg/FFprobe 原生命令执行层 -> FFmpeg H264/H265 真实压缩 -> FFprobe 反查压缩输出 -> FFmpeg copy/trim 命令 -> FFmpeg 单帧/序列帧取图命令 -> 取消取帧/元数据/探测/裁剪/压缩兼容输出/原生命令任务 -> 按裁剪/压缩/取帧/FFmpeg 类型清理缓存”的真实闭环；Android 会从应用 nativeLibraryDir 解析插件私有的 liblizhao_video_editor_ffmpeg.so 和 liblizhao_video_editor_ffprobe.so，存在且可执行时运行真实命令，不存在时公共 FFmpeg/FFprobe 命令直接 fail，避免伪造成完整命令成功；接入或替换原生二进制、裁剪 UI 或平台 UTS 原生逻辑后需要重新打对应平台自定义基座。

功能特色

• 双层 API：保留 crop / compress / ffmpegCommand / ffprobeCommand 等迁移友好接口，同时提供 openVideoCropper / compressVideo / executeFfmpeg / executeFfprobe 等类型化接口。
• Android 真实闭环：getVideoMetadata / executeFfprobe / extractVideoFrames / openVideoCropper / compressVideo(codec=copy 全量/时间段) / compressVideo(有 FFmpeg 二进制时 h264/h265 真实压缩，缺失时预检失败) / executeFfmpeg / cancelVideoTask / clearVideoEditorCache 已可处理本地路径、_doc、static、file://、路径空格和 content:// 授权视频；示例页提供 uni.chooseVideo({ sourceType: ['album'] }) 相册选择入口，会把系统返回的 tempFilePath/content:// 授权路径直接写入 sampleVideo 并调用 getVideoMetadata，便于客户验证 Android 10/11+ 分区存储路径；裁剪、压缩、FFmpeg 输出和单帧取图支持自定义 _doc / file:// / 绝对路径 / content:// 输出，未传输出路径时默认写入插件分类型缓存目录，嵌套父目录会自动创建，同名文件按覆盖语义重写，Android 10/11+ 公共绝对路径会通过 MediaStore 写入公共目录并在结果诊断里带回 contentUri=content://media/... 证据，普通自动验收还会用该 contentUri 再调用 getVideoMetadata 反查宽高和时长；普通自动验收会对 cropWidth/cropHeight 区域裁剪输出追加 FFprobe 反查宽高，确认 160x90 产物真实生成，并对 H264/H265/AAC 压缩输出追加 FFprobe 反查压缩输出，确认输出流包含 h264 / hevc / aac 等目标编码名；缓存已支持 crop / compress / frame / ffmpeg / all 分类型清理，清理结果会返回 deleted= 与 bytes= 统计，便于定位缓存是否实际被扫描和删除。
• 统一 success / fail / complete / progress 回调结构，Android 元数据、取帧、无 UI 时间裁剪、压缩 copy 兼容输出、真实 FFmpeg/FFprobe 原生命令已支持 taskId 取消和日志关联；公共 executeFfmpeg/executeFfprobe 缺少二进制时走 fail/complete，不再回退到兼容子集伪造成功。
• 统一错误码段 9070001 起，覆盖平台不支持、路径不可读、FFmpeg 缺失、编码不支持、任务取消、缓存失败和原生 UI 不可用。
• 当前能力矩阵会真实声明 Android metadata=true / frame=true / cancel=true / cropUi=true，h264/h265 来自设备 MediaCodec.createEncoderByType('video/avc' / 'video/hevc') 动态预检；ffmpeg 与 ffprobe 不再写死，而是分别由 ffmpegReady / ffprobeReady 检测应用 nativeLibraryDir 下两个插件私有原生文件是否已随自定义基座安装且可执行；compress 跟随 ffmpegReady，二进制存在时 compressVideo/compress 会生成 h264_mediacodec / hevc_mediacodec FFmpeg 命令并支持 width / height / bitrate / fps / audioCodec；androidRuntimeBuild 用于真机 smoke 识别旧 UTS 自定义基座；openVideoCropper/crop 默认打开 Android 原生裁剪 UI，提供视频预览、开始/结束时间轴、自由/1:1/4:3/16:9 比例选择和确认/取消回调，自动验收或无界面业务可传 showUi:false 直接执行裁剪。
• Android 默认包仅在 app-android/libs/<abi>/ 放置私有命名的 liblizhao_video_editor_ffmpeg.so 与 liblizhao_video_editor_ffprobe.so，安装时通过 android:extractNativeLibs="true" 解压到应用 nativeLibraryDir 后直接执行，避免 Android 10+ 从 cache 执行 ELF 被 SELinux 拒绝；插件不注册共享包名或通用 libffmpeg.so，LGPL 默认包不含 GPL/nonfree 外部编解码扩展，如后续提供 GPL 或 vendor SDK 扩展包，应独立发包并重新打自定义基座。

接入方式选择

Android 原生包与冲突边界

最小可运行示例

import { getVideoEditorCapabilities, getVideoMetadata, executeFfprobe, extractVideoFrames } from '@/uni_modules/lizhao-video-editor'

// 先读取真实能力矩阵；Android 会按当前自定义基座是否包含 FFmpeg/FFprobe 二进制返回 ffmpeg/ffprobe。
const capabilities = getVideoEditorCapabilities()
console.log('视频编辑能力矩阵', capabilities)

// Android 首个真实闭环：读取本地视频宽高和时长。
getVideoMetadata({
  src: 'static/video/flower.mp4',
  progress(event) {
    console.log('视频信息进度', event.progress, event.message)
  },
  success(res) {
    console.log('视频宽高时长', res.width, res.height, res.duration)
  },
  fail(err) {
    console.log('视频信息失败', err.errCode, err.errMsg)
  }
})

// Android FFprobe 原生命令：需要自定义基座内置 FFprobe 二进制，缺失时返回 9070006。
executeFfprobe({
  command: ['-v', 'quiet', '-print_format', 'json', '-show_format', '-show_streams', 'static/video/flower.mp4'],
  success(res) {
    console.log('ffprobe stdout', res.stdout)
  },
  fail(err) {
    console.error('探测失败', err)
  }
})

// Android 首个真实闭环：提取 0ms 帧图并写入插件缓存目录。
extractVideoFrames({
  src: 'static/video/flower.mp4',
  timesMs: [0],
  format: 'jpg',
  outputType: 'file',
  success(res) {
    console.log('帧图路径', res.frames[0].imagePath)
  }
})

常见增强示例

import { openVideoCropper, executeFfmpeg, compressVideo, clearVideoEditorCache } from '@/uni_modules/lizhao-video-editor'

// Android 默认打开原生裁剪 UI：预览视频，调整开始/结束时间和比例，点击确认后输出 MP4。
openVideoCropper({
  src: 'static/video/flower.mp4',
  outputPath: '_doc/demo-crop.mp4',
  startTimeMs: 0,
  endTimeMs: 1500,
  aspectRatio: '16:9',
  codec: 'h264',
  hardware: 'auto',
  success(res) {
    console.log('裁剪输出路径', res.outputPath)
  },
  fail(err) {
    console.log('裁剪失败', err.errCode, err.errMsg)
  }
})

// Android 无界面裁剪：适合自动验收或业务自定义 UI，直接按参数输出。
openVideoCropper({
  src: 'static/video/flower.mp4',
  outputPath: '_doc/demo-crop-headless.mp4',
  showUi: false,
  startTimeMs: 0,
  endTimeMs: 1500,
  aspectRatio: '16:9',
  success(res) {
    console.log('无界面裁剪输出路径', res.outputPath)
  }
})

// Android FFmpeg 原生命令：需要自定义基座内置 FFmpeg 二进制，缺失时返回 9070005。
executeFfmpeg({
  command: ['-y', '-ss', '0', '-t', '1.5', '-i', 'static/video/flower.mp4', '-map', '0:v:0', '-map', '0:a?', '-c:v', 'copy', '-c:a', 'copy', '-movflags', '+faststart', '_doc/demo-ffmpeg-copy.mp4'],
  progress(event) {
    console.log('FFmpeg 原生命令进度', event.progress, event.message)
  },
  success(res) {
    console.log('FFmpeg 原生命令输出路径', res.outputPath)
  },
  fail(err) {
    console.log('FFmpeg 原生命令失败', err.errCode, err.errMsg)
  }
})

// Android FFmpeg 单帧取图：通过真实 FFmpeg 二进制输出图片。
executeFfmpeg({
  command: ['-y', '-ss', '0.6', '-i', 'static/video/flower.mp4', '-frames:v', '1', '-q:v', '2', '_doc/demo-ffmpeg-frame.jpg'],
  progress(event) {
    console.log('FFmpeg 取帧进度', event.progress, event.message)
  },
  success(res) {
    console.log('FFmpeg 取帧输出路径', res.outputPath, res.stdout)
  },
  fail(err) {
    console.log('FFmpeg 取帧命令失败', err.errCode, err.errMsg)
  }
})

// Android FFmpeg 序列帧命令：通过真实 FFmpeg 二进制输出序列帧。
executeFfmpeg({
  command: ['-y', '-ss', '0', '-i', 'static/video/flower.mp4', '-vf', 'fps=1', '-q:v', '3', '_doc/demo-ffmpeg-seq_d.jpg'],
  progress(event) {
    console.log('FFmpeg 序列帧进度', event.progress, event.message)
  },
  success(res) {
    console.log('FFmpeg 序列帧数量', res.frames.length, res.stdout)
  },
  fail(err) {
    console.log('FFmpeg 序列帧命令失败', err.errCode, err.errMsg)
  }
})

// Android compressVideo：未内置 FFmpeg 时 codec=copy 走系统兼容输出；内置 FFmpeg 时可执行真实压缩。
compressVideo({
  src: 'static/video/flower.mp4',
  outputPath: '_doc/demo-compress-trim-copy.mp4',
  startTimeMs: 300,
  endTimeMs: 1800,
  codec: 'copy',
  success(res) {
    console.log('压缩时间段兼容输出路径', res.outputPath, res.duration, res.stdout)
  },
  fail(err) {
    console.log('压缩兼容输出失败', err.errCode, err.errMsg)
  }
})

// Android H264 压缩：新自定义基座内置 FFmpeg 时会真实压缩；旧基座缺失二进制时返回 9070009 预检失败。
compressVideo({
  src: 'static/video/flower.mp4',
  outputPath: '_doc/demo-compress-h264.mp4',
  width: 720,
  bitrate: 1200000,
  fps: 30,
  codec: 'h264',
  audioCodec: 'aac',
  hardware: 'auto',
  progress(event) {
    console.log('H264 压缩进度', event.progress, event.message)
  },
  fail(err) {
    console.log('硬编码预检诊断', err.errCode, err.errMsg)
  }
})

// 缓存清理按类型执行，Android 已映射到裁剪/压缩/取帧/FFmpeg 缓存目录。
clearVideoEditorCache({
  // 可选 crop / compress / frame / ffmpeg / all；兼容 API clearCropVideoCache 等会自动映射到对应目录。
  // 传入其它字符串会返回 9070003，并同时触发 fail / complete，避免把错误类型静默当成清理成功。
  type: 'all',
  complete(res) {
    console.log('缓存清理完成', res)
  }
})

完整示例源码路径

支持平台

API 列表

openVideoCropper(options)

说明 打开视频裁剪能力。Android 默认打开原生裁剪 UI，支持视频预览、开始/结束时间轴、自由/1:1/4:3/16:9 比例选择、确认裁剪和取消回调；确认后复用真实裁剪命令，未传画面区域参数时使用系统 MediaExtractor + MediaMuxer 按关键帧附近复制视频/音频轨道并输出 MP4，不重编码、不改变码率或分辨率；传入 cropWidth / cropHeight / aspectRatio 或在 UI 中选择固定比例时，会优先使用 FFmpeg 二进制生成 crop= 滤镜做居中区域裁剪，可叠加 startTimeMs / endTimeMs / bitrate / fps / codec，缺少 FFmpeg 二进制时返回 9070005，不伪造成只裁时间成功；传 showUi:false 可绕过原生 UI 直接执行裁剪。

支持平台 Android。iOS / HarmonyOS 当前仅保留类型入口，调用会明确返回平台不支持。

参数

返回值

compressVideo(options)

说明 执行无界面压缩能力。Android codec: 'copy' 会使用系统 MediaExtractor + MediaMuxer 复制原视频/音频轨道并输出 MP4/M4V，可通过 startTimeMs / endTimeMs 输出指定时间段，不改变码率、分辨率或帧率；未传 outputPath 时写入 compress 缓存目录，传入嵌套 _doc / file:// / 绝对路径 时会创建父目录并覆盖同名文件，传入单目标 content:// 或公共目录绝对路径时会先写插件私有临时文件，再回写客户目标；当传入 width / height / bitrate / fps 或 codec: 'auto' / 'h264' / 'h265' 时，如果当前自定义基座的 nativeLibraryDir 包含插件私有 FFmpeg 文件，会生成 FFmpeg 命令执行真实压缩，默认优先 h264_mediacodec / hevc_mediacodec，支持 -b:v、-vf scale/fps、audioCodec: 'copy' / 'aac' / 'none'；如果未内置二进制，则继续执行 H264/H265 硬编码压缩预检并返回 9070009 诊断，不伪造压缩成功。

支持平台 Android。iOS / HarmonyOS 当前仅保留类型入口，调用会明确返回平台不支持。

参数

返回值

executeFfmpeg(options)

说明 执行 FFmpeg 命令。Android 会解析应用 nativeLibraryDir 下的 liblizhao_video_editor_ffmpeg.so 并通过原生进程直接执行，不会复制到 cache；命令 stdout 会收集到返回值，time=、out_time=、out_time_us=、out_time_ms= 和 progress=end 会解析为真实进度，调用 cancelVideoTask 会真实销毁进程并返回 9070012。如果当前自定义基座未内置 FFmpeg 二进制或文件不可执行，会返回 9070005 并触发 fail/complete，不会回退 copy/trim、取帧或其它系统兼容子集伪造成功。

支持平台 Android。iOS / HarmonyOS 当前仅保留类型入口，调用会明确返回平台不支持。

参数

返回值

错误码

自定义基座说明

当前版本新增了 utssdk/app-android/index.uts、utssdk/app-ios/index.uts、utssdk/app-harmony/index.uts 和 Android AndroidManifest.xml。Android 视频信息读取、真实 FFprobe、取帧、原生裁剪 UI、无 UI 裁剪 showUi:false、FFmpeg 画面区域裁剪、compressVideo codec=copy 兼容输出、content:// 输入/输出回写、MediaStore 写入公共目录、FFmpeg 二进制真实压缩、H264/H265 硬编码压缩预检、完整 FFmpeg 命令、真实 FFprobe 原生命令、任务取消和分类型缓存清理属于平台 UTS 原生逻辑，真机要使用该闭环需要重新运行 Android 原生联编或重新打 Android 自定义基座；后续只要接入新的 FFmpeg AAR/so、iOS xcframework、Harmony 原生库或继续修改平台 UTS 原生逻辑，也都必须重新打 Android/iOS/Harmony 自定义基座；仅更新 wgt/appResource 不能替换旧基座中的原生能力。

Android 自定义基座安装到真机后，可以在项目根目录执行下面的脚本做一键回归。脚本不会执行 HBuilderX launch，只会通过 ADB 打开示例页并读取 logcat 标记，当前覆盖能力矩阵、视频信息、取帧、真实 FFprobe、真实 FFmpeg copy/trim 与进度回调、路径空格 FFmpeg 输出与 FFprobe 输入、直接 executeFfmpeg H264 转码命令与 FFprobe 反查、真实 FFmpeg 取消请求、9070012 取消回调、取消后同一 taskId 清理验证、真实 FFmpeg 单帧、真实 FFmpeg 序列帧、原生裁剪 UI 打开取消与自动确认输出、无 UI 裁剪 showUi:false、compress copy 全量/时间段、真实 H264 压缩、H264 输出 FFprobe 反查、H265 可用时真实压缩并反查 hevc 输出或不可用时明确 marker、AAC 音频转码并反查 aac 输出、输出路径父目录创建、同名覆盖、不支持扩展名 fail/complete 回调、公共目录 MediaStore 输出及 content://media Uri 证据、该 content://media 产物的 getVideoMetadata 反查、FFmpeg 失败 fail 回调、缓存清理和每个清理结果的 deleted=/bytes= 统计、非法缓存类型 9070003 的 fail/complete 边界：

发布前推荐优先执行最终编排脚本。它会先运行本地发布守卫、生成 Kotlin P0/P1 门禁和源码私有原生文件门禁，再按顺序运行已安装自定义基座原生文件检查、普通 smoke、stress、USB evidence 和 release readiness；总闸通过后才输出 PASS Android video editor final acceptance orchestration。如果设备未授权或某个步骤失败，脚本也会写入 final-acceptance-summary.json，用 status / completedSteps / failedStep / failureLogPath 标明已完成的前置门禁和阻塞步骤：

powershell -ExecutionPolicy Bypass -File scripts/run-lizhao-video-editor-android-final-acceptance.ps1 -DeviceId 9fc5a9b8

powershell -ExecutionPolicy Bypass -File scripts/acceptance-lizhao-video-editor-android.ps1

需要额外验证大文件稳定性时，再执行压力脚本。它会先抽查已安装 Android 自定义基座的 base.apk 是否包含 lib/arm64-v8a/liblizhao_video_editor_ffmpeg.so 和 liblizhao_video_editor_ffprobe.so，并确认 manifest 元数据仍在插件私有 assets 路径。如果任一私有原生文件缺失，会直接提示重新打 Android 自定义基座，因为 wgt/appResource 不能补进这些原生文件。预检通过后，脚本会通过 autoVideoEditorStress=1 单独进入长视频、4K、大码率和音视频同步场景；其中长视频 copy 成功后必须输出 AUTO_VIDEO_EDITOR_STRESS_LONG_PROBE_OK，4K、高码率和音视频同步场景会输出 AUTO_VIDEO_EDITOR_STRESS_4K_PROBE_CHECK_OK、AUTO_VIDEO_EDITOR_STRESS_HIGH_BITRATE_PROBE_CHECK_OK、AUTO_VIDEO_EDITOR_STRESS_AV_SYNC_PROBE_CHECK_OK，用于确认成功产物已通过 FFprobe 反查或不支持路径已进入 fail 回调。该脚本独立于普通 smoke，避免拖慢日常回归：

powershell -ExecutionPolicy Bypass -File scripts/acceptance-lizhao-video-editor-android-stress.ps1

如果只想先确认插件源码、新基座 APK 或当前已安装包是否带上 FFmpeg/FFprobe 私有原生文件，可以单独运行基座检查脚本。它不会打开页面，只检查两个 lib/arm64-v8a/liblizhao_video_editor_*.so、assets manifest 的 16KB / LGPL / no GPL/nonfree 标记、源码 manifest 中的 SHA256，以及是否出现通用 FFmpeg 原生库名或共享包名：

powershell -ExecutionPolicy Bypass -File scripts/check-lizhao-video-editor-android-base-assets.ps1 -ResourceRoot E:\test\lizhao-plugin\unpackage\resources
powershell -ExecutionPolicy Bypass -File scripts/check-lizhao-video-editor-android-base-assets.ps1 -ApkPath <新基座.apk>
powershell -ExecutionPolicy Bypass -File scripts/check-lizhao-video-editor-android-base-assets.ps1 -DeviceId 9fc5a9b8

注意事项

• 当前首版已内置 Android arm64-v8a FFmpeg/FFprobe 二进制并通过 16KB 0x4000 对齐校验，支持 Android 原生裁剪 UI、无 UI 裁剪、视频信息读取、真实 FFprobe、取帧、content:// 输入/输出回写、MediaStore 写入公共目录、画面区域裁剪、compressVideo codec=copy 全量/时间段兼容输出、FFmpeg 真实压缩、H264/H265 硬编码压缩预检、完整 FFmpeg 命令、真实 FFprobe 原生命令、任务取消和分类型缓存清理闭环；其它 ABI、iOS xcframework 和 Harmony 原生库仍待后续接入。
• Android 默认包只允许两个插件私有 .so 执行文件；不要把第三方 FFmpeg AAR、通用 libffmpeg.so、libav*、x264/x265 或共享包名直接放进默认包。基座检查脚本会扫描最终 APK，并在缺少私有文件或发现冲突型 FFmpeg/AAR/JAR/SO 时失败。需要接入其它 ABI、GPL 编解码、厂商硬编 SDK 或额外 .so 扩展时，应使用独立扩展包名和 16KB page-size 兼容构建，并重新打 Android 自定义基座。
• 所有暂不可用能力都会触发 fail 和 complete，不会伪造成功。
• 客户侧应先调用 getVideoEditorCapabilities() 判断当前基座是否包含原生能力。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。