在鸿蒙PC上适配Pitivi手记
鸿蒙适配开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_pitivi
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
这篇文章记录的是开源视频编辑器 Pitivi 在 OpenHarmony / HarmonyOS PC(2in1 形态)上的适配过程,偏向「工程复盘」:每一步做什么、遇到什么报错、怎么定位、改哪一层、如何确认生效,全部真实执行与留档。
本次适配没有搬运 Python/GTK 代码,而是「以 Pitivi 为行为规格」重新构建了一条链路:ArkUI 重写全部界面 + GStreamer/GES 交叉编译作为编辑引擎 + NAPI 桥接 C++ 原生内核。渲染链路从纯 CPU 软件渲染起步,GPU 加速已由「强制关闭」改为「允许开启」(CPU 仍为默认路径)。围绕完整可用的视频编辑体验,重点处理了几条主线:
- HAP 工程能够在鸿蒙 PC 本机独立构建、签名、安装
- ArkUI 编辑器界面(媒体库 / 预览 / 时间线 / 属性 / 状态栏)稳定承载
- C++ 原生内核通过 NAPI 提供合成、时间线编辑与撤销/重做
- GStreamer/GES 1.26.6 引擎交叉编译进 HAP 并在真机自检通过
- GPU 策略、截图验证等证据链如实上报
最终效果——签名 HAP 在本机(HongMeng Kernel 1.13.0,2in1 形态)安装、启动并正常运行:

完整适配过程(命令 / 报错 / 解决 / 证据):docs/harmonyos-pc-adaptation-log.md
一、项目背景
Pitivi 是 GNOME 下的开源非线性视频编辑器,项目描述是:
Pitivi is a video editor built upon the GStreamer Editing Services (GES).
It aims to be an intuitive and flexible application that can appeal to
newbies and professionals alike.
当前适配项目版本:
org.pitivi.harmony 0.1.0-alpha(HAP)
项目原生的技术栈包括:
- Python 3 + GTK 3(界面)
- GStreamer Editing Services(GES,多轨合成 / 转场 / 关键帧 / xges 持久化)
- GStreamer 插件体系(解码、编排、导出)
这个项目的关键特点是:编辑器最难的领域逻辑全在 GES 引擎里,而 UI 与引擎的耦合点是 Python/GTK。因此鸿蒙适配的取舍是:GES 引擎交叉编译保留,UI 层用 ArkUI 重写,两层之间以 NAPI 桥接的 C++ 原生内核衔接。这也决定了适配不能只做「HAP 打包」,而要同时处理交叉编译工具链、ArkTS 界面、NAPI 边界与鸿蒙 PC 运行时约束(如 fork/exec 受限、2in1 桌面窗口行为)。
全部构建、签名、安装、运行与验证均在鸿蒙 PC 本机完成:系统预装命令行工具包 hmos-clt(hvigor / ohpm / SDK / hdc),配合已登录华为开发者账号的 devecocli 完成签名,不需要额外的桌面开发机。
二、项目结构
.
├── pitivi/ # 原始 GNOME/GTK 源码(适配的行为规格参照)
├── pitivi-ohos/ # 鸿蒙 HAP 工程(本仓库的实际交付物)
│ ├── AppScope/ # 应用级配置(bundleName=org.pitivi.harmony)
│ ├── entry/
│ │ └── src/main/
│ │ ├── module.json5 # deviceTypes: ["2in1"]
│ │ ├── ets/ # ArkUI 编辑器界面(媒体库/预览/时间线/属性/GPU 面板)
│ │ └── cpp/ # pitivi_core C++ 原生内核 + GES 探针(NAPI 桥接)
│ ├── libs/arm64-v8a/ # 交叉编译的 GStreamer/GES 1.26.6 库(43 个插件)
│ ├── build-ohos/ # GStreamer/GES 依赖栈交叉编译脚本
│ ├── signing/ # 签名物料(不入库,用 devecocli 本地重生成)
│ ├── build-profile.json5 # HAP 构建与签名配置
│ └── hvigorfile.ts # hvigor 构建配置
├── docs/
│ ├── harmonyos-pc-adaptation-log.md # 完整适配日志(E1–E18 报错索引与证据)
│ └── harmonyos-pc/evidence/ # 构建日志、截图、GPU 审计、设备信息
└── README.OpenHarmony_CN.md # 本文档
一次安装包含两部分:「以最小改动跑通工程」——ArkUI 界面 + CPU 软件渲染内核 + NAPI 桥接(无需交叉编译产物即可构建);「引擎接入」——把交叉编译的 GStreamer/GES 栈放进 entry/libs/arm64-v8a/ 并打开 -DPITIVI_WITH_GES=ON,获得真实的多轨合成引擎。
三、环境要求
| 项 | 要求 | 说明 |
|---|---|---|
| 设备 | 鸿蒙 PC(2in1 形态),aarch64 | 实测 HUAWEI MateBook Pro,HarmonyOS 6.1.x |
| 命令行工具 | hmos-clt 1.0.0(系统预装) | hvigor / ohpm / SDK / hap-sign-tool / hdc |
| Node | hmos-clt 自带 v24.18.1 | 不要用系统 /data/service/hnp/bin/node(V8 崩溃,见 E11) |
| 签名 | devecocli(已登录华为开发者账号) | AGC 调试证书 + 本机 UDID profile |
| SDK 版本 | compatibleSdkVersion 6.1.0(23) / targetSdkVersion 6.1.1(24) | 对齐真机 |
| 设备类型 | 2in1 | 仅 PC 形态 |
| 交叉编译(可选) | Linux 容器 + OHOS Linux 工具链 + meson cross file | 仅 GES 引擎栈需要 |
四、编译与运行
1. 获取代码与依赖
git clone https://atomgit.com/OpenHarmonyPCDeveloper/ohos_pitivi.git
cd ohos_pitivi/pitivi-ohos
CLT=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0
export NODE_HOME=$CLT/node
export PATH=$CLT/node/bin:$PATH
export DEVECO_SDK_HOME=$CLT/sdk
node $CLT/ohpm/bin/ohpm install
2. 构建 HAP
node $CLT/hvigor/bin/hvigorw.js --mode module -p product=default assembleHap --no-daemon
构建包含 native CMake(clang + ninja 编译 pitivi_core.so)与 ArkTS 编译两段,BUILD SUCCESSFUL 即产出 entry/build/default/outputs/default/entry-default-signed.hap(未配置签名时为 entry-default-unsigned.hap)。
也可以用 DevEco Studio 打开 pitivi-ohos/ 目录:首次打开等待 Sync 完成,选择 2in1 真机后直接 Run,由 IDE 完成构建、签名与安装。
已知构建问题:
gst/gst.h: file not found(E13):PITIVI_WITH_GES=ON但交叉编译产物不在本机。先在entry/build-profile.json5切-DPITIVI_WITH_GES=OFF(UI + CPU 内核完整可用),待第四步产物就位后再打开;00305004 Syntax Error:build-profile.json5是 JSON5,注释只能用//。
3. 签名
推荐 devecocli(华为 AGC 调试证书),前提是已登录华为开发者账号:
~/devecocli/bin/devecocli auth status # Current user: hal****
cd pitivi-ohos
~/devecocli/bin/devecocli signature generate --force
# → AGC 调试证书 + 本机 UDID profile,signingConfigs 自动写入 build-profile.json5
之后重新执行第 2 步构建,hvigor 的 SignHap 任务自动完成签名。
离线
hap-sign-tool自建签名链路能产出格式合法的 HAP,但商用 HarmonyOS PC 只信任 AGC 签发的调试证书链(自建根 CA 安装时报code:9568257,E16–E18)。安装签名请直接用 devecocli。
4. 安装、启动与验证
HDC=$CLT/sdk/default/openharmony/toolchains/hdc
$HDC -t 127.0.0.1:39207 install -r \
entry/build/default/outputs/default/entry-default-signed.hap
# → install bundle successfully.
$HDC -t 127.0.0.1:39207 shell "aa start -a EntryAbility -b org.pitivi.harmony --ps demo play"
# → start ability successfully.
启动后用 hilog 验证运行状态与 GPU 策略:
PitiviOhos: main window maximized
PitiviOhos: core info: {...,"gpuAcceleration":"allowed","renderer":"CPU (software, default)"...}
PitiviOhos: gpu evidence: {"PITIVI_ENABLE_GPU":1,"eglDependency":true,...,"policy":"GPU allowed, CPU default"}
--ps demo 支持确定性的状态驱动(2in1 桌面坐标注入不可靠):play(播放)/ gpu(GPU 证据面板)/ edit(剪辑编辑)/ undo(撤销)/ ges(GES 引擎自检,需 GES 产物)。
注:部分 devecocli 调用会向 stderr 输出
Ensure the project source is trusted before proceeding.,或在结束时返回非零退出码,但日志中已打印App installed successfully/start ability successfully——这是提示级噪音,不是失败,以设备侧实际安装结果为准(hdc shell bm dump -a可查org.pitivi.harmony)。如 CI 需要严格退出码,改用devecocli build+hdc install+aa start分步执行。
五、如何完成 PC 适配
适配按实际操作顺序分十步完成,每一步做什么、遇到什么报错、怎么定位、改哪一层、如何确认生效,全部真实执行与留档。这里给出主干流程,完整命令与报错见 docs/harmonyos-pc-adaptation-log.md(E1–E18 报错索引)与 docs/harmonyos-pc/evidence/。
| 步骤 | 内容 | 关键结果 |
|---|---|---|
| 1. 准备开发环境 | hmos-clt 工具链、Node 版本坑(E11)、ohpm 依赖、设备与账号 | 本机即开发机 |
| 2. 创建工程骨架 | Stage 模型 HAP、deviceTypes: ["2in1"]、窗口 maximize() | 3120×2080 全屏界面 |
| 3. 原生内核与 NAPI 桥接 | pitivi_core C++ 内核、10 个 NAPI 接口、CPU 合成链路 | 960×540 单帧 12.4–21.9 ms |
| 4. 交叉编译 GStreamer/GES | Linux 容器 + OHOS 工具链 + meson cross file,GLib/GStreamer/GES 1.26.6 | 43 个插件,产物 81 MB |
| 5. GES 引擎真机自检 | --ps demo ges 分阶段日志 | pipeline PLAYING,播放到 2000 ms |
| 6. GPU 加速策略 | 从「四层强制关闭」改为「允许开启」,CPU 保留为默认路径 | 证据 JSON 如实上报 |
| 7. 构建 | hvigor 一键构建(native CMake + ArkTS) | 签名 HAP 28.4 MB |
| 8. 签名 | devecocli AGC 调试证书(自建 CA 不被设备信任,E16–E18) | SignHap 成功 |
| 9. 安装、启动与验证 | hdc install + aa start + hilog | install/start successfully |
| 10. 界面功能与截图验证 | snapshot_display 原生分辨率截图,未做图像编辑 | 证据见 evidence/ 01–16 |
几个在真机上实测得到的关键差异,供后续适配者参考:
- 2in1 桌面与手机形态差异大:窗口默认不最大化、坐标注入不可靠、
wm/uilist工具缺失,自动化验证改用 Ability 参数驱动; - HarmonyOS 限制 fork/exec:GStreamer 注册表扫描设
GST_REGISTRY_FORK=no,在应用进程内扫描; - 图像格式陷阱:
createPixelMapSync的srcPixelFormat默认是 BGRA_8888,不指定会红蓝互换。
以下按实际操作顺序分步详述每一步的做法与踩坑。
第一步:准备开发环境
系统已预装 hmos-clt 1.0.0,位于 /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0(下文记作 $CLT):
| 目录 | 内容 |
|---|---|
$CLT/hvigor | hvigor 构建工具(hvigorw.js) |
$CLT/ohpm | OpenHarmony 包管理器 |
$CLT/sdk/default/openharmony | SDK:ets / native(llvm clang + musl sysroot)/ toolchains(hdc)/ previewer |
$CLT/sdk/default/openharmony/toolchains/lib | hap-sign-tool 签名工具(musl aarch64 原生版) |
$CLT/node | 自带 Node.js v24.18.1 |
环境变量(每次构建前设置):
CLT=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0
export NODE_HOME=$CLT/node
export PATH=$CLT/node/bin:$PATH
export DEVECO_SDK_HOME=$CLT/sdk
Node 版本坑(E11,必读):直接用系统自带的 /data/service/hnp/bin/node(v24.13.0)运行 ohpm/hvigor 会立刻崩溃(报错 E11):
# Fatal error in , line 0
# Check failed: 12 == (*__errno_location()).
Signal 5 (core dumped)
定位:hnp 分发的 node 与 musl 环境的 V8 errno 断言不兼容。解决:全部 node 调用走 hmos-clt 自带的 v24.18.1,即上面的 NODE_HOME 写法。换掉之后 ohpm/hvigor 一切正常。
安装工程依赖与确认设备、账号:
cd pitivi-ohos
node $CLT/ohpm/bin/ohpm install
# install completed in 0s 115ms
# 本机即设备,hdc 回环目标
$CLT/sdk/default/openharmony/toolchains/hdc list targets
# 127.0.0.1:39207
# 设备 UDID(调试 profile 需要)
$CLT/sdk/default/openharmony/toolchains/hdc shell bm get --udid
# devecocli(已登录华为开发者账号)
~/devecocli/bin/devecocli auth status # Current user: hal****
第二步:创建工程骨架
工程是标准 Stage 模型 HAP 工程(pitivi-ohos/),三个关键配置决定它在鸿蒙 PC 上的形态。
entry/src/main/module.json5 —— 设备类型只保留 PC 形态:
"deviceTypes": [
"2in1"
]
pitivi-ohos/build-profile.json5 —— SDK 版本对齐真机(HarmonyOS 6.1.x):
targetSdkVersion: '6.1.1(24)',
compatibleSdkVersion: '6.1.0(23)',
runtimeOS: 'HarmonyOS'
entry/src/main/ets/entryability/EntryAbility.ets —— 2in1 桌面窗口默认不最大化,必须在窗口创建时显式处理(否则应用以浮动窗口启动,预览区偏小):
onWindowStageCreate(windowStage: window.WindowStage): void {
const mainWindow = windowStage.getMainWindowSync();
mainWindow.maximize()
.then(() => hilog.info(0x0000, TAG, 'main window maximized'));
windowStage.loadContent('pages/Index', ...);
}
hilog 确认 main window maximized 后,截图即为 3120×2080 全屏界面。
这一步在真机上实测得到三个与手机形态的重要差异:
- 坐标注入不可靠:桌面窗口坐标随窗口位置/层级变化,
uinput -T -c x y曾把别的窗口切到前台。自动化验证改用 Ability 参数驱动确定性状态:
hdc shell "aa force-stop org.pitivi.harmony"
hdc shell "aa start -a EntryAbility -b org.pitivi.harmony --ps demo play"
# demo=play|gpu|edit|undo|ges,页面通过 @StorageLink 读取后自行动作
- 手机侧工具缺失:
wm、uilist在 PC 版本上不存在。 - 截图工具:
/system/bin/snapshot_display输出原生分辨率 JPEG,配合hdc file recv回收。
脚手架残留清理(首次构建前):工程以已验证的 HAP 工程为脚手架复制而来,若混入上一项目的产物必须先清理——否则旧 .so 会被打进 HAP、lockfile 指向不存在的本地依赖导致 ohpm install 失败、.cxx 缓存沿用旧 target、多余的设备类型改变窗口行为:
- 删除
entry/.cxx/、entry/build/、.hvigor/、oh_modules/等缓存目录; - 删除不属于本工程的
entry/libs/旧原生库与entry/oh-package-lock.json5(由 hvigor 按新依赖重新生成); - 确认
module.json5的deviceTypes只保留2in1。
清理后 ohpm install 正常完成,C++ 编译目标只剩 pitivi_core。
第三步:编写原生内核与 NAPI 桥接
界面之下的核心是 C++ 原生内核 pitivi_core(entry/src/main/cpp/),负责 CPU 合成、时间线模型、撤销栈与证据上报。
内核接口设计——通过 NAPI 按「命令下行、证据上行」原则暴露 10 个接口:
| 接口 | 作用 |
|---|---|
coreInfo() | 内核信息 JSON(渲染后端 / GPU 状态 / 帧规格) |
gpuEvidence() | GPU 状态证据 JSON(见第六步) |
composeFrame(frame, w, h) | CPU 合成一帧,返回 RGBA ArrayBuffer |
lastRenderMs() | 上一帧合成耗时(ms) |
timelineJson() | 时间线快照(剪辑 / 轨道 / 播放头 / 撤销重做计数) |
editClip(id, start) | 移动剪辑(写入撤销栈,清空重做栈) |
undo() / redo() | 撤销 / 重做,返回新快照 |
seek(frame) | 播放头定位(钳制到总帧数) |
resetDemo() | 重置演示工程 |
CPU 软件渲染链路:
C++ ComposeRgba() → RGBA8 ArrayBuffer(960×540,逐像素 CPU 循环 + alpha 混合)
│ napi_create_arraybuffer
▼
ArkTS image.createPixelMapSync(buffer, { srcPixelFormat: RGBA_8888, pixelFormat: RGBA_8888 })
▼
ArkUI Image(pixelMap)
这里有个必须显式处理的格式陷阱:createPixelMapSync 的 srcPixelFormat 默认是 BGRA_8888,不指定就会红蓝互换——这是实现时真实踩到的坑,颜色条顺序正确即为修复生效的证据。
合成耗时由 std::chrono 在 C++ 内统计,经 lastRenderMs() 回传,真机实测 960×540 单帧 12.4–21.9 ms(单线程、未优化)。
CMake 门控:
add_library(pitivi_core SHARED pitivi_core.cpp ges_probe.cpp)
option(PITIVI_WITH_GES "Link the cross-compiled GStreamer + GES stack" OFF)
option(PITIVI_ENABLE_GPU "Link EGL/GLES/native_window so GPU paths can be used" ON)
if(PITIVI_ENABLE_GPU)
target_compile_definitions(pitivi_core PUBLIC PITIVI_ENABLE_GPU=1)
target_link_libraries(pitivi_core PUBLIC libEGL.so libGLESv3.so libnative_window.so)
endif()
target_link_libraries(pitivi_core PUBLIC libace_napi.z.so hilog_ndk.z)
第四步:交叉编译 GStreamer/GES 引擎
编辑器最难的部分(多轨合成、帧精确、转场、关键帧、xges 持久化)全在 GES 里,因此引擎层选择交叉编译保留 GES 1.26.6,而不是重写。
编译需要一个 Linux 构建环境(鸿蒙 PC 上通过容器使用,任何能跑容器/虚拟机的宿主机均可复用此流程)+ OHOS Linux 工具链 + meson cross file:
# 启动构建容器,挂载 OHOS SDK(Linux 版 native 工具链)与仓库目录
docker run -d --name pitivi-ohos-build \
-v "<ohos_sdk>:/ohos_sdk:ro" -v "<仓库目录>:/work" ubuntu:24.04 sleep infinity
docker exec pitivi-ohos-build bash -lc \
"apt-get update -qq && apt-get install -y -qq build-essential ninja-build pkg-config \
python3 python3-pip git curl xz-utils bison flex gettext autoconf automake \
libtool cmake file && python3 -m pip install --break-system-packages -q meson"
cd /work/pitivi-ohos/build-ohos
bash build_deps.sh # 依赖栈(幂等,带 stamp 断点续建)
bash build_good.sh # gst-plugins-good
bash fix_symlinks.sh && bash collect_libs.sh
依赖版本与关键构建参数:
| 库 | 版本 | 关键构建参数 |
|---|---|---|
| zlib / libffi / pcre2 / libxml2 / orc | 1.3.1 / 3.4.6 / 10.44 / 2.13.5 / 0.4.40 | 基础依赖 |
| GLib/GObject/GIO | 2.84.4 | introspection=disabled libmount=disabled selinux=disabled nls=disabled |
| GStreamer core / base | 1.26.6 | introspection=disabled;base:gl=disabled x11=disabled alsa=disabled pango=disabled |
| gst-plugins-good | 1.26.6 | auto_features=disabled,仅启用 GES 必需的 videoflip/videobox/videocrop/alpha/level/autodetect/audioparsers/matroska/isomp4/wavparse/wavenc 等 |
| GES | 1.26.6 | introspection=disabled tests/examples/doc=disabled |
真实踩到的坑(E1–E9 精选,完整记录见适配日志):
config.sub aarch64-linux-ohos failed(E1):GNU config.sub 不认识 ohos 段。autotools 系统一改用--host=aarch64-linux,编译器 wrapper 强制--target=aarch64-linux-ohos。- libffi configure 失败(E2):multi-os configure 在交叉场景失效,加
--disable-builddir源码内构建。 - meson option 不存在(E3):gst-plugins-base 1.26 已移除
glx/wayland/vulkan选项,报Unknown option,按meson_options.txt实际可选项收敛参数。 - 容器产物 0 字节(E4):Docker bind mount 对容器内符号链接表现为 0 字节,
fix_symlinks.sh解引用 +collect_libs.sh用cp -L。 - 头文件路径(E5):CMake 中
PITIVI_OHOS_PREFIX少退一级导致gst/gst.h: file not found,改为四级回退。 - GES 1.26 API 与旧记忆不一致(E6/E7):改用
GES_VERSION_MAJOR/MINOR、GES_TRACK()、GES_CLIP();ges_layer_add_clip自 1.18+ 返回gboolean。 - 真机 SIGSEGV(E8):GES 视频源链需要
videoflip,它在 plugins-good 里;漏构建导致 factory 返回 NULL 直接崩溃。补建后插件数由 28 升至 43。 - 清理阶段 SIGSEGV(E9):GES/NLE 在 musl 下 teardown 崩溃,探针改为「单次运行 + 不销毁 pipeline」规避(保留泄漏有界)。
产物落 pitivi-ohos/build-ohos/prefix/(共享库 + lib/gstreamer-1.0 42 个插件),收集进 HAP 的 entry/libs/arm64-v8a/。
平台运行时约束:
- HarmonyOS 限制 fork/exec:GStreamer 注册表扫描设
GST_REGISTRY_FORK=no,在应用进程内扫描;注册表缓存写入应用 cacheDir,失败退化为内存注册表; - 危险探针放在按钮/演示参数之后,不放启动路径——崩溃不能拖垮 UI。
第五步:GES 引擎真机自检
产物就位后,在 entry/build-profile.json5 打开 -DPITIVI_WITH_GES=ON 重新构建,用 --ps demo ges 触发 headless 自检。分阶段日志(evidence/12-ges-selftest.log):
PITIVI_GES stage=gst_init value=43
PITIVI_GES stage=factories value=1111 # videotestsrc/compositor/audiomixer/nle 均存在
PITIVI_GES stage=ges_init value=1
PITIVI_GES stage=timeline_new value=1
PITIVI_GES stage=after_add_clip value=1
PITIVI_GES stage=pipeline_ready value=1
PITIVI_GES stage=position value=2000
JSON 汇总:43 个插件注册成功、GES TestClip 加入时间线、pipeline 进入 ASYNC/PLAYING 并播放到 2000ms(整段 2 秒时长)。

第六步:GPU 加速从「强制关闭」到「允许」
最初的设计决策是把 GPU 加速在四个层面强制关闭(编译宏、ELF 依赖、运行时证据、UI 面板),防止通过运行时开关悄悄打开。本轮按需求改为「允许开启」,四个层面同步变更:
| 层面 | 原做法 | 现做法 |
|---|---|---|
| CMake | PITIVI_ENABLE_GPU=0,注释声明 never link EGL | option(PITIVI_ENABLE_GPU ... ON),链接 libEGL.so/libGLESv3.so/libnative_window.so |
| C++ | gpuEvidence() 硬编码 gpuAcceleration:false | 上报 policy:"GPU allowed, CPU default";sysroot 已确认存在 libEGL/libGLESv3/libnative_window/libvulkan |
| ELF | readelf 验证无图形依赖 | 开启后按需包含图形库依赖 |
| UI | GPU OFF 徽标 | GPU READY 徽标,状态面板「允许(默认 CPU)/ 可链接 / 可用」 |
需要强调:GPU 开关不是「翻一个开关」。解除禁止只是让构建允许链接图形库、证据链如实上报;真正的 GPU 渲染还需要实现 XComponent/OHNativeWindow 承载与 GPU 合成器。因此当前 CPU 软件渲染(960×540 合成 12–22 ms/帧)仍是默认预览路径。
第七步:构建
本机一键构建:
node $CLT/hvigor/bin/hvigorw.js --mode module -p product=default assembleHap --no-daemon
构建包含 native CMake(clang + ninja 编译 pitivi_core.so)与 ArkTS 编译两段,BUILD SUCCESSFUL 即产出 entry-default-signed.hap(未配置签名时为 entry-default-unsigned.hap)。
两个已知报错:
gst/gst.h: file not found(E13):PITIVI_WITH_GES=ON但build-ohos/prefix交叉编译产物不在本机。解决:先切-DPITIVI_WITH_GES=OFF(UI + CPU 内核完整可用),待第四步产物就位后再打开。00305004 Syntax Error:build-profile.json5是 JSON5,注释只能用//,写#直接构建失败。
产物体积参考:接入 GES 栈后签名 HAP 28.4 MB(libs/ 收集 81 MB,含重复副本可再裁剪)。
其它实测注意点:
- 双 ABI 导致体积翻倍:默认产物包含
arm64-v8a与x86_64两套libpitivi_core.so;在entry/build-profile.json5的externalNativeOptions.abiFilters中只保留arm64-v8a可直接减半(需要模拟器时再按需加回); - clang 警告可忽略:
argument unused during compilation: '--gcc-toolchain=...'是构建模板固定传入的参数,OHOS clang 使用自带 sysroot,参数未使用属正常,不影响产物(BUILD SUCCESSFUL)。
第八步:签名
安装 HAP 必须签名。推荐路径是 devecocli(华为 AGC 调试证书),前提是已登录华为开发者账号:
~/devecocli/bin/devecocli auth status # Current user: hal****
cd pitivi-ohos
~/devecocli/bin/devecocli signature generate --force
# → AGC 调试证书 + 本机 UDID profile
# → Profile covers 1 device(s): F9E5...48C7 (detected)
# → signingConfigs 自动写入 build-profile.json5
之后重新执行第七步构建,hvigor 的 SignHap 任务自动完成签名。
离线
hap-sign-tool自建签名链路(generate-keypair→generate-ca→generate-app-cert→sign-profile→sign-app)可以产出格式完全合法的签名 HAP(sign-app success),其中 profile JSON 必须是官方 HarmonyAppProvision 结构、development-certificate必须是 PEM 文本、-appCertFile必须是证书链且必须带-signCode 1(详细记录见适配日志 §10.4、E16/E17)。但自建根 CA 签名的 HAP 安装时仍报code:9568257 fail to verify pkcs7 file——商用 HarmonyOS PC 只信任 AGC 签发的调试证书链。所以安装签名请直接用 devecocli。
签名物料管理(实测得到的约束):
- devecocli 生成的
signingConfigs含本机 keystore 路径与加密口令,不可提交:.gitignore已忽略signing/、*.hap、build/;若需入库build-profile.json5,提交前把signingConfigs清空为[],由使用者本地执行devecocli signature generate重新生成; - 换构建环境后 hvigor 签名报
Invalid storeFile value(E14):signingConfigs 仍指向旧环境的 keystore 路径——清空signingConfigs后重新执行devecocli signature generate即可; - hvigor 内置签名要求 keystore 密码为 DevEco 加密密文(长度 ≥32),明文密码不被接受,因此命令行链路用「未签名 HAP + 构建后签名工具」组合。
第九步:安装、启动与验证
HDC=$CLT/sdk/default/openharmony/toolchains/hdc
$HDC -t 127.0.0.1:39207 install -r \
entry/build/default/outputs/default/entry-default-signed.hap
# → install bundle successfully.
$HDC -t 127.0.0.1:39207 shell "aa start -a EntryAbility -b org.pitivi.harmony --ps demo play"
# → start ability successfully.
启动后用 hilog 验证运行状态与 GPU 策略:
PitiviOhos: Ability onCreate demo=
PitiviOhos: main window maximized
PitiviOhos: core info: {...,"gpuAcceleration":"allowed","renderer":"CPU (software, default)"...}
PitiviOhos: gpu evidence: {"PITIVI_ENABLE_GPU":1,"eglDependency":true,"glesDependency":true,
"vulkanDependency":false,"nativeWindowDependency":true,...,"policy":"GPU allowed, CPU default"}
第十步:界面功能与截图验证
编辑器界面各区域:左侧媒体库、中部 CPU 合成预览 + 传输控制、右侧剪辑属性 + GPU 状态面板、下方 Canvas 时间线(双轨 + 播放头 + 选中态)、底部状态栏(渲染后端 / GPU 状态 / 规格)。
主界面(默认状态,浮动窗口 + 系统任务栏):媒体库 3 素材、SMPTE 彩条 + 移动叠加层预览、GPU 状态面板、双轨时间线 + 波形 + 播放头;截图包含底部系统任务栏(时间 / 电量 / 音量):

GPU 证据面板:展开原生内核返回的 gpuEvidence JSON,底部状态栏同步显示 GPU 状态:

播放中:--ps demo play 驱动,按钮变暂停、帧计数推进、状态 PLAYING、预览时间码与合成耗时实时更新:

剪辑移动后撤销:--ps demo undo,先把剪辑移动到 00:02.000 再撤销——剪辑恢复原位、「重做」变为可用,验证软件编辑内核 + 撤销栈:

GES 引擎自检(--ps demo ges,需第四步产物 + PITIVI_WITH_GES=ON):

所有截图来自真机 snapshot_display(原生分辨率),经 hdc file recv 回收,未做任何图像合成/编辑。更多构建日志、GPU 审计、设备信息等证据见 docs/harmonyos-pc/evidence/(01–18 号文件,含 SHA256 与完整日志)。
截图要求(重新截图时必须遵守):
- 隐藏其他窗口,只保留应用窗口:2in1 桌面是自由多窗口,
snapshot_display截的是整个桌面。截图前先aa force-stop掉可见的其它应用(HiSH 终端、应用市场等),再aa start启动本应用并maximize(),确保画面中只有 Pitivi 一个应用窗口(此前的遮挡问题见适配日志 §5.2); - 必须带上系统状态栏:截图需包含屏幕顶部的 HarmonyOS 系统状态栏(时间 / 电量 / 信号),用于证明是真实设备运行,而非应用内自绘画面;
# 重新截图的标准流程(devecocli)
CLI=~/devecocli/bin/devecocli
$CLI device list # 确认设备(本机回环 127.0.0.1:39207)
$CLI ui window list --device 127.0.0.1:39207 # 确认除系统外只有 Pitivi 一个应用窗口
$CLI shell "aa force-stop <其他应用包名>" # 逐个隐藏其它窗口
$CLI shell "aa force-stop org.pitivi.harmony"
$CLI shell "aa start -a EntryAbility -b org.pitivi.harmony --ps demo play"
$CLI ui screenshot --device 127.0.0.1:39207 --path shot.jpeg # 全屏截取,含系统状态栏
# 备选:系统自带 snapshot_display(devecocli ui screenshot 不可用时)
# $CLT/sdk/default/openharmony/toolchains/hdc shell "snapshot_display -f /data/local/tmp/shot.jpeg"
六、改动了哪些代码
一个重要事实:仓库中原有的 GNOME/GTK Pitivi 源码(pitivi/ 目录)一行未改,仅作为适配的行为规格参照;全部适配代码都在新增的 pitivi-ohos/ 鸿蒙工程里。下面按文件把关键代码贴出来。
7.1 ArkUI 界面与 Ability(entry/src/main/ets/)
entryability/EntryAbility.ets——demo 启动参数驱动确定性状态(2in1 桌面坐标注入不可靠的工程化替代),以及 2in1 桌面必需的窗口最大化:
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// Demo hook: `aa start ... --ps demo play|gpu|edit|undo`
// Lets CI / screenshots drive deterministic states without UI automation.
let demo: string = '';
const parameters = want.parameters;
if (parameters !== undefined) {
const value = parameters['demo'];
if (typeof value === 'string') {
demo = value;
}
}
AppStorage.setOrCreate<string>('demoMode', demo);
hilog.info(0x0000, TAG, 'Ability onCreate demo=%{public}s', demo);
}
onWindowStageCreate(windowStage: window.WindowStage): void {
// PC/2in1: a video editor is expected to be maximized on launch.
const mainWindow = windowStage.getMainWindowSync();
mainWindow.maximize().then(() => {
hilog.info(0x0000, TAG, 'main window maximized');
}).catch((error: BusinessError) => {
hilog.warn(0x0000, TAG, 'maximize failed: %{public}s', JSON.stringify(error));
});
windowStage.loadContent('pages/Index', ...);
}
pages/Index.ets——页面通过 @StorageLink 读取 demo 参数后自行动作:
@StorageLink('demoMode') demoMode: string = '';
module.json5——设备类型只保留 PC 形态:
"deviceTypes": [
"2in1"
]
7.2 C++ 原生内核(entry/src/main/cpp/)
pitivi_core.cpp——CPU 逐像素合成(SMPTE 彩条 + 移动叠加层 + 棋盘格 + 进度条):
void ComposeRgba(int frame, int width, int height, uint8_t *pixels) {
const auto begin = std::chrono::steady_clock::now();
const double seconds = static_cast<double>(frame) / static_cast<double>(kFps);
// Simulated V1 clip: SMPTE-like colour bars.
static const double kBarColors[7][3] = {
{192.0, 192.0, 192.0}, {192.0, 192.0, 0.0}, {0.0, 192.0, 192.0}, {0.0, 192.0, 0.0},
{192.0, 0.0, 192.0}, {192.0, 0.0, 0.0}, {0.0, 0.0, 192.0},
};
// Simulated V2 overlay: a soft highlight moving over the frame.
const double circle_x = 0.38 + 0.28 * std::sin(seconds * 1.25);
const double circle_y = 0.30 + 0.12 * std::cos(seconds * 0.85);
// ... 逐像素循环:彩条着色 + alpha 混合 + 棋盘格 + CPU 进度条
}
pitivi_core.cpp——NAPI 按「命令下行、证据上行」暴露 10 个接口(节选):
napi_property_descriptor desc[] = {
{"coreInfo", nullptr, CoreInfo, nullptr, nullptr, nullptr, napi_default, nullptr},
{"gpuEvidence", nullptr, GpuEvidence, nullptr, nullptr, nullptr, napi_default, nullptr},
{"composeFrame", nullptr, ComposeFrame, nullptr, nullptr, nullptr, napi_default, nullptr},
{"lastRenderMs", nullptr, LastRenderMs, nullptr, nullptr, nullptr, napi_default, nullptr},
{"timelineJson", nullptr, TimelineJson, nullptr, nullptr, nullptr, napi_default, nullptr},
{"gesSelfTest", nullptr, GesSelfTest, nullptr, nullptr, nullptr, napi_default, nullptr},
{"editClip", nullptr, EditClip, nullptr, nullptr, nullptr, napi_default, nullptr},
{"undo", nullptr, Undo, nullptr, nullptr, nullptr, napi_default, nullptr},
{"redo", nullptr, Redo, nullptr, nullptr, nullptr, napi_default, nullptr},
{"seek", nullptr, Seek, nullptr, nullptr, nullptr, napi_default, nullptr},
// ...
};
ges_probe.cpp——GES headless 自检;HarmonyOS 限制 fork/exec,注册表扫描改在应用进程内进行:
// HarmonyOS restricts fork/exec: scan plugins in-process instead of forking.
setenv("GST_REGISTRY_FORK", "no", 0);
std::string json = "{\"available\":true";
GError *error = nullptr;
if (!gst_init_check(nullptr, nullptr, &error)) {
json += ",\"gstInit\":false,\"error\":\"";
// ...
自检按「单次运行、不销毁 pipeline」规避 musl 下 GES/NLE teardown 崩溃(E9),分阶段打点:
PITIVI_GES stage=gst_init value=43
PITIVI_GES stage=factories value=1111
PITIVI_GES stage=ges_init value=1
PITIVI_GES stage=timeline_new value=1
PITIVI_GES stage=after_add_clip value=1
PITIVI_GES stage=pipeline_ready value=1
PITIVI_GES stage=position value=2000
CMakeLists.txt——两个 option 门控:是否链接交叉编译的 GES 栈、是否允许 GPU 图形库:
add_library(pitivi_core SHARED pitivi_core.cpp ges_probe.cpp)
option(PITIVI_WITH_GES "Link the cross-compiled GStreamer + GES stack" OFF)
option(PITIVI_ENABLE_GPU "Link EGL/GLES/native_window so GPU paths can be used" ON)
set(PITIVI_OHOS_PREFIX "${CMAKE_CURRENT_SOURCE_DIR}/../../../../build-ohos/prefix")
if(PITIVI_WITH_GES)
target_include_directories(pitivi_core PRIVATE
"${PITIVI_OHOS_PREFIX}/include"
"${PITIVI_OHOS_PREFIX}/include/glib-2.0"
"${PITIVI_OHOS_PREFIX}/lib/glib-2.0/include"
"${PITIVI_OHOS_PREFIX}/include/gstreamer-1.0"
"${PITIVI_OHOS_PREFIX}/include/gst-editing-services-1.0"
"${PITIVI_OHOS_PREFIX}/include/libxml2")
target_link_directories(pitivi_core PRIVATE "${PITIVI_OHOS_PREFIX}/lib")
target_link_libraries(pitivi_core PUBLIC
ges-1.0 gstreamer-1.0 gstbase-1.0 gstvideo-1.0 gstaudio-1.0
gstapp-1.0 gstpbutils-1.0 gsttag-1.0 gobject-2.0 gio-2.0 gmodule-2.0 glib-2.0 xml2)
endif()
if(PITIVI_ENABLE_GPU)
target_compile_definitions(pitivi_core PUBLIC PITIVI_ENABLE_GPU=1)
target_link_libraries(pitivi_core PUBLIC libEGL.so libGLESv3.so libnative_window.so)
else()
target_compile_definitions(pitivi_core PUBLIC PITIVI_ENABLE_GPU=0)
endif()
target_link_libraries(pitivi_core PUBLIC libace_napi.z.so hilog_ndk.z)
types/libpitivi_core/index.d.ts——NAPI 接口的 ArkTS 类型声明:
export const coreInfo: () => string;
export const gpuEvidence: () => string;
export const composeFrame: (frame: number, width: number, height: number) => ArrayBuffer;
export const lastRenderMs: () => number;
export const timelineJson: () => string;
export const gesSelfTest: (cacheDir: string) => string;
export const editClip: (id: string, startFrame: number) => string;
export const undo: () => string;
export const redo: () => string;
export const seek: (frame: number) => number;
export const resetDemo: () => string;
7.3 构建与工程配置
entry/build-profile.json5——CMake 参数门控 GES,abiFilters 只保留 arm64(双 ABI 会使 HAP 体积翻倍):
"externalNativeOptions": {
"path": "./src/main/cpp/CMakeLists.txt",
"arguments": "-DPITIVI_WITH_GES=OFF",
"abiFilters": [
"arm64-v8a"
]
}
pitivi-ohos/build-profile.json5——SDK 版本对齐真机;signingConfigs 由 devecocli 本地生成、提交前清空为 []:
targetSdkVersion: '6.1.1(24)',
compatibleSdkVersion: '6.1.0(23)',
runtimeOS: 'HarmonyOS'
AppScope/app.json5——应用标识:
"bundleName": "org.pitivi.harmony"
7.4 交叉编译脚本(build-ohos/)
meson-cross-aarch64-ohos.txt——meson cross file 用 aarch64-linux host 绕开 GNU config.sub 不识别 ohos 段的问题(E1),编译器 wrapper 强制 --target=aarch64-linux-ohos:
[binaries]
c = 'aarch64-linux-ohos-clang'
cpp = 'aarch64-linux-ohos-clang++'
ar = 'llvm-ar'
strip = 'llvm-strip'
[host_machine]
system = 'linux'
cpu_family = 'aarch64'
cpu = 'aarch64'
endian = 'little'
build_deps.sh / build_good.sh——GLib/GStreamer/GES 依赖栈交叉编译(幂等、带 stamp 断点续建),关键参数如:
# GStreamer base: GPU 路径全部关闭
meson setup build . \
-Dgl=disabled -Dx11=disabled -Dalsa=disabled -Dpango=disabled \
-Dintrospection=disabled
# gst-plugins-good: auto_features=disabled,仅启用 GES 必需插件
meson setup build . \
-Dauto_features=disabled \
-Dvideofilter=enabled -Dvideobox=enabled -Dvideocrop=enabled \
-Dalpha=enabled -Dlevel=enabled -Dautodetect=enabled \
-Daudioparsers=enabled -Dmatroska=enabled -Disomp4=enabled ...
fix_symlinks.sh / collect_libs.sh——容器产物符号链接解引用(E4)与 cp -L 收集落盘,最终 entry/libs/arm64-v8a/ 81 MB(签名 HAP 28.4 MB)。
各文件的完整实现与踩坑经过,见前文十步详述与 docs/harmonyos-pc-adaptation-log.md。
七、迁移能力(T0 / T1 / T2)
适配情况不是「能用/不能用」两个极端,而是按 T0 基础能力(能不能编、能不能装、能不能起、能不能渲染)、T1 主要能力(视频编辑器的日常核心功能)、T2 增强能力(桌面端的加分项)三档如实标注。
表里的结论取自适配日志的真机实测证据,状态分三种:
- 能用:在真机上实际操作过,并有可复核的证据(构建输出、日志、截图)。
- 待验证:只给出做法或计划,尚未给出实测结论。
- 未适配:按当前阶段尚未实现的能力,属于明确的下一步工作项,不是隐藏缺陷。
T0 基础能力(能不能编、能不能装、能不能起、能不能渲染)
| 能力 | 状态 | 依据 |
|---|---|---|
| 原生 C++ 内核与 GStreamer/GES 交叉编译 | 能用 | GLib/GStreamer/GES 1.26.6 交叉编译为 aarch64-linux-ohos,43 个插件真机注册 |
| HAP 打包与签名 | 能用 | hvigor BUILD SUCCESSFUL + devecocli AGC 调试证书签名,SignHap 成功 |
| 鸿蒙 PC 本机构建 | 能用 | 系统预装 hmos-clt(hvigor/ohpm/SDK/hdc),本机即开发机 |
| 真机安装与启动 | 能用 | install bundle successfully + start ability successfully,E18 验签问题已由 AGC 证书解除 |
| ArkUI 编辑器界面加载与渲染 | 能用 | 媒体库、预览、属性面板、双轨时间线、状态栏均可见(3120×2080 全屏) |
| CPU 软件渲染预览 | 能用 | RGBA8888 → PixelMap 链路,960×540 单帧 12.4–21.9 ms(实测) |
| 页面与原生 NAPI 桥接 | 能用 | 10 个 NAPI 接口全部接通 |
| GPU 加速策略 | 能用(CPU 默认) | PITIVI_ENABLE_GPU=1 允许开启,CPU 软件渲染为默认路径;真机 GPU 证据 JSON 如实上报 |
T1 主要能力(视频编辑器的日常核心)
| 能力 | 状态 | 依据 |
|---|---|---|
| GES 引擎真机运行 | 能用 | GES TestClip 加入时间线,pipeline 进入 ASYNC/PLAYING 并播放到 2000 ms |
| 时间线编辑与撤销/重做 | 能用 | --ps demo undo 移动剪辑后撤销恢复原位,软件编辑内核 + 撤销栈真机验证 |
| 真实媒体解码预览(OH_AVCodec 软解) | 未适配 | 当前预览是 CPU 合成演示帧,非真实视频解码(日志 §8 下一步第 2 项) |
| xges 工程打开/保存 | 未适配 | GES XmlFormatter 对接尚未开始 |
| 剪辑导出(encodebin → MP4/WebM) | 未适配 | 下一步工作项 |
| 真实媒体库导入 | 未适配 | 媒体库当前为 3 个演示素材 + 软件探测标注 |
T2 增强能力(桌面端的加分项)
| 能力 | 状态 | 依据 |
|---|---|---|
| GPU 合成预览(XComponent/OHNativeWindow 承载) | 未适配 | 构建已允许链接图形库,真正的 GPU 渲染需实现承载与 GPU 合成器(工作项,非开关) |
| 拖拽/trim 手势编辑 | 未适配 | Canvas 时间线已有播放头/选中/缩放,拖拽、trim、框选手势未做 |
| 500 clip 时间线压测 / 多线程合成 | 未适配 | 下一步工作项 |
这里不折算百分比:每一项都对应适配日志中的实测证据或明确的取舍/计划说明;缺实测证据的项如实标为「未适配」,不用估算把表补满。
八、与原版差异(如实说明)
- 界面为 ArkUI 重写,不是 GTK 版原样运行:布局与功能对标 Pitivi(媒体库 / 预览 / 时间线 / 属性 / 状态栏),交互细节以适配后的实现为准;
- 预览为 CPU 软件渲染:当前是 CPU 合成演示帧;真实媒体解码、GPU 合成预览为明确的工作项;
- 没有隐藏不兼容:所有已知差异(GPU 策略、签名方式、2in1 桌面差异、GES teardown 规避等)均在适配日志中如实记录,未适配的能力是明确的下一步工作项,而不是「宣称已迁移」。
一句话总结:ohos_pitivi 已在鸿蒙 PC 本机完成「构建 → AGC 签名 → 安装 → 启动 → 界面渲染」全链路验证,GES 1.26.6 引擎真机自检通过,时间线编辑与撤销在演示数据上跑通;真实媒体解码、xges 持久化与导出是明确的下一步工作项。
更多推荐



所有评论(0)