1# VideoDecoder 2 3 4## Overview 5 6The VideoDecoder module provides the APIs for video decoding. 7 8For details about the development guide and sample, see [Video Decoding](../../media/avcodec/video-decoding.md). 9 10**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 11 12**Since**: 9 13 14The following figures show the APIs supported by each version and the APIs that can be called in different states. 15 16 17 18 19 20## Summary 21 22 23### Files 24 25| Name| Description| 26| -------- | -------- | 27| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | Declares the APIs used for video decoding. | 28 29 30### Functions 31 32| Name| Description| 33| -------- | -------- | 34| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | Creates a video decoder instance based on a [MIME](_codec_base.md#media-codec-formats) type.| 35| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | Creates a video decoder instance based on a decoder name. | 36| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the internal resources of a video decoder and destroys the decoder instance. | 37| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetCallback](#oh_videodecoder_setcallback) ([OH_AVCodec](_codec_base.md#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. It is deprecated from API version 11.) | 38| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) ([OH_AVCodec](_codec_base.md#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. | 39| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OHNativeWindow](_codec_base.md#ohnativewindow) \*window) | Sets an output surface for a video decoder. | 40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Configure](#oh_videodecoder_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVFormat](_core.md#oh_avformat) \*format) | Configures a video decoder. Typically, you need to configure the video track description information that can be extracted from [OH_AVSource](_a_v_source.md). | 41| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Prepares internal resources for a video decoder. | 42| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Start](#oh_videodecoder_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Starts a video decoder. This function should be called after a successful call of **OH_VideoDecoder_Prepare**. | 43| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Stop](#oh_videodecoder_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Stops a video decoder and releases the input and output buffers. | 44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Flush](#oh_videodecoder_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video decoder. | 45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Reset](#oh_videodecoder_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Resets a video decoder. The decoder returns to the initial state. | 46| [OH_AVFormat](_core.md#oh_avformat) \* [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Obtains the OH_AVFormat information about the output data of a video decoder. | 47| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVFormat](_core.md#oh_avformat) \*format) | Sets dynamic parameters for a video decoder. | 48| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_PushInputData](#oh_videodecoder_pushinputdata) ([OH_AVCodec](_codec_base.md#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. (It is deprecated from API version 11.) | 49| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputData](#oh_videodecoder_renderoutputdata) ([OH_AVCodec](_codec_base.md#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. (It is deprecated from API version 11.) | 50| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Frees an output buffer of a video decoder. (It is deprecated from API version 11.) | 51| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Notifies a video decoder that the buffer corresponding to the index has been filled with input data. | 52| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering on the output surface. | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputBufferAtTime](#oh_videodecoder_renderoutputbufferattime) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, int64_t renderTimestampNs) | Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering within the specified duration on the output surface. | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Frees an output buffer of a video decoder. | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_IsValid](#oh_videodecoder_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | Checks whether a video decoder instance is valid. | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetDecryptionConfig](#oh_videodecoder_setdecryptionconfig) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, MediaKeySession \*mediaKeySession, bool secureVideoPath) | Sets the decryption configuration. | 57| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_QueryInputBuffer](#oh_videodecoder_queryinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | Obtains the index of the next available input buffer.| 58| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoDecoder_GetInputBuffer](#oh_videodecoder_getinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Obtains the instance of the available input buffer.| 59| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_QueryOutputBuffer](#oh_videodecoder_queryoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | Obtains the index of the next available output buffer.| 60| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoDecoder_GetOutputBuffer](#oh_videodecoder_getoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Obtains the instance of the available output buffer.| 61 62 63## Function Description 64 65 66### OH_VideoDecoder_Configure() 67 68``` 69OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 70``` 71 72**Description** 73 74Configures a video decoder. Typically, you need to configure the video description information that can be extracted from [OH_AVSource](_a_v_source.md). This function must be called prior to **OH_VideoDecoder_Prepare**. 75 76The value ranges of the following parameters can be obtained from [Capability Query](../../media/avcodec/obtain-supported-codecs.md). All the values of **OH_MD_KEY_ROTATION** are supported. 77 78If the current platform does not support **OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY**, no error is reported and the normal decoding process is used. 79 80Parameter verification rules are as follows: 81 82| Key | Value Within the Range| Value Out of Range| No Value Configured| 83| -----------------------------------------------------------------------------| -------- | -------- | ------ | 84| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 85| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 86| OH_MD_KEY_PIXEL_FORMAT<br>For details, see [OH_AVPixelFormat](_core.md#oh_avpixelformat-1). | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 87| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 88| OH_MD_KEY_ROTATION<br>For details, see [OH_MD_KEY_ROTATION](_codec_base.md#oh_md_key_rotation).| AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 89 90> **NOTE** 91> 92> You are advised to set the parameters based on the maximum resolution supported by the instance. Otherwise, an exception may occur when streams with the resolution higher than the maximum resolution are to be decoded. This setting directly affects the memory usage of the application. 93 94 95**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 96 97**Since**: 9 98 99**Parameters** 100 101| Name| Description| 102| -------- | -------- | 103| codec | Pointer to a video decoder instance. | 104| format | Pointer to an OH_AVFormat instance, which provides the description information about the video track to be decoded. | 105 106**Returns** 107 108One of the following result codes: 109 110**AV_ERR_OK**: The operation is successful. 111 112**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 113 114**AV_ERR_INVALID_VAL**: 115 116 1. The value of **codec** is nullptr or does not point to a decoder instance. 117 2. The format is not supported. 118 119**AV_ERR_UNKNOWN**: An unknown error occurs. 120 121**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 122 123**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. 124 125**AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION**: CSC is not supported. 126 127**AV_ERR_UNSUPPORT**: The feature is not supported. 128 129 130### OH_VideoDecoder_CreateByMime() 131 132``` 133OH_AVCodec* OH_VideoDecoder_CreateByMime (const char *mime) 134``` 135 136**Description** 137 138Creates a video decoder instance based on a MIME type. This function is recommended in most cases. 139 140**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 141 142**Since**: 9 143 144**Parameters** 145 146| Name| Description| 147| -------- | -------- | 148| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 149 150**Returns** 151 152Pointer to the video decoder instance. If the decoder type is not supported or the memory is insufficient, NULL is returned. 153 154 155### OH_VideoDecoder_CreateByName() 156 157``` 158OH_AVCodec* OH_VideoDecoder_CreateByName (const char *name) 159``` 160 161**Description** 162 163Creates a video decoder instance based on a decoder name. To use this function, you must know the exact name of the decoder. The decoder name can be obtained through capability query. 164 165For details, see [Obtaining Supported Codecs](../../media/avcodec/obtain-supported-codecs.md#creating-a-codec-with-the-specified-name). 166 167**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 168 169**Since**: 9 170 171**Parameters** 172 173| Name| Description| 174| -------- | -------- | 175| name | Pointer to a video decoder name. | 176 177**Returns** 178 179Pointer to the video decoder instance. If the decoder name is not supported or the memory is insufficient, NULL is returned. 180 181 182### OH_VideoDecoder_Destroy() 183 184``` 185OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec *codec) 186``` 187 188**Description** 189 190Clears the internal resources of a video decoder and destroys the decoder instance. You only need to call the function once. 191 192**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 193 194**Since**: 9 195 196**Parameters** 197 198| Name| Description| 199| -------- | -------- | 200| codec | Pointer to a video decoder instance. | 201 202**Returns** 203 204One of the following result codes: 205 206**AV_ERR_OK**: The operation is successful. 207 208**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 209 210**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 211 212**AV_ERR_UNKNOWN**: An unknown error occurs. 213 214**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 215 216 217### OH_VideoDecoder_Flush() 218 219``` 220OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec *codec) 221``` 222 223**Description** 224 225Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video decoder. This 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. 226 227**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 228 229**Since**: 9 230 231**Parameters** 232 233| Name| Description| 234| -------- | -------- | 235| codec | Pointer to a video decoder instance. | 236 237**Returns** 238 239One of the following result codes: 240 241**AV_ERR_OK**: The operation is successful. 242 243**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 244 245**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 246 247**AV_ERR_UNKNOWN**: An unknown error occurs. 248 249**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 250 251**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 252 253 254### OH_VideoDecoder_FreeOutputBuffer() 255 256``` 257OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 258``` 259 260**Description** 261 262Frees an output buffer of a video decoder. 263 264You need to call this function to release the output buffer in a timely manner. Otherwise, the decoding process is blocked. 265 266For details, see step 12 in surface mode or step 10 in buffer mode in [Video Decoding](../../media/avcodec/video-decoding.md). 267 268**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 269 270**Since**: 11 271 272**Parameters** 273 274| Name| Description| 275| -------- | -------- | 276| codec | Pointer to a video decoder instance.| 277| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 278 279**Returns** 280 281One of the following result codes: 282 283**AV_ERR_OK**: The operation is successful. 284 285**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 286 287**AV_ERR_INVALID_VAL**: 288 289 1. The value of **codec** is nullptr or does not point to a decoder instance. 290 2. The index is invalid or the same index is used consecutively. This error does not affect the subsequent decoding process. 291 292**AV_ERR_UNKNOWN**: An unknown error occurs. 293 294**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 295 296**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 297 298 299### OH_VideoDecoder_GetOutputDescription() 300 301``` 302OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec *codec) 303``` 304**Description** 305 306Obtains the OH_AVFormat information about the output data of a video decoder. For details, see [OH_AVFormat](_core.md#oh_avformat). 307 308You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 309 310**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 311 312**Since**: 9 313 314**Parameters** 315 316| Name| Description| 317| -------- | -------- | 318| codec | Pointer to a video decoder instance. | 319 320**Returns** 321 322Pointer to an OH_AVFormat instance. If the value of **codec** is nullptr or does not point to a decoder instance, NULL is returned. 323 324 325### OH_VideoDecoder_IsValid() 326 327``` 328OH_AVErrCode OH_VideoDecoder_IsValid (OH_AVCodec *codec, bool *isValid ) 329``` 330 331**Description** 332 333Checks whether the decoder service is valid when a decoder instance exists. 334 335**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 336 337**Since**: 10 338 339**Parameters** 340 341| Name| Description| 342| -------- | -------- | 343| codec | Pointer to a video decoder instance. | 344| isValid | Pointer of the Boolean type. The value indicates the validity of the decoder service only when the function returns **AV_ERR_OK**. The value **true** means that the decoder service is valid, and **false** means the opposite. It is recommended that you initialize **isValid** to **false**. | 345 346**Returns** 347 348One of the following result codes: 349 350**AV_ERR_OK**: The operation is successful. 351 352**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 353 354 355### OH_VideoDecoder_Prepare() 356 357``` 358OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec *codec) 359``` 360 361**Description** 362 363Prepares internal resources for a video decoder. This function must be called after **OH_VideoDecoder_Configure**. 364 365**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 366 367**Since**: 9 368 369**Parameters** 370 371| Name| Description| 372| -------- | -------- | 373| codec | Pointer to a video decoder instance. | 374 375**Returns** 376 377One of the following result codes: 378 379**AV_ERR_OK**: The operation is successful. 380 381**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 382 383**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 384 385**AV_ERR_UNKNOWN**: An unknown error occurs. 386 387**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 388 389**AV_ERR_OPERATE_NOT_PERMIT**: 390 391 1. An internal execution error occurs. 392 2. CSC is configured, but the decoder is in buffer mode. 393 394 395### OH_VideoDecoder_PushInputBuffer() 396 397``` 398OH_AVErrCode OH_VideoDecoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 399``` 400 401**Description** 402 403Notifies a video decoder that the buffer corresponding to the index has been filled with input data. 404 405The 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. 406 407In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 408 409This function is used to transfer the parameters (such as H.264 PPS/SPS) required for decoding to the decoder. The parameters can be transferred to the decoder separately or together with the data to be decoded. 410 411**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 412 413**Since**: 11 414 415**Parameters** 416 417| Name| Description| 418| -------- | -------- | 419| codec | Pointer to a video decoder instance. | 420| index | Index of an input buffer. The index is obtained from [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer).| 421 422**Returns** 423 424One of the following result codes: 425 426**AV_ERR_OK**: The operation is successful. 427 428**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 429 430**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 431 432**AV_ERR_UNKNOWN**: An unknown error occurs. 433 434**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 435 436**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 437 438 439### OH_VideoDecoder_RegisterCallback() 440 441``` 442OH_AVErrCode OH_VideoDecoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 443``` 444 445**Description** 446 447Registers an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to **OH_VideoDecoder_Prepare**. 448 449**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 450 451**Since**: 11 452 453**Parameters** 454 455| Name| Description| 456| -------- | -------- | 457| codec | Pointer to a video decoder instance. | 458| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md). | 459| userData | Pointer to the data on which the caller depends when executing the callback. | 460 461**Returns** 462 463One of the following result codes: 464 465**AV_ERR_OK**: The operation is successful. 466 467**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 468 469**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 470 471**AV_ERR_UNKNOWN**: An unknown error occurs. 472 473**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 474 475**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. 476 477 478### OH_VideoDecoder_RenderOutputBuffer() 479 480``` 481OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer (OH_AVCodec *codec, uint32_t index ) 482``` 483 484**Description** 485 486Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering on the output surface. 487 488If no output surface is configured, calling this function only frees the output buffer. 489 490**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 491 492**Since**: 11 493 494**Parameters** 495 496| Name| Description| 497| -------- | -------- | 498| codec | Pointer to a video decoder instance. | 499| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer). | 500 501**Returns** 502 503One of the following result codes: 504 505**AV_ERR_OK**: The operation is successful. 506 507**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 508 509**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 510 511**AV_ERR_UNKNOWN**: An unknown error occurs. 512 513**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 514 515**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 516 517 518### OH_VideoDecoder_RenderOutputBufferAtTime() 519 520``` 521OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs); 522``` 523 524**Description** 525 526Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering within the specified duration on the output surface. 527 528If no output surface is configured, calling this function only frees the output buffer. 529 530You can request the system to render the buffer at a specific time (after the VSYNC or buffer timestamp) based on the timestamp. To render the buffer at the specified timestamp, that timestamp should approximate the current system time within an acceptable margin of error. Pay attention to the following: 5311. Buffers are processed sequentially, which may result in the display of subsequent buffers on the surface being blocked. This is particularly important for interactive scenarios, such as responding to user actions like stopping, fast-forwarding, or rewinding a video. 5322. If multiple buffers are sent to the surface for rendering on a single VSYNC event, the last buffer is rendered and other buffers are discarded. 5333. If the difference between the timestamp and the current system time exceeds the acceptable margin of error, the surface ignores the timestamp and renders the buffer at the earliest feasible time. In this case, no frames are discarded. 5344. If you want the system to handle frame-dropping based on the display's refresh rate, you have to use this function. Otherwise, your application manages frame-dropping on its own. 535 536**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 537 538**Since**: 12 539 540**Parameters** 541 542| Name| Description| 543| -------- | -------- | 544| codec | Pointer to a video decoder instance. | 545| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 546| renderTimestampNs | Timestamp (in nanoseconds) when the output buffer is sent to the surface. The value must be greater than 0 and should be generated by the clock of the std::chrono::steady_clock standard library. | 547 548**Returns** 549 550One of the following result codes: 551 552**AV_ERR_OK**: The operation is successful. 553 554**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 555 556**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 557 558**AV_ERR_UNKNOWN**: An unknown error occurs. 559 560**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 561 562**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 563 564 565### OH_VideoDecoder_Reset() 566 567``` 568OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec *codec) 569``` 570 571**Description** 572 573Resets a video decoder. The decoder returns to the initial state. To continue decoding, you must call **OH_VideoDecoder_Configure** to configure the decoder again. 574 575**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 576 577**Since**: 9 578 579**Parameters** 580 581| Name| Description| 582| -------- | -------- | 583| codec | Pointer to a video decoder instance. | 584 585**Returns** 586 587One of the following result codes: 588 589**AV_ERR_OK**: The operation is successful. 590 591**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 592 593**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 594 595**AV_ERR_UNKNOWN**: An unknown error occurs. 596 597**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 598 599 600### OH_VideoDecoder_SetDecryptionConfig() 601 602``` 603OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath) 604``` 605**Description** 606 607Sets the decryption configuration. This function can be called prior to **OH_VideoDecoder_Prepare**. 608 609**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 610 611**Since**: 11 612 613**Parameters** 614 615| Name| Description| 616| -------- | -------- | 617| codec | Pointer to a video decoder instance. | 618| mediaKeySession | Pointer to a media key session instance with decryption capabilities. For details, see [MediaKeySession](../../reference/apis-drm-kit/capi-native-mediakeysession-h.md). | 619| secureVideoPath | Whether a secure video channel is used. The value **true** means a secure video channel, and **false** means a non-secure video channel. In [surface mode](../../media/avcodec/video-decoding.md#surface-mode), both secure and non-secure video channels are supported. In [buffer mode](../../media/avcodec/video-decoding.md#buffer-mode), only non-secure video channels are supported. | 620 621**Returns** 622 623One of the following result codes: 624 625**AV_ERR_OK**: The operation is successful. 626 627**AV_ERR_OPERATE_NOT_PERMIT**: 628 629 1. An internal execution error occurs. 630 2. The decoding service process is abnormal. 631 3. The media key session service is in an error state. 632 633**AV_ERR_INVALID_VAL**: 634 635 1. The value of **codec** is nullptr or does not point to a decoder instance. 636 2. The value of **mediaKeySession** is NULL or invalid. 637 638**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 639 640 641### OH_VideoDecoder_SetParameter() 642 643``` 644OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 645``` 646 647**Description** 648 649Sets dynamic parameters for a video decoder. 650 651This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. 652 653**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 654 655**Since**: 9 656 657**Parameters** 658 659| Name| Description| 660| -------- | -------- | 661| codec | Pointer to a video decoder instance. | 662| format | Pointer to an OH_AVFormat instance. | 663 664**Returns** 665 666One of the following result codes: 667 668**AV_ERR_OK**: The operation is successful. 669 670**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 671 672**AV_ERR_INVALID_VAL**: 673 674 1. The value of **codec** is nullptr or does not point to a decoder instance. 675 2. The format is not supported. 676 677**AV_ERR_UNKNOWN**: An unknown error occurs. 678 679**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 680 681**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 682 683 684### OH_VideoDecoder_SetSurface() 685 686``` 687OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window ) 688``` 689 690**Description** 691 692Sets an output surface for a video decoder. 693 694In the initialization phase, this function must be called prior to **OH_VideoDecoder_Prepare**. In the executing state, it can be called directly. 695 696 697**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 698 699**Since**: 9 700 701**Parameters** 702 703| Name| Description| 704| -------- | -------- | 705| codec | Pointer to a video decoder instance. | 706| window | Pointer to an OHNativeWindow instance. For details, see [OHNativeWindow](_codec_base.md#ohnativewindow). | 707 708**Returns** 709 710One of the following result codes: 711 712**AV_ERR_OK**: The operation is successful. 713 714**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 715 716**AV_ERR_OPERATE_NOT_PERMIT**: The function is called in the buffer mode. It can be called only in the surface mode. 717 718**AV_ERR_INVALID_VAL**: 719 720 1. The value of **codec** is nullptr or does not point to a decoder instance. 721 2. The value of **window** is nullptr. 722 723**AV_ERR_UNKNOWN**: An unknown error occurs. 724 725**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 726 727 728### OH_VideoDecoder_Start() 729 730``` 731OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec *codec) 732``` 733 734**Description** 735 736Starts a video decoder. This function should be called after a successful call of **OH_VideoDecoder_Prepare**. After being started, the decoder starts to report the registered event. 737 738**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 739 740**Since**: 9 741 742**Parameters** 743 744| Name| Description| 745| -------- | -------- | 746| codec | Pointer to a video decoder instance. | 747 748**Returns** 749 750One of the following result codes: 751 752**AV_ERR_OK**: The operation is successful. 753 754**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 755 756**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 757 758**AV_ERR_UNKNOWN**: An unknown error occurs. 759 760**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 761 762**AV_ERR_OPERATE_NOT_PERMIT**: 763 764 1. An internal execution error occurs. 765 2. CSC is configured, but **OH_VideoDecoder_Prepare** is not called. 766 767 768### OH_VideoDecoder_Stop() 769 770``` 771OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec *codec) 772``` 773 774**Description** 775 776Stops a video decoder and releases the input and output buffers. After the video decoder is stopped, you can call **OH_VideoDecoder_Start** to enter the running state again. 777 778If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. 779 780**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 781 782**Since**: 9 783 784**Parameters** 785 786| Name| Description| 787| -------- | -------- | 788| codec | Pointer to a video decoder instance. | 789 790**Returns** 791 792One of the following result codes: 793 794**AV_ERR_OK**: The operation is successful. 795 796**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 797 798**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 799 800**AV_ERR_UNKNOWN**: An unknown error occurs. 801 802**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 803 804**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 805 806 807### OH_VideoDecoder_QueryInputBuffer() 808 809``` 810OH_AVErrCode OH_VideoDecoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 811``` 812 813**Description** 814 815Obtains the index of the next available input buffer. 816 817After calling this function, you must call [OH_VideoDecoder_GetInputBuffer](#oh_videodecoder_getinputbuffer) to obtain the buffer instance and call [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) to pass the buffer instance to the decoder. 818 819Note that the preceding operations are supported only in synchronous mode. 820 821**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 822 823**Since**: 20 824 825**Parameters** 826 827| Name| Description| 828| -------- | -------- | 829| codec | Pointer to a video decoder instance. | 830| index | Pointer to the index of the input buffer.| 831| timeoutUs | Timeout duration, in microseconds. A negative value means to wait infinitely. The value **0** means to return immediately. A positive value means to wait for the specified time before exiting. | 832 833**Returns** 834 835One of the following result codes: 836 837**AV_ERR_OK**: The operation is successful. 838 839**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 840 841**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 842 843**AV_ERR_UNKNOWN**: An unknown error occurs. 844 845**AV_ERR_SERVICE_DIED**: The codec service has been terminated. 846 847**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 848 849**AV_ERR_OPERATE_NOT_PERMIT**: This function is called in asynchronous mode. 850 851**AV_ERR_TRY_AGAIN_LATER**: The query fails. Try again after a short interval. 852 853 854### OH_VideoDecoder_GetInputBuffer() 855 856``` 857OH_AVBuffer *OH_VideoDecoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index); 858``` 859 860**Description** 861 862Obtains the instance of the available input buffer. 863 864Note that this function works only in synchronous mode. 865 866**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 867 868**Since**: 20 869 870**Parameters** 871 872| Name| Description| 873| -------- | -------- | 874| codec | Pointer to a video decoder instance. | 875| index | Index of the input buffer. It can be obtained by calling [OH_VideoDecoder_QueryInputBuffer](#oh_videodecoder_queryinputbuffer).| 876 877**Returns** 878 879Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned. 880 881 882### OH_VideoDecoder_QueryOutputBuffer() 883 884``` 885OH_AVErrCode OH_VideoDecoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 886``` 887 888**Description** 889 890Obtains the index of the next available output buffer. 891 892You can perform the following operations to display or release the decoded frame of the buffer instance obtained through [OH_VideoDecoder_GetOutputBuffer](#oh_videodecoder_getoutputbuffer): 8931. Return the processed output buffer to the decoder by calling [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer). 8942. Render the output surface by calling [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer). 8953. Render the output surface within the specified time by calling [OH_VideoDecoder_RenderOutputBufferAtTime](#oh_videodecoder_renderoutputbufferattime). 896 897Note that the preceding operations are supported only in synchronous mode. 898 899**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 900 901**Since**: 20 902 903**Parameters** 904 905| Name| Description| 906| -------- | -------- | 907| codec | Pointer to a video decoder instance. | 908| index | Pointer to the index of the output buffer.| 909| timeoutUs | Timeout duration, in microseconds. A negative value means to wait infinitely. The value **0** means to return immediately. A positive value means to wait for the specified time before exiting. | 910 911**Returns** 912 913One of the following result codes: 914 915**AV_ERR_OK**: The operation is successful. 916 917**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 918 919**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 920 921**AV_ERR_UNKNOWN**: An unknown error occurs. 922 923**AV_ERR_SERVICE_DIED**: The codec service has been terminated. 924 925**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 926 927**AV_ERR_OPERATE_NOT_PERMIT**: This function is called in asynchronous mode. 928 929**AV_ERR_STREAM_CHANGED**: The stream format has changed. You can call **OH_VideoDecoder_GetOutputDescription** to obtain the new stream information. 930 931**AV_ERR_TRY_AGAIN_LATER**: The query fails. Try again after a short interval. 932 933 934### OH_VideoDecoder_GetOutputBuffer() 935 936``` 937OH_AVBuffer *OH_VideoDecoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index); 938``` 939 940**Description** 941 942Obtains the instance of the available output buffer. 943 944Note that this function works only in synchronous mode. 945 946**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 947 948**Since**: 20 949 950**Parameters** 951 952| Name| Description| 953| -------- | -------- | 954| codec | Pointer to a video decoder instance. | 955| index | Index of the output buffer. It can be obtained by calling [OH_VideoDecoder_QueryOutputBuffer](#oh_videodecoder_queryoutputbuffer).| 956 957**Returns** 958 959Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned. 960 961 962## Description of Deprecated Functions 963 964 965### OH_VideoDecoder_SetCallback() 966 967``` 968OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 969``` 970 971**Description** 972 973Sets an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to **OH_VideoDecoder_Prepare**. 974 975**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 976 977**Since**: 9 978 979**Deprecated from**: 11 980 981**Substitute**: [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) 982 983**Parameters** 984 985| Name| Description| 986| -------- | -------- | 987| codec | Pointer to a video decoder instance. | 988| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md). | 989| userData | Pointer to the data on which the caller depends when executing the callback. | 990 991**Returns** 992 993One of the following result codes: 994 995**AV_ERR_OK**: The operation is successful. 996 997**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 998 999**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 1000 1001**AV_ERR_UNKNOWN**: An unknown error occurs. 1002 1003**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1004 1005**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. 1006 1007 1008### OH_VideoDecoder_RenderOutputData() 1009 1010``` 1011OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec *codec, uint32_t index ) 1012``` 1013 1014**Description** 1015 1016Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. 1017 1018If no output surface is configured, calling this function only frees the output buffer. 1019 1020**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 1021 1022**Since**: 9 1023 1024**Deprecated from**: 11 1025 1026**Substitute**: [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) 1027 1028**Parameters** 1029 1030| Name| Description| 1031| -------- | -------- | 1032| codec | Pointer to a video decoder instance. | 1033| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | 1034 1035**Returns** 1036 1037One of the following result codes: 1038 1039**AV_ERR_OK**: The operation is successful. 1040 1041**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 1042 1043**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 1044 1045**AV_ERR_UNKNOWN**: An unknown error occurs. 1046 1047**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1048 1049**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 1050 1051 1052### OH_VideoDecoder_PushInputData() 1053 1054``` 1055OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 1056``` 1057 1058**Description** 1059 1060Pushes the input buffer filled with data to a video decoder. 1061 1062The input callback reports the available input buffer and the index. For details, see [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). 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. 1063 1064In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 1065 1066**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 1067 1068**Since**: 9 1069 1070**Deprecated from**: 11 1071 1072**Substitute**: [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) 1073 1074**Parameters** 1075 1076| Name| Description| 1077| -------- | -------- | 1078| codec | Pointer to a video decoder instance. | 1079| index | Index of an input buffer. The index is obtained from [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). | 1080| attr | Description information about the data in the buffer. | 1081 1082**Returns** 1083 1084One of the following result codes: 1085 1086**AV_ERR_OK**: The operation is successful. 1087 1088**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 1089 1090**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 1091 1092**AV_ERR_UNKNOWN**: An unknown error occurs. 1093 1094**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1095 1096**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 1097 1098 1099### OH_VideoDecoder_FreeOutputData() 1100 1101``` 1102OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 1103``` 1104 1105**Description** 1106 1107Frees an output buffer of a video decoder. 1108 1109**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 1110 1111**Since**: 9 1112 1113**Deprecated from**: 11 1114 1115**Substitute**: [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) 1116 1117**Parameters** 1118 1119| Name| Description| 1120| -------- | -------- | 1121| codec | Pointer to a video decoder instance. | 1122| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | 1123 1124**Returns** 1125 1126One of the following result codes: 1127 1128**AV_ERR_OK**: The operation is successful. 1129 1130**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 1131 1132**AV_ERR_INVALID_VAL**: The value of **codec** is nullptr or does not point to a decoder instance. 1133 1134**AV_ERR_UNKNOWN**: An unknown error occurs. 1135 1136**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 1137 1138**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 1139
