更新记录

1.2.1（2026-07-12）

更新文档

1.2.0（2026-07-12）

• 首次发布 Android/iOS 音视频裁剪、压缩与 FFmpeg/FFprobe 命令能力。

平台兼容性

uni-app(4.85)

uni-app x(4.85)

hl-ffmpeg-video

hl-ffmpeg-video 是一个运行在 Android 和 iOS 手机上的本地音视频处理插件。它可以裁剪、压缩、取帧、提取音频、拼接视频、生成 GIF，也可以直接执行 FFmpeg 和 FFprobe 命令。

所有处理都在设备本地完成。插件不会上传视频，也不会收集用户数据。

先了解这三件事

1. 插件只处理本地视频文件，不能直接传网络 URL。
2. 必须使用包含本插件的自定义基座或云端打包后的 App。标准基座不包含 FFmpeg 依赖。
3. 所有处理结果都在回调里返回。成功时读取路径字段，例如 result.mp4、result.image 或 result.audio。

支持的平台

第一次使用

1. 导入插件

插件放在项目的 uni_modules 目录时，不需要额外安装。

import { getVideoEditor } from '@/uni_modules/hl-ffmpeg-video'

const editor = getVideoEditor()

2. 选择视频并保存本地路径

uni.chooseVideo 返回的 tempFilePath 可以直接传给插件。

import { ref } from 'vue'

const videoPath = ref('')

function chooseVideo() {
  uni.chooseVideo({
    sourceType: ['album', 'camera'],
    compressed: false,
    success: (file) => {
      videoPath.value = file.tempFilePath
    }
  })
}

如果你使用 _doc、_www 一类目录，请先转换为绝对路径：

const videoPath = plus.io.convertLocalFileSystemURL('_doc/source.mp4')

3. 用最小示例验证插件

先读取视频信息。看到 code: 0 即说明视频路径和原生依赖可用。

editor.getVideoInfo({ url: videoPath.value }, (result) => {
  if (result.code === 0) {
    console.log('视频尺寸：', result.width, result.height)
    console.log('视频时长：', result.duration, '秒')
    return
  }
  console.error('读取失败：', result.msg)
})

最常用：比例裁剪

下面的示例会打开原生裁剪页面。用户可以拖动裁剪框和时间滑块，点击“完成”后生成一条 9:16、720p 的视频。

editor.openCrop({
  url: videoPath.value,
  ratio: '9/16',
  resolution: '720p',
  mode: 'scale',
  quality: 'hd',
  mintime: 2000,
  maxtime: 30,
  codecs: 1,
  fps: 30,
  gop: 60
}, (result) => {
  if (result.code === 1 && result.progress != null) {
    console.log('处理进度：', result.progress)
    return
  }
  if (result.code === 0) {
    console.log('视频路径：', result.mp4)
    console.log('封面路径：', result.image)
    return
  }
  console.error(result.msg, result.detail || '')
})

mode 的含义：

全部能力一览

常用调用示例

直接压缩到 720p

editor.videoToZip({
  url: videoPath.value,
  resolutionMax: '720p',
  quality: 'hd',
  codecs: 1,
  startTime: 0,
  endTime: 10_000
}, (result) => {
  if (result.code === 0) console.log(result.mp4)
})

获取首帧和第 5 秒画面

editor.getVideoFirstFrame({ url: videoPath.value, width: 720 }, (result) => {
  if (result.code === 0) console.log('首帧：', result.image)
})

editor.getVideoFrame({ url: videoPath.value, timeMs: 5000, width: 720 }, (result) => {
  if (result.code === 0) console.log('第 5 秒画面：', result.image)
})

生成 6 张缩略图

editor.generateThumbnails({
  url: videoPath.value,
  startTime: 0,
  intervalMs: 2000,
  count: 6,
  width: 320
}, (result) => {
  if (result.code === 0) console.log(result.images)
})

提取音频、生成无声视频、替换音轨

editor.extractAudio({ url: videoPath.value, format: 'm4a', bitrate: '192k' }, (audioResult) => {
  if (audioResult.code !== 0) return

  editor.mergeAudioVideo({
    url: videoPath.value,
    audioUrl: audioResult.audio
  }, (mergeResult) => {
    if (mergeResult.code === 0) console.log('新视频：', mergeResult.mp4)
  })
})

editor.removeAudio({ url: videoPath.value }, (result) => {
  if (result.code === 0) console.log('无声视频：', result.mp4)
})

拼接视频和生成 GIF

editor.concatVideos({
  urls: [firstVideoPath, secondVideoPath]
}, (result) => {
  if (result.code === 0) console.log('拼接结果：', result.mp4)
})

editor.videoToGif({
  url: videoPath.value,
  startTime: 1000,
  durationMs: 3000,
  width: 480,
  fps: 12
}, (result) => {
  if (result.code === 0) console.log('GIF：', result.gif)
})

执行 FFmpeg 和 FFprobe

命令可以带 ffmpeg / ffprobe 前缀，也可以只传参数。路径中有空格时请用单引号包住。

const input = videoPath.value
const cover = plus.io.convertLocalFileSystemURL('_doc/cover.jpg')

editor.FFmpeg(
  { command: `ffmpeg -y -ss 1 -i '${input}' -frames:v 1 '${cover}'` },
  (log) => console.log(log),
  (result) => console.log(result)
)

editor.FFprobe(
  { command: `ffprobe -i '${input}' -show_streams -show_format` },
  (log) => console.log(log)
)

参数说明

所有生成文件的方法

裁剪、压缩和导出参数

crf 是软件编码质量参数。移动端首次接入建议先使用 quality，不必设置 crf。如同时设置 bitrate 和 crf，bitrate 优先。

裁剪界面额外参数

回调结果和进度

每个回调至少包含 code 和 msg。

失败时建议同时输出 result.msg 和 result.detail：

if (result.code < 0) {
  console.error(result.msg)
  console.error(result.detail || '')
}

常见问题

提示找不到 FFmpeg 或原生类

当前运行的不是新制作的自定义基座。重新制作并安装基座后再运行项目；普通标准基座无法加载本插件的原生依赖。

提示文件不存在或无法读取视频

确认传入的是 App 可访问的本地绝对路径。不要直接传 _doc/a.mp4，应先通过 plus.io.convertLocalFileSystemURL() 转换。

处理完成后找不到输出文件

先使用回调中的 mp4、image、audio 或 gif 路径。未设置 saveDirectory 时，文件位于插件缓存目录；调用 deleteCache() 会清理这些默认输出。

处理失败如何定位

打印 result.detail。其中包含 FFmpeg 日志和失败时实际执行的命令。常见原因包括输入路径错误、输出目录不可写、视频编码不受支持或参数超出视频尺寸。

iOS 比例裁剪或压缩失败

iOS 使用 h264_videotoolbox 或 hevc_videotoolbox 进行编码。请使用本插件最新版本制作自定义基座，不要在 iOS 上手动指定 libx264 或 libx265。