1# VideoDecoder 2 3 4## Overview 5 6The VideoDecoder module provides the functions for video decoding. 7 8**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 9 10**Since**: 9 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | Declares the native APIs used for video decoding.| 21 22 23### Functions 24 25| Name| Description| 26| -------- | -------- | 27| OH_AVCodec \* [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | Creates a video decoder instance based on an MIME type.| 28| OH_AVCodec \* [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | Creates a video decoder instance based on a decoder name.| 29| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of a video decoder and destroys the decoder instance.| 30| [OH_AVErrCode](_core.md#oh_averrcode)[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.| 31| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) (OH_AVCodec \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | Registers an asynchronous callback so that your application can respond to events generated by a video decoder.| 32| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) (OH_AVCodec \*codec, OHNativeWindow \*window) | Sets an output surface for a video decoder. This function must be called prior to **Prepare**.| 33| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Configure](#oh_videodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | Configures a video decoder. Typically, you need to configure the video track description information that can be extracted from **OH_AVSource**.| 34| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for a video decoder.| 35| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Start](#oh_videodecoder_start) (OH_AVCodec \*codec) | Starts a video decoder. This function can be called only after the decoder is prepared.| 36| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Stop](#oh_videodecoder_stop) (OH_AVCodec \*codec) | Stops a video decoder.| 37| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Flush](#oh_videodecoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of a video decoder.| 38| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_Reset](#oh_videodecoder_reset) (OH_AVCodec \*codec) | Resets a video decoder.| 39| OH_AVFormat \* [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the description information about the output data of a video decoder.| 40| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for a video decoder.| 41| [OH_AVErrCode](_core.md#oh_averrcode)[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.| 42| [OH_AVErrCode](_core.md#oh_averrcode)[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.| 43| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video decoder.| 44| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) (OH_AVCodec \*codec, uint32_t index) | Pushes the input buffer filled with data to a video decoder.| 45| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) (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.| 46| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video decoder.| 47| [OH_AVErrCode](_core.md#oh_averrcode)[OH_VideoDecoder_IsValid](#oh_videodecoder_isvalid) (OH_AVCodec \*codec, bool \*isValid) | Checks whether a video decoder instance is valid.| 48 49 50## Function Description 51 52 53### OH_VideoDecoder_Configure() 54 55``` 56OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 57``` 58 59**Description** 60 61Configures a video decoder. Typically, you need to configure the video track description information that can be extracted from **OH_AVSource**. 62 63This function must be called prior to **Prepare**. 64 65**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 66 67**Since**: 9 68 69**Parameters** 70 71| Name| Description| 72| -------- | -------- | 73| codec | Pointer to the video decorder instance.| 74| format | Pointer to an **OH_AVFormat** instance, which provides the description information about the video track to be decoded.| 75 76**Returns** 77 78Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 79 80 81### OH_VideoDecoder_CreateByMime() 82 83``` 84OH_AVCodec* OH_VideoDecoder_CreateByMime (const char *mime) 85``` 86 87**Description** 88 89Creates a video decoder instance based on a MIME type. This function is recommended in most cases. 90 91**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 92 93**Since**: 9 94 95**Parameters** 96 97| Name| Description| 98| -------- | -------- | 99| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 100 101**Returns** 102 103Pointer to the video decoder instance. 104 105 106### OH_VideoDecoder_CreateByName() 107 108``` 109OH_AVCodec* OH_VideoDecoder_CreateByName (const char *name) 110``` 111 112**Description** 113 114Creates a video decoder instance based on a decoder name. To use this function, you must know the exact name of the decoder. 115 116**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 117 118**Since**: 9 119 120**Parameters** 121 122| Name| Description| 123| -------- | -------- | 124| name | Pointer to a video decoder name.| 125 126**Returns** 127 128Pointer to the video decoder instance. 129 130 131### OH_VideoDecoder_Destroy() 132 133``` 134OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec *codec) 135``` 136 137**Description** 138 139Clears the internal resources of a video decoder and destroys the decoder instance. 140 141**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 142 143**Since**: 9 144 145**Parameters** 146 147| Name| Description| 148| -------- | -------- | 149| codec | Pointer to the video decorder instance.| 150 151**Returns** 152 153Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 154 155 156### OH_VideoDecoder_Flush() 157 158``` 159OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec *codec) 160``` 161 162**Description** 163 164Clears the input and output data in the internal buffer of a video decoder. 165 166This 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. 167 168**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 169 170**Since**: 9 171 172**Parameters** 173 174| Name| Description| 175| -------- | -------- | 176| codec | Pointer to the video decorder instance.| 177 178**Returns** 179 180Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 181 182 183### OH_VideoDecoder_FreeOutputBuffer() 184 185``` 186OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 187``` 188 189**Description** 190 191Frees an output buffer of a video decoder. 192 193**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 194 195**Since**: 11 196 197**Parameters** 198 199| Name| Description| 200| -------- | -------- | 201| codec | Pointer to the video decorder instance.| 202| index | Index of an output buffer.| 203 204**Returns** 205 206Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 207 208 209### OH_VideoDecoder_FreeOutputData() 210 211``` 212OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 213``` 214 215**Description** 216 217Frees an output buffer of a video decoder. 218 219**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 220 221**Since**: 9 222 223**Deprecated version**: 11 224 225**Substitute**: [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) 226 227**Parameters** 228 229| Name| Description| 230| -------- | -------- | 231| codec | Pointer to the video decorder instance.| 232| index | Index of an output buffer.| 233 234**Returns** 235 236Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 237 238 239### OH_VideoDecoder_GetOutputDescription() 240 241``` 242OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec *codec) 243``` 244 245**Description** 246 247Obtains the description information about the output data of a video decoder. 248 249The caller must manually release the **OH_AVFormat** instance in the return value. 250 251**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 252 253**Since**: 9 254 255**Parameters** 256 257| Name| Description| 258| -------- | -------- | 259| codec | Pointer to the video decorder instance.| 260 261**Returns** 262 263Returns the pointer to an **OH_AVFormat** instance. 264 265 266### OH_VideoDecoder_IsValid() 267 268``` 269OH_AVErrCode OH_VideoDecoder_IsValid (OH_AVCodec *codec, bool *isValid ) 270``` 271 272**Description** 273 274Checks whether a video decoder instance is valid. 275 276**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 277 278**Since**: 10 279 280**Parameters** 281 282| Name| Description| 283| -------- | -------- | 284| codec | Pointer to the video decorder instance.| 285| isValid | Output parameter. Pointer to an instance of the Boolean type. The value **true** means that the decoder instance is valid and **false** means the opposite.| 286 287**Returns** 288 289Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 290 291 292### OH_VideoDecoder_Prepare() 293 294``` 295OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec *codec) 296``` 297 298**Description** 299 300Prepares internal resources for a video decoder. This function must be called after **Configure**. 301 302**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 303 304**Since**: 9 305 306**Parameters** 307 308| Name| Description| 309| -------- | -------- | 310| codec | Pointer to the video decorder instance.| 311 312**Returns** 313 314Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 315 316 317### OH_VideoDecoder_PushInputBuffer() 318 319``` 320OH_AVErrCode OH_VideoDecoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 321``` 322 323**Description** 324 325Pushes the input buffer filled with data to a video decoder. 326 327The input callback reports the available input buffer and the index. For details, see [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer). After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the input callback. 328 329In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 330 331**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 332 333**Since**: 11 334 335**Parameters** 336 337| Name| Description| 338| -------- | -------- | 339| codec | Pointer to the video decorder instance.| 340| index | Index of an input buffer.| 341 342**Returns** 343 344Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 345 346 347### OH_VideoDecoder_PushInputData() 348 349``` 350OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 351``` 352 353**Description** 354 355Pushes the input buffer filled with data to a video decoder. 356 357The input callback reports the available input buffer and the index. For details, see [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). 358 359After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the input callback. 360 361In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 362 363**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 364 365**Since**: 9 366 367**Deprecated version**: 11 368 369**Substitute**: [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) 370 371**Parameters** 372 373| Name| Description| 374| -------- | -------- | 375| codec | Pointer to the video decorder instance.| 376| index | Index of an input buffer.| 377| attr | Description information about the data in the buffer.| 378 379**Returns** 380 381Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 382 383 384### OH_VideoDecoder_RegisterCallback() 385 386``` 387OH_AVErrCode OH_VideoDecoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 388``` 389 390**Description** 391 392Registers an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to **Prepare**. 393 394**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 395 396**Since**: 11 397 398**Parameters** 399 400| Name| Description| 401| -------- | -------- | 402| codec | Pointer to the video decorder instance.| 403| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md).| 404| userData | User-specific data.| 405 406**Returns** 407 408Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 409 410 411### OH_VideoDecoder_RenderOutputBuffer() 412 413``` 414OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer (OH_AVCodec *codec, uint32_t index ) 415``` 416 417**Description** 418 419Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. 420 421If no output surface is configured, calling this function only frees the output buffer. 422 423**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 424 425**Since**: 11 426 427**Parameters** 428 429| Name| Description| 430| -------- | -------- | 431| codec | Pointer to the video decorder instance.| 432| index | Index of an output buffer.| 433 434**Returns** 435 436Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 437 438 439### OH_VideoDecoder_RenderOutputData() 440 441``` 442OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec *codec, uint32_t index ) 443``` 444 445**Description** 446 447Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. 448 449If no output surface is configured, calling this function only frees the output buffer. 450 451**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 452 453**Since**: 9 454 455**Deprecated version**: 11 456 457**Substitute**: [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) 458 459**Parameters** 460 461| Name| Description| 462| -------- | -------- | 463| codec | Pointer to the video decorder instance.| 464| index | Index of an output buffer.| 465 466**Returns** 467 468Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 469 470 471### OH_VideoDecoder_Reset() 472 473``` 474OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec *codec) 475``` 476 477**Description** 478 479Resets a video decoder. To continue decoding, you must call **Configure** to configure the decoder again. 480 481**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 482 483**Since**: 9 484 485**Parameters** 486 487| Name| Description| 488| -------- | -------- | 489| codec | Pointer to the video decorder instance.| 490 491**Returns** 492 493Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 494 495 496### OH_VideoDecoder_SetCallback() 497 498``` 499OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 500``` 501 502**Description** 503 504Sets an asynchronous callback so that your application can respond to events generated by a video decoder. 505 506This function must be called prior to **Prepare**. 507 508**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 509 510**Since**: 9 511 512**Deprecated version**: 11 513 514**Substitute**: [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) 515 516**Parameters** 517 518| Name| Description| 519| -------- | -------- | 520| codec | Pointer to the video decorder instance.| 521| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 522| userData | User-specific data.| 523 524**Returns** 525 526Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 527 528 529### OH_VideoDecoder_SetParameter() 530 531``` 532OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 533``` 534 535**Description** 536 537Sets dynamic parameters for a video decoder. 538 539This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. 540 541**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 542 543**Since**: 9 544 545**Parameters** 546 547| Name| Description| 548| -------- | -------- | 549| codec | Pointer to the video decorder instance.| 550| format | Pointer to an **OH_AVFormat** instance.| 551 552**Returns** 553 554Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 555 556 557### OH_VideoDecoder_SetSurface() 558 559``` 560OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec *codec, OHNativeWindow *window ) 561``` 562 563**Description** 564 565Sets an output surface for a video decoder. This function must be called prior to **Prepare**. 566 567**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 568 569**Since**: 9 570 571**Parameters** 572 573| Name| Description| 574| -------- | -------- | 575| codec | Pointer to the video decorder instance.| 576| window | Pointer to an **OHNativeWindow** instance.| 577 578**Returns** 579 580Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 581 582 583### OH_VideoDecoder_Start() 584 585``` 586OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec *codec) 587``` 588 589**Description** 590 591Starts a video decoder. This function can be called only after the decoder is prepared. 592 593 After being started, the decoder starts to report the registered event. 594 595**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 596 597**Since**: 9 598 599**Parameters** 600 601| Name| Description| 602| -------- | -------- | 603| codec | Pointer to the video decorder instance.| 604 605**Returns** 606 607Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 608 609 610### OH_VideoDecoder_Stop() 611 612``` 613OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec *codec) 614``` 615 616**Description** 617 618Stops a video decoder. After the encoder is stopped, you can call **Start** to start it again. 619 620If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. 621 622**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 623 624**Since**: 9 625 626**Parameters** 627 628| Name| Description| 629| -------- | -------- | 630| codec | Pointer to the video decorder instance.| 631 632**Returns** 633 634Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 635