跪拜 Guibai
← Back to the summary

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:

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:

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:

  1. The old videoTranscode(...) has been marked deprecated and is planned for removal in v0.4.0; the current version keeps a compatibility layer.
  2. The new videoTranscodePlan is 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."

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!

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 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.