FFmpeg for HarmonyOS Ships with Native Hardware Decode and Dual ABI Packages
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.
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.
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.