跪拜 Guibai
← All articles
HarmonyOS

FFmpeg for HarmonyOS Ships with Native Hardware Decode and Dual ABI Packages

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

HarmonyOS NEXT teams no longer have to hand-roll FFmpeg cross-compilation or settle for software-only decode; this base provides a prebuilt dual-ABI library with hardware codec integration and a software fallback, cutting what's typically weeks of ABI and system-specific integration work down to a dependency add. The LGPL licensing and absence of GPL codecs keep it usable in commercial apps.

Summary

ffmpeg-for-HarmonyOS v0.2.2 fills a gap that's been blocking HarmonyOS audio/video work: a complete FFmpeg library that actually compiles and runs on pure HarmonyOS. The author hit four dead ends in existing solutions: Linux/Android .so files that don't match HarmonyOS ABIs, partial FFmpeg builds missing demux/resample/filter components, example-only code without reproducible dual-ABI releases, and software-only decode with no native hardware hooks. The project combines FFmpeg's full demux, resample, filter, and mux capabilities with HarmonyOS's native OH_AudioCodec and OH_VideoDecoder interfaces, then packages it for both ArkTS and C++ consumers.

The current release provides dual ABI arm64-v8a and x86_64 dynamic libraries aligned to 16KB pages, kept under LGPL-2.1-or-later with no GPL, nonfree, x264, or x265 codecs enabled. Audio covers AAC/MP3/FLAC/Opus/WAV with hardware decode and software fallback; video offers H.264/H.265 decode and Surface rendering plus basic H.264 hardware encoding. Text and image watermarks, libavfilter-based scaling and overlay chains, and MP4/MKV/FLV container support are in. The author is explicit that v0.2.2 is a public beta, not final: complex filters, more encoders, and more bitstream features are still planned, and image watermark alpha handling needs polishing.

Distribution comes in two forms. An 18MB HAR package for ArkTS frontend developers exposes 23 methods and handles ohpm dependency management, leaving C++ runtime to the host app. An 18.5MB ZIP SDK for C++ developers gives direct access to AVFormatContext/AVCodecContext via CMake add_subdirectory. The SDK includes a renamed zlib (libffz.so.1) because HarmonyOS lacks a stable system zlib and host projects may already carry one. Known pitfalls documented include HiSilicon screen tearing fixed by two-stage muxing, mono-to-stereo upmix causing a precise -3dB transient drop, a fake 8.9KB zlib stub, and a full-relink requirement to avoid stale DT_NEEDED dependencies.

Takeaways
— ffmpeg-for-HarmonyOS v0.2.2 is a complete FFmpeg base for HarmonyOS NEXT/OpenHarmony, integrating native OH_AudioCodec and OH_VideoDecoder hardware decode/encode interfaces.
— Licensed LGPL-2.1-or-later with no GPL, nonfree, x264, or x265 enabled, so commercial use is possible without GPL contamination.
— Ships dual ABI arm64-v8a and x86_64 dynamic libraries aligned to 16KB pages, in both HAR (18MB, 23 ArkTS methods) and ZIP SDK (18.5MB, 8 imported libraries) forms.
— Audio supports AAC, MP3, FLAC, Opus, WAV with hardware decode and software fallback; video supports H.264/H.265 decode, Surface rendering, and basic H.264 hardware encoding.
— Watermark pipeline supports text and image overlays with position, size, color, alpha, and bold options; image watermark alpha and blending are still incomplete.
— HAR excludes libc++_shared.so; the host app must supply its own C++ runtime to avoid conflicts.
— ZIP SDK renames zlib to libffz.so.1 because HarmonyOS has no stable system libz.so and host projects may bundle their own zlib.
— A known HiSilicon screen-tearing bug was fixed by switching from hand-written AVCC mux to a two-stage AnnexB → MPEG-TS → FFmpeg remux → MP4 pipeline.
— Mono-to-stereo force upmix caused transient peaks to drop exactly -3dB; the fix preserves source channel count for FLAC/WAV/Opus.
— A fake 8.9KB zlib stub in the system broke PNG decode with AVERROR_EXTERNAL until real zlib was cross-compiled and renamed.
— Every FFmpeg build now force-deletes build/<abi> to prevent stale libraries that still depend on the old zlib; release gates check DT_NEEDED closure.
— Current v0.2.2 is a public beta: no binary compatibility promise, hardware decode behavior varies by device and system version, and complex filters/encoders/containers are planned for later.
Conclusions

The hardware decode integration is the real differentiator; most existing HarmonyOS FFmpeg ports stop at getting the code to compile and leave OH_AudioCodec/OH_VideoDecoder as unimplemented documentation.

The zlib naming workaround and the fake 8.9KB stub reveal that HarmonyOS's system library set is still immature enough that even a well-known C library like FFmpeg needs careful patching to be reliable.

Keeping the project LGPL while omitting GPL codecs is a deliberate trade to make the base usable in commercial apps without license headaches.

The documented pitfalls—screen tearing, -3dB transient drop, stale DT_NEEDED—show that the hard part of porting FFmpeg to a new platform isn't API calls but system boundary behavior that only shows up under real device workloads.

Concepts & terms
HAR
HarmonyOS Archive, a package format for distributing native libraries and ArkTS interfaces consumable through the ohpm dependency manager, similar to an AAR in Android.
OH_AudioCodec / OH_VideoDecoder
HarmonyOS native APIs for hardware-accelerated audio and video decoding. They require explicit decoder wrapping, Surface binding, and timestamp/EOS handling to connect with FFmpeg's AVCodecContext.
Dual ABI
The library ships binaries for both arm64-v8a (real devices) and x86_64 (emulators/tools), so the same SDK works across the two main HarmonyOS target architectures.
libffz.so.1
A renamed version of zlib included in the SDK. HarmonyOS lacks a stable system libz.so, and renaming avoids conflicts with a host project's own zlib.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗