1# VideoDecoder 2 3 4## Overview 5 6Provides the functions for video decoding. 7 8\@syscap SystemCapability.Multimedia.Media.VideoDecoder 9 10**Since:** 119 12 13 14## Summary 15 16 17### Files 18 19| Name | Description | 20| -------- | -------- | 21| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | Declares the native APIs used for video decoding. <br>File to Include: <multimedia/player_framework/native_avcodec_videodecoder.h> | 22 23 24### Functions 25 26| Name | Description | 27| -------- | -------- | 28| [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | Creates a video decoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This API is recommended in most cases. | 29| [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | Creates a video decoder instance based on a video decoder name. To use this API, you must know the exact name of the video decoder. | 30| [OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of a video decoder and destroys the video decoder instance. | 31| [OH_VideoDecoder_SetCallback](#oh_videodecoder_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 decoder. This API must be called prior to **Prepare**. | 32| [OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) (OH_AVCodec \*codec, [OHNativeWindow](_native_window.md) \*window) | Sets an output surface for a video decoder. This API must be called prior to **Prepare**. | 33| [OH_VideoDecoder_Configure](#oh_videodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | Configures a video decoder. Typically, you need to configure the attributes, which can be extracted from the container, of the video track that can be decoded. This API must be called prior to **Prepare**. | 34| [OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for a video decoder. This API must be called after **Configure**. | 35| [OH_VideoDecoder_Start](#oh_videodecoder_start) (OH_AVCodec \*codec) | Starts a video decoder. This API can be called only after the decoder is prepared successfully. After being started, the decoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. | 36| [OH_VideoDecoder_Stop](#oh_videodecoder_stop) (OH_AVCodec \*codec) | Stops a video decoder. After the decoder is stopped, you can call **Start** to start it again. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. | 37| [OH_VideoDecoder_Flush](#oh_videodecoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of a video decoder. 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. | 38| [OH_VideoDecoder_Reset](#oh_videodecoder_reset) (OH_AVCodec \*codec) | Resets a video decoder. To continue decoding, you must call **Configure** and **Start** to configure and start the decoder again. | 39| [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the attributes of the output data of a video decoder. 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. | 40| [OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for a video decoder. This API can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. | 41| [OH_VideoDecoder_PushInputData](#oh_videodecoder_pushinputdata) (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 decoder. The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports available input buffers and their indexes. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. | 42| [OH_VideoDecoder_RenderOutputData](#oh_videodecoder_renderoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. If no output surface is configured, calling this API only frees the output buffer. | 43| [OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video decoder. | 44 45 46## Function Description 47 48 49### OH_VideoDecoder_Configure() 50 51 52``` 53OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec * codec, OH_AVFormat * format ) 54``` 55**Description**<br> 56Configures a video decoder. Typically, you need to configure the attributes, which can be extracted from the container, of the video track that can be decoded. This API must be called prior to **Prepare**. 57 58\@syscap SystemCapability.Multimedia.Media.VideoDecoder 59 60 **Parameters** 61 62| Name | Description | 63| -------- | -------- | 64| codec | Indicates the pointer to an **OH_AVCodec** instance. | 65| format | Indicates the handle to an **OH_AVFormat** instance, which provides the attributes of the video track to be decoded. | 66 67**Returns** 68 69Returns **AV_ERR_OK** if the operation is successful. 70 71Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 72 73 74### OH_VideoDecoder_CreateByMime() 75 76 77``` 78OH_AVCodec* OH_VideoDecoder_CreateByMime (const char * mime) 79``` 80**Description**<br> 81Creates a video decoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This API is recommended in most cases. 82 83\@syscap SystemCapability.Multimedia.Media.VideoDecoder 84 85 **Parameters** 86 87| Name | Description | 88| -------- | -------- | 89| mime | Indicates the pointer to a MIME type. For details, see [OH_AVCODEC_MIMETYPE_VIDEO_AVC](_codec_base.md#oh_avcodec_mimetype_video_avc). | 90 91**Returns** 92 93Returns the pointer to an **OH_AVCodec** instance. 94 95 96### OH_VideoDecoder_CreateByName() 97 98 99``` 100OH_AVCodec* OH_VideoDecoder_CreateByName (const char * name) 101``` 102**Description**<br> 103Creates a video decoder instance based on a video decoder name. To use this API, you must know the exact name of the video decoder. 104 105\@syscap SystemCapability.Multimedia.Media.VideoDecoder 106 107 **Parameters** 108 109| Name | Description | 110| -------- | -------- | 111| name | Indicates the pointer to a video decoder name. | 112 113**Returns** 114 115Returns the pointer to an **OH_AVCodec** instance. 116 117 118### OH_VideoDecoder_Destroy() 119 120 121``` 122OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec * codec) 123``` 124**Description**<br> 125Clears the internal resources of a video decoder and destroys the video decoder instance. 126 127\@syscap SystemCapability.Multimedia.Media.VideoDecoder 128 129 **Parameters** 130 131| Name | Description | 132| -------- | -------- | 133| codec | Indicates the pointer to an **OH_AVCodec** instance. | 134 135**Returns** 136 137Returns **AV_ERR_OK** if the operation is successful. 138 139Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 140 141 142### OH_VideoDecoder_Flush() 143 144 145``` 146OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec * codec) 147``` 148**Description**<br> 149Clears the input and output data in the internal buffer of a video decoder. 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. 150 151\@syscap SystemCapability.Multimedia.Media.VideoDecoder 152 153 **Parameters** 154 155| Name | Description | 156| -------- | -------- | 157| codec | Indicates the pointer to an **OH_AVCodec** instance. | 158 159**Returns** 160 161Returns **AV_ERR_OK** if the operation is successful. 162 163Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 164 165 166### OH_VideoDecoder_FreeOutputData() 167 168 169``` 170OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec * codec, uint32_t index ) 171``` 172**Description**<br> 173Frees an output buffer of a video decoder. 174 175\@syscap SystemCapability.Multimedia.Media.VideoDecoder 176 177 **Parameters** 178 179| Name | Description | 180| -------- | -------- | 181| codec | Indicates the pointer to an **OH_AVCodec** instance. | 182| index | Indicates the index of an output buffer. | 183 184**Returns** 185 186Returns **AV_ERR_OK** if the operation is successful. 187 188Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 189 190 191### OH_VideoDecoder_GetOutputDescription() 192 193 194``` 195OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec * codec) 196``` 197**Description**<br> 198Obtains the attributes of the output data of a video decoder. 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. 199 200\@syscap SystemCapability.Multimedia.Media.VideoDecoder 201 202 **Parameters** 203 204| Name | Description | 205| -------- | -------- | 206| codec | Indicates the pointer to an **OH_AVCodec** instance. | 207 208**Returns** 209 210Returns the pointer to an **OH_AVFormat** instance. 211 212 213### OH_VideoDecoder_Prepare() 214 215 216``` 217OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec * codec) 218``` 219**Description**<br> 220Prepares internal resources for a video decoder. This API must be called after **Configure**. 221 222\@syscap SystemCapability.Multimedia.Media.VideoDecoder 223 224 **Parameters** 225 226| Name | Description | 227| -------- | -------- | 228| codec | Indicates the pointer to an **OH_AVCodec** instance. | 229 230**Returns** 231 232Returns **AV_ERR_OK** if the operation is successful. 233 234Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 235 236 237### OH_VideoDecoder_PushInputData() 238 239 240``` 241OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec * codec, uint32_t index, OH_AVCodecBufferAttr attr ) 242``` 243**Description**<br> 244Pushes the input buffer filled with data to a video decoder. The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports available input buffers and their indexes. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 245 246\@syscap SystemCapability.Multimedia.Media.VideoDecoder 247 248 **Parameters** 249 250| Name | Description | 251| -------- | -------- | 252| codec | Indicates the pointer to an **OH_AVCodec** instance. | 253| index | Indicates the index of an input buffer. | 254| attr | Indicates the attributes of the data contained in the buffer. | 255 256**Returns** 257 258Returns **AV_ERR_OK** if the operation is successful. 259 260Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 261 262 263### OH_VideoDecoder_RenderOutputData() 264 265 266``` 267OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec * codec, uint32_t index ) 268``` 269**Description**<br> 270Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. If no output surface is configured, calling this API only frees the output buffer. 271 272\@syscap SystemCapability.Multimedia.Media.VideoDecoder 273 274 **Parameters** 275 276| Name | Description | 277| -------- | -------- | 278| codec | Indicates the pointer to an **OH_AVCodec** instance. | 279| index | Indicates the index of an output buffer. | 280 281**Returns** 282 283Returns **AV_ERR_OK** if the operation is successful. 284 285Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 286 287 288### OH_VideoDecoder_Reset() 289 290 291``` 292OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec * codec) 293``` 294**Description**<br> 295Resets a video decoder. To continue decoding, you must call **Configure** and **Start** to configure and start the decoder again. 296 297\@syscap SystemCapability.Multimedia.Media.VideoDecoder 298 299 **Parameters** 300 301| Name | Description | 302| -------- | -------- | 303| codec | Indicates the pointer to an **OH_AVCodec** instance. | 304 305**Returns** 306 307Returns **AV_ERR_OK** if the operation is successful. 308 309Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 310 311 312### OH_VideoDecoder_SetCallback() 313 314 315``` 316OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData ) 317``` 318**Description**<br> 319Sets an asynchronous callback so that your application can respond to events generated by a video decoder. This API must be called prior to **Prepare**. 320 321\@syscap SystemCapability.Multimedia.Media.VideoDecoder 322 323 **Parameters** 324 325| Name | Description | 326| -------- | -------- | 327| codec | Indicates the pointer to an **OH_AVCodec** instance. | 328| callback | Indicates a collection of all callback functions. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md). | 329| userData | Indicates the pointer to user-specific data. | 330 331**Returns** 332 333Returns **AV_ERR_OK** if the operation is successful. 334 335Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 336 337 338### OH_VideoDecoder_SetParameter() 339 340 341``` 342OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format ) 343``` 344**Description**<br> 345Sets dynamic parameters for a video decoder. This API can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. 346 347\@syscap SystemCapability.Multimedia.Media.VideoDecoder 348 349 **Parameters** 350 351| Name | Description | 352| -------- | -------- | 353| codec | Indicates the pointer to an **OH_AVCodec** instance. | 354| format | Indicates the handle to an **OH_AVFormat** instance. | 355 356**Returns** 357 358Returns **AV_ERR_OK** if the operation is successful. 359 360Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 361 362 363### OH_VideoDecoder_SetSurface() 364 365 366``` 367OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window ) 368``` 369**Description**<br> 370Sets an output surface for a video decoder. This API must be called prior to **Prepare**. 371 372\@syscap SystemCapability.Multimedia.Media.VideoDecoder 373 374 **Parameters** 375 376| Name | Description | 377| -------- | -------- | 378| codec | Indicates the pointer to an **OH_AVCodec** instance. | 379| window | Indicates the pointer to an **OHNativeWindow** instance. | 380 381**Returns** 382 383Returns **AV_ERR_OK** if the operation is successful. 384 385Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 386 387 388### OH_VideoDecoder_Start() 389 390 391``` 392OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec * codec) 393``` 394**Description**<br> 395Starts a video decoder. This API can be called only after the decoder is prepared successfully. After being started, the decoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. 396 397\@syscap SystemCapability.Multimedia.Media.VideoDecoder 398 399 **Parameters** 400 401| Name | Description | 402| -------- | -------- | 403| codec | Indicates the pointer to an **OH_AVCodec** instance. | 404 405**Returns** 406 407Returns **AV_ERR_OK** if the operation is successful. 408 409Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 410 411 412### OH_VideoDecoder_Stop() 413 414 415``` 416OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec * codec) 417``` 418**Description**<br> 419Stops a video decoder. After the decoder is stopped, you can call **Start** to start it again. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. 420 421\@syscap SystemCapability.Multimedia.Media.VideoDecoder 422 423 **Parameters** 424 425| Name | Description | 426| -------- | -------- | 427| codec | Indicates the pointer to an **OH_AVCodec** instance. | 428 429**Returns** 430 431Returns **AV_ERR_OK** if the operation is successful. 432 433Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 434