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