1# VideoEncoder 2 3 4## 概述 5 6VideoEncoder模块提供用于视频编码的接口。 7 8开发者可根据实际的开发需求，参考对应的开发指南及样例： 9 10- [视频编码](../../media/avcodec/video-encoding.md) 11- [时域可分层视频编码](../../media/avcodec/video-encoding-temporal-scalability.md) 12 13**系统能力：** SystemCapability.Multimedia.VideoEncoder 14 15**起始版本：** 9 16 17接口在每个版本，对每种模式的支持情况说明，如下图所示。 18 19 20 21 22 23## 汇总 24 25 26### 文件 27 28| 名称 | 描述 | 29| -------- | -------- | 30| [native_avcodec_videoencoder.h](native__avcodec__videoencoder_8h.md) | 声明用于视频编码的接口。 | 31 32 33### 类型定义 34 35| 名称 | 描述 | 36| -------- | -------- | 37| typedef void(\* [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter)) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, OH_AVFormat \*parameter, void \*userData) | 配置随帧参数，当需要设置index对应帧的编码参数时，可以通过该接口设置。只在Surface模式生效。 | 38 39### 枚举 40 41| 名称 | 描述 | 42| -------- | -------- | 43| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) { CBR = 0, VBR = 1, CQ = 2 } | 视频编码器的码率控制模式。（API14废弃） | 44 45 46### 函数 47 48| 名称 | 描述 | 49| -------- | -------- | 50| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoEncoder_CreateByMime](#oh_videoencoder_createbymime) (const char \*mime) | 根据[MIME](_codec_base.md#媒体编解码格式)类型创建视频编码器实例，推荐使用。 | 51| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoEncoder_CreateByName](#oh_videoencoder_createbyname) (const char \*name) | 根据视频编码器名称创建视频编码器实例。 | 52| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Destroy](#oh_videoencoder_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 清理编码器内部资源，销毁编码器实例。 | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetCallback](#oh_videoencoder_setcallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | 设置OH_AVCodecCallback回调函数，让应用可以响应视频编码器生成的事件。（API11废弃） | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | 注册OH_AVCodecCallback回调函数，让应用可以响应视频编码器生成的事件。 | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_RegisterParameterCallback](#oh_videoencoder_registerparametercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter) onInputParameter, void \*userData) | 注册OH_AVCodecCallback输入参数回调函数，让应用可以响应视频编码器生成的事件。 | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Configure](#oh_videoencoder_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, OH_AVFormat \*format) | 配置视频编码器的编码参数，通常需要配置要编码的视频轨的描述信息，如宽、高、像素格式等。 | 57| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Prepare](#oh_videoencoder_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 准备编码器的内部资源。 | 58| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Start](#oh_videoencoder_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 调用OH_VideoEncoder_Prepare接口成功后调用此接口启动编码器。 | 59| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Stop](#oh_videoencoder_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 停止编码器，释放输入输出buffer。 | 60| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Flush](#oh_videoencoder_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 清除编码器中缓存的输入和输出数据及参数集如H.264格式的PPS/SPS。 | 61| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Reset](#oh_videoencoder_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 重置编码器，编码器回到初始化状态。 | 62| OH_AVFormat \* [OH_VideoEncoder_GetOutputDescription](#oh_videoencoder_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 获取编码器输出数据的OH_AVFormat信息。 | 63| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetParameter](#oh_videoencoder_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, OH_AVFormat \*format) | 在编码器运行时设置编码器参数。 | 64| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_GetSurface](#oh_videoencoder_getsurface) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OHNativeWindow](_codec_base.md#ohnativewindow) \*\*window) | 从视频编码器获取输入surface。 | 65| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputData](#oh_videoencoder_freeoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出缓冲区返回给编码器。（API11废弃） | 66| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_NotifyEndOfStream](#oh_videoencoder_notifyendofstream) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 通知视频编码器输入流已结束。 | 67| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputData](#oh_videoencoder_pushinputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | 将填入数据的输入缓冲区提交给视频编码器。（API11废弃） | 68| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Buffer模式下，将index对应的OH_AVBuffer送入编码器编码。 | 69| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputParameter](#oh_videoencoder_pushinputparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Surface模式下，将index对应帧的编码参数送入编码器编码。 | 70| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的index对应的OH_AVBuffer返回给编码器。 | 71| OH_AVFormat \* [OH_VideoEncoder_GetInputDescription](#oh_videoencoder_getinputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 编码器接收到的图像的描述信息。 | 72| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_IsValid](#oh_videoencoder_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | 检查当前编码实例是否有效。 | 73| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_QueryInputBuffer](#oh_videoencoder_queryinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | 查询下一个可用输入缓冲区的索引。 | 74| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoEncoder_GetInputBuffer](#oh_videoencoder_getinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 获取可用输入缓冲区的实例。 | 75| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_QueryOutputBuffer](#oh_videoencoder_queryoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | 查询下一个可用输出缓冲区的索引。 | 76| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoEncoder_GetOutputBuffer](#oh_videoencoder_getoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 获取可用输出缓冲区的实例。 | 77 78## 类型定义说明 79 80### OH_VideoEncoder_OnNeedInputParameter 81 82``` 83typedef void(* OH_VideoEncoder_OnNeedInputParameter) (OH_AVCodec *codec, uint32_t index, OH_AVFormat *parameter, void *userData) 84``` 85**描述** 86配置随帧参数，当需要设置index对应帧的编码参数时，可以通过该接口设置。只在Surface模式生效。 87 88该接口只能在Surface模式下使用，使用前需要调用OH_VideoEncoder_RegisterParameterCallback接口注册。 89 90在Buffer模式下，OH_AVBuffer可以直接携带帧的编码参数，当前可以支持的随帧参数有帧级QPMin/QPMax，指定LTR设置参考帧。 91 92**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 93 94**起始版本：** 12 95 96**参数:** 97 98| 名称 | 描述 | 99| -------- | -------- | 100| codec | 指向视频编码实例的指针。 | 101| index | 对应编码帧的index。 | 102| parameter | 编码参数。 | 103| userData | 开发者执行回调所依赖的数据。 | 104 105 106## 枚举类型说明 107 108 109### OH_VideoEncodeBitrateMode 110 111``` 112enum OH_VideoEncodeBitrateMode 113``` 114**描述** 115视频编码器的码率控制模式。 116 117**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 118 119**起始版本：** 9 120 121**废弃版本：** 14 122 123**替代接口：** [OH_BitrateMode](_codec_base.md#oh_bitratemode-1) 124 125| 枚举值 | 描述 | 126| -------- | -------- | 127| CBR | 恒定码率模式。 | 128| VBR | 可变码率模式。 | 129| CQ | 恒定QP模式。 | 130 131 132## 函数说明 133 134 135### OH_VideoEncoder_Configure() 136 137``` 138OH_AVErrCode OH_VideoEncoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 139``` 140**描述** 141配置视频编码器的编码参数，通常需要配置要编码的视频轨的描述信息，如宽、高、像素格式等。必须在调用OH_VideoEncoder_Prepare接口之前，调用此接口。 142 143该接口对配置参数进行合法性校验，部分非法参数不会强校验，使用默认值或直接丢弃。部分非法参数会强校验，具体规则如下： 144 145以下参数的配置范围可通过[能力查询](../../media/avcodec/obtain-supported-codecs.md)获取，OH_MD_KEY_I_FRAME_INTERVAL暂不支持。 146 147设置OH_MD_KEY_VIDEO_ENCODER_ENABLE_TEMPORAL_SCALABILITY、OH_MD_KEY_VIDEO_ENCODER_LTR_FRAME_COUNT接口时如果当前平台不支持，不报错，走正常编码流程。 148 149参数校验： 150 151| Key | 配置正常范围的值 | 配置超出范围的值 | 不配置该参数 | 152| ------------------------------------------------------------------------- | -------- | -------- | ------ | 153| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 154| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 155| OH_MD_KEY_PIXEL_FORMAT 请参阅[OH_AVPixelFormat](_core.md#oh_avpixelformat-1) | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 156| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL |AV_ERR_OK | 157| OH_MD_KEY_PROFILE 请参阅[OH_MD_KEY_PROFILE](_codec_base.md#oh_md_key_profile) | AV_ERR_OK | AV_ERR_INVALID_VAL |AV_ERR_OK | 158| OH_MD_KEY_I_FRAME_INTERVAL | AV_ERR_OK | \\ | AV_ERR_OK | 159 160| OH_MD_KEY_<br>BITRATE | OH_MD_KEY_<br>QUALITY | OH_MD_KEY_<br>VIDEO_ENCODER_BITRATE_MODE | 返回值 | 说明 | 161| :-------------------- | :-------------------- | :--------------------------------------- | ---- | ---------------------- | 162| \\ | \\ | \\ | AV_ERR_OK | 使用编码器默认值 | 163| 超出范围 | 超出范围 | 不支持的模式 | AV_ERR_INVALID_VAL | 异常值均报错 | 164| 正常值 | 正常值 | \\ | AV_ERR_INVALID_VAL | Bitrate 与 Quality 冲突 | 165| 正常值 | \\ | \\ | AV_ERR_OK | 使能默认码控模式 | 166| 正常值 | \\ | BITRATE_MODE_VBR、BITRATE_MODE_CBR | AV_ERR_OK | | 167| 正常值 | \\ | BITRATE_MODE_CQ | AV_ERR_INVALID_VAL | Bitrate 与 CQ 模式冲突 | 168| \\ | 正常值 | \\ | AV_ERR_OK | 使能 CQ 模式 | 169| \\ | 正常值 | BITRATE_MODE_CQ | AV_ERR_OK | | 170| \\ | 正常值 | BITRATE_MODE_VBR、BITRATE_MODE_CBR | AV_ERR_INVALID_VAL | Quality 与 VBR、CBR 模式冲突 | 171| \\ | \\ | BITRATE_MODE_VBR、BITRATE_MODE_CBR | AV_ERR_OK | 使用编码器默认码率 | 172| \\ | \\ | BITRATE_MODE_CQ | AV_ERR_OK | 使用默认quality | 173 174 175**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 176 177**起始版本：** 9 178 179**参数:** 180 181| 名称 | 描述 | 182| -------- | -------- | 183| codec | 指向视频编码实例的指针。 | 184| format | 指向OH_AVFormat的指针，用于给出要编码的视频轨的描述。 | 185 186**返回：** 187 188返回接口结果： 189 190AV_ERR_OK：执行成功。 191 192AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 193 194AV_ERR_INVALID_VAL： 195 196 1. 输入的codec指针为非编码器实例，或者为空指针； 197 2. 输入format参数不支持。 198 199AV_ERR_UNKNOWN：未知错误。 200 201AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 202 203AV_ERR_INVALID_STATE：本接口必须在OH_VideoEncoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 204 205AV_ERR_UNSUPPORT：未支持的功能。 206 207 208### OH_VideoEncoder_CreateByMime() 209 210``` 211OH_AVCodec* OH_VideoEncoder_CreateByMime (const char *mime) 212``` 213**描述** 214根据MIME类型创建视频编码器实例，推荐使用。 215 216**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 217 218**起始版本：** 9 219 220**参数:** 221 222| 名称 | 描述 | 223| -------- | -------- | 224| mime | MIME类型描述字符串，请参阅[AVCODEC_MIMETYPE](_codec_base.md#变量)。 | 225 226**返回：** 227 228成功则返回一个指向视频编码实例的指针。如果输入为不支持的编码器类型或内存不足时，则返回NULL。 229 230 231### OH_VideoEncoder_CreateByName() 232 233``` 234OH_AVCodec* OH_VideoEncoder_CreateByName (const char *name) 235``` 236**描述** 237根据视频编码器名称创建视频编码器实例。使用此接口的前提是知道编码器的确切名称，编码器的名称可以通过能力查询获取。 238 239详情请参见：[获取支持的编解码能力](../../media/avcodec/obtain-supported-codecs.md#创建指定名称的编解码器)。 240 241**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 242 243**起始版本：** 9 244 245**参数:** 246 247| 名称 | 描述 | 248| -------- | -------- | 249| name | 视频编码器名称。 | 250 251**返回：** 252 253成功则返回一个指向视频编码实例的指针。如果输入是不支持编码器名称或者内存资源不足，则返回NULL。 254 255 256### OH_VideoEncoder_Destroy() 257 258``` 259OH_AVErrCode OH_VideoEncoder_Destroy (OH_AVCodec *codec) 260``` 261**描述** 262清理编码器内部资源，销毁编码器实例。不能重复销毁。 263 264**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 265 266**起始版本：** 9 267 268**参数:** 269 270| 名称 | 描述 | 271| -------- | -------- | 272| codec | 指向视频编码实例的指针。 | 273 274**返回：** 275 276返回接口结果： 277 278AV_ERR_OK：执行成功。 279 280AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 281 282AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 283 284AV_ERR_UNKNOWN：未知错误。 285 286AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 287 288 289### OH_VideoEncoder_Flush() 290 291``` 292OH_AVErrCode OH_VideoEncoder_Flush (OH_AVCodec *codec) 293``` 294**描述** 295 296清除编码器中缓存的输入和输出数据及参数集如H.264格式的PPS/SPS。 297 298调用此接口后，以前通过异步回调上报的所有缓冲区index都将失效，请确保不要访问这些index对应的缓冲区。该接口不能连续调用。 299 300**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 301 302**起始版本：** 9 303 304**参数:** 305 306| 名称 | 描述 | 307| -------- | -------- | 308| codec | 指向视频编码实例的指针。 | 309 310**返回：** 311 312返回接口结果： 313 314AV_ERR_OK：执行成功。 315 316AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 317 318AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 319 320AV_ERR_UNKNOWN：未知错误。 321 322AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 323 324AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 325 326 327### OH_VideoEncoder_FreeOutputBuffer() 328 329``` 330OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 331``` 332**描述** 333将处理后的index对应的OH_AVBuffer退回给编码器。开发者使用完需要及时调用此接口释放输出缓存区，否则会阻塞编码流程。 334 335详情请参见：[视频编码](../../media/avcodec/video-encoding.md) “Surface模式的步骤-13或Buffer模式步骤-11”。 336 337**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 338 339**起始版本：** 11 340 341**参数:** 342 343| 名称 | 描述 | 344| -------- | -------- | 345| codec | 指向视频编码实例的指针。 | 346| index | 输出缓冲区对应的索引值。 由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 347 348**返回：** 349 350返回接口结果： 351 352AV_ERR_OK：执行成功。 353 354AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 355 356AV_ERR_INVALID_VAL： 357 358 1. 输入的codec指针为非编码器实例，或者为空指针； 359 2. 输入format参数不支持； 360 3. index非法或者连续给同一个index，该错误不影响后续编码流程。 361 362AV_ERR_UNKNOWN：未知错误。 363 364AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 365 366AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 367 368 369### OH_VideoEncoder_GetInputDescription() 370 371``` 372OH_AVFormat* OH_VideoEncoder_GetInputDescription (OH_AVCodec *codec) 373``` 374**描述** 375编码器接收到的图像的描述信息。调用[OH_VideoEncoder_Configure](#oh_videoencoder_configure)后调用此接口。 376 377需要注意的是，返回指针所指向的OH_AVFormat实例的生命周期需要由开发者通过调用OH_AVFormat_Destroy接口释放，请参阅[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)。 378 379**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 380 381**起始版本：** 10 382 383**参数:** 384 385| 名称 | 描述 | 386| -------- | -------- | 387| codec | 指向视频编码实例的指针。 | 388 389**返回：** 390 391返回指向OH_AVFormat实例的指针。当codec指针非编码实例，或者为空指针，则返回NULL。 392 393 394### OH_VideoEncoder_GetOutputDescription() 395 396``` 397OH_AVFormat* OH_VideoEncoder_GetOutputDescription (OH_AVCodec *codec) 398``` 399**描述** 400获取编码器输出数据的OH_AVFormat信息。 401 402需要注意的是，返回值指向的OH_AVFormat实例的生命周期需要开发者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 403 404**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 405 406**起始版本：** 9 407 408**参数:** 409 410| 名称 | 描述 | 411| -------- | -------- | 412| codec | 指向视频编码实例的指针。 | 413 414**返回：** 415 416返回指向OH_AVFormat实例的指针。当输入的codec指针非编码实例，或者为空指针，则返回NULL。 417 418 419### OH_VideoEncoder_GetSurface() 420 421``` 422OH_AVErrCode OH_VideoEncoder_GetSurface (OH_AVCodec *codec, OHNativeWindow ** window ) 423``` 424**描述** 425从视频编码器获取输入surface，必须在调用OH_VideoEncoder_Configure接口之后OH_VideoEncoder_Prepare接口之前调用此接口。 426 427**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 428 429**起始版本：** 9 430 431**参数:** 432 433| 名称 | 描述 | 434| -------- | -------- | 435| codec | 指向视频编码实例的指针。 | 436| window | 指向OHNativeWindow实例的指针，请参阅[OHNativeWindow](_codec_base.md#ohnativewindow)。 应用负责管理window的生命周期，结束时调用OH_NativeWindow_DestroyNativeWindow释放。 | 437 438**返回：** 439 440返回接口结果： 441 442AV_ERR_OK：执行成功。 443 444AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 445 446AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 447 448 449### OH_VideoEncoder_IsValid() 450 451``` 452OH_AVErrCode OH_VideoEncoder_IsValid (OH_AVCodec *codec, bool *isValid ) 453``` 454**描述** 455在编码器实例存在的情况下，检查当前编码器服务是否有效。 456 457**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 458 459**起始版本：** 10 460 461**参数:** 462 463| 名称 | 描述 | 464| -------- | -------- | 465| codec | 指向视频编码实例的指针。 | 466| isValid | 输出参数，指向布尔类型的指针。只有当接口返回AV_ERR_OK时，该值表示编码器服务的有效性（true为有效，false为无效）。建议开发者将isValid初始化为false。 | 467 468**返回：** 469 470返回接口结果： 471 472AV_ERR_OK：执行成功。 473 474AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 475 476 477### OH_VideoEncoder_NotifyEndOfStream() 478 479``` 480OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec *codec) 481``` 482**描述** 483通知视频编码器输入流已结束。建议使用此接口进行通知。该接口只在Surface模式下使用，Buffer模式通过OH_AVBuffer携带EOS信息，通知输入流的结束。 484 485**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 486 487**起始版本：** 9 488 489**参数:** 490 491| 名称 | 描述 | 492| -------- | -------- | 493| codec | 指向视频编码实例的指针。 | 494 495**返回：** 496 497返回接口结果： 498 499AV_ERR_OK：执行成功。 500 501AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 502 503AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 504 505AV_ERR_UNKNOWN：未知错误。 506 507AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 508 509AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 510 511 512### OH_VideoEncoder_Prepare() 513 514``` 515OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec *codec) 516``` 517**描述** 518准备编码器的内部资源，在OH_VideoEncoder_Configure接口后调用。 519 520**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 521 522**起始版本：** 9 523 524**参数:** 525 526| 名称 | 描述 | 527| -------- | -------- | 528| codec | 指向视频编码实例的指针。 | 529 530**返回：** 531 532返回接口结果： 533 534AV_ERR_OK：执行成功。 535 536AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 537 538AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 539 540 541### OH_VideoEncoder_PushInputBuffer() 542 543``` 544OH_AVErrCode OH_VideoEncoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 545``` 546**描述** 547Buffer模式下，将index对应的OH_AVBuffer送入编码器编码。 548 549**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 550 551**起始版本：** 11 552 553**参数:** 554 555| 名称 | 描述 | 556| -------- | -------- | 557| codec | 指向视频编码实例的指针。 | 558| index | 输入缓冲区对应的索引值。由[OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer)给出。 | 559 560**返回：** 561 562返回接口结果： 563 564AV_ERR_OK：执行成功。 565 566AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 567 568AV_ERR_INVALID_VAL： 569 570 1. 输入的codec指针为非编码器实例，或者为空指针； 571 2. 输入format参数不支持。 572 573AV_ERR_UNKNOWN：未知错误。 574 575AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 576 577AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 578 579 580### OH_VideoEncoder_PushInputParameter() 581 582``` 583OH_AVErrCode OH_VideoEncoder_PushInputParameter (OH_AVCodec *codec, uint32_t index) 584``` 585**描述** 586Surface模式下，将index对应帧的编码参数送入编码器编码。 587 588**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 589 590**起始版本：** 12 591 592**参数:** 593 594| 名称 | 描述 | 595| -------- | -------- | 596| codec | 指向视频编码实例的指针。 | 597| index | 输入参数缓冲区对应的索引值。由[OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter)给出。 | 598 599**返回：** 600 601返回接口结果： 602 603AV_ERR_OK：执行成功。 604 605AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 606 607AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 608 609AV_ERR_UNKNOWN：未知错误。 610 611AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 612 613AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 614 615 616### OH_VideoEncoder_RegisterCallback() 617 618``` 619OH_AVErrCode OH_VideoEncoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 620``` 621**描述** 622注册OH_AVCodecCallback回调函数，让应用可以响应视频编码器生成的事件。在调用OH_VideoEncoder_Prepare接口之前，必须调用此接口。 623 624**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 625 626**起始版本：** 11 627 628**参数:** 629 630| 名称 | 描述 | 631| -------- | -------- | 632| codec | 指向视频编码实例的指针。 | 633| callback | 所有回调函数的集合，请参阅[OH_AVCodecCallback](_o_h___a_v_codec_callback.md)。 | 634| userData | 开发者执行回调所依赖的数据。 | 635 636**返回：** 637 638返回接口结果： 639 640AV_ERR_OK：执行成功。 641 642AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 643 644AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 645 646AV_ERR_UNKNOWN：未知错误。 647 648AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 649 650AV_ERR_INVALID_STATE：本接口必须在OH_VideoEncoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 651 652 653### OH_VideoEncoder_RegisterParameterCallback() 654 655``` 656OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback (OH_AVCodec *codec, OH_VideoEncoder_OnNeedInputParameter onInputParameter, void *userData) 657``` 658**描述** 659注册OH_AVCodecCallback输入参数回调函数，让应用可以响应视频编码器生成的事件。编码Surface模式，需要设置随帧参数时，须使用该接口。 660 661如果使用该接口，必须在[OH_VideoEncoder_Configure](#oh_videoencoder_configure)之前调用该接口。 662 663**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 664 665**起始版本：** 12 666 667**参数:** 668 669| 名称 | 描述 | 670| -------- | -------- | 671| codec | 指向视频编码实例的指针。 | 672| onInputParameter | 输入参数回调指针，请参阅[OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter)。 | 673| userData | 开发者执行回调所依赖的数据。 | 674 675**返回：** 676 677返回接口结果： 678 679AV_ERR_OK：执行成功。 680 681AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 682 683AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 684 685AV_ERR_UNKNOWN：未知错误。 686 687AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 688 689AV_ERR_INVALID_STATE：本接口必须在OH_VideoEncoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 690 691 692### OH_VideoEncoder_Reset() 693 694``` 695OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec *codec) 696``` 697**描述** 698重置编码器，编码器回到初始化状态。如果要继续编码，需要再次调用OH_VideoEncoder_Configure接口配置编码器实例。 699 700**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 701 702**起始版本：** 9 703 704**参数:** 705 706| 名称 | 描述 | 707| -------- | -------- | 708| codec | 指向视频编码实例的指针。 | 709 710**返回：** 711 712返回接口结果： 713 714AV_ERR_OK：执行成功。 715 716AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 717 718AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 719 720AV_ERR_UNKNOWN：未知错误。 721 722AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 723 724 725### OH_VideoEncoder_SetParameter() 726 727``` 728OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 729``` 730**描述** 731在编码器运行时设置编码器参数。 732 733注意，此接口只有在编码器启动后才能调用。 同时，不正确的参数设置可能会导致编码失败。 734 735**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 736 737**起始版本：** 9 738 739**参数:** 740 741| 名称 | 描述 | 742| -------- | -------- | 743| codec | 指向视频编码实例的指针。 | 744| format | 指向OH_AVFormat实例的指针。 | 745 746**返回：** 747 748返回接口结果： 749 750AV_ERR_OK：执行成功。 751 752AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 753 754AV_ERR_INVALID_VAL： 755 756 1. 输入的codec指针为非编码器实例，或者为空指针； 757 2. 输入format参数不支持。 758 759AV_ERR_UNKNOWN：未知错误。 760 761AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 762 763AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 764 765 766### OH_VideoEncoder_Start() 767 768``` 769OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec *codec) 770``` 771**描述** 772调用OH_VideoEncoder_Prepare接口成功后调用此接口启动编码器。成功启动后，编码器将开始报告注册的回调事件。 773 774Surface模式下，在surface中有正确的输入后，每完成一帧编码会触发OnNewOutputBuffer。 775 776Buffer模式下，编码器会立即触发输入回调，开发者每完成一次输入，编码器执行编码，每完成一帧编码会触发OnNewOutputBuffer。 777 778**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 779 780**起始版本：** 9 781 782**参数:** 783 784| 名称 | 描述 | 785| -------- | -------- | 786| codec | 指向视频编码实例的指针。 | 787 788**返回：** 789 790返回接口结果： 791 792AV_ERR_OK：执行成功。 793 794AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 795 796AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 797 798AV_ERR_UNKNOWN：未知错误。 799 800AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 801 802AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 803 804 805### OH_VideoEncoder_Stop() 806 807``` 808OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec *codec) 809``` 810**描述** 811停止编码器，释放输入输出buffer。停止之后，可以通过调用OH_VideoEncoder_Start接口重新进入Running状态。 812 813**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 814 815**起始版本：** 9 816 817**参数:** 818 819| 名称 | 描述 | 820| -------- | -------- | 821| codec | 指向视频编码实例的指针。 | 822 823**返回：** 824 825返回接口结果： 826 827AV_ERR_OK：执行成功。 828 829AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 830 831AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 832 833AV_ERR_UNKNOWN：未知错误。 834 835AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 836 837AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 838 839 840### OH_VideoEncoder_QueryInputBuffer() 841 842``` 843OH_AVErrCode OH_VideoEncoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 844``` 845**描述** 846 847查询下一个可用输入缓冲区的索引。 848 849调用此接口后需要接着调用[OH_VideoEncoder_GetInputBuffer](#oh_videoencoder_getinputbuffer)接口获取缓冲区实例，并通过[OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer)接口传递给编码器。 850 851需要注意的是，上述操作仅在同步模式下支持。 852 853**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 854 855**起始版本：** 20 856 857**参数:** 858 859| 名称 | 描述 | 860| -------- | -------- | 861| codec | 指向视频编码实例的指针。 | 862| index | 输入buffer对应的索引值。| 863| timeoutUs | 超时时长，单位为微秒。负值：无限等待；0：立即退出；正值：等待指定时长后退出。 | 864 865**返回：** 866 867返回接口结果： 868 869AV_ERR_OK：执行成功。 870 871AV_ERR_NO_MEMORY：输入的编码器实例已经销毁。 872 873AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 874 875AV_ERR_UNKNOWN：未知错误。 876 877AV_ERR_SERVICE_DIED：编解码服务已终止。 878 879AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 880 881AV_ERR_OPERATE_NOT_PERMIT：禁止异步模式下使用。 882 883AV_ERR_TRY_AGAIN_LATER：查询失败，建议等待短暂间隔后重试。 884 885 886### OH_VideoEncoder_GetInputBuffer() 887 888``` 889OH_AVBuffer *OH_VideoEncoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index); 890``` 891**描述** 892 893获取可用输入缓冲区的实例。 894 895需要注意的是，此接口仅适用于同步模式。 896 897**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 898 899**起始版本：** 20 900 901**参数:** 902 903| 名称 | 描述 | 904| -------- | -------- | 905| codec | 指向视频编码实例的指针。 | 906| index | 输入buffer对应的索引值，可通过[OH_VideoEncoder_QueryInputBuffer](#oh_videoencoder_queryinputbuffer)接口获取。| 907 908**返回：** 909 910如果执行成功，则返回一个指向OH_AVBuffer实例的指针，否则返回NULL。 911 912 913### OH_VideoEncoder_QueryOutputBuffer() 914 915``` 916OH_AVErrCode OH_VideoEncoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 917``` 918**描述** 919 920查询下一个可用输出缓冲区的索引。 921 922通过[OH_VideoEncoder_GetOutputBuffer](#oh_videoencoder_getoutputbuffer)接口获取的缓冲区实例可以通过[OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer)接口将处理后的输出缓冲区返回到编码器。 923 924需要注意的是，上述操作仅在同步模式下支持。 925 926**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 927 928**起始版本：** 20 929 930**参数:** 931 932| 名称 | 描述 | 933| -------- | -------- | 934| codec | 指向视频编码实例的指针。 | 935| index | 输出buffer对应的索引值。| 936| timeoutUs | 超时时长，单位为微秒。负值：无限等待；0：立即退出；正值：等待指定时长后退出。 | 937 938**返回：** 939 940返回接口结果： 941 942AV_ERR_OK：执行成功。 943 944AV_ERR_NO_MEMORY：输入的编码器实例已经销毁。 945 946AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 947 948AV_ERR_UNKNOWN：未知错误。 949 950AV_ERR_SERVICE_DIED：编解码服务已终止。 951 952AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 953 954AV_ERR_OPERATE_NOT_PERMIT：禁止异步模式下使用。 955 956AV_ERR_STREAM_CHANGED：流格式已变更，可以通过调用OH_VideoEncoder_GetOutputDescription接口获取新的流信息。 957 958AV_ERR_TRY_AGAIN_LATER：查询失败，建议等待短暂间隔后重试。 959 960 961### OH_VideoEncoder_GetOutputBuffer() 962 963``` 964OH_AVBuffer *OH_VideoEncoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index); 965``` 966**描述** 967 968获取可用输出缓冲区的实例。 969 970需要注意的是，此接口仅适用于同步模式。 971 972**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 973 974**起始版本：** 20 975 976**参数:** 977 978| 名称 | 描述 | 979| -------- | -------- | 980| codec | 指向视频编码实例的指针。 | 981| index | 输出buffer对应的索引值，可通过[OH_VideoEncoder_QueryOutputBuffer](#oh_videoencoder_queryoutputbuffer)接口获取。| 982 983**返回：** 984 985如果执行成功，则返回一个指向OH_AVBuffer实例的指针，否则返回NULL。 986 987 988## 废弃函数说明 989 990 991### OH_VideoEncoder_SetCallback() 992 993``` 994OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 995``` 996**描述** 997设置OH_AVCodecCallback回调函数，让应用可以响应视频编码器生成的事件。在调用OH_VideoEncoder_Prepare接口之前，必须调用此接口。 998 999**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 1000 1001**起始版本：** 9 1002 1003**废弃版本：** 11 1004 1005**替代接口：**[OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) 1006 1007**参数:** 1008 1009| 名称 | 描述 | 1010| -------- | -------- | 1011| codec | 指向视频编码实例的指针。 | 1012| callback | 所有回调函数的集合，请参阅[OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md)。 | 1013| userData | 开发者执行回调所依赖的数据。 | 1014 1015**返回：** 1016 1017返回接口结果： 1018 1019AV_ERR_OK：执行成功。 1020 1021AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 1022 1023AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 1024 1025AV_ERR_UNKNOWN：未知错误。 1026 1027AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 1028 1029AV_ERR_INVALID_STATE：本接口必须在OH_VideoEncoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 1030 1031 1032### OH_VideoEncoder_PushInputData() 1033 1034``` 1035OH_AVErrCode OH_VideoEncoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 1036``` 1037**描述** 1038将填入数据的输入缓冲区提交给视频编码器。 1039 1040**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 1041 1042**起始版本：** 10 1043 1044**废弃版本：** 11 1045 1046**替代接口：**[OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) 1047 1048**参数:** 1049 1050| 名称 | 描述 | 1051| -------- | -------- | 1052| codec | 指向视频编码实例的指针。 | 1053| index | 输入缓冲区对应的索引值。由[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)给出。 | 1054| attr | 缓冲区中包含数据的描述信息。 | 1055 1056**返回：** 1057 1058返回接口结果： 1059 1060AV_ERR_OK：执行成功。 1061 1062AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 1063 1064AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 1065 1066AV_ERR_UNKNOWN：未知错误。 1067 1068AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 1069 1070AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。 1071 1072 1073### OH_VideoEncoder_FreeOutputData() 1074 1075``` 1076OH_AVErrCode OH_VideoEncoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 1077``` 1078**描述** 1079将处理后的输出缓冲区返回给编码器。 1080 1081**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 1082 1083**起始版本：** 9 1084 1085**废弃版本：** 11 1086 1087**替代接口：**[OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) 1088 1089**参数:** 1090 1091| 名称 | 描述 | 1092| -------- | -------- | 1093| codec | 指向视频编码实例的指针。 | 1094| index | 输出缓冲区对应的索引值。由[OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata)给出。 | 1095 1096**返回：** 1097 1098返回接口结果： 1099 1100AV_ERR_OK：执行成功。 1101 1102AV_ERR_NO_MEMORY：输入的编码实例内部异常，如内部出现异常空指针。 1103 1104AV_ERR_INVALID_VAL：输入的codec指针为非编码器实例，或者为空指针。 1105 1106AV_ERR_UNKNOWN：未知错误。 1107 1108AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 1109 1110AV_ERR_INVALID_STATE：编码器状态不支持调用本接口时调用。
