1# VideoEncoder 2 3 4## Overview 5 6The VideoEncoder module provides the APIs for video encoding. 7 8**System capability**: SystemCapability.Multimedia.VideoEncoder 9 10**Since**: 9 11 12The following figures show the APIs supported by each version and the APIs that can be called in different states. 13 14 15 16 17 18## Summary 19 20 21### Files 22 23| Name| Description| 24| -------- | -------- | 25| [native_avcodec_videoencoder.h](native__avcodec__videoencoder_8h.md) | Declares the APIs used for video encoding. | 26 27 28### Types 29 30| Name| Description| 31| -------- | -------- | 32| typedef void(\* [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter)) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, OH_AVFormat \*parameter, void \*userData) | Defines the pointer to the function that is called when new input parameters are required for a frame with the specified index. It takes effect only in surface mode. | 33 34### Enums 35 36| Name| Description| 37| -------- | -------- | 38| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) { CBR = 0, VBR = 1, CQ = 2 } | Enumerates the bit rate modes of a video encoder. | 39 40 41### Functions 42 43| Name| Description| 44| -------- | -------- | 45| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoEncoder_CreateByMime](#oh_videoencoder_createbymime) (const char \*mime) | Creates a video encoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This function is recommended. | 46| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoEncoder_CreateByName](#oh_videoencoder_createbyname) (const char \*name) | Creates a video encoder instance based on an encoder name. | 47| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Destroy](#oh_videoencoder_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the internal resources of a video encoder and destroys the encoder instance. | 48| [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) | Sets an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. (This function is deprecated in API version 11.) | 49| [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) | Registers an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. | 50| [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) | Registers an OH_AVCodecCallback input parameter callback so that your application can respond to events generated by a video encoder. | 51| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Configure](#oh_videoencoder_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, OH_AVFormat \*format) | Configures a video encoder. Typically, you need to configure the description information about the video track to be encoded, such as the width, height, and pixel format. | 52| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Prepare](#oh_videoencoder_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Prepares internal resources for a video encoder. | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Start](#oh_videoencoder_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Starts a video encoder. This function should be called after a successful call of **OH_VideoEncoder_Prepare**. | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Stop](#oh_videoencoder_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Stops a video encoder and releases the input and output buffers. | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Flush](#oh_videoencoder_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video encoder. | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Reset](#oh_videoencoder_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Resets a video encoder. The encoder returns to the initial state. | 57| OH_AVFormat \* [OH_VideoEncoder_GetOutputDescription](#oh_videoencoder_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Obtains the OH_AVFormat information about the output data of a video encoder. | 58| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetParameter](#oh_videoencoder_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, OH_AVFormat \*format) | Set the OH_AVFormat information when a video encoder is running. | 59| [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) | Obtains the input surface from a video encoder. | 60| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputData](#oh_videoencoder_freeoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Frees an output buffer of a video encoder. (This function is deprecated in API version 11.) | 61| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_NotifyEndOfStream](#oh_videoencoder_notifyendofstream) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Notifies a video encoder that input streams end. | 62| [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) | Pushes the input buffer filled with data to a video encoder. (This function is deprecated in API version 11.) | 63| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Pushes the OH_AVBuffer corresponding to the index to a video encoder in buffer mode. | 64| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputParameter](#oh_videoencoder_pushinputparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Pushes the parameter configured for a frame with the given index to a video encoder in surface mode. | 65| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Returns the processed OH_AVBuffer corresponding to the index to a video encoder. | 66| OH_AVFormat \* [OH_VideoEncoder_GetInputDescription](#oh_videoencoder_getinputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Obtains the description of the image received by a video encoder. | 67| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_IsValid](#oh_videoencoder_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | Checks whether a video encoder instance is valid. | 68 69 70## Type Description 71 72### OH_VideoEncoder_OnNeedInputParameter 73 74``` 75typedef void(* OH_VideoEncoder_OnNeedInputParameter) (OH_AVCodec *codec, uint32_t index, OH_AVFormat *parameter, void *userData) 76``` 77 78**Description** 79 80Defines the pointer to the function that is called when new input parameters are required for a frame with the specified index. 81 82This callback can be used only in surface mode after it is registered by calling OH_VideoEncoder_RegisterParameterCallback. 83 84In buffer mode, OH_AVBuffer can directly carry the encoding parameter associated with each frame. Currently, it can manage parameters, including **QPMin**, **QPMax**, and reference frames for Long Term Reference (LTR), on a per-frame basis. 85 86**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 87 88**Since**: 12 89 90**Parameters** 91 92| Name| Description| 93| -------- | -------- | 94| codec | Pointer to a video encoder instance. | 95| index | Index of the frame to encode. | 96| parameter | Pointer to the encoding parameter | 97| userData | Pointer to the data on which the caller depends when executing the callback. | 98 99 100## Enum Description 101 102 103### OH_VideoEncodeBitrateMode 104 105``` 106enum OH_VideoEncodeBitrateMode 107``` 108 109**Description** 110 111Enumerates the bit rate modes of a video encoder. 112 113**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 114 115**Since**: 9 116 117| Value| Description| 118| -------- | -------- | 119| CBR | Constant bit rate. | 120| VBR | Variable bit rate. | 121| CQ | Constant quality. | 122 123 124## Function Description 125 126 127### OH_VideoEncoder_Configure() 128 129``` 130OH_AVErrCode OH_VideoEncoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 131``` 132 133**Description** 134 135Configures a video encoder. Typically, you need to configure the description information about the video track to be encoded, such as the width, height, and pixel format. This function must be called prior to **OH_VideoEncoder_Prepare**. 136 137This function is used to verify the validity of configuration parameters. Some invalid parameters are not forcibly verified. The default values are used or discarded. Some invalid parameters are forcibly verified. The rules are as follows: 138 139The value ranges of the following parameters can be obtained from [Capability Query](../../media/avcodec/obtain-supported-codecs.md). All the values of **OH_MD_KEY_I_FRAME_INTERVAL** are supported. 140 141If the current platform does not support **OH_MD_KEY_VIDEO_ENCODER_ENABLE_TEMPORAL_SCALABILITY** or **OH_MD_KEY_VIDEO_ENCODER_LTR_FRAME_COUNT**, no error is reported and the normal encoding process is used. 142 143Parameter verification rules are as follows: 144 145| Key | Value Within the Range| Value Out of Range| No Value Configured| 146| ------------------------------------------------------------------------- | -------- | -------- | ------ | 147| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 148| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 149| OH_MD_KEY_PIXEL_FORMAT<br>For details, see [OH_AVPixelFormat](_core.md#oh_avpixelformat).| AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 150| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL |AV_ERR_OK | 151| OH_MD_KEY_PROFILE<br>For details, see [OH_MD_KEY_PROFILE](_codec_base.md#oh_md_key_profile). | AV_ERR_OK | AV_ERR_INVALID_VAL |AV_ERR_OK | 152| OH_MD_KEY_I_FRAME_INTERVAL | AV_ERR_OK | \\ | AV_ERR_OK | 153 154| OH_MD_KEY_<br>BITRATE | OH_MD_KEY_<br>QUALITY | OH_MD_KEY_<br>VIDEO_ENCODER_BITRATE_MODE | Return Value| Description | 155| :-------------------- | :-------------------- | :--------------------------------------- | ---- | ---------------------- | 156| \\ | \\ | \\ | AV_ERR_OK | The default value of the encoder is used. | 157| Out of range | Out of range | Unsupported mode | AV_ERR_INVALID_VAL | An error is reported for all abnormal values. | 158| Normal value | Normal value | \\ | AV_ERR_INVALID_VAL | The bit rate conflicts with the quality. | 159| Normal value | \\ | \\ | AV_ERR_OK | The default bit rate control mode is enabled. | 160| Normal value | \\ | VBR and CBR | AV_ERR_OK | | 161| Normal value | \\ | CQ | AV_ERR_INVALID_VAL | The bit rate conflicts with the CQ mode. | 162| \\ | Normal value | \\ | AV_ERR_OK | The CQ mode is enabled. | 163| \\ | Normal value | CQ | AV_ERR_OK | | 164| \\ | Normal value | VBR and CBR | AV_ERR_INVALID_VAL | The quality conflicts with the VBR or CBR mode.| 165| \\ | \\ | VBR and CBR | AV_ERR_OK | The default bit rate of the encoder is used. | 166| \\ | \\ | CQ | AV_ERR_OK | The default quality is used. | 167 168 169**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 170 171**Since**: 9 172 173**Parameters** 174 175| Name| Description| 176| -------- | -------- | 177| codec | Pointer to a video encoder instance. | 178| format | Pointer to an **OH_AVFormat** instance, which provides the description information about the video track to be encoded. | 179 180**Returns** 181 182Returns any of the following result codes: 183 184**AV_ERR_OK**: The operation is successful. 185 186**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 187 188**AV_ERR_INVALID_VAL**: 189 190 1. The value of **codec** is a null pointer or does not point to an encoder instance. 191 2. The format is not supported. 192 193**AV_ERR_UNKNOWN**: An unknown error occurs. 194 195**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 196 197**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 198 199 200### OH_VideoEncoder_CreateByMime() 201 202``` 203OH_AVCodec* OH_VideoEncoder_CreateByMime (const char *mime) 204``` 205 206**Description** 207 208Creates a video encoder instance based on a MIME type. This function is recommended. 209 210**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 211 212**Since**: 9 213 214**Parameters** 215 216| Name| Description| 217| -------- | -------- | 218| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 219 220**Returns** 221 222Returns the pointer to the video encoder instance created if the operation is successful; returns NULL if the encoder type is not supported or the memory is insufficient. 223 224 225### OH_VideoEncoder_CreateByName() 226 227``` 228OH_AVCodec* OH_VideoEncoder_CreateByName (const char *name) 229``` 230 231**Description** 232 233Creates a video encoder instance based on an encoder name. Tho use this function, you must know the exact name of the encoder. The encoder name can be obtained through capability query. 234 235**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 236 237**Since**: 9 238 239**Parameters** 240 241| Name| Description| 242| -------- | -------- | 243| name | Pointer to a video encoder name. | 244 245**Returns** 246 247Returns the pointer to the video encoder instance created if the operation is successful; returns NULL if the encoder name is not supported or the memory is insufficient. 248 249 250### OH_VideoEncoder_Destroy() 251 252``` 253OH_AVErrCode OH_VideoEncoder_Destroy (OH_AVCodec *codec) 254``` 255 256**Description** 257 258Clears the internal resources of a video encoder and destroys the encoder instance. You only need to call the function once. 259 260**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 261 262**Since**: 9 263 264**Parameters** 265 266| Name| Description| 267| -------- | -------- | 268| codec | Pointer to a video encoder instance. | 269 270**Returns** 271 272Returns any of the following result codes: 273 274**AV_ERR_OK**: The operation is successful. 275 276**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 277 278**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 279 280**AV_ERR_UNKNOWN**: An unknown error occurs. 281 282**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 283 284 285### OH_VideoEncoder_Flush() 286 287``` 288OH_AVErrCode OH_VideoEncoder_Flush (OH_AVCodec *codec) 289``` 290 291**Description** 292 293Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video encoder. 294 295This function invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this function, ensure that the buffers with the specified indexes are no longer required. This function cannot be called consecutively. 296 297**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 298 299**Since**: 9 300 301**Parameters** 302 303| Name| Description| 304| -------- | -------- | 305| codec | Pointer to a video encoder instance. | 306 307**Returns** 308 309Returns any of the following result codes: 310 311**AV_ERR_OK**: The operation is successful. 312 313**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 314 315**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 316 317**AV_ERR_UNKNOWN**: An unknown error occurs. 318 319**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 320 321**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 322 323 324### OH_VideoEncoder_FreeOutputBuffer() 325 326``` 327OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 328``` 329 330**Description** 331 332Returns the processed OH_AVBuffer corresponding to the index to a video encoder. You need to call this function to release the output buffer in a timely manner. Otherwise, the encoding process is blocked. 333 334**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 335 336**Since**: 11 337 338**Parameters** 339 340| Name| Description| 341| -------- | -------- | 342| codec | Pointer to a video encoder instance. | 343| index | Index of the output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 344 345**Returns** 346 347Returns any of the following result codes: 348 349**AV_ERR_OK**: The operation is successful. 350 351**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 352 353**AV_ERR_INVALID_VAL**: 354 355 1. The value of **codec** is a null pointer or does not point to an encoder instance. 356 2. The format is not supported. 357 3. The index is invalid or the same index is used consecutively. This error does not affect the subsequent encoding process. 358 359**AV_ERR_UNKNOWN**: An unknown error occurs. 360 361**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 362 363**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 364 365 366### OH_VideoEncoder_GetInputDescription() 367 368``` 369OH_AVFormat* OH_VideoEncoder_GetInputDescription (OH_AVCodec *codec) 370``` 371 372**Description** 373 374Obtains the description of the image received by a video encoder. This function must be called after [OH_VideoEncoder_Configure](#oh_videoencoder_configure) is called. 375 376The caller must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to manually release the **OH_AVFormat** instance in the return value. 377 378**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 379 380**Since**: 10 381 382**Parameters** 383 384| Name| Description| 385| -------- | -------- | 386| codec | Pointer to a video encoder instance. | 387 388**Returns** 389 390Returns the pointer to an **OH_AVFormat** instance if the operation is successful; returns NULL if the value of **codec** is a null pointer or does not point to an encoder instance. 391 392 393### OH_VideoEncoder_GetOutputDescription() 394 395``` 396OH_AVFormat* OH_VideoEncoder_GetOutputDescription (OH_AVCodec *codec) 397``` 398 399**Description** 400 401Obtains the OH_AVFormat information about the output data of a video encoder. 402 403The caller must call **OH_AVFormat_Destroy()** to release the **OH_AVFormat** instance in the return value. 404 405**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 406 407**Since**: 9 408 409**Parameters** 410 411| Name| Description| 412| -------- | -------- | 413| codec | Pointer to a video encoder instance. | 414 415**Returns** 416 417Returns the pointer to an **OH_AVFormat** instance if the operation is successful; returns NULL if the value of **codec** is a null pointer or does not point to an encoder instance. 418 419 420### OH_VideoEncoder_GetSurface() 421 422``` 423OH_AVErrCode OH_VideoEncoder_GetSurface (OH_AVCodec *codec, OHNativeWindow ** window ) 424``` 425 426**Description** 427 428Sets an input surface for a video encoder. This function must be called prior to **OH_VideoEncoder_Prepare**. 429 430**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 431 432**Since**: 9 433 434**Parameters** 435 436| Name| Description| 437| -------- | -------- | 438| codec | Pointer to a video encoder instance. | 439| window | Pointer to an **OHNativeWindow** instance. For details, see [OHNativeWindow](_codec_base.md#ohnativewindow). The application manages the lifecycle of the window and calls **OH_NativeWindow_DestroyNativeWindow** to release the window when the lifecycle ends. | 440 441**Returns** 442 443Returns any of the following result codes: 444 445**AV_ERR_OK**: The operation is successful. 446 447**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 448 449**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 450 451 452### OH_VideoEncoder_IsValid() 453 454``` 455OH_AVErrCode OH_VideoEncoder_IsValid (OH_AVCodec *codec, bool *isValid ) 456``` 457 458**Description** 459 460Checks whether a video encoder instance is valid. 461 462**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 463 464**Since**: 10 465 466**Parameters** 467 468| Name| Description| 469| -------- | -------- | 470| codec | Pointer to a video encoder instance. | 471| isValid | Pointer of the Boolean type. The value **true** means that the encoder instance is valid and **false** means the opposite. It is recommended that the caller initialize **isValid** to **false**. | 472 473**Returns** 474 475Returns either of the following result codes: 476 477**AV_ERR_OK**: The operation is successful. 478 479**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 480 481 482### OH_VideoEncoder_NotifyEndOfStream() 483 484``` 485OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec *codec) 486``` 487 488**Description** 489 490Notifies a video encoder that input streams end. You are advised to use this function for notification. This function is used only in surface mode. In buffer mode, OH_AVBuffer is used to carry the EOS information to notify the end of the input stream. 491 492**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 493 494**Since**: 9 495 496**Parameters** 497 498| Name| Description| 499| -------- | -------- | 500| codec | Pointer to a video encoder instance. | 501 502**Returns** 503 504Returns any of the following result codes: 505 506**AV_ERR_OK**: The operation is successful. 507 508**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 509 510**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 511 512**AV_ERR_UNKNOWN**: An unknown error occurs. 513 514**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 515 516**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 517 518 519### OH_VideoEncoder_Prepare() 520 521``` 522OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec *codec) 523``` 524 525**Description** 526 527Prepares internal resources for a video encoder. This function must be called after **OH_VideoEncoder_Configure**. 528 529**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 530 531**Since**: 9 532 533**Parameters** 534 535| Name| Description| 536| -------- | -------- | 537| codec | Pointer to a video encoder instance. | 538 539**Returns** 540 541Returns any of the following result codes: 542 543**AV_ERR_OK**: The operation is successful. 544 545**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 546 547**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 548 549 550### OH_VideoEncoder_PushInputBuffer() 551 552``` 553OH_AVErrCode OH_VideoEncoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 554``` 555 556**Description** 557 558Pushes the OH_AVBuffer corresponding to the index to a video encoder in buffer mode. 559 560**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 561 562**Since**: 11 563 564**Parameters** 565 566| Name| Description| 567| -------- | -------- | 568| codec | Pointer to a video encoder instance. | 569| index | Index of the input buffer. The index is obtained from [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer).| 570 571**Returns** 572 573Returns any of the following result codes: 574 575**AV_ERR_OK**: The operation is successful. 576 577**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 578 579**AV_ERR_INVALID_VAL**: 580 581 1. The value of **codec** is a null pointer or does not point to an encoder instance. 582 2. The format is not supported. 583 584**AV_ERR_UNKNOWN**: An unknown error occurs. 585 586**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 587 588**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 589 590 591### OH_VideoEncoder_PushInputParameter() 592 593``` 594OH_AVErrCode OH_VideoEncoder_PushInputParameter (OH_AVCodec *codec, uint32_t index) 595``` 596 597**Description** 598 599Pushes the parameter configured for a frame with the given index to a video encoder in surface mode. 600 601**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 602 603**Since**: 12 604 605**Parameters** 606 607| Name| Description| 608| -------- | -------- | 609| codec | Pointer to a video encoder instance. | 610| index | Index of the input parameter buffer. The index is obtained from [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter). | 611 612**Returns** 613 614Returns any of the following result codes: 615 616**AV_ERR_OK**: The operation is successful. 617 618**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 619 620**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 621 622**AV_ERR_UNKNOWN**: An unknown error occurs. 623 624**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 625 626**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 627 628 629### OH_VideoEncoder_RegisterCallback() 630 631``` 632OH_AVErrCode OH_VideoEncoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 633``` 634 635**Description** 636 637Registers an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. This function must be called prior to **OH_VideoEncoder_Prepare**. 638 639**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 640 641**Since**: 11 642 643**Parameters** 644 645| Name| Description| 646| -------- | -------- | 647| codec | Pointer to a video encoder instance. | 648| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md). | 649| userData | Pointer to the data on which the caller depends when executing the callback. | 650 651**Returns** 652 653Returns any of the following result codes: 654 655**AV_ERR_OK**: The operation is successful. 656 657**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 658 659**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 660 661**AV_ERR_UNKNOWN**: An unknown error occurs. 662 663**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 664 665**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 666 667 668### OH_VideoEncoder_RegisterParameterCallback() 669 670``` 671OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback (OH_AVCodec *codec, OH_VideoEncoder_OnNeedInputParameter onInputParameter, void *userData) 672``` 673 674**Description** 675 676Registers an OH_AVCodecCallback input parameter callback so that your application can respond to events generated by a video encoder. In surface encoding mode, this function must be called when frame parameters need to be set, and it must be called before [OH_VideoEncoder_Configure](#oh_videoencoder_configure). 677 678**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 679 680**Since**: 12 681 682**Parameters** 683 684| Name| Description| 685| -------- | -------- | 686| codec | Pointer to a video encoder instance. | 687| onInputParameter | Pointer to the input parameter callback. For details, see [OH_VideoEncoder_OnNeedInputParameter](#oh_videoencoder_onneedinputparameter). | 688| userData | Pointer to the data on which the caller depends when executing the callback. | 689 690**Returns** 691 692Returns any of the following result codes: 693 694**AV_ERR_OK**: The operation is successful. 695 696**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 697 698**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 699 700**AV_ERR_UNKNOWN**: An unknown error occurs. 701 702**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 703 704**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 705 706 707### OH_VideoEncoder_Reset() 708 709``` 710OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec *codec) 711``` 712 713**Description** 714 715Resets a video encoder. The encoder returns to the initial state. To continue encoding, you must call **OH_VideoEncoder_Configure** to configure the encoder again. 716 717**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 718 719**Since**: 9 720 721**Parameters** 722 723| Name| Description| 724| -------- | -------- | 725| codec | Pointer to a video encoder instance. | 726 727**Returns** 728 729Returns any of the following result codes: 730 731**AV_ERR_OK**: The operation is successful. 732 733**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 734 735**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 736 737**AV_ERR_UNKNOWN**: An unknown error occurs. 738 739**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 740 741 742### OH_VideoEncoder_SetParameter() 743 744``` 745OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 746``` 747 748**Description** 749 750Set the OH_AVFormat information when a video encoder is running. 751 752This function can be called only after the encoder is started. Incorrect parameter settings may cause encoding failure. 753 754**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 755 756**Since**: 9 757 758**Parameters** 759 760| Name| Description| 761| -------- | -------- | 762| codec | Pointer to a video encoder instance. | 763| format | Pointer to an **OH_AVFormat** instance. | 764 765**Returns** 766 767Returns any of the following result codes: 768 769**AV_ERR_OK**: The operation is successful. 770 771**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 772 773**AV_ERR_INVALID_VAL**: 774 775 1. The value of **codec** is a null pointer or does not point to an encoder instance. 776 2. The format is not supported. 777 778**AV_ERR_UNKNOWN**: An unknown error occurs. 779 780**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 781 782**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 783 784 785### OH_VideoEncoder_Start() 786 787``` 788OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec *codec) 789``` 790 791**Description** 792 793Starts a video encoder. This function should be called after a successful call of **OH_VideoEncoder_Prepare**. After being started, the encoder starts to report the registered event. 794 795In surface mode, when there is a correct input on the surface, **OnNewOutputBuffer** is triggered each time a frame is encoded. 796 797In buffer mode, the encoder immediately triggers the input callback. Each time the caller completes an input, the encoder performs encoding. **OnNewOutputBuffer** is triggered each time a frame is encoded. 798 799**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 800 801**Since**: 9 802 803**Parameters** 804 805| Name| Description| 806| -------- | -------- | 807| codec | Pointer to a video encoder instance. | 808 809**Returns** 810 811Returns any of the following result codes: 812 813**AV_ERR_OK**: The operation is successful. 814 815**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 816 817**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 818 819**AV_ERR_UNKNOWN**: An unknown error occurs. 820 821**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 822 823**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 824 825 826### OH_VideoEncoder_Stop() 827 828``` 829OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec *codec) 830``` 831 832**Description** 833 834Stops a video encoder and releases the input and output buffers. After the video encoder is stopped, you can call **OH_VideoEncoder_Start** to enter the running state again. 835 836**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 837 838**Since**: 9 839 840**Parameters** 841 842| Name| Description| 843| -------- | -------- | 844| codec | Pointer to a video encoder instance. | 845 846**Returns** 847 848Returns any of the following result codes: 849 850**AV_ERR_OK**: The operation is successful. 851 852**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 853 854**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 855 856**AV_ERR_UNKNOWN**: An unknown error occurs. 857 858**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 859 860**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 861 862 863## Description of Deprecated Functions 864 865 866### OH_VideoEncoder_SetCallback() 867 868``` 869OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 870``` 871 872**Description** 873 874Sets an OH_AVCodecCallback callback so that your application can respond to events generated by a video encoder. This function must be called prior to **OH_VideoEncoder_Prepare**. 875 876**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 877 878**Since**: 9 879 880**Deprecated from**: 11 881 882**Substitute API**: [OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) 883 884**Parameters** 885 886| Name| Description| 887| -------- | -------- | 888| codec | Pointer to a video encoder instance. | 889| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md). | 890| userData | Pointer to the data on which the caller depends when executing the callback. | 891 892**Returns** 893 894Returns any of the following result codes: 895 896**AV_ERR_OK**: The operation is successful. 897 898**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 899 900**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 901 902**AV_ERR_UNKNOWN**: An unknown error occurs. 903 904**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 905 906**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoEncoder_Prepare**. 907 908 909### OH_VideoEncoder_PushInputData() 910 911``` 912OH_AVErrCode OH_VideoEncoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 913``` 914 915**Description** 916 917Pushes the input buffer filled with data to a video encoder. 918 919**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 920 921**Since**: 10 922 923**Deprecated from**: 11 924 925**Substitute API**: [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) 926 927**Parameters** 928 929| Name| Description| 930| -------- | -------- | 931| codec | Pointer to a video encoder instance. | 932| index | Index of the input buffer. The index is obtained from [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). | 933| attr | Description of the data contained in the buffer. | 934 935**Returns** 936 937Returns any of the following result codes: 938 939**AV_ERR_OK**: The operation is successful. 940 941**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 942 943**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 944 945**AV_ERR_UNKNOWN**: An unknown error occurs. 946 947**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 948 949**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 950 951 952### OH_VideoEncoder_FreeOutputData() 953 954``` 955OH_AVErrCode OH_VideoEncoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 956``` 957 958**Description** 959 960Frees an output buffer of a video encoder. 961 962**System capability**: SystemCapability.Multimedia.Media.VideoEncoder 963 964**Since**: 9 965 966**Deprecated from**: 11 967 968Substitute API: [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) 969 970**Parameters** 971 972| Name| Description| 973| -------- | -------- | 974| codec | Pointer to a video encoder instance. | 975| index | Index of the output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | 976 977**Returns** 978 979Returns any of the following result codes: 980 981**AV_ERR_OK**: The operation is successful. 982 983**AV_ERR_NO_MEMORY**: An internal exception occurs in the encoder instance, for example, a null pointer internally. 984 985**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to an encoder instance. 986 987**AV_ERR_UNKNOWN**: An unknown error occurs. 988 989**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 990 991**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 992
