【鸿蒙优选三方库】@ohos/ffmpeg-kit：把 FFmpeg 的全部能量带进鸿蒙

FFmpeg 是音视频领域的瑞士军刀，但要在鸿蒙里用它，得自己编译源码、写 NAPI 桥接、处理异步回调。@ohos/ffmpeg-kit 把这些活全干了——在 ArkTS 里直接执行 FFmpeg 命令，会写命令行的人零学习成本。

📦 仓库地址 ｜ ohpm install @ohos/ffmpeg-kit ｜ v1.0.1 ｜ MIT

---

它解决什么问题

音视频处理的复杂度是出了名的：转码要懂编码器和容器、剪辑要处理时间戳对齐、加水印要实现滤镜引擎。自己写？按人月算。

FFmpeg 早就把这些全做好了，一条命令搞定。@ohos/ffmpeg-kit 是 FFmpegKit 跨平台项目在 OpenHarmony 上的移植，底层依赖 @ohos/aki 做 JS↔C++ 桥接，native 库 libffmpegkit_napi.so 一并交付，免编译即可用。

📌 上游 FFmpegKit 已于 2025 年停止维护（6.0 版本二进制 2025-04-01 下线）。本仓库是 OpenHarmony 社区的延续维护。

---

核心能力

能力	说明
FFmpeg 命令	转码、剪辑、拼接、滤镜、混音
FFprobe 探测	时长、码率、编码、分辨率
异步执行	后台跑，Promise + 回调通知
日志回调	FFmpeg 全部 stderr/stdout 实时上来
会话管理	每个命令一个 Session，可取消可查状态
多端复用	仓库同时维护 OHOS / Flutter / RN 桥接

---

30 秒上手

ohpm install @ohos/ffmpeg-kit

视频转音频：

import { FFmpegKit, ReturnCode } from '@ohos/ffmpeg-kit'

const session = FFmpegKit.execute(
  '-i /data/storage/el2/base/files/input.mp4 -vn -acodec copy /data/storage/el2/base/files/output.aac'
)

session.setLogCallback((log) => console.info(`[FFmpeg] ${log.getMessage()}`))

// ⚠️ 必须等 complete 之后再查输出数据
const stats = await session.getCompleteFuture()
if (ReturnCode.isSuccess(stats.getReturnCode())) {
  console.info('成功，输出: ' + session.getOutput())
} else if (ReturnCode.isCancel(stats.getReturnCode())) {
  console.info('已取消')
} else {
  console.error('失败: ' + stats.getFailStackTrace())
}

探测媒体信息：

import { FFprobeKit } from '@ohos/ffmpeg-kit'

const session = await FFprobeKit.getMediaInformation(videoPath)
const info = session.getMediaInformation()

console.info(`时长 ${info.getDuration()}ms / 码率 ${info.getBitrate()} / 格式 ${info.getFormat()}`)
info.getStreams().forEach((s) => {
  if (s.getType() === 'video') console.info(`视频 ${s.getWidth()}x${s.getHeight()} ${s.getCodec()}`)
  if (s.getType() === 'audio') console.info(`音频 ${s.getCodec()} ${s.getSampleRate()}Hz`)
})

取消执行：

const sessionId = session.getSessionId()
FFmpegKit.cancel(sessionId)   // 取消指定会话
FFmpegKit.cancel()            // 取消全部

---

社区已解决的典型问题

会话完成后查不到输出数据（#30）
命令执行完成后通过 Session 查询输出拿不到结果。已修复查询逻辑。关键是要在 getCompleteFuture() resolve 之后再查，执行中查是空的。

FFprobe 没有信息输出（#28 / #29）
调用 FFprobe 后 Session 里没有信息。已修复。取数据有两种方式：getMediaInformation() 拿结构化对象（推荐，类型安全），getOutput() 拿原始文本（适合排查问题）。

Demo 依赖引入导致编译失败（#27）
改为本地 HAR 包维护，Demo 正常编译运行。如果你的工程遇到依赖解析问题，可以参考这个方式——把编译好的 HAR 放进工程直接依赖，绕过 ohpm 网络解析。

Flutter 侧质量加固（#26）
仓库同时维护 OHOS / Flutter / RN 三个平台的桥接，多端质量同步提升。

---

适合谁用

• 视频工具类 App：转码、剪辑、拼接、加水印
• 音频处理：提取音轨、格式转换、铃声制作
• 直播推拉流：拉 RTMP/HLS 流并处理
• 媒体信息解析：用 FFprobe 拿元数据
• Flutter / RN 应用：仓库同源支持

---

一个必须知道的点

FFmpeg 是 CPU 密集型任务。批量处理时要串行，不要并行——并行跑多个会让每个都变慢，还可能触发内存压力：

for (const cfg of configs) {
  await processOne(cfg)                              // 串行
  await new Promise((r) => setTimeout(r, 200))       // 批间喘息
}

会写 FFmpeg 命令行的人，装上就能用。不会写的，把需求描述给 AI 让它生成命令，再粘进来——这也是一种生产力。