1# VideoEncoder 2 3 4## Overview 5 6The **VideoEncoder** module provides the functions for video encoding. 7 8\@syscap SystemCapability.Multimedia.Avcodec.VideoEncoder 9 10**Since** 11 129 13 14 15## Summary 16 17 18### Files 19 20| Name| Description| 21| -------- | -------- | 22| [native_avcodec_videoencoder.h](native__avcodec__videoencoder_8h.md) | Declares the native APIs used for video encoding.<br>**File to include**: <multimedia/player_framework/native_avcodec_videoencoder.h><br> **Library**: libnative_media_venc.so| 23 24 25### Types 26 27| Name| Description| 28| -------- | -------- | 29| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) | Defines an enum that enumerates the bit rate modes of a video encoder.| 30 31 32### Enums 33 34| Name| Description| 35| -------- | -------- | 36| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) {<br> **CBR** = 0,<br> **VBR** = 1,<br> **CQ** = 2<br>} | Enumerates the bit rate modes of a video encoder.| 37 38 39### Functions 40 41| Name| Description| 42| -------- | -------- | 43| \*[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 in most cases.| 44| \*[OH_VideoEncoder_CreateByName](#oh_videoencoder_createbyname) (const char \*name) | Creates a video encoder instance based on an encoder name. To use this function, you must know the exact name of the encoder.| 45| [OH_VideoEncoder_Destroy](#oh_videoencoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of a video encoder and destroys the encoder instance.| 46| [OH_VideoEncoder_SetCallback](#oh_videoencoder_setcallback) (OH_AVCodec \*codec, OH_AVCodecAsyncCallback callback, void \*userData) | Sets an asynchronous callback so that your application can respond to events generated by a video encoder.| 47| [OH_VideoEncoder_Configure](#oh_videoencoder_configure) (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.| 48| [OH_VideoEncoder_Prepare](#oh_videoencoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for a video encoder. This function must be called after **Configure**.| 49| [OH_VideoEncoder_Start](#oh_videoencoder_start) (OH_AVCodec \*codec) | Starts a video encoder. This function can be called only after the encoder is prepared successfully.| 50| [OH_VideoEncoder_Stop](#oh_videoencoder_stop) (OH_AVCodec \*codec) | Stops a video encoder.| 51| [OH_VideoEncoder_Flush](#oh_videoencoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of a video encoder.| 52| [OH_VideoEncoder_Reset](#oh_videoencoder_reset) (OH_AVCodec \*codec) | Resets a video encoder.| 53| \*[OH_VideoEncoder_GetOutputDescription](#oh_videoencoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the description information about the output data of a video encoder. For details, see **OH_AVFormat**.| 54| [OH_VideoEncoder_SetParameter](#oh_videoencoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for a video encoder.| 55| [OH_VideoEncoder_GetSurface](#oh_videoencoder_getsurface) (OH_AVCodec \*codec, OHNativeWindow \*\*window) | Sets an input surface for a video encoder. This function must be called prior to **Prepare**.| 56| [OH_VideoEncoder_FreeOutputData](#oh_videoencoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video encoder.| 57| [OH_VideoEncoder_NotifyEndOfStream](#oh_videoencoder_notifyendofstream) (OH_AVCodec \*codec) | Notifies a video encoder that input streams end. You are advised to use this function for notification.| 58| [OH_VideoEncoder_PushInputData](#oh_videoencoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, OH_AVCodecBufferAttr attr) | Pushes the input buffer filled with data to a video encoder.| 59| \*[OH_VideoEncoder_GetInputDescription](#oh_videoencoder_getinputdescription) (OH_AVCodec \*codec) | Obtains the description information received by the video encoder. This function must be called after **Configure**. For details, see **OH_AVFormat**.| 60| [OH_VideoEncoder_IsValid](#oh_videoencoder_isvalid) (OH_AVCodec \*codec, bool \*isValid) | Checks whether a video encoder instance is valid.| 61 62 63## Type Description 64 65 66### OH_VideoEncodeBitrateMode 67 68 69``` 70typedef enum OH_VideoEncodeBitrateMode OH_VideoEncodeBitrateMode 71``` 72 73**Description** 74 75Defines the bit rate mode of a video encoder. 76 77\@syscap SystemCapability.Multimedia.Media.VideoEncoder 78 79**Since** 80 819 82 83 84## Enum Description 85 86 87### OH_VideoEncodeBitrateMode 88 89 90``` 91enum OH_VideoEncodeBitrateMode 92``` 93 94**Description** 95 96Enumerates the bit rate modes of a video encoder. 97 98\@syscap SystemCapability.Multimedia.Media.VideoEncoder 99 100**Since** 101 1029 103 104| Value| Description| 105| -------- | -------- | 106| CBR | Constant bit rate.| 107| VBR | Variable bit rate.| 108| CQ | Constant quality.| 109 110 111## Function Description 112 113 114### OH_VideoEncoder_Configure() 115 116 117``` 118OH_AVErrCode OH_VideoEncoder_Configure (OH_AVCodec *codec, OH_AVFormat *format) 119``` 120 121**Description** 122 123Configures a video encoder. Typically, you need to configure the description information about the video track to be encoded. 124 125This function must be called prior to **Prepare**. 126 127\@syscap SystemCapability.Multimedia.Media.VideoEncoder 128 129**Parameters** 130 131| Name| Description| 132| -------- | -------- | 133| codec | Pointer to an **OH_AVCodec** instance.| 134| format | Pointer to an **OH_AVFormat** instance, which provides the description information about the video track to be encoded.| 135 136**Returns** 137 138Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 139 140**Since** 141 1429 143 144 145### OH_VideoEncoder_CreateByMime() 146 147 148``` 149OH_AVCodec* OH_VideoEncoder_CreateByMime (const char *mime) 150``` 151 152**Description** 153 154Creates a video encoder instance based on a MIME type. This function is recommended in most cases. 155 156\@syscap SystemCapability.Multimedia.Media.VideoEncoder 157 158**Parameters** 159 160| Name| Description| 161| -------- | -------- | 162| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 163 164**Returns** 165 166Returns the pointer to the **OH_AVCodec** instance created. You must call **OH_VideoEncoder_Destroy** to destroy the instance when it is no longer needed. 167 168**Since** 169 1709 171 172 173### OH_VideoEncoder_CreateByName() 174 175 176``` 177OH_AVCodec* OH_VideoEncoder_CreateByName (const char *name) 178``` 179 180**Description** 181 182Creates a video encoder instance based on an encoder name. To use this function, you must know the exact name of the encoder. 183 184\@syscap SystemCapability.Multimedia.Media.VideoEncoder 185 186**Parameters** 187 188| Name| Description| 189| -------- | -------- | 190| name | Pointer to a video encoder name.| 191 192**Returns** 193 194Returns the pointer to an **OH_AVCodec** instance. 195 196**Since** 197 1989 199 200 201### OH_VideoEncoder_Destroy() 202 203 204``` 205OH_AVErrCode OH_VideoEncoder_Destroy (OH_AVCodec *codec) 206``` 207 208**Description** 209 210Clears the internal resources of a video encoder and destroys the encoder instance. 211 212\@syscap SystemCapability.Multimedia.Media.VideoEncoder 213 214**Parameters** 215 216| Name| Description| 217| -------- | -------- | 218| codec | Pointer to an **OH_AVCodec** instance.| 219 220**Returns** 221 222Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 223 224**Since** 225 2269 227 228 229### OH_VideoEncoder_Flush() 230 231 232``` 233OH_AVErrCode OH_VideoEncoder_Flush (OH_AVCodec *codec) 234``` 235 236**Description** 237 238Clears the input and output data in the internal buffer of a video encoder. 239 240This 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. 241 242\@syscap SystemCapability.Multimedia.Media.VideoEncoder 243 244**Parameters** 245 246| Name| Description| 247| -------- | -------- | 248| codec | Pointer to an **OH_AVCodec** instance.| 249 250**Returns** 251 252Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 253 254**Since** 255 2569 257 258 259### OH_VideoEncoder_FreeOutputData() 260 261 262``` 263OH_AVErrCode OH_VideoEncoder_FreeOutputData (OH_AVCodec *codec, uint32_t index) 264``` 265 266**Description** 267 268Frees an output buffer of a video encoder. 269 270\@syscap SystemCapability.Multimedia.Media.VideoEncoder 271 272**Parameters** 273 274| Name| Description| 275| -------- | -------- | 276| codec | Pointer to an **OH_AVCodec** instance.| 277| index | Index of the output buffer.| 278 279**Returns** 280 281Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 282 283**Since** 284 2859 286 287 288### OH_VideoEncoder_GetInputDescription() 289 290 291``` 292OH_AVFormat* OH_VideoEncoder_GetInputDescription (OH_AVCodec *codec) 293``` 294 295**Description** 296 297Obtains the description information received by the video encoder. This function must be called after **Configure**. For details, see **OH_AVFormat**. 298 299The caller must manually release the **OH_AVFormat** instance in the return value. 300 301\@syscap SystemCapability.Multimedia.Media.VideoEncoder 302 303**Parameters** 304 305| Name| Description| 306| -------- | -------- | 307| codec | Pointer to an **OH_AVCodec** instance.| 308 309**Returns** 310 311Returns the pointer to an **OH_AVFormat** instance. 312 313**Since** 314 31510 316 317 318### OH_VideoEncoder_GetOutputDescription() 319 320 321``` 322OH_AVFormat* OH_VideoEncoder_GetOutputDescription (OH_AVCodec *codec) 323``` 324 325**Description** 326 327Obtains the description information about the output data of a video encoder. For details, see **OH_AVFormat**. 328 329The caller must manually release the **OH_AVFormat** instance in the return value. 330 331\@syscap SystemCapability.Multimedia.Media.VideoEncoder 332 333**Parameters** 334 335| Name| Description| 336| -------- | -------- | 337| codec | Pointer to an **OH_AVCodec** instance.| 338 339**Returns** 340 341Returns the pointer to an **OH_AVFormat** instance. 342 343**Since** 344 3459 346 347 348### OH_VideoEncoder_GetSurface() 349 350 351``` 352OH_AVErrCode OH_VideoEncoder_GetSurface (OH_AVCodec *codec, OHNativeWindow **window) 353``` 354 355**Description** 356 357Sets an input surface for a video encoder. This function must be called prior to **Prepare**. 358 359\@syscap SystemCapability.Multimedia.Media.VideoEncoder 360 361**Parameters** 362 363| Name| Description| 364| -------- | -------- | 365| codec | Pointer to an **OH_AVCodec** instance.| 366| window | Pointer to an **OHNativeWindow** instance. For details, see **OHNativeWindow**.| 367 368**Returns** 369 370Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 371 372**Since** 373 3749 375 376 377### OH_VideoEncoder_IsValid() 378 379 380``` 381OH_AVErrCode OH_VideoEncoder_IsValid (OH_AVCodec *codec, bool *isValid) 382``` 383 384**Description** 385 386Checks whether a video encoder instance is valid. 387 388\@syscap SystemCapability.Multimedia.Media.VideoEncoder 389 390**Parameters** 391 392| Name| Description| 393| -------- | -------- | 394| codec | Pointer to an **OH_AVCodec** instance.| 395| isValid | Pointer to an instance of the Boolean type. The value **true** means that the encoder instance is valid and **false** means the opposite.| 396 397**Returns** 398 399Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 400 401**Since** 402 40310 404 405 406### OH_VideoEncoder_NotifyEndOfStream() 407 408 409``` 410OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec *codec) 411``` 412 413**Description** 414 415Notifies a video encoder that input streams end. You are advised to use this function for notification. 416 417This function is recommended in surface mode. 418 419\@syscap SystemCapability.Multimedia.Media.VideoEncoder 420 421**Parameters** 422 423| Name| Description| 424| -------- | -------- | 425| codec | Pointer to an **OH_AVCodec** instance.| 426 427**Returns** 428 429Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 430 431**Since** 432 4339 434 435 436### OH_VideoEncoder_Prepare() 437 438 439``` 440OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec *codec) 441``` 442 443**Description** 444 445Prepares internal resources for a video encoder. This function must be called after **Configure**. 446 447\@syscap SystemCapability.Multimedia.Media.VideoEncoder 448 449**Parameters** 450 451| Name| Description| 452| -------- | -------- | 453| codec | Pointer to an **OH_AVCodec** instance.| 454 455**Returns** 456 457Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 458 459**Since** 460 4619 462 463 464### OH_VideoEncoder_PushInputData() 465 466 467``` 468OH_AVErrCode OH_VideoEncoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr) 469``` 470 471**Description** 472 473Pushes the input buffer filled with data to a video encoder. 474 475\@syscap SystemCapability.Multimedia.Media.VideoEncoder 476 477**Parameters** 478 479| Name| Description| 480| -------- | -------- | 481| codec | Pointer to an **OH_AVCodec** instance.| 482| index | Index of the input buffer.| 483| attr | Description of the data contained in the buffer.| 484 485**Returns** 486 487Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 488 489**Since** 490 49110 492 493 494### OH_VideoEncoder_Reset() 495 496 497``` 498OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec *codec) 499``` 500 501**Description** 502 503Resets a video encoder. To continue encoding, you must call **Configure** to configure the encoder again. 504 505\@syscap SystemCapability.Multimedia.Media.VideoEncoder 506 507**Parameters** 508 509| Name| Description| 510| -------- | -------- | 511| codec | Pointer to an **OH_AVCodec** instance.| 512 513**Returns** 514 515Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 516 517**Since** 518 5199 520 521 522### OH_VideoEncoder_SetCallback() 523 524 525``` 526OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData) 527``` 528 529**Description** 530 531Sets an asynchronous callback so that your application can respond to events generated by a video encoder. 532 533This function must be called prior to **Prepare**. 534 535\@syscap SystemCapability.Multimedia.Media.VideoEncoder 536 537**Parameters** 538 539| Name| Description| 540| -------- | -------- | 541| codec | Pointer to an **OH_AVCodec** instance.| 542| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 543| userData | User-specific data.| 544 545**Returns** 546 547Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 548 549**Since** 550 5519 552 553 554### OH_VideoEncoder_SetParameter() 555 556 557``` 558OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format) 559``` 560 561**Description** 562 563Sets dynamic parameters for a video encoder. 564 565This function can be called only after the encoder is started. Incorrect parameter settings may cause encoding failure. 566 567\@syscap SystemCapability.Multimedia.Media.VideoEncoder 568 569**Parameters** 570 571| Name| Description| 572| -------- | -------- | 573| codec | Pointer to an **OH_AVCodec** instance.| 574| format | Handle to an **OH_AVFormat** instance.| 575 576**Returns** 577 578Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 579 580**Since** 581 5829 583 584 585### OH_VideoEncoder_Start() 586 587 588``` 589OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec *codec) 590``` 591 592**Description** 593 594Starts a video encoder. This function can be called only after the encoder is prepared successfully. 595 596After being started, the encoder starts to report the **NeedInputData** event. 597 598\@syscap SystemCapability.Multimedia.Media.VideoEncoder 599 600**Parameters** 601 602| Name| Description| 603| -------- | -------- | 604| codec | Pointer to an **OH_AVCodec** instance.| 605 606**Returns** 607 608Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 609 610**Since** 611 6129 613 614 615### OH_VideoEncoder_Stop() 616 617 618``` 619OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec *codec) 620``` 621 622**Description** 623 624Stops a video encoder. After the encoder is stopped, you can call **Start** to start it again. 625 626\@syscap SystemCapability.Multimedia.Media.VideoEncoder 627 628**Parameters** 629 630| Name| Description| 631| -------- | -------- | 632| codec | Pointer to an **OH_AVCodec** instance.| 633 634**Returns** 635 636Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 637 638**Since** 639 6409 641