【鸿蒙优选三方库】@ohos/ffmpeg-kit：把 FFmpeg 的全部能量带进 HarmonyOS
【鸿蒙优选三方库】@ohos/ffmpeg-kit：把 FFmpeg 的全部能量带进 HarmonyOS
想在鸿蒙应用里直接调用 FFmpeg 处理音视频？
@ohos/ffmpeg-kit是 FFmpegKit 在 OpenHarmony 上的官方移植——一套脚本、一套原生库、一套 ArkTS 封装，让你在 HarmonyOS 上像在 Android/iOS 一样运行 FFmpeg/FFprobe 命令。
- 包名：
@ohos/ffmpeg-kit - 当前版本：v1.0.1
- 协议：MIT
- 安装：
ohpm install @ohos/ffmpeg-kit - 仓库：https://gitcode.com/CPF-ApplicationTPC/ohos_ffmpeg_kit
一、它解决了什么问题？
FFmpeg 是音视频领域的"瑞士军刀"——转码、剪辑、拼接、滤镜、流媒体推拉，几乎无所不能。但要在 HarmonyOS 应用里使用 FFmpeg，传统路径是：自己编译 FFmpeg 源码 → 写 NAPI 桥接 → 处理异步回调与日志 → 还要考虑 license 与依赖……
@ohos/ffmpeg-kit继承自业界知名的 FFmpegKit 跨平台项目（曾支持 Android/iOS/macOS/Linux/tvOS/Flutter/RN），把整套工程实践与脚本完整带到了 OHOS，让你 5 分钟接入 FFmpeg 能力。
📌小贴士：上游 FFmpegKit 已于 2025 年正式宣告停止维护（< 6.0 版本二进制已于 2025-02-01 下线，6.0 版本于 2025-04-01 下线）。本仓库是 OpenHarmony 社区在 FFmpegKit 基础上的延续，专门为 HarmonyOS 生态服务。
二、核心特点
| 特性 | 说明 |
|---|---|
| 基于 FFmpeg v4.5-dev+ | 可选系统库与外部库支持 |
| FFmpeg + FFprobe | 完整命令执行能力 |
| ArkTS NAPI 封装 | 异步执行、日志回调、返回码捕获 |
| 多架构构建脚本 | 沿用上游buildEnv.sh、android.sh等工程脚本 |
| Flutter / RN 复用 | 同源支持 Flutter、React Native（flutter/、react-native/目录） |
| 集成 AKI 桥接 | 底层依赖@ohos/aki提供高效的 JS↔Native 互调 |
| 完整 native 库 | libffmpegkit_napi.so一并交付，免编译即可用 |
三、适用场景
- 音视频转码：把一种格式/编码转成另一种（如 mp4 → wav、H.264 → H.265）。
- 视频剪辑与拼接：客户端纯本地完成，无需上传服务端。
- 直播推流 / 拉流：使用 FFmpeg 拉 RTMP/HLS/HTTP-FLV 流并解码。
- 音视频元信息解析：通过 FFprobe 拿到时长、码率、编码格式等。
- 滤镜与特效：加水印、缩放、调色、混音等。
- 教育/工具类 App：在线转码器、格式转换工具、音频编辑器。
- Flutter / RN 应用：如果你是 Flutter 或 React Native 开发者，本仓库也提供对应平台支持。
四、快速上手
1. 安装
ohpminstall@ohos/ffmpeg-kit依赖项会自动安装：
libffmpegkit_napi.so（native 库）@ohos/aki（JS↔C++ 互调框架）
2. 执行一条 FFmpeg 命令
import{FFmpegKit,FFmpegSession,ReturnCode}from'@ohos/ffmpeg-kit'// 异步执行 FFmpeg 命令constsession:FFmpegSession=FFmpegKit.execute('-i /data/storage/el2/base/input.mp4 -vn -acodec copy /data/storage/el2/base/output.aac')// 监听日志（可选）session.setLogCallback((log)=>{console.info(`[FFmpeg]${log.getMessage()}`)})// 等待执行完成session.complete.then((stats)=>{if(ReturnCode.isSuccess(stats.getReturnCode())){console.info('转码成功')}elseif(ReturnCode.isCancel(stats.getReturnCode())){console.info('转码被取消')}else{console.error('转码失败: '+stats.getFailStackTrace())}})3. 用 FFprobe 探测媒体信息
import{FFprobeKit}from'@ohos/ffmpeg-kit'FFprobeKit.getMediaInformation('/data/storage/el2/base/video.mp4').then((session)=>{constinfo=session.getMediaInformation()console.info('时长: '+info.getDuration()+' ms')console.info('码率: '+info.getBitrate())console.info('格式: '+info.getFormat())})五、亮点能力速览
- 异步执行模型：命令在后台跑，结果通过 Promise + 回调通知，UI 永远不卡。
- 完整日志通道：FFmpeg 的全部 stderr/stdout 日志都能回调上来，调试无忧。
- 会话管理：每个命令是一个
FFmpegSession，可取消、可查询状态。 - 跨平台血统：项目结构沿用上游 FFmpegKit，熟悉上游的人零学习成本。
- 多端统一：除 OHOS 外，仓库内同时维护 Flutter、React Native 等平台的桥接代码。
六、为什么值得选它？
- 能力天花板：FFmpeg 几乎能干任何音视频活，库等于给你一座矿山。
- 省掉踩坑：编译 FFmpeg、解决依赖、写 NAPI 这些"硬骨头"已被踩平。
- ArkTS 友好：Promise + 回调，贴合鸿蒙开发习惯。
- 社区接力：上游虽然停止维护，但本仓库持续在 OHOS 社区演进。
- 多端复用：一套脚本体系横跨 OHOS / Flutter / RN，工程资产不浪费。
如果你做的应用需要"处理音视频"，而不是"播放音视频"（播放请看 @ohos/ijkplayer），@ohos/ffmpeg-kit几乎是 OpenHarmony 上的不二之选。