前文见# 一份鸿蒙原生支持硬解的 ffmpeg 开发基座项目简介:ffmpeg-for-HarmonyOS 是一个为纯血鸿蒙( - 掘金 上一篇项目版本为 v0.2.2:仍以解决"鸿蒙有没有一套能编译、硬解的 FFmpeg 基座"为主。
这一篇更新到 v0.3.2。重点不再是"能不能跑",而是转码链路里原来缺的哪几块被补上了、现在补到了什么程度、以及哪些地方仍不能承诺。
项目:ffmpeg-for-HarmonyOS
当前版本:v0.3.2
定位:HarmonyOS NEXT / OpenHarmony 的音视频基础库,不是成品播放器 App。 项目仓库地址:github.com/Sirius-Ji/f... 以及 ffmpeg-for-HarmonyOS:基于 FFmpeg 的 HarmonyOS 音频解码与转码基础库 - AtomGit
1. v0.2.2 之后补了什么
v0.2.2 的转码链主要是缩放、overlay、文字水印和基础编码。实际接入时,下面这些问题很快就会碰到:
- 视频要裁剪、调色、变速,原来的参数不够;
- 字幕要烧进画面,SRT 和 ASS 都要支持;
- 画中画要按时间段出现和消失,不能一直挂着;
- 变速之后,字幕和 PiP 的时间轴要跟着输出走;
- 字幕文件缺失、字体缺失时,不能把整条转码带崩。
v0.3.2 补的是这些具体环节,不是把 FFmpeg 全量能力重新包装一遍。
2. 字幕与滤镜链
字幕
当前支持 SRT、ASS、WebVTT,通过 libass 烧录。入口是 optionsJson 里的三个字段:
json
{
"subtitlePath": "/data/.../subs.srt",
"fontsDir": "/data/.../files",
"subtitleStyle": "FontName=Source Han Sans CN,FontSize=24,PrimaryColour=&H0000FF00&"
}
fontsDir 是 camelCase 写法,C++ 侧同时兼容旧的 fontsdir。force_style 里的冒号会做转义,不会把 filter graph 截断。
几个实际行为:
- SRT 不传
subtitleStyle时,默认使用内置的 Source Han Sans CN 兜底; - 字幕文件不存在时,打日志并跳过字幕,转码继续;
fontsDir为空时打 WARN,转码继续;- 字体名不存在时,不会导致进程崩溃;结果通常是无字幕,或回退到可用字体。
视频滤镜
optionsJson 目前支持:
text
trimStart / trimEnd
cropW / cropH / cropX / cropY
brightness / contrast / saturation / temperature
speed / atempo
textX / textY
imageX / imageY / rotate
pipPath / pipEnableStart / pipEnableEnd / pipX / pipY
PiP 是时间区间叠加,不是永久贴图。drawtext 在 subtitles 之后执行,所以文字水印会盖在字幕上;PiP 在 subtitles 之前,所以字幕会盖在 PiP 上。这个顺序由滤镜链决定,不是靠 z-order 配置。
时间轴
变速时,滤镜 PTS 会映射到输出时间轴。也就是说,用户写"第 5 秒出现字幕",对应的是输出文件的第 5 秒,而不是源文件的第 5 秒。
v0.3.2 测过 1.25x 和 0.5x。硬编侧增加了帧数监控:
text
filter_frames=240 encoder_frames=240
不相等时会打 WARN 并记录差值。它目前是监控,不会自动补帧或丢帧。
3. 接口形态
现有入口还是:
ts
FFmpegOhos.videoTranscode(
srcPath,
dstPath,
format,
resolution,
volume,
imagePath,
optionsJson?
)
第 7 个参数是可选 JSON 字符串。旧的 6 参数调用继续可用。
需要明确两点:
- 旧
videoTranscode(...)已标记 deprecated,计划在 v0.4.0 移除;当前版本保留兼容层。 - 新的
videoTranscodePlan只有接口草稿,尚未实现,不要按草稿直接调用。
类型侧补了 TranscodeOptions,字段与 C++ 解析保持一致;fontsDir、subtitlePath、trimStart 这些名字不用再猜。
4. 双形态分发
v0.3.2 仍然同时提供 HAR 和 ZIP SDK,但两者的内容边界做了调整。
HAR
text
ffmpeg_ohos-v0.3.2.har 约 18.75 MB
给 ArkTS 工程使用,包含 ArkTS 接口和双 ABI native 库。
HAR 只保留 LICENSES,不再带 RELINK 材料。RELINK 是 C++ 侧重链接和 LGPL 合规材料,对 ArkTS 使用者没有直接价值,放在 HAR 里只会增加体积。
HAR 不包含 libc++_shared.so,宿主 App 需要用自己的 NDK 版本提供 C++ runtime。
ZIP SDK
text
ffmpeg-ohos-sdk-v0.3.2.zip 约 20.7 MB
给 C++ 工程使用,包含:
text
include/
lib/arm64-v8a/
lib/x86_64/
CMakeLists.txt
BUILD-INFO.txt
NOTICE.md
LICENSES/
RELINK/
RELINK 里有应用侧 .o、链接命令、FriBidi 源码和说明,供需要重新链接的发布方使用。
per-ABI ZIP
text
ffmpeg-n9.0-ohos-arm64-v8a.zip
ffmpeg-n9.0-ohos-x86_64.zip
适合只需要某个 ABI 动态库的场景,同样带 LICENSES 和 RELINK。
5. 极简接入
ArkTS
json5
// entry/oh-package.json5
{
"dependencies": {
"@sirius/ffmpeg_ohos": "file:../ffmpeg_ohos"
}
}
ts
import { FFmpegOhos, TranscodeOptions } from '@sirius/ffmpeg_ohos';
const opts: TranscodeOptions = {
trimStart: 5,
trimEnd: 15,
cropW: 640,
cropH: 480,
speed: 1.25,
subtitlePath: `${ctx.filesDir}/subs.srt`,
fontsDir: ctx.filesDir
};
const r = FFmpegOhos.videoTranscode(
srcPath,
dstPath,
'mp4',
'720p',
1.0,
'',
JSON.stringify(opts)
);
if (!r.ok) {
console.error(r.data);
}
转码是异步任务,状态通过 videoTranscodeStatus() 查询。state 为 1 表示运行中,2 表示完成,3 表示失败。
C++
cmake
cmake_minimum_required(VERSION 3.16)
project(my_media_tool CXX)
add_subdirectory(ffmpeg-ohos-sdk)
add_executable(my_tool main.cpp)
target_link_libraries(my_tool PRIVATE ffmpeg_ohos_sdk)
target_link_libraries(my_tool PRIVATE c++_shared)
业务代码直接使用 FFmpeg 原生头文件,不需要再包一层自定义句柄。
6. 边界
v0.3.2 不是"FFmpeg 全功能移植完成"。
- x86_64 保留编译产物和符号校验,但当前版本没有模拟器运行验收证据,实际运行仍需在具备 x86_64 环境时补测。
- HAR 和 SDK 的版本号已经统一到 0.3.2,
versionCode为 3000003;旧包名com.example已移除,当前包名是com.siriusji.ffmpegohos。 - 字幕默认字体、libass 字体匹配和复杂 ASS 样式仍有设备/字体差异,生产接入前要用自己的素材验证。
- 帧数监控只输出日志,不自动修复硬编丢帧或重复帧。
- 旧 API 已进入 deprecated 阶段,新 VideoPlan 入口未实现,不建议现在按草稿做长期设计。
- 许可证仍是 LGPL-2.1-or-later,没有启用 GPL/nonfree,也没有引入 x264/x265。
7. 发布信息
text
版本:v0.3.2
Tag:v0.3.2
HAR:ffmpeg_ohos-v0.3.2.har
SDK:ffmpeg-ohos-sdk-v0.3.2.zip
per-ABI:ffmpeg-n9.0-ohos-arm64-v8a.zip
ffmpeg-n9.0-ohos-x86_64.zip
如果说上一版还只解决的是"把 FFmpeg 跑在鸿蒙上",这一版则已经能进入实际转码流程:字幕、裁剪、调色、变速、PiP、降级和合规材料,都已经在包里了。
当前仍为测试版本,有不完整处(如网络流抓取),但比 v0.2.2 更接近能直接接进项目的状态,还请各位多多点star支持,也希望能有更多鸿蒙开发者能在实际开发流程中发现问题、提出issue,这对我后续的改进工作十分重要,感谢!