# HelloAVCodec

**Repository Path**: westyao/hello-avcodec

## Basic Information

- **Project Name**: HelloAVCodec
- **Description**: No description available
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-02-14
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
 
# HelloAVCodec
</br>
 
![star](https://gitcode.com/HelloAVCodec/hello-avcodec/star/badge.svg)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![Static Badge](https://img.shields.io/badge/av_codec-link-blue?style=flat&logoColor=blue)](https://gitcode.com/openharmony/multimedia_av_codec)

</div>


一个基于 HarmonyOS Stage UI 的多媒体演示工程。它把 ArkTS 页面、原生 C++ NAPI 桥接和嵌入式 `sample_framework` runtime 组合在一起，既能做传统播放器演示，也能做可视化 pipeline 组装、预览和导出。

## 项目目标

- 提供一个可运行的 AVCodec 播放示例。
- 提供一个面向 DAG 的 Pipeline Builder，用图形化方式组装媒体处理链路。
- 复用同一套 native runtime，同时支持播放型 pipeline 和 producer/export 型 pipeline。
- 为后续新增节点、设置项、导出能力和测试用例保留清晰边界。

## 当前能力

### 1. Player 工作流

- 从导航页进入播放器页面。
- 默认使用内置测试视频 `TestVideo_hevc_600k_1I.mp4`。
- 支持 URI、本地文件、导出文件作为输入。
- 支持播放、停止、暂停/恢复、倍速、步进模式。
- 支持查看 demuxer/container、track 和 codec format 信息。
- 支持通过设置弹窗切换 pipeline preset 和解码器色彩空间转换选项。

### 2. Pipeline Builder 工作流

- 从导航页进入 Builder 页面。
- 支持拖拽节点到画布、自动追加/插入、连线、断线、删除节点。
- 支持画布缩放、平移、Fit to graph。
- 支持节点配置编辑和预览面板。
- 支持将草稿导出到应用沙箱，再从沙箱重新导入。
- 支持运行播放型 DAG，也支持导出型 producer graph。

### 3. 已接入的节点

- Source
  - `Demuxer`
  - `CameraInput`
- Decode
  - `VideoDecoder`
  - `AudioDecoder`
- Render
  - `Renderer`
  - `AudioRenderer`
- Encode / Export
  - `VideoEncoder`
  - `Muxer`

节点目录和默认字段定义见 `AVCodecDemo/src/main/ets/pipelinebuilder/models/NodeCatalog.ets`。

## 架构概览

运行主链分成四层：

1. ArkTS 页面层
   - `AVCodecDemo/src/main/ets/pages/NavigationPage.ets`
   - `AVCodecDemo/src/main/ets/pages/PlayerPage.ets`
   - `AVCodecDemo/src/main/ets/pages/PipelineBuilderPage.ets`
2. ArkTS 状态与序列化层
   - `AVCodecDemo/src/main/ets/settings/`
   - `AVCodecDemo/src/main/ets/pipelinebuilder/state/`
   - `AVCodecDemo/src/main/ets/pipelinebuilder/serialization/`
3. NAPI 桥接层
   - `AVCodecDemo/src/main/cpp/types/libavcodecdemo/Index.d.ts`
   - `AVCodecDemo/src/main/cpp/napi_wrapper/player_napi.cpp`
   - `AVCodecDemo/src/main/cpp/napi_wrapper/sample/sample_napi_wrapper.cpp`
4. Native runtime 层
   - `AVCodecDemo/src/main/cpp/sample_framework/test/unittest/video_test/video_test/`

核心调用关系：

- Player:
  - `PlayerPage -> libavcodecdemo.so.Play(...) -> player_napi.cpp -> PlayerSession -> PipelineGraph/PipelineManager`
- Builder:
  - `PipelineBuilderPage -> PipelineBuilderStore.runPayload() -> PipelineDraftSerializer -> PipelineBuilderRuntime.run(...) -> libavcodecdemo.so.Play(...)`

## 仓库结构

```text
.
├─ AppScope/                               # 应用级清单和资源
├─ AVCodecDemo/
│  ├─ src/main/ets/                        # ArkTS 页面、组件、状态、设置
│  ├─ src/main/cpp/                        # NAPI、surface wrapper、native runtime 接入
│  ├─ src/main/resources/                  # 页面资源、rawfile、预置 pipeline
│  ├─ src/test/                            # 本地 ArkTS 单测
│  └─ src/ohosTest/                        # 设备侧 UI/集成测试
├─ scripts/bootstrap.ps1                   # 安装依赖并构建
├─ build-profile.json5                     # 产品、签名和 SDK 配置
└─ hvigorfile.ts                           # Hvigor 入口
```

## 关键模块说明

### 页面与入口

- `NavigationPage` 是双入口导航页。
- `PlayerPage` 负责播放、媒体信息查看、设置和手动控制。
- `PipelineBuilderPage` 负责图形化编辑、运行、导入导出和预览。

### Player 设置系统

Player 设置采用 spec-driven 结构：

- `AVCodecDemo/src/main/ets/settings/PlayerSettingsSpec.ets`
  - 设置 key、分组、默认值、枚举选项和 payload 映射的单一事实源
- `AVCodecDemo/src/main/ets/components/SettingsItems.ets`
  - 可复用的设置项 UI 组件
- `AVCodecDemo/src/main/ets/settings/README.md`
  - 更细的设置系统说明

### Builder 状态与文件

- `PipelineBuilderStore` 管理编辑态 draft、连线规则、运行前校验和 runtime payload。
- `PipelineDraftSerializer` 将 port-aware 画布模型压缩成 native 可运行的 `graph.nodes + graph.edges`。
- `PipelineBuilderDraftFiles` 负责草稿文件目录和读写。
- `PipelineBuilderProducerFiles` 负责导出文件目录和文件名校验。

### Native 桥接与运行时

- `Index.d.ts` 定义 ArkTS-visible 的 native contract。
- `player_napi.cpp` 负责：
  - `Play / Stop / StopAsync`
  - `GetMediaInfo / GetCodecFormat`
  - `SetPlaybackSpeed / SetStepMode / SetPaused`
  - EOS callback 与 session 生命周期
- `sample_framework` 负责实际 DAG 执行、节点连接、媒体解复用、解码、渲染和导出。

## 数据与文件约定

- 内置测试视频：
  - `AVCodecDemo/src/main/resources/rawfile/TestVideo_hevc_600k_1I.mp4`
  - 首次运行时会复制到应用沙箱，逻辑在 `AVCodecDemo/src/main/ets/shared/BundledTestVideo.ets`
- Player 预置 pipeline：
  - `AVCodecDemo/src/main/resources/rawfile/pipelines/player_default.json`
  - `AVCodecDemo/src/main/resources/rawfile/pipelines/player_no_audio.json`
- Builder 草稿保存目录：
  - `files/pipeline_builder/configs`
- Builder 导出产物目录：
  - `files/pipeline_builder/exports`

## 开发环境

建议准备以下环境：

- HarmonyOS SDK / DevEco Studio 对应命令行工具
- `ohpm`
- `hvigorw`
- `hdc`
- 可用的本地签名材料
- `OHOS_SDK_NATIVE` 环境变量，供 native CMake 使用

注意：

- `build-profile.json5` 当前包含本机签名配置，换机器时需要改成你自己的签名材料。
- `AVCodecDemo/src/main/cpp/CMakeLists.txt` 在缺失依赖目录时会尝试拉取：
  - `sample_framework`
  - `bounds_checking_function`

## 快速开始

### 1. 安装依赖并构建

```powershell
pwsh ./scripts/bootstrap.ps1
```

如果只想手动执行，也可以：

```powershell
ohpm install --all
hvigorw assembleHap -q
```

### 2. 构建 `ohosTest`

```powershell
hvigorw assembleHap -q -p module=AVCodecDemo@ohosTest
```

### 3. 安装到设备

```powershell
hdc install -r .\AVCodecDemo\build\default\outputs\default\AVCodecDemo-default-signed.hap
hdc install -r .\AVCodecDemo\build\default\outputs\ohosTest\AVCodecDemo-ohosTest-signed.hap
```

### 4. 启动应用

```powershell
hdc shell aa start -a AVCodecDemoAbility -b team.AVCodec.helloavcodec -m AVCodecDemo
```

### 5. 运行设备侧测试

```powershell
hdc shell aa test -b team.AVCodec.helloavcodec -m AVCodecDemo_test -s unittest OpenHarmonyTestRunner -s timeout 300000
```

## 测试说明

### 本地 ArkTS 单测

```powershell
hvigorw test -q
```

主要覆盖：

- Builder store 和拓扑校验
- Builder 序列化、草稿文件和视口行为
- producer graph 约束

### 设备侧 `ohosTest`

覆盖：

- Navigation 到 Player / Builder 的主流程
- Player 的播放、暂停、步进、设置弹窗、文件信息
- Builder 的画布交互、导入导出、运行/暂停/停止

相关文件：

- `AVCodecDemo/src/ohosTest/ets/test/PlayerPage.test.ets`
- `AVCodecDemo/src/ohosTest/ets/test/PipelineBuilderUiSuite.test.ets`

## 开发约束与注意事项

- `libavcodecdemo.so` 的 ArkTS 导出面以 `AVCodecDemo/src/main/cpp/types/libavcodecdemo/Index.d.ts` 为准，改动前要先确认兼容性。
- 当前播放 session 在 native 侧是单例模型，Player 和 Builder 共享同一套 surface/playback contract。
- Builder 画布是 port-aware 的，但传给 native runtime 的 schema 是简化后的 node-level graph，不要把 UI 语义误认为 native contract。
- `XComponent` 必须继续使用 `libraryname: 'avcodecdemo'`，否则 surface 无法绑定到 native。
- `player_napi.cpp` 中很多控制接口使用软失败语义，ArkTS 侧要接受 `applied=false` 或重试。

## 适合从哪里入手

如果你要继续开发这个项目，通常可以这样找入口：

- 想改播放器 UI 或设置：
  - 看 `AVCodecDemo/src/main/ets/pages/PlayerPage.ets`
  - 看 `AVCodecDemo/src/main/ets/settings/`
- 想改 Builder 交互或节点：
  - 看 `AVCodecDemo/src/main/ets/pages/PipelineBuilderPage.ets`
  - 看 `AVCodecDemo/src/main/ets/pipelinebuilder/models/NodeCatalog.ets`
  - 看 `AVCodecDemo/src/main/ets/pipelinebuilder/state/PipelineBuilderStore.ets`
- 想改 ArkTS 到 native 的桥接：
  - 看 `AVCodecDemo/src/main/cpp/types/libavcodecdemo/Index.d.ts`
  - 看 `AVCodecDemo/src/main/cpp/napi_wrapper/player_napi.cpp`
- 想改真正的媒体 runtime：
  - 看 `AVCodecDemo/src/main/cpp/sample_framework/test/unittest/video_test/video_test/`

## License

Apache License 2.0. 见 `LICENSE`。