从硬解基座到字幕与滤镜链:ffmpeg-for-HarmonyOS v0.3.2

0 阅读5分钟

前文见# 一份鸿蒙原生支持硬解的 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 里的三个字段:

{
  "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 目前支持:

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。硬编侧增加了帧数监控:

filter_frames=240 encoder_frames=240

不相等时会打 WARN 并记录差值。它目前是监控,不会自动补帧或丢帧。

3. 接口形态

现有入口还是:

FFmpegOhos.videoTranscode(
  srcPath,
  dstPath,
  format,
  resolution,
  volume,
  imagePath,
  optionsJson?
)

第 7 个参数是可选 JSON 字符串。旧的 6 参数调用继续可用。

需要明确两点:

  1. 旧 videoTranscode(...) 已标记 deprecated,计划在 v0.4.0 移除;当前版本保留兼容层。
  2. 新的 videoTranscodePlan 只有接口草稿,尚未实现,不要按草稿直接调用。

类型侧补了 TranscodeOptions,字段与 C++ 解析保持一致;fontsDir、subtitlePath、trimStart 这些名字不用再猜。

4. 双形态分发

v0.3.2 仍然同时提供 HAR 和 ZIP SDK,但两者的内容边界做了调整。

HAR

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

ffmpeg-ohos-sdk-v0.3.2.zip    约 20.7 MB

给 C++ 工程使用,包含:

include/
lib/arm64-v8a/
lib/x86_64/
CMakeLists.txt
BUILD-INFO.txt
NOTICE.md
LICENSES/
RELINK/

RELINK 里有应用侧 .o、链接命令、FriBidi 源码和说明,供需要重新链接的发布方使用。

per-ABI ZIP

ffmpeg-n9.0-ohos-arm64-v8a.zip
ffmpeg-n9.0-ohos-x86_64.zip

适合只需要某个 ABI 动态库的场景,同样带 LICENSES 和 RELINK。

5. 极简接入

ArkTS

// entry/oh-package.json5
{
  "dependencies": {
    "@sirius/ffmpeg_ohos": "file:../ffmpeg_ohos"
  }
}
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_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. 发布信息

版本: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,这对我后续的改进工作十分重要,感谢!