跪拜 Guibai
← All articles
HarmonyOS

ffmpeg-for-HarmonyOS v0.3.2: Real Transcoding Features Arrive, Old API Gets Deprecated

By Sirius_Ji ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

HarmonyOS media apps can now integrate a native FFmpeg base that handles the common transcoding pain points: subtitle burning with graceful fallbacks, filter chains with fixed ordering, and frame-count monitoring. The deprecation notice gives teams a window to migrate before v0.4.0 removes the old API, while the honest boundaries around x86_64 and frame logging prevent production surprises.

Summary

ffmpeg-for-HarmonyOS v0.3.2 fills the gaps that v0.2.2 left in the transcode chain. Instead of re-exposing all of FFmpeg, it targets the specific steps that break in real use: subtitle burning, cropping, color grading, speed changes, and picture-in-picture with temporal start/end. Subtitle support now covers SRT, ASS, and WebVTT through libass, with sane fallbacks when a subtitle file, font directory, or specific font name is missing; the transcode continues instead of crashing. The filter list includes trim/crop, brightness/contrast/saturation/temperature, speed/atempo, text overlay, and PiP, with PiP confined to a time interval rather than a permanent overlay. Filter ordering is fixed: PiP renders before subtitles, drawtext after, so text always sits on top. When speed changes are applied, PTS values are remapped to the output timeline, so a subtitle programmed for second 5 lands at second 5 of the output, not the source. The release tests 1.25x and 0.5x speeds and adds a frame counter that logs a warning if filter_frames and encoder_frames differ.

On the API side, the 7-parameter videoTranscode remains, but the old signature is deprecated and will be removed in v0.4.0; a new videoTranscodePlan exists only as a draft and is not implemented. A TranscodeOptions type now mirrors the C++ parser, so field names like fontsDir and subtitlePath no longer require guessing. Distribution also changes: the HAR package drops RELINK materials (only LICENSES) and the C++ runtime is expected from the host app; the ZIP SDK keeps all headers, static libs, CMakeLists, and RELINK for relinkers. Per-ABI ZIPs are available for arm64-v8a and x86_64. The package name is now com.siriusji.ffmpegohos with versionCode 3000003, and the reminder that x86_64 still lacks runtime validation, frame monitoring only logs, and the library remains LGPL-2.1-or-later with no GPL or non-free codecs.

Takeaways
— Subtitle burning supports SRT, ASS, and WebVTT via libass, with built-in Source Han Sans CN as default and fallback behavior for missing files or fonts.
— The filter chain includes trimStart/trimEnd, cropW/H/X/Y, brightness/contrast/saturation/temperature, speed/atempo, textX/Y, imageX/Y/rotate, and PiP with pipEnableStart/End.
— Filter order is fixed: PiP renders before subtitles, drawtext after, so text always covers subtitles.
— Speed changes remap PTS to the output timeline; tested at 1.25x and 0.5x.
— Frame counting logs a warning when filter_frames and encoder_frames differ; it does not auto-fill or drop frames.
— The old videoTranscode is deprecated and scheduled for removal in v0.4.0; videoTranscodePlan is only a draft and not implemented.
— TranscodeOptions type now mirrors the C++ parser, eliminating guesswork for field names like fontsDir and subtitlePath.
— HAR no longer includes RELINK materials or libc++_shared.so; the ZIP SDK keeps them for relinkers.
— Per-ABI ZIPs for arm64-v8a and x86_64 are provided.
— Package name is com.siriusji.ffmpegohos, versionCode 3000003, license LGPL-2.1-or-later with no GPL or non-free codecs.
— x86_64 lacks runtime validation; frame monitoring only logs; network stream capture is incomplete.
Conclusions

The update deliberately prioritizes failure tolerance over feature completeness: missing subtitles, fonts, or directories degrade gracefully rather than aborting the transcode, which is a pragmatism that production users need.

The fixed filter ordering (PiP under subtitles, text on top) removes a class of configuration errors but also limits flexibility; teams that need z-order control will have to extend the filter chain themselves.

The deprecation of videoTranscode while videoTranscodePlan is still a draft creates a transitional uncertainty; the compatibility layer is present now, but v0.4.0 will force a migration that isn't fully specified yet.

The careful separation of HAR and ZIP SDK content shows a clear understanding of two different consumer types: ArkTS apps that just need the binary and C++ integrators that need to relink for LGPL compliance.

Concepts & terms
PTS
Presentation timestamp, the time at which a frame should be displayed. Mapping PTS to the output timeline ensures that after speed changes, events like subtitles align with the sped-up output, not the source timeline.
Filter graph
A chain of connected FFmpeg filters that process video or audio streams. The library exposes a subset of these filters via optionsJson rather than a full graph specification, keeping the interface simple for common transcode tasks.
HAR
HarmonyOS Archive, a package format for distributing ArkTS libraries. It contains compiled native libraries and ArkTS interfaces, allowing direct use in HarmonyOS NEXT / OpenHarmony projects.
RELINK
Materials needed to relink FFmpeg libraries for LGPL compliance, including application-side object files, link commands, and FriBidi source. Only relevant for C++ integrators who must rebuild the final binary to satisfy license obligations.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗