ffmpeg-for-HarmonyOS v0.3.2: Real Transcoding Features Arrive, Old API Gets Deprecated
Previous article: # A Brief Introduction to a HarmonyOS Native Hardware-Decoding FFmpeg Development Base Project: ffmpeg-for-HmOS is a FFmpeg base for Pure HarmonyOS ( - Juejin The previous project version was v0.2.2: still focused on solving "Does HarmonyOS have a set of FFmpeg base that can compile and hardware-decode?" This update goes to v0.3.2. The focus is no longer "whether it can run", but which missing parts of the transcode chain have been filled, to what extent they are now filled, and which areas still cannot be promised.
Project: ffmpeg-for-HarmonyOS
Current version: v0.3.2
Positioning: A base library for audio/video on HarmonyOS NEXT / OpenHarmony, not a finished player app.
Repository: https://github.com/Sirius-Ji/ffmpeg-for-HarmonyOS and ffmpeg-for-HarmonyOS: HarmonyOS audio decoding and transcoding base library based on FFmpeg - AtomGit
1. What has been added since v0.2.2?
The v0.2.2 transcode chain mainly covered scaling, overlay, text watermark, and basic encoding. In practical integration, these problems quickly appear:
- Video needs cropping, color adjustment, speed change; the original parameters are insufficient;
- Subtitles need to be burned into the picture; both SRT and ASS must be supported;
- Picture-in-picture (PiP) needs to appear and disappear based on time intervals, not stay permanently;
- After speed change, the subtitle and PiP timelines must follow the output;
- When subtitle files or fonts are missing, the whole transcode must not crash.
v0.3.2 fills these specific links, not by re-wrapping all FFmpeg capabilities.
2. Subtitles and Filter Chain
Subtitles
Currently supports SRT, ASS, WebVTT, burned via libass. The entry is the three fields in optionsJson:
{
"subtitlePath": "/data/.../subs.srt",
"fontsDir": "/data/.../files",
"subtitleStyle": "FontName=Source Han Sans CN,FontSize=24,PrimaryColour=&H0000FF00&"
}
fontsDir is written in camelCase, and the C++ side also supports the old fontsdir for compatibility. The colons in force_style are escaped so they don't break the filter graph.
Several practical behaviors:
- When SRT is provided without
subtitleStyle, the built-in Source Han Sans CN is used as fallback; - If the subtitle file doesn't exist, a log is written and the subtitle is skipped, transcode continues;
- When
fontsDiris empty, a WARN is logged and transcode continues; - If the font name doesn't exist, it doesn't crash the process; the result is usually no subtitles, or a fallback to an available font.
Video Filters
optionsJson currently supports:
trimStart / trimEnd
cropW / cropH / cropX / cropY
brightness / contrast / saturation / temperature
speed / atempo
textX / textY
imageX / imageY / rotate
pipPath / pipEnableStart / pipEnableEnd / pipX / pipY
PiP is a time-interval overlay, not a permanent static image. drawtext runs after subtitles, so the text watermark covers subtitles; PiP runs before subtitles, so subtitles cover PiP. This order is determined by the filter chain, not through a z-order configuration.
Timeline
When speed changes, filter PTS is mapped to the output timeline. That is, when a user writes "subtitle appears at second 5", it corresponds to the 5th second of the output file, not the 5th second of the source file.
v0.3.2 has tested 1.25x and 0.5x. The hardware encoder side has added frame counting:
filter_frames=240 encoder_frames=240
When they are not equal, a WARN is logged with the difference. At present this is only monitoring; it does not automatically fill or drop frames.
3. Interface Form
The existing entry point remains:
FFmpegOhos.videoTranscode(
srcPath,
dstPath,
format,
resolution,
volume,
imagePath,
optionsJson?
)
The 7th argument is an optional JSON string. The old 6-argument call continues to work.
Two points need to be clear:
- The old
videoTranscode(...)has been marked deprecated and is planned for removal in v0.4.0; the current version keeps a compatibility layer. - The new
videoTranscodePlanis only an interface draft and is not implemented; do not call it directly based on the draft.
The type side has added TranscodeOptions, whose fields align with the C++ parser; names like fontsDir, subtitlePath, trimStart no longer need to be guessed.
4. Dual-form Distribution
v0.3.2 still provides both HAR and ZIP SDK, but the content boundaries have been adjusted.
HAR
ffmpeg_ohos-v0.3.2.har approx 18.75 MB
For ArkTS projects; it contains ArkTS interfaces and dual-ABI native libraries.
The HAR now only keeps LICENSES and no longer includes RELINK materials. RELINK is the C++ side's relinking and LGPL compliance material; it has no direct value for ArkTS users, and including it in the HAR only increases size.
The HAR does not include libc++_shared.so; the host app must provide the C++ runtime using its own NDK version.
ZIP SDK
ffmpeg-ohos-sdk-v0.3.2.zip approx 20.7 MB
For C++ projects; includes:
include/
lib/arm64-v8a/
lib/x86_64/
CMakeLists.txt
BUILD-INFO.txt
NOTICE.md
LICENSES/
RELINK/
RELINK contains application-side .o files, link commands, FriBidi source, and documentation for publishers who need to relink.
per-ABI ZIP
ffmpeg-n9.0-ohos-arm64-v8a.zip
ffmpeg-n9.0-ohos-x86_64.zip
For scenarios that only need a specific ABI's dynamic library; also includes LICENSES and RELINK.
5. Minimal Integration
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);
}
Transcoding is an asynchronous task; status is queried via videoTranscodeStatus(). state 1 means running, 2 means completed, 3 means failed.
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)
Business code directly uses FFmpeg native headers, no need to wrap a custom handle again.
6. Boundaries
v0.3.2 is not "FFmpeg full-feature port complete."
- x86_64 keeps compiled artifacts and symbol validation, but there is no simulator runtime validation evidence for this version; actual runtime testing still needs to be done in an x86_64 environment.
- The HAR and SDK version numbers are unified to 0.3.2,
versionCodeis 3000003; the old package namecom.examplehas been removed; the current package name iscom.siriusji.ffmpegohos. - Subtitle default font, libass font matching, and complex ASS styles still have device/font differences; verify with your own assets before production integration.
- Frame counting only outputs logs; it does not automatically fix hardware-encoder frame drops or duplicates.
- The old API has entered the deprecated stage, and the new VideoPlan entry is not implemented; do not design long-term based on the draft.
- License remains LGPL-2.1-or-later; GPL/nonfree are not enabled, and x264/x265 are not introduced.
7. Release Information
Version: 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
If the previous version only solved "running FFmpeg on HarmonyOS", this version can already enter the actual transcode flow: subtitles, cropping, color adjustment, speed change, PiP, fallback, and compliance materials are all in the package.
It is still a test version with incomplete parts (such as network stream capture), but it is closer to the state of being directly integrated into a project than v0.2.2. Please give a star to support, and I hope more HarmonyOS developers will find issues and submit them during actual development. This is very important for my future improvements. Thank you!
Top 1 from juejin.cn, machine-translated. The original thread is authoritative.
Repository address: https://github.com/Sirius-Ji/ffmpeg-for-HarmonyOS https://github.com/Sirius-Ji/ffmpeg-for-HarmonyOS The content at both links is the same. Everyone is welcome to star the repo and file issues [applause]. As a newbie, I really need everyone's support.