【HarmonyOS 6.0】AVCodec Kit 同步模式视频编解码深度解析：从API演进到高性能实战

文章目录

[1 -> 概述：AVCodec Kit 与视频编解码的技术演进](#1 -> 概述：AVCodec Kit 与视频编解码的技术演进)
[2 -> 同步模式的核心机制与设计哲学](#2 -> 同步模式的核心机制与设计哲学)
- [2.1 -> 同步 vs 异步：本质差异在于控制权的归属](#2.1 -> 同步 vs 异步：本质差异在于控制权的归属)
- [2.2 -> 为什么需要同步模式？](#2.2 -> 为什么需要同步模式？)
[3 -> 开发准备与环境配置](#3 -> 开发准备与环境配置)
- [3.1 -> CMake 链接配置](#3.1 -> CMake 链接配置)
- [3.2 -> 头文件引入](#3.2 -> 头文件引入)
- [3.3 -> 关键全局变量定义](#3.3 -> 关键全局变量定义)
[4 -> 同步模式视频编码实战](#4 -> 同步模式视频编码实战)
- [4.1 -> 创建编码器实例](#4.1 -> 创建编码器实例)
- [4.2 -> 配置编码器参数](#4.2 -> 配置编码器参数)
- [4.3 -> 设置 Surface 输入源](#4.3 -> 设置 Surface 输入源)
- [4.4 -> 启动编码器并执行同步编码循环](#4.4 -> 启动编码器并执行同步编码循环)
- [4.5 -> 编码器清理](#4.5 -> 编码器清理)
[5 -> 同步模式视频解码实战](#5 -> 同步模式视频解码实战)
- [5.1 -> 创建和配置解码器](#5.1 -> 创建和配置解码器)
- [5.2 -> 解码循环：从码流到图像](#5.2 -> 解码循环：从码流到图像)
[6 -> 性能分析与优化建议](#6 -> 性能分析与优化建议)
- [6.1 -> 同步模式的性能特征](#6.1 -> 同步模式的性能特征)
- [6.2 -> 两种模式的选用决策](#6.2 -> 两种模式的选用决策)
- [6.3 -> Surface 模式 vs Buffer 模式的选择](#6.3 -> Surface 模式 vs Buffer 模式的选择)
[7 -> 技术展望与生态演进](#7 -> 技术展望与生态演进)

1 -> 概述：AVCodec Kit 与视频编解码的技术演进

在移动操作系统领域，音视频处理能力始终是衡量一个系统底层实力的重要标尺。HarmonyOS 自诞生之初便将多媒体能力作为核心基础设施进行建设，而 AVCodec Kit（Audio & Video Codec Kit） 正是鸿蒙媒体子系统中最底层的原子能力支柱------它不仅仅是音视频的编解码器，更涵盖了解析、封装及媒体数据输入等全链路操作。

进入 HarmonyOS 6.0 时代，AVCodec Kit 迎来了一次重要的架构升级：视频编解码的同步模式正式加入 API 支持列表，起始 API version 为 20。在此之前，AVCodec Kit 主要提供异步回调模式，应用通过注册回调函数来接收编解码器的输入输出事件。这种模式在多数场景下是合理且高效的，但对于某些特定的业务需求------例如需要精确控制 buffer 生命周期、在主线程中同步等待编解码完成、或者简化某些工具类应用的实现逻辑------异步模式反而会带来不必要的复杂度。

同步模式的加入，标志着鸿蒙在音视频编解码 API 设计上走向了更加灵活和完备的方向。它为开发者提供了一种主动轮询式的数据处理路径，允许应用在需要的时候主动向编解码器请求 buffer，完成数据填充或读取后主动返回，整个过程在一个函数调用上下文中同步完成。这种设计思路与 Android MediaCodec 的同步模式有异曲同工之处，但鸿蒙在此基础上结合了自身硬件加速架构做了针对性优化。

从架构层面看，AVCodec Kit 直接管理与调度底层的 Media Foundation 框架和硬件编解码器（如 VPU、GPU、DSP），实现真正的硬编硬解。在鸿蒙 6.0 中，同步模式并非简单地在异步模式之上封装一层轮询逻辑，而是在编解码器内核层面提供了同步调度的通道，使得应用在调用 PushInputBuffer 和 GetOutputBuffer 时能够获得确定性的返回行为。

2 -> 同步模式的核心机制与设计哲学

2.1 -> 同步 vs 异步：本质差异在于控制权的归属

理解同步模式的价值，需要先从它与异步模式的本质差异说起。

在传统的异步模式下，视频编解码器的工作流程是这样的：

复制代码

应用线程 → 启动解码器 → 注册回调 → 持续送数据 → 回调线程通知输出可用 → 应用处理输出

应用将数据送入编解码器后便不再阻塞，当编解码器完成处理（输入 buffer 已取用、输出 buffer 已产出）时，系统通过预先注册的回调函数通知应用。这种模式的核心优势在于非阻塞 ------应用的调用线程不会因为编解码器的处理耗时而被挂起。但代价是控制权的转移：应用无法精确预测输出何时到来，必须通过回调函数来响应，这在某些需要线性逻辑的场景下会增加代码的复杂度。

而同步模式则完全不同：

复制代码

应用线程 → 启动解码器 → 轮询输入 buffer → 填充数据 → 轮询输出 buffer → 读取结果 → 继续循环

应用主动调用 OH_VideoDecoder_GetInputBuffer 获取可用的输入 buffer，填充数据后调用 OH_VideoDecoder_PushInputBuffer 提交，然后主动调用 OH_VideoDecoder_GetOutputBuffer 获取输出结果。整个过程由应用线程驱动，编解码器不会主动回调。这意味着应用的业务逻辑可以线性地写在同一个函数中，无需在多个回调函数之间跳转。

2.2 -> 为什么需要同步模式？

官方文档中明确提到："通常情况下，推荐使用异步模式。若需要主动请求 buffer 去送帧，则可以采用同步模式。"这句话看似轻描淡写，但背后包含了深刻的设计考量。

同步模式的典型适用场景包括：

编解码工具类应用：例如一个视频转码工具，输入输出都是本地文件，业务逻辑天然是顺序的------读取一帧、编码一帧、写入文件。使用异步模式反而需要在回调中维护状态机，而同步模式可以让代码逻辑与业务逻辑完全对齐。
需要精细控制 buffer 生命周期的场景：某些应用需要对编码后的码流做二次处理（如添加自定义 SEI、修改 NAL 单元），同步模式下可以在获取输出 buffer 后立即处理，处理完再释放，所有操作在同一个上下文中完成，无需跨线程传递数据。
低复杂度场景的快速实现：对于不需要极致性能、但对开发效率有要求的场景，同步模式提供了更简单的编程模型。
与现有同步框架的集成：某些应用已经在主循环中使用同步 I/O 模型，引入异步编解码会破坏整体架构的一致性，同步模式可以无缝融入。

值得注意的是，同步模式的性能并不一定低于异步模式。从 Android MediaCodec 的实践来看，有开发者观察到同步模式下的视频播放反而更流畅、延迟更低。这是因为同步模式下应用主动轮询的方式避免了回调线程的调度开销，同时应用的 buffer 处理节奏可以与显示刷新率形成更好的配合。当然，这取决于具体场景和实现质量。

3 -> 开发准备与环境配置

在开始编写同步模式视频编解码代码之前，需要先完成环境配置。由于 AVCodec Kit 基于性能考虑仅提供 C/C++ Native API，所有开发工作都需要在 NDK 层面完成。

3.1 -> CMake 链接配置

在模块级的 CMakeLists.txt 中，需要链接以下动态库：

cmake 复制代码

target_link_libraries(sample PUBLIC libnative_media_codecbase.so)
target_link_libraries(sample PUBLIC libnative_media_core.so)
target_link_libraries(sample PUBLIC libnative_media_venc.so)   # 视频编码
target_link_libraries(sample PUBLIC libnative_media_vdec.so)   # 视频解码

说明：上述 sample 字样仅为示例，实际使用时应替换为项目的 target 名称。

3.2 -> 头文件引入

同步模式编解码需要引入以下头文件：

cpp 复制代码

#include <multimedia/player_framework/native_avcodec_videoencoder.h>
#include <multimedia/player_framework/native_avcodec_videodecoder.h>
#include <multimedia/player_framework/native_avcapability.h>
#include <multimedia/player_framework/native_avcodec_base.h>
#include <multimedia/player_framework/native_avbuffer.h>
#include <fstream>
#include <thread>
#include <shared_mutex>

3.3 -> 关键全局变量定义

为了方便示例说明，可以定义以下全局变量（实际开发中建议封装为类成员）：

cpp 复制代码

// 视频参数
int32_t width = 1920;
int32_t height = 1080;
int32_t widthStride = 0;
int32_t heightStride = 0;
OH_AVPixelFormat pixelFormat = AV_PIXEL_FORMAT_NV12;

// 同步控制
std::shared_mutex codecMutex;
OH_AVCodec *videoEnc = nullptr;
OH_AVCodec *videoDec = nullptr;
bool outputDone = false;
bool inputDone = false;
std::unique_ptr<std::ifstream> inFile;
std::unique_ptr<std::ofstream> outFile;

4 -> 同步模式视频编码实战

本节以 Surface 模式输入、编码为 H.264 格式为例，完整展示同步模式视频编码的全流程。Surface 模式是官方推荐的高性能数据流转方案，在编码场景中可以直接将图形管线产生的 Surface 数据送入编码器，避免了内存拷贝开销。

4.1 -> 创建编码器实例

编码器的创建需要先获取系统能力，再通过能力获取编码器名称，最后创建实例：

cpp 复制代码

// 获取硬件编码器能力
OH_AVCapability *capability = OH_AVCodec_GetCapabilityByCategory(
    OH_AVCODEC_MIMETYPE_VIDEO_AVC,  // AVC(H.264)格式
    true,                            // 是否为软件编码器，false表示硬件
    HARDWARE                         // 编码器类型
);

if (capability == nullptr) {
    printf("Failed to get capability for video encoder\n");
    return;
}

const char *name = OH_AVCapability_GetName(capability);
OH_AVCodec *videoEnc = OH_VideoEncoder_CreateByName(name);

if (videoEnc == nullptr) {
    printf("Failed to create video encoder\n");
    return;
}

4.2 -> 配置编码器参数

配置是编码流程中最关键的一步，参数设置直接影响编码质量和性能：

cpp 复制代码

// 配置视频格式
OH_AVFormat *format = OH_AVFormat_Create();
OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, width);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, height);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, pixelFormat);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_FRAME_RATE, 30);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_BITRATE, 4000000);  // 4Mbps
OH_AVFormat_SetIntValue(format, OH_MD_KEY_I_FRAME_INTERVAL, 2); // 关键帧间隔2秒
OH_AVFormat_SetIntValue(format, OH_MD_KEY_COLOR_STANDARD, OH_ColorStandard_BT709);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_COLOR_RANGE, OH_ColorRange_Video);

// 配置编码器
int32_t ret = OH_VideoEncoder_Configure(videoEnc, format);
if (ret != AV_ERR_OK) {
    printf("Failed to configure video encoder\n");
    return;
}

4.3 -> 设置 Surface 输入源

Surface 模式下，编码器从 Surface 中直接获取图像数据：

cpp 复制代码

// 获取编码器的 Surface
OH_NativeBuffer *nativeBuffer = nullptr;
OH_VideoEncoder_GetSurface(videoEnc, &nativeBuffer);

// 将 Surface 设置给图像生产者（如相机、OpenGL等）
// 这部分代码取决于具体的图像数据来源

4.4 -> 启动编码器并执行同步编码循环

同步模式的核心在于编码器启动后的主动轮询循环：

cpp 复制代码

// 启动编码器
ret = OH_VideoEncoder_Start(videoEnc);
if (ret != AV_ERR_OK) {
    printf("Failed to start video encoder\n");
    return;
}

// 同步编码循环
bool isRunning = true;
int frameCount = 0;
int maxFrames = 300;  // 编码300帧

while (isRunning && frameCount < maxFrames) {
    // 1. 主动获取输入 buffer
    OH_AVBuffer *inputBuffer = nullptr;
    ret = OH_VideoEncoder_GetInputBuffer(videoEnc, &inputBuffer);
    
    if (ret == AV_ERR_OK && inputBuffer != nullptr) {
        // 填充数据到 input buffer（Surface 模式下通常通过 Surface 直接写入）
        // Buffer 模式则需要手动拷贝像素数据
        
        // 提交输入 buffer
        OH_AVBuffer_SetBufferAttr(inputBuffer, attr);
        ret = OH_VideoEncoder_PushInputBuffer(videoEnc, inputBuffer);
        if (ret != AV_ERR_OK) {
            printf("Failed to push input buffer\n");
            break;
        }
        frameCount++;
    }
    
    // 2. 主动获取输出 buffer
    OH_AVBuffer *outputBuffer = nullptr;
    ret = OH_VideoEncoder_GetOutputBuffer(videoEnc, &outputBuffer);
    
    if (ret == AV_ERR_OK && outputBuffer != nullptr) {
        OH_AVBufferAttr outAttr;
        OH_AVBuffer_GetBufferAttr(outputBuffer, &outAttr);
        
        // 处理输出数据（写入文件或网络发送）
        if (outAttr.size > 0) {
            uint8_t *data = OH_AVBuffer_GetAddr(outputBuffer);
            // 写入文件或进行其他处理
            outFile->write(reinterpret_cast<char*>(data), outAttr.size);
        }
        
        // 释放输出 buffer
        ret = OH_VideoEncoder_FreeOutputBuffer(videoEnc, outputBuffer);
    }
    
    // 控制编码速率，避免过度占用 CPU
    std::this_thread::sleep_for(std::chrono::milliseconds(33));
}

4.5 -> 编码器清理

编码完成后需要按顺序释放资源：

cpp 复制代码

// 发送结束标志
OH_VideoEncoder_NotifyEos(videoEnc);

// 等待输出完成
while (!outputDone) {
    std::this_thread::sleep_for(std::chrono::milliseconds(10));
}

// 停止编码器
OH_VideoEncoder_Stop(videoEnc);

// 释放编码器资源
OH_VideoEncoder_Destroy(videoEnc);

5 -> 同步模式视频解码实战

视频解码的同步模式与编码类似，核心同样是主动轮询输入输出 buffer。解码通常有两种工作模式：Surface 模式 （直接送显）和 Buffer 模式（获取 YUV 数据做二次处理）。

5.1 -> 创建和配置解码器

cpp 复制代码

// 获取解码器能力
OH_AVCapability *capability = OH_AVCodec_GetCapabilityByCategory(
    OH_AVCODEC_MIMETYPE_VIDEO_AVC,
    false,  // 解码器
    HARDWARE
);

const char *name = OH_AVCapability_GetName(capability);
OH_AVCodec *videoDec = OH_VideoDecoder_CreateByName(name);

// 配置解码器参数
OH_AVFormat *format = OH_AVFormat_Create();
OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, width);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, height);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12);

OH_VideoDecoder_Configure(videoDec, format);

5.2 -> 解码循环：从码流到图像

同步解码的核心流程是：读取码流 → 送入解码器 → 获取解码后的图像：

cpp 复制代码

// 启动解码器
OH_VideoDecoder_Start(videoDec);

while (hasMoreData) {
    // 1. 获取输入 buffer
    OH_AVBuffer *inputBuffer = nullptr;
    int ret = OH_VideoDecoder_GetInputBuffer(videoDec, &inputBuffer);
    
    if (ret == AV_ERR_OK && inputBuffer != nullptr) {
        // 从文件读取码流数据
        uint8_t *bufferAddr = OH_AVBuffer_GetAddr(inputBuffer);
        int bufferSize = OH_AVBuffer_GetCapacity(inputBuffer);
        
        inFile->read(reinterpret_cast<char*>(bufferAddr), bufferSize);
        int bytesRead = inFile->gcount();
        
        // 设置 buffer 属性
        OH_AVBufferAttr attr;
        attr.size = bytesRead;
        attr.pts = pts;
        attr.flags = (inFile->eof()) ? AVCODEC_BUFFER_FLAGS_EOS : 0;
        OH_AVBuffer_SetBufferAttr(inputBuffer, &attr);
        
        // 提交输入
        ret = OH_VideoDecoder_PushInputBuffer(videoDec, inputBuffer);
    }
    
    // 2. 获取输出 buffer（解码后的图像）
    OH_AVBuffer *outputBuffer = nullptr;
    ret = OH_VideoDecoder_GetOutputBuffer(videoDec, &outputBuffer);
    
    if (ret == AV_ERR_OK && outputBuffer != nullptr) {
        OH_AVBufferAttr outAttr;
        OH_AVBuffer_GetBufferAttr(outputBuffer, &outAttr);
        
        if (outAttr.size > 0 && !(outAttr.flags & AVCODEC_BUFFER_FLAGS_EOS)) {
            // 获取解码后的 YUV 数据
            uint8_t *yuvData = OH_AVBuffer_GetAddr(outputBuffer);
            
            // 根据需求处理 YUV 数据（渲染、保存或进一步处理）
            // Surface 模式下会自动送显，Buffer 模式则需要手动处理
            
            // 渲染或保存
            renderYUV(yuvData, width, height);
        }
        
        // 释放输出 buffer
        OH_VideoDecoder_FreeOutputBuffer(videoDec, outputBuffer);
    }
}

6 -> 性能分析与优化建议

6.1 -> 同步模式的性能特征

根据实际测试经验，同步模式在以下方面表现出独特优势：

确定性延迟：由于避免了回调线程的调度，同步模式下从提交输入到获取输出的时间更加可预测，这对于实时性要求高的场景（如视频会议、云游戏）尤其有利。
缓存友好：同步模式下数据处理的局部性更好，输入处理和输出处理在同一线程上下文中完成，CPU 缓存命中率更高。
无回调开销：异步模式中每次回调都涉及线程切换和上下文保存，同步模式消除了这部分开销。

不过，同步模式也有其局限性：如果编解码器处理速度跟不上应用的轮询速度，应用线程会阻塞在 GetOutputBuffer 调用上，可能导致 UI 卡顿。因此，同步模式更适合在独立的工作线程中运行，主线程应保持响应。

6.2 -> 两种模式的选用决策

场景	推荐模式	理由
实时音视频通话	异步	需要极低的端到端延迟，回调模式更适合流水线处理
视频播放器	异步	输出时序由系统控制，与音画同步机制配合更紧密
视频转码工具	同步	业务逻辑本身就是顺序的，同步模式代码更简洁
离线视频分析	同步	对实时性无要求，同步模式便于调试和维护
VR/AR 应用	异步	需要与渲染管线紧密配合，Surface 模式配合异步更优
流媒体推流	同步	需要精确控制每一帧的发送时机，同步模式更直观

6.3 -> Surface 模式 vs Buffer 模式的选择

在鸿蒙 AVCodec Kit 中，编解码器的数据输入输出有两种模式：

Surface 模式：编码器直接从 Surface 获取图像数据，解码器直接向 Surface 输出图像。这种模式利用 DMA-BUF 机制实现了零拷贝数据传输，避免了帧数据的内存拷贝。适合需要最高性能的场景，如游戏录制、屏幕共享、VR 播放等。

Buffer 模式：应用通过 buffer 传递像素数据（NV12、RGBA 等）。这种模式虽然需要手动拷贝数据，但灵活性更高，可以在数据传递过程中进行二次处理，如添加滤镜、缩放、格式转换等。

7 -> 技术展望与生态演进

鸿蒙 6.0 引入同步模式视频编解码，不仅仅是一个 API 层面的补充，更折射出鸿蒙多媒体框架的成熟度在持续提升。从最早的异步回调到如今的同步主动轮询，AVCodec Kit 正在覆盖更加丰富的开发者需求。

展望未来，可以预见几个演进方向：

更细粒度的同步控制：目前的同步模式仍以 buffer 为粒度，未来可能会引入帧级别的同步控制 API，允许开发者更精细地控制每一帧的处理时序。
跨设备编解码同步：随着鸿蒙分布式能力的深化，跨设备的同步编解码将成为可能------在手机端编码、在平板端解码，并通过分布式软总线保持同步。
AI 辅助编解码：NPU 的加入将为编解码带来新的可能，AI 超分、AI 画质增强等能力将与同步模式深度集成。

对于开发者而言，同步模式的出现提供了一个新的选择。在实际开发中，建议根据业务场景的特点------是否对延迟敏感、是否需要精确控制 buffer 生命周期、代码复杂度能否接受------来选择最合适的模式。毕竟，没有绝对的最优模式，只有最合适的模式。

感谢各位大佬支持！！！
互三啦！！！