视频动态元数据生成
=========

调用者可以调用本模块提供的[C API接口](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-videoprocessing)，实现HDRVivid标准动态元数据生成。

该能力常用于视频编辑中，如下图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7a/v3/EVlfFJLOQQifonGfx49dKQ/zh-cn_image_0000002625188249.png?HW-CC-KV=V1&HW-CC-Date=20260612T073525Z&HW-CC-Expire=86400&HW-CC-Sign=FB06FE2C6C49A242401636A192F21A80567C62AB0AC7DA7B045775BF28F0CDC5)

#### 规格说明

当前支持的数据输入格式类型组合如下：

*   格式类型组合一：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_PQ\_LIMIT |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_VIVID |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | 
    NATIVEBUFFER\_PIXEL\_FMT\_YCBCR\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_YCRCB\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102
    
     |
    
*   格式类型组合二：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_HLG\_LIMIT |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_VIVID |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | 
    NATIVEBUFFER\_PIXEL\_FMT\_YCBCR\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_YCRCB\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102
    
     |
    
*   格式类型组合三：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_HLG\_LIMIT |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_HLG |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | 
    NATIVEBUFFER\_PIXEL\_FMT\_YCBCR\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_YCRCB\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102
    
     |
    
*   格式类型组合四：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_PQ\_LIMIT |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_HDR10 |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | 
    NATIVEBUFFER\_PIXEL\_FMT\_YCBCR\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_YCRCB\_P010,
    
    NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102
    
     |
    
*   格式类型组合五（从API version 23 开始支持）：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_PQ\_FULL |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_VIVID |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102 |
    
*   格式类型组合六（从API version 23 开始支持）：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_HLG\_FULL |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_VIVID |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102 |
    
*   格式类型组合七（从API version 23 开始支持）：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_HLG\_FULL |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_HLG |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102 |
    
*   格式类型组合八（从API version 23 开始支持）：
    
    | 参数 | 数据输入格式 |
    | :-- | :-- |
    | [ColorSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_colorspace) | OH\_COLORSPACE\_BT2020\_PQ\_FULL |
    | [MetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_metadatatype) | OH\_VIDEO\_HDR\_HDR10 |
    | [pixelFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-buffer-common-h#oh_nativebuffer_format) | NATIVEBUFFER\_PIXEL\_FMT\_RGBA\_1010102 |
    

**支持的分辨率规格：**

| 最小分辨率（单位：像素） | 最大分辨率（单位：像素） |
| :-- | :-- |
| 32\*32 | 8192\*8192 |

#### 约束与限制

1.  为保障转换效率，建议并行转换不超过5个。
    
2.  视频动态元数据生成，只支持生成OH\_VIDEO\_HDR\_VIVID类型的动态元数据，转换后会将metadataType修改为OH\_VIDEO\_HDR\_VIVID。
    
3.  不允许在视频处理回调函数中，直接调用视频处理相关接口或其他耗时操作，请在应用自己的线程中调用。
    

#### 开发指导

具体实现可参考[示例工程](https://gitcode.com/HarmonyOS_Samples/VideoProcessing)。

#### \[h2\]在 CMake 脚本中链接动态库

target\_link\_libraries(sample PUBLIC libvideo\_processing.so)

#### \[h2\]开发步骤

1.  添加头文件。
    
    #include <multimedia/video\_processing\_engine/video\_processing.h>
    #include <multimedia/video\_processing\_engine/video\_processing\_types.h>
    #include <native\_window/external\_window.h>
    #include <native\_buffer/native\_buffer.h>
    #include <ace/xcomponent/native\_interface\_xcomponent.h>
    #include <multimedia/player\_framework/native\_avformat.h>
    
2.  （可选）初始化环境。
    
    一般在进程内第一次使用时调用，可提前完成部分耗时操作。
    
    OH\_VideoProcessing\_InitializeEnvironment();
    
3.  （可选）查询能力支持。建议在使用对应能力前调用。
    
    //输入格式
    VideoProcessing\_ColorSpaceInfo videoInfo;
    videoInfo.metadataType = OH\_VIDEO\_HDR\_HDR10;
    videoInfo.colorSpace = OH\_COLORSPACE\_BT2020\_PQ\_LIMIT;
    videoInfo.pixelFormat = NATIVEBUFFER\_PIXEL\_FMT\_YCBCR\_P010;
    
    //输入格式是否支持转换为vivid元数据类型
    bool isSupport = OH\_VideoProcessing\_IsMetadataGenerationSupported(&videoInfo);
    
4.  创建动态元数据生成转换模块。
    
    应用可以通过视频处理引擎模块类型来创建动态元数据生成模块。示例中的变量说明如下：
    
    *   videoProcessor：动态元数据生成模块实例。
    *   VIDEO\_PROCESSING\_TYPE\_METADATA\_GENERATION：动态元数据生成类型。
    *   预期返回值：VIDEO\_PROCESSING\_SUCCESS
    
    // 通过指定视频处理引擎类型创建动态元数据生成模块实例
    OH\_VideoProcessing\* videoProcessor = nullptr;
    VideoProcessing\_ErrorCode ret = OH\_VideoProcessing\_Create(&videoProcessor, VIDEO\_PROCESSING\_TYPE\_METADATA\_GENERATION);
    
5.  配置异步回调函数。
    
    // 回调函数声明（其中userData会传递注册回调时传入的调用者数据，如：this指针）
    void OnError(OH\_VideoProcessing\* videoProcessor, VideoProcessing\_ErrorCode error, void\* userData);
    void OnState(OH\_VideoProcessing\* videoProcessor, VideoProcessing\_State state, void\* userData);
    void OnNewOutputBuffer(OH\_VideoProcessing\* videoProcessor, uint32\_t index, void\* userData);
    
    // 创建回调实例
    VideoProcessing\_Callback\* callback = nullptr;
    ret = OH\_VideoProcessingCallback\_Create(&callback);
    // 绑定回调函数
    OH\_VideoProcessingCallback\_BindOnError(callback, OnError);
    OH\_VideoProcessingCallback\_BindOnState(callback, OnState);
    OH\_VideoProcessingCallback\_BindOnNewOutputBuffer(callback, OnNewOutputBuffer);
    // 注册回调函数
    ret = OH\_VideoProcessing\_RegisterCallback(videoProcessor, callback, this);
    
6.  （可选）从API version 22 开始，支持配置视频动态元数据生成的风格模式，当前有对比度风格模式和亮度风格模式两种，若不配置则默认为对比度风格模式。
    
    // 创建format实例
    OH\_AVFormat\* parameter = OH\_AVFormat\_Create();
    // 指定为亮度风格模式
    OH\_AVFormat\_SetIntValue(parameter, VIDEO\_METADATA\_GENERATOR\_STYLE\_CONTROL, VIDEO\_METADATA\_GENERATOR\_BRIGHT\_MODE);
    // 配置参数
    OH\_VideoProcessing\_SetParameter(videoProcessor, parameter);
    // 销毁format实例
    OH\_AVFormat\_Destroy(parameter);
    
7.  获取Surface。
    
    //获取输入surface
    OHNativeWindow \*inWindow = nullptr;
    ret = OH\_VideoProcessing\_GetSurface(videoProcessor, &inWindow);
    
8.  设置Surface。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/77/v3/QAtXsEZkR-KkxAhU17XooA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073525Z&HW-CC-Expire=86400&HW-CC-Sign=CF0B58C18E0B6E781AD82FE8369DEE7396F391AFE7962DB1BF510B6281CD7C33)
    
    可以通过XComponent等其他方式获取OHNativeWindow实例，具体参见[NativeWindows开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/native-window-guidelines)。
    
    视频处理引擎的SetSurface的windowOut从XComponent的[OnSurfaceCreatedCB](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/native-window-guidelines)回调函数获取，需要对windowOut设置元数据类型、数据格式和颜色空间等参数。
    
    // 设置元数据类型、数据格式、颜色空间
    uint8\_t metadataType = OH\_VIDEO\_HDR\_HLG;
    OH\_NativeWindow\_SetMetadataValue(windowOut, OH\_HDR\_METADATA\_TYPE, sizeof(uint8\_t),
    (uint8\_t \*)&metadataType);
    OH\_NativeBuffer\_Format format = NATIVEBUFFER\_PIXEL\_FMT\_YCBCR\_P010;
    OH\_NativeWindow\_NativeWindowHandleOpt(windowOut, SET\_FORMAT, format);
    OH\_NativeBuffer\_ColorSpace colorSpace = OH\_COLORSPACE\_BT2020\_HLG\_LIMIT;
    OH\_NativeWindow\_SetColorSpace(windowOut, colorSpace);
    // 设置输出surface
    VideoProcessing\_ErrorCode ret = OH\_VideoProcessing\_SetSurface(videoProcessor, windowOut);
    
9.  调用[OH\_VideoProcessing\_Start()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-video-processing-h#oh_videoprocessing_start)启动动态元数据生成处理。
    
    // 开始动态元数据生成转换处理
    ret = OH\_VideoProcessing\_Start(videoProcessor);
    
10.  调用[OH\_VideoProcessing\_Stop()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-video-processing-h#oh_videoprocessing_stop)停止动态元数据生成处理。
     
     //停止动态元数据生成处理
     ret = OH\_VideoProcessing\_Stop(videoProcessor);
     
11.  释放处理实例。
     
     OH\_VideoProcessingCallback\_Destroy(callback);
     callback = nullptr;
     OH\_VideoProcessing\_Destroy(videoProcessor);
     videoProcessor = nullptr;
     
12.  释放处理资源。
     
     OH\_VideoProcessing\_DeinitializeEnvironment();