1# VideoEncoder 2 3 4## Overview 5 6Provides the functions and enums for video encoding. This module may not be supported on some devices. You can call [CanIUse](../syscap.md) to check whether this module is supported on your device. 7 8@syscap SystemCapability.Multimedia.Media.VideoEncoder 9 10**Since** 119 12 13## Summary 14 15 16### Files 17 18 | Name| Description| 19| -------- | -------- | 20| [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> | 21 22 23### Types 24 25 | Name| Description| 26| -------- | -------- | 27| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) | Enumerates the bit rate modes of video encoding. | 28 29 30### Enums 31 32 | Name| Description| 33| -------- | -------- | 34| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) { **CBR** = 0, **VBR** = 1, **CQ** = 2 } | Enumerates the bit rate modes of video encoding. | 35 36 37### Functions 38 39 | Name| Description| 40| -------- | -------- | 41| [OH_VideoEncoder_CreateByMime](#oh_videoencoder_createbymime) (const char \*mime) | Creates a video encoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This API is recommended in most cases. | 42| [OH_VideoEncoder_CreateByName](#oh_videoencoder_createbyname) (const char \*name) | Creates a video encoder instance based on a video encoder name. To use this API, you must know the exact name of the video encoder. | 43| [OH_VideoEncoder_Destroy](#oh_videoencoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of a video encoder and destroys the video encoder instance. | 44| [OH_VideoEncoder_SetCallback](#oh_videoencoder_setcallback) (OH_AVCodec \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | Sets an asynchronous callback so that your application can respond to events generated by a video encoder. This API must be called prior to **Prepare**. | 45| [OH_VideoEncoder_Configure](#oh_videoencoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | Configures a video encoder. Typically, you need to configure the attributes of the video track that can be encoded. This API must be called prior to **Prepare**. | 46| [OH_VideoEncoder_Prepare](#oh_videoencoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for a video encoder. This API must be called after **Configure**. | 47| [OH_VideoEncoder_Start](#oh_videoencoder_start) (OH_AVCodec \*codec) | Starts a video encoder. This API can be called only after the encoder is prepared successfully. After being started, the encoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. | 48| [OH_VideoEncoder_Stop](#oh_videoencoder_stop) (OH_AVCodec \*codec) | Stops a video encoder. After the encoder is stopped, you can call **Start** to start it again. | 49| [OH_VideoEncoder_Flush](#oh_videoencoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of a video encoder. This API invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this API, ensure that the buffers corresponding to the indexes are no longer required. | 50| [OH_VideoEncoder_Reset](#oh_videoencoder_reset) (OH_AVCodec \*codec) | Resets a video encoder. To continue encoding, you must call **Configure** and **Start** to configure and start the encoder again. | 51| [OH_VideoEncoder_GetOutputDescription](#oh_videoencoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the attributes of the output data of a video encoder. The **OH_AVFormat** instance in the return value will become invalid when this API is called again or when the **OH_AVCodec** instance is destroyed. | 52| [OH_VideoEncoder_SetParameter](#oh_videoencoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for a video encoder. This API can be called only after the encoder is started. Incorrect parameter settings may cause encoding failure. | 53| [OH_VideoEncoder_GetSurface](#oh_videoencoder_getsurface) (OH_AVCodec \*codec, OHNativeWindow \*\*window) | Obtains an input surface from a video encoder. This API must be called prior to **Prepare**. | 54| [OH_VideoEncoder_FreeOutputData](#oh_videoencoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video encoder. | 55| [OH_VideoEncoder_NotifyEndOfStream](#oh_videoencoder_notifyendofstream) (OH_AVCodec \*codec) | Notifies a video encoder that input streams end. This API is recommended in surface mode. | 56 57 58## Type Description 59 60 61### OH_VideoEncodeBitrateMode 62 63 64``` 65typedef enum OH_VideoEncodeBitrateModeOH_VideoEncodeBitrateMode 66``` 67**Description**<br> 68Enumerates the bit rate modes of video encoding. 69 70@syscap SystemCapability.Multimedia.Media.VideoEncoder 71 72 73## Enum Description 74 75 76### OH_VideoEncodeBitrateMode 77 78 79``` 80enum OH_VideoEncodeBitrateMode 81``` 82**Description**<br> 83Enumerates the bit rate modes of video encoding. 84 85@syscap SystemCapability.Multimedia.Media.VideoEncoder 86 87 | Value| Description| 88| -------- | -------- | 89| CBR | Constant bit rate.| 90| VBR | Variable bit rate.| 91| CQ | Constant quality.| 92 93 94## Function Description 95 96 97### OH_VideoEncoder_Configure() 98 99 100``` 101OH_AVErrCode OH_VideoEncoder_Configure (OH_AVCodec * codec, OH_AVFormat * format ) 102``` 103**Description**<br> 104Configures a video encoder. Typically, you need to configure the attributes of the video track that can be encoded. This API must be called prior to **Prepare**. 105 106@syscap SystemCapability.Multimedia.Media.VideoEncoder 107 108**Parameters** 109 110 | Name| Description| 111| -------- | -------- | 112| codec | Indicates the pointer to an **OH_AVCodec** instance. | 113| format | Indicates the handle to an **OH_AVFormat** instance, which provides the attributes of the video track to be encoded. | 114 115**Returns** 116 117Returns **AV_ERR_OK** if the operation is successful. 118 119Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 120 121 122### OH_VideoEncoder_CreateByMime() 123 124 125``` 126OH_AVCodec* OH_VideoEncoder_CreateByMime (const char * mime) 127``` 128**Description**<br> 129Creates a video encoder instance based on a MIME type. This API is recommended in most cases. 130 131@syscap SystemCapability.Multimedia.Media.VideoEncoder 132 133**Parameters** 134 135 | Name| Description| 136| -------- | -------- | 137| mime | Indicates the pointer to a MIME type. For details, see [OH_AVCODEC_MIMETYPE_VIDEO_AVC](_codec_base.md#oh_avcodec_mimetype_video_avc).| 138 139**Returns** 140 141Returns the pointer to an **OH_AVCodec** instance. 142 143 144### OH_VideoEncoder_CreateByName() 145 146 147``` 148OH_AVCodec* OH_VideoEncoder_CreateByName (const char * name) 149``` 150**Description**<br> 151Creates a video encoder instance based on a video encoder name. To use this API, you must know the exact name of the video encoder. 152 153@syscap SystemCapability.Multimedia.Media.VideoEncoder 154 155**Parameters** 156 157 | Name| Description| 158| -------- | -------- | 159| name | Indicates the pointer to a video encoder name. | 160 161**Returns** 162 163Returns the pointer to an **OH_AVCodec** instance. 164 165 166### OH_VideoEncoder_Destroy() 167 168 169``` 170OH_AVErrCode OH_VideoEncoder_Destroy (OH_AVCodec * codec) 171``` 172**Description**<br> 173Clears the internal resources of a video encoder and destroys the video encoder instance. 174 175@syscap SystemCapability.Multimedia.Media.VideoEncoder 176 177**Parameters** 178 179 | Name| Description| 180| -------- | -------- | 181| codec | Indicates the pointer to an **OH_AVCodec** instance. | 182 183**Returns** 184 185Returns **AV_ERR_OK** if the operation is successful. 186 187Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 188 189 190### OH_VideoEncoder_Flush() 191 192 193``` 194OH_AVErrCode OH_VideoEncoder_Flush (OH_AVCodec * codec) 195``` 196**Description**<br> 197Clears the input and output data in the internal buffer of a video encoder. This API invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this API, ensure that the buffers corresponding to the indexes are no longer required. 198 199@syscap SystemCapability.Multimedia.Media.VideoEncoder 200 201**Parameters** 202 203 | Name| Description| 204| -------- | -------- | 205| codec | Indicates the pointer to an **OH_AVCodec** instance. | 206 207**Returns** 208 209Returns **AV_ERR_OK** if the operation is successful. 210 211Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 212 213 214### OH_VideoEncoder_FreeOutputData() 215 216 217``` 218OH_AVErrCode OH_VideoEncoder_FreeOutputData (OH_AVCodec * codec, uint32_t index ) 219``` 220**Description**<br> 221Frees an output buffer of a video encoder. 222 223@syscap SystemCapability.Multimedia.Media.VideoEncoder 224 225**Parameters** 226 227 | Name| Description| 228| -------- | -------- | 229| codec | Indicates the pointer to an **OH_AVCodec** instance. | 230| index | Indicates the index of an output buffer. | 231 232**Returns** 233 234Returns **AV_ERR_OK** if the operation is successful. 235 236Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 237 238 239### OH_VideoEncoder_GetOutputDescription() 240 241 242``` 243OH_AVFormat* OH_VideoEncoder_GetOutputDescription (OH_AVCodec * codec) 244``` 245**Description**<br> 246Obtains the attributes of the output data of a video encoder. The **OH_AVFormat** instance in the return value will become invalid when this API is called again or when the **OH_AVCodec** instance is destroyed. 247 248@syscap SystemCapability.Multimedia.Media.VideoEncoder 249 250**Parameters** 251 252 | Name| Description| 253| -------- | -------- | 254| codec | Indicates the pointer to an **OH_AVCodec** instance. | 255 256**Returns** 257 258Returns the pointer to an **OH_AVFormat** instance. 259 260 261### OH_VideoEncoder_GetSurface() 262 263 264``` 265OH_AVErrCode OH_VideoEncoder_GetSurface (OH_AVCodec * codec, OHNativeWindow ** window ) 266``` 267**Description**<br> 268Obtains an input surface from a video encoder. This API must be called prior to **Prepare**. 269 270@syscap SystemCapability.Multimedia.Media.VideoEncoder 271 272**Parameters** 273 274 | Name| Description| 275| -------- | -------- | 276| codec | Indicates the pointer to an **OH_AVCodec** instance. | 277| window | Indicates the double pointer to an **OHNativeWindow** instance. | 278 279**Returns** 280 281Returns **AV_ERR_OK** if the operation is successful. 282 283Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 284 285 286### OH_VideoEncoder_NotifyEndOfStream() 287 288 289``` 290OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec * codec) 291``` 292**Description**<br> 293Notifies a video encoder that input streams end. This API is recommended in surface mode. 294 295@syscap SystemCapability.Multimedia.Media.VideoEncoder 296 297**Parameters** 298 299 | Name| Description| 300| -------- | -------- | 301| codec | Indicates the pointer to an **OH_AVCodec** instance. | 302 303**Returns** 304 305Returns **AV_ERR_OK** if the operation is successful. 306 307Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 308 309 310### OH_VideoEncoder_Prepare() 311 312 313``` 314OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec * codec) 315``` 316**Description**<br> 317Prepares internal resources for a video encoder. This API must be called after **Configure**. 318 319@syscap SystemCapability.Multimedia.Media.VideoEncoder 320 321**Parameters** 322 323 | Name| Description| 324| -------- | -------- | 325| codec | Indicates the pointer to an **OH_AVCodec** instance. | 326 327**Returns** 328 329Returns **AV_ERR_OK** if the operation is successful. 330 331Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 332 333 334### OH_VideoEncoder_Reset() 335 336 337``` 338OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec * codec) 339``` 340**Description**<br> 341Resets a video encoder. To continue encoding, you must call **Configure** and **Start** to configure and start the encoder again. 342 343@syscap SystemCapability.Multimedia.Media.VideoEncoder 344 345**Parameters** 346 347 | Name| Description| 348| -------- | -------- | 349| codec | Indicates the pointer to an **OH_AVCodec** instance. | 350 351**Returns** 352 353Returns **AV_ERR_OK** if the operation is successful. 354 355Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 356 357 358### OH_VideoEncoder_SetCallback() 359 360 361``` 362OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData ) 363``` 364**Description**<br> 365Sets an asynchronous callback so that your application can respond to events generated by a video encoder. This API must be called prior to **Prepare**. 366 367@syscap SystemCapability.Multimedia.Media.VideoEncoder 368 369**Parameters** 370 371 | Name| Description| 372| -------- | -------- | 373| codec | Indicates the pointer to an **OH_AVCodec** instance. | 374| callback | Indicates a collection of all callback functions. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 375| userData | Indicates the pointer to user-specific data. | 376 377**Returns** 378 379Returns **AV_ERR_OK** if the operation is successful. 380 381Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 382 383 384### OH_VideoEncoder_SetParameter() 385 386 387``` 388OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format ) 389``` 390**Description**<br> 391Sets dynamic parameters for a video encoder. This API can be called only after the encoder is started. Incorrect parameter settings may cause encoding failure. 392 393@syscap SystemCapability.Multimedia.Media.VideoEncoder 394 395**Parameters** 396 397 | Name| Description| 398| -------- | -------- | 399| codec | Indicates the pointer to an **OH_AVCodec** instance. | 400| format | Indicates the handle to an **OH_AVFormat** instance. | 401 402**Returns** 403 404Returns **AV_ERR_OK** if the operation is successful. 405 406Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 407 408 409### OH_VideoEncoder_Start() 410 411 412``` 413OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec * codec) 414``` 415**Description**<br> 416Starts a video encoder. This API can be called only after the encoder is prepared successfully. After being started, the encoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. 417 418@syscap SystemCapability.Multimedia.Media.VideoEncoder 419 420**Parameters** 421 422 | Name| Description| 423| -------- | -------- | 424| codec | Indicates the pointer to an **OH_AVCodec** instance. | 425 426**Returns** 427 428Returns **AV_ERR_OK** if the operation is successful. 429 430Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 431 432 433### OH_VideoEncoder_Stop() 434 435 436``` 437OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec * codec) 438``` 439**Description**<br> 440Stops a video encoder. After the encoder is stopped, you can call **Start** to start it again. 441 442@syscap SystemCapability.Multimedia.Media.VideoEncoder 443 444**Parameters** 445 446 | Name| Description| 447| -------- | -------- | 448| codec | Indicates the pointer to an **OH_AVCodec** instance. | 449 450**Returns** 451 452Returns **AV_ERR_OK** if the operation is successful. 453 454Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 455