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.| 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](_core.md) .| 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](_core.md).| 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. It is used 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**. 358The application manages the lifecycle of the window and calls **OH_NativeWindow_DestroyNativeWindow()** to release the window when the lifecycle ends. 359 360\@syscap SystemCapability.Multimedia.Media.VideoEncoder 361 362**Parameters** 363 364| Name| Description| 365| -------- | -------- | 366| codec | Pointer to an **OH_AVCodec** instance.| 367| window | Pointer to an **OHNativeWindow** instance. For details, see **OHNativeWindow**.| 368 369**Returns** 370 371Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 372 373**Since** 374 3759 376 377 378### OH_VideoEncoder_IsValid() 379 380 381``` 382OH_AVErrCode OH_VideoEncoder_IsValid (OH_AVCodec *codec, bool *isValid) 383``` 384 385**Description** 386 387Checks whether a video encoder instance is valid. 388 389\@syscap SystemCapability.Multimedia.Media.VideoEncoder 390 391**Parameters** 392 393| Name| Description| 394| -------- | -------- | 395| codec | Pointer to an **OH_AVCodec** instance.| 396| isValid | Pointer to an instance of the Boolean type. The value **true** means that the encoder instance is valid and **false** means the opposite.| 397 398**Returns** 399 400Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 401 402**Since** 403 40410 405 406 407### OH_VideoEncoder_NotifyEndOfStream() 408 409 410``` 411OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec *codec) 412``` 413 414**Description** 415 416Notifies a video encoder that input streams end. You are advised to use this function for notification. 417 418This function is recommended in surface mode. 419 420\@syscap SystemCapability.Multimedia.Media.VideoEncoder 421 422**Parameters** 423 424| Name| Description| 425| -------- | -------- | 426| codec | Pointer to an **OH_AVCodec** instance.| 427 428**Returns** 429 430Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 431 432**Since** 433 4349 435 436 437### OH_VideoEncoder_Prepare() 438 439 440``` 441OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec *codec) 442``` 443 444**Description** 445 446Prepares internal resources for a video encoder. This function must be called after **Configure**. 447 448\@syscap SystemCapability.Multimedia.Media.VideoEncoder 449 450**Parameters** 451 452| Name| Description| 453| -------- | -------- | 454| codec | Pointer to an **OH_AVCodec** instance.| 455 456**Returns** 457 458Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 459 460**Since** 461 4629 463 464 465### OH_VideoEncoder_PushInputData() 466 467 468``` 469OH_AVErrCode OH_VideoEncoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr) 470``` 471 472**Description** 473 474Pushes the input buffer filled with data to a video encoder. 475 476\@syscap SystemCapability.Multimedia.Media.VideoEncoder 477 478**Parameters** 479 480| Name| Description| 481| -------- | -------- | 482| codec | Pointer to an **OH_AVCodec** instance.| 483| index | Index of the input buffer.| 484| attr | Description of the data contained in the buffer.| 485 486**Returns** 487 488Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 489 490**Since** 491 49210 493 494 495### OH_VideoEncoder_Reset() 496 497 498``` 499OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec *codec) 500``` 501 502**Description** 503 504Resets a video encoder. To continue encoding, you must call **Configure** to configure the encoder again. 505 506\@syscap SystemCapability.Multimedia.Media.VideoEncoder 507 508**Parameters** 509 510| Name| Description| 511| -------- | -------- | 512| codec | Pointer to an **OH_AVCodec** instance.| 513 514**Returns** 515 516Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 517 518**Since** 519 5209 521 522 523### OH_VideoEncoder_SetCallback() 524 525 526``` 527OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData) 528``` 529 530**Description** 531 532Sets an asynchronous callback so that your application can respond to events generated by a video encoder. 533 534This function must be called prior to **Prepare**. 535 536\@syscap SystemCapability.Multimedia.Media.VideoEncoder 537 538**Parameters** 539 540| Name| Description| 541| -------- | -------- | 542| codec | Pointer to an **OH_AVCodec** instance.| 543| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 544| userData | User-specific data.| 545 546**Returns** 547 548Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 549 550**Since** 551 5529 553 554 555### OH_VideoEncoder_SetParameter() 556 557 558``` 559OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format) 560``` 561 562**Description** 563 564Sets dynamic parameters for a video encoder. 565 566This function can be called only after the encoder is started. Incorrect parameter settings may cause encoding failure. 567 568\@syscap SystemCapability.Multimedia.Media.VideoEncoder 569 570**Parameters** 571 572| Name| Description| 573| -------- | -------- | 574| codec | Pointer to an **OH_AVCodec** instance.| 575| format | Handle to an **OH_AVFormat** instance.| 576 577**Returns** 578 579Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 580 581**Since** 582 5839 584 585 586### OH_VideoEncoder_Start() 587 588 589``` 590OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec *codec) 591``` 592 593**Description** 594 595Starts a video encoder. This function can be called only after the encoder is prepared successfully. 596 597After being started, the encoder starts to report the **NeedInputData** event. 598 599\@syscap SystemCapability.Multimedia.Media.VideoEncoder 600 601**Parameters** 602 603| Name| Description| 604| -------- | -------- | 605| codec | Pointer to an **OH_AVCodec** instance.| 606 607**Returns** 608 609Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 610 611**Since** 612 6139 614 615 616### OH_VideoEncoder_Stop() 617 618 619``` 620OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec *codec) 621``` 622 623**Description** 624 625Stops a video encoder. After the encoder is stopped, you can call **Start** to start it again. 626 627\@syscap SystemCapability.Multimedia.Media.VideoEncoder 628 629**Parameters** 630 631| Name| Description| 632| -------- | -------- | 633| codec | Pointer to an **OH_AVCodec** instance.| 634 635**Returns** 636 637Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 638 639**Since** 640 6419 642