跪拜 Guibai
← Back to the summary

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

A FFmpeg Development Base with Native Hardware Decode Support for HarmonyOS

Author: Sirius_Ji

Project Intro: ffmpeg-for-HarmonyOS is an audio/video base library built for pure HarmonyOS (HarmonyOS NEXT / OpenHarmony). It not only opens up FFmpeg's full audio/video processing capabilities, but also natively connects to HarmonyOS's hardware decode/encode interfaces, provided in both HAR and C++ SDK forms.

Project: ffmpeg-for-HarmonyOS Current Version: v0.2.2 Positioning: An audio/video base library for HarmonyOS NEXT / OpenHarmony, not a finished player app.

1. Development Background and Motivation

When doing HarmonyOS audio/video development last year, the most direct problem I hit was: I couldn't find a complete FFmpeg library that would run directly on pure HarmonyOS.

The solutions you can find online broadly fall into a few categories:

The first two categories are "won't compile"; the latter two are "compiles but isn't usable." For someone actually building audio/video features, what's missing is not FFmpeg source code, but a base that can interface with HarmonyOS system capabilities and be integrated into engineering workflows.

This is also why the project includes hardware decoding.

First, pure software decoding has a direct cost on mobile devices. FFmpeg's software decoding continuously occupies the CPU, especially with high-resolution, high-bitrate video, and then device heating, battery drain, and frequency throttling follow. For players, transcoders, camera processing, and similar scenarios, relying only on software decoding makes it hard to maintain experience over time.

Second, many similar open-source products on the market still focus on "getting FFmpeg to compile on HarmonyOS," but have incomplete support for HarmonyOS's native hardware decoding capabilities. System interfaces like OH_AudioCodec and OH_VideoDecoder don't naturally connect with FFmpeg's AVCodecContext; they require additional decoder wrapping, Surface binding, timestamp and EOS handling. Without that work, hardware decoding is just a noun in documentation.

So this project from the start was not "recompile FFmpeg again," but putting three things together:

  1. FFmpeg's full demux, resample, filter, and mux capabilities;
  2. HarmonyOS native hardware decode/encode interfaces;
  3. Distribution forms directly consumable by ArkTS and C++ projects.

The project stays LGPL-2.1-or-later, with no GPL, nonfree, x264, or x265 enabled. Currently provides arm64-v8a and x86_64 dual ABI, with dynamic libraries aligned to 16KB pages.

2. Core Capabilities and Boundaries

Available Capabilities

fe763a9e4f7335bbbb6c884e8094ae45.png

Boundaries That Must Be Stated Clearly

Current v0.2.2 is just an initial public beta, not the final completed version.

3. Dual-Form Distribution Design

Different developers integrate FFmpeg in different ways, so v0.2.2 provides two forms simultaneously.

image.png

HAR Package: For ArkTS Frontend Developers

ffmpeg_ohos-v0.2.2.har, about 18MB, includes ArkTS interfaces and dual-ABI native libraries.

Suitable for:

The HAR does not include libc++_shared.so; the host app needs to provide the C++ runtime with its own NDK version to avoid conflicts with the host project's C++ runtime.

ZIP SDK: For C++ Lower-Level Developers

ffmpeg-ohos-sdk-v0.2.2.zip, about 18.5MB, includes:

include/                 FFmpeg + freetype + harfbuzz + lame header files
lib/arm64-v8a/           7 FFmpeg/lame libraries + libffz.so.1
lib/x86_64/
CMakeLists.txt           Example that can be added via add_subdirectory directly
BUILD-INFO.txt           ABI, SONAME, sha256 manifest
NOTICE.md
LICENSES/

Suitable for:

Among these, libffz.so.1 is renamed zlib. The reason is that there is no stable libz.so available in the HarmonyOS system environment, while the host project may already bundle zlib, and naming it libz directly would cause conflicts. After renaming, the NEEDED entries of libavcodec.so.63 and libavformat.so.63 both point to libffz.so.1.

4. Minimal Integration Guide

4.1 ArkTS: Calling Transcoder via HAR

First put the HAR into the project as a local dependency:

// entry/oh-package.json5
{
  "dependencies": {
    "@sirius/ffmpeg_ohos": "file:../ffmpeg_ohos"
  }
}

Then call it:

import { FFmpegOhos } from '@sirius/ffmpeg_ohos';

const src = `${ctx.filesDir}/input.mp4`;
const dst = `${ctx.filesDir}/output.mp4`;

const r = FFmpegOhos.videoTranscode(
  src,
  dst,
  'mp4',       // container format
  '720p',      // original | 720p | 1080p
  1.0          // volume 0.0 - 2.0
);

if (!r.ok) {
  console.error('transcode start failed:', r.data);
}

When adding text + image watermark, format uses this parameter string:

watermark|<text>|<position>|<fontSize>|<color>|<fontPath>|<alpha>|<bold>

Example:

const fontPath = `${ctx.filesDir}/SourceHanSansCN-Regular.otf`;
const logoPath = `${ctx.filesDir}/logo.png`;

const format =
  `watermark|FFmpeg-ohos|bottom-right|42|[email protected]|${fontPath}|80|1`;

FFmpegOhos.videoTranscode(
  src,
  dst,
  format,
  '1080p',
  1.0,
  logoPath       // 6th parameter: image watermark
);

position supports top-left / top-right / bottom-left / bottom-right / center; alpha is 0–100; bold is 0 or 1. Fonts and images need to be placed in an app-readable sandbox path first.

Transcoding is an asynchronous task; progress can be queried via the status interface:

const status = JSON.parse(FFmpegOhos.videoTranscodeStatus().data);
// status.state: 1 running, 2 completed, 3 failed

4.2 C++: Linking via ZIP SDK

After unzipping the SDK, directly reference it in a CMake project:

cmake_minimum_required(VERSION 3.16)
project(my_media_tool CXX)

set(OHOS_ARCH arm64-v8a)
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_ohos_sdk automatically includes the include paths and 8 imported libraries. Business code can directly use FFmpeg native headers:

extern "C" {
#include <libavformat/avformat.h>
#include <libavcodec/avcodec.h>
}

AVFormatContext *fmt = nullptr;
if (avformat_open_input(&fmt, path, nullptr, nullptr) < 0) {
    // error
}

If the host project has its own C++ runtime, ensure the version of libc++_shared.so matches the SDK's compiler toolchain; the SDK does not bundle an extra C++ runtime.

5. Pitfalls and Technical Depth

The harder parts of this project are mostly not "getting an API to work," but problems at system boundaries.

These efforts may not be reflected in the API count, but they determine whether the library can run directly in an unfamiliar project.

6. Open Source Call

Open-source infrastructure work is not easy. One person maintaining cross-compilation, dual ABI, hardware decode adaptation, filter chains, release packages, and documentation means progress won't be as fast as a commercial project, but each step tries to leave reproducible build and verification records.

Current v0.2.2 is just an initial version. Fellow developers are welcome to:

Repositories and Downloads

Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

Sirius_Ji

Repository address: https://github.com/Sirius-Ji/ffmpeg-for-HarmonyOS https://github.com/Sirius-Ji/ffmpeg-for-HarmonyOS The content on both ends is the same. Everyone is welcome to star and raise issues. [applause] A newbie really needs everyone's support.