1# VideoDecoder 2 3 4## Overview 5 6The VideoDecoder module provides the APIs for video decoding. 7 8**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 9 10**Since**: 9 11 12The following figures show the APIs supported by each version and the APIs that can be called in different states. 13 14 15 16 17 18## Summary 19 20 21### Files 22 23| Name| Description| 24| -------- | -------- | 25| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | Declares the APIs used for video decoding. | 26 27 28### Functions 29 30| Name| Description| 31| -------- | -------- | 32| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | Creates a video decoder instance based on a Multipurpose Internet Mail Extension (MIME) type.| 33| [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. | 34| [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. | 35| [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. (This function is deprecated in API version 11.) | 36| [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. | 37| [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. | 38| [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**. | 39| [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. | 40| [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**. | 41| [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. | 42| [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. | 43| [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. | 44| [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. | 45| [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. | 46| [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. (This function is deprecated in API version 11.) | 47| [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. (This function is deprecated in API version 11.) | 48| [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. (This function is deprecated in API version 11.) | 49| [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. | 50| [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. | 51| [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. | 52| [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. | 53| [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. | 54| [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. | 55 56 57## Function Description 58 59 60### OH_VideoDecoder_Configure() 61 62``` 63OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 64``` 65 66**Description** 67 68Configures a video decoder. Typically, you need to configure the video description information that can be extracted from **OH_AVSource**. This function must be called prior to **OH_VideoDecoder_Prepare**. 69 70The 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. 71 72If the current platform does not support **OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY**, no error is reported and the normal decoding process is used. 73 74Parameter verification rules are as follows: 75 76| Key | Value Within the Range| Value Out of Range| No Value Configured| 77| -----------------------------------------------------------------------------| -------- | -------- | ------ | 78| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 79| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 80| OH_MD_KEY_PIXEL_FORMAT<br>For details, see [OH_AVPixelFormat](_core.md#oh_avpixelformat). | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 81| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 82| 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 | 83 84> **NOTE** 85> 86> 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. 87 88 89**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 90 91**Since**: 9 92 93**Parameters** 94 95| Name| Description| 96| -------- | -------- | 97| codec | Pointer to a video decoder instance. | 98| format | Pointer to an **OH_AVFormat** instance, which provides the description information about the video track to be decoded. | 99 100**Returns** 101 102Returns any of the following result codes: 103 104**AV_ERR_OK**: The operation is successful. 105 106**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 107 108**AV_ERR_INVALID_VAL**: 109 110 1. The value of **codec** is a null pointer or does not point to a decoder instance. 111 2. The format is not supported. 112 113**AV_ERR_UNKNOWN**: An unknown error occurs. 114 115**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 116 117**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. 118 119**AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION**: CSC is not supported. 120 121 122### OH_VideoDecoder_CreateByMime() 123 124``` 125OH_AVCodec* OH_VideoDecoder_CreateByMime (const char *mime) 126``` 127 128**Description** 129 130Creates a video decoder instance based on a MIME type. This function is recommended in most cases. 131 132**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 133 134**Since**: 9 135 136**Parameters** 137 138| Name| Description| 139| -------- | -------- | 140| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 141 142**Returns** 143 144Returns the pointer to the video decoder instance if the operation is successful; returns NULL if the decoder type is not supported or the memory is insufficient. 145 146 147### OH_VideoDecoder_CreateByName() 148 149``` 150OH_AVCodec* OH_VideoDecoder_CreateByName (const char *name) 151``` 152 153**Description** 154 155Creates 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. 156 157**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 158 159**Since**: 9 160 161**Parameters** 162 163| Name| Description| 164| -------- | -------- | 165| name | Pointer to a video decoder name. | 166 167**Returns** 168 169Returns the pointer to the video decoder instance if the operation is successful; returns NULL if the decoder name is not supported or the memory is insufficient. 170 171 172### OH_VideoDecoder_Destroy() 173 174``` 175OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec *codec) 176``` 177 178**Description** 179 180Clears the internal resources of a video decoder and destroys the decoder instance. You only need to call the function once. 181 182**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 183 184**Since**: 9 185 186**Parameters** 187 188| Name| Description| 189| -------- | -------- | 190| codec | Pointer to a video decoder instance. | 191 192**Returns** 193 194Returns any of the following result codes: 195 196**AV_ERR_OK**: The operation is successful. 197 198**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 199 200**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 201 202**AV_ERR_UNKNOWN**: An unknown error occurs. 203 204**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 205 206 207### OH_VideoDecoder_Flush() 208 209``` 210OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec *codec) 211``` 212 213**Description** 214 215Clears 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. 216 217**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 218 219**Since**: 9 220 221**Parameters** 222 223| Name| Description| 224| -------- | -------- | 225| codec | Pointer to a video decoder instance. | 226 227**Returns** 228 229Returns any of the following result codes: 230 231**AV_ERR_OK**: The operation is successful. 232 233**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 234 235**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 236 237**AV_ERR_UNKNOWN**: An unknown error occurs. 238 239**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 240 241**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 242 243 244### OH_VideoDecoder_FreeOutputBuffer() 245 246``` 247OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 248``` 249 250**Description** 251 252Frees an output buffer of a video decoder. 253 254You need to call this function to release the output buffer in a timely manner. Otherwise, the decoding process is blocked. 255 256**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 257 258**Since**: 11 259 260**Parameters** 261 262| Name| Description| 263| -------- | -------- | 264| codec | Pointer to a video decoder instance.| 265| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 266 267**Returns** 268 269Returns any of the following result codes: 270 271**AV_ERR_OK**: The operation is successful. 272 273**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 274 275**AV_ERR_INVALID_VAL**: 276 277 1. The value of **codec** is a null pointer or does not point to a decoder instance. 278 2. The index is invalid or the same index is used consecutively. This error does not affect the subsequent decoding process. 279 280**AV_ERR_UNKNOWN**: An unknown error occurs. 281 282**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 283 284**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 285 286 287### OH_VideoDecoder_GetOutputDescription() 288 289``` 290OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec *codec) 291``` 292**Description** 293 294Obtains the OH_AVFormat information about the output data of a video decoder. For details, see [OH_AVFormat](_core.md#oh_avformat). 295 296The caller must call **OH_AVFormat_Destroy** to release the **OH_AVFormat** instance in the return value. 297 298**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 299 300**Since**: 9 301 302**Parameters** 303 304| Name| Description| 305| -------- | -------- | 306| codec | Pointer to a video decoder instance. | 307 308**Returns** 309 310Returns the pointer to an **OH_AVFormat** instance if the operation is successful; returns NULL if the value of **codec** is a null pointer or does not point to a decoder instance. 311 312 313### OH_VideoDecoder_IsValid() 314 315``` 316OH_AVErrCode OH_VideoDecoder_IsValid (OH_AVCodec *codec, bool *isValid ) 317``` 318 319**Description** 320 321Checks whether a video decoder instance is valid. 322 323**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 324 325**Since**: 10 326 327**Parameters** 328 329| Name| Description| 330| -------- | -------- | 331| codec | Pointer to a video decoder instance. | 332| isValid | Output parameter. Pointer of the Boolean type. The value **true** means that the decoder instance is valid and **false** means the opposite. It is recommended that the caller initialize **isValid** to **false**. | 333 334**Returns** 335 336Returns either of the following result codes: 337 338**AV_ERR_OK**: The operation is successful. 339 340**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 341 342 343### OH_VideoDecoder_Prepare() 344 345``` 346OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec *codec) 347``` 348 349**Description** 350 351Prepares internal resources for a video decoder. This function must be called after **OH_VideoDecoder_Configure**. 352 353**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 354 355**Since**: 9 356 357**Parameters** 358 359| Name| Description| 360| -------- | -------- | 361| codec | Pointer to a video decoder instance. | 362 363**Returns** 364 365Returns any of the following result codes: 366 367**AV_ERR_OK**: The operation is successful. 368 369**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 370 371**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 372 373**AV_ERR_UNKNOWN**: An unknown error occurs. 374 375**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 376 377**AV_ERR_OPERATE_NOT_PERMIT**: 378 379 1. An internal execution error occurs. 380 2. CSC is configured, but the decoder is in buffer mode. 381 382 383### OH_VideoDecoder_PushInputBuffer() 384 385``` 386OH_AVErrCode OH_VideoDecoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 387``` 388 389**Description** 390 391Notifies a video decoder that the buffer corresponding to the index has been filled with input data. 392 393The 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. 394 395In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 396 397This 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. 398 399**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 400 401**Since**: 11 402 403**Parameters** 404 405| Name| Description| 406| -------- | -------- | 407| codec | Pointer to a video decoder instance. | 408| index | Index of an input buffer. The index is obtained from [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer).| 409 410**Returns** 411 412Returns any of the following result codes: 413 414**AV_ERR_OK**: The operation is successful. 415 416**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 417 418**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 419 420**AV_ERR_UNKNOWN**: An unknown error occurs. 421 422**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 423 424**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 425 426 427### OH_VideoDecoder_RegisterCallback() 428 429``` 430OH_AVErrCode OH_VideoDecoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 431``` 432 433**Description** 434 435Registers 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**. 436 437**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 438 439**Since**: 11 440 441**Parameters** 442 443| Name| Description| 444| -------- | -------- | 445| codec | Pointer to a video decoder instance. | 446| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md). | 447| userData | Pointer to the data on which the caller depends when executing the callback. | 448 449**Returns** 450 451Returns any of the following result codes: 452 453**AV_ERR_OK**: The operation is successful. 454 455**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 456 457**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 458 459**AV_ERR_UNKNOWN**: An unknown error occurs. 460 461**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 462 463**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. 464 465 466### OH_VideoDecoder_RenderOutputBuffer() 467 468``` 469OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer (OH_AVCodec *codec, uint32_t index ) 470``` 471 472**Description** 473 474Returns 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. 475 476If no output surface is configured, calling this function only frees the output buffer. 477 478**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 479 480**Since**: 11 481 482**Parameters** 483 484| Name| Description| 485| -------- | -------- | 486| codec | Pointer to a video decoder instance. | 487| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer). | 488 489**Returns** 490 491Returns any of the following result codes: 492 493**AV_ERR_OK**: The operation is successful. 494 495**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 496 497**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 498 499**AV_ERR_UNKNOWN**: An unknown error occurs. 500 501**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 502 503**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 504 505 506### OH_VideoDecoder_RenderOutputBufferAtTime() 507 508``` 509OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs); 510``` 511 512**Description** 513 514Returns 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. 515 516If no output surface is configured, calling this function only frees the output buffer. 517 518The caller 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: 5191. 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. 5202. 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. 5213. 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. 522 523**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 524 525**Since**: 12 526 527**Parameters** 528 529| Name| Description| 530| -------- | -------- | 531| codec | Pointer to a video decoder instance. | 532| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 533| 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. | 534 535**Returns** 536 537Returns any of the following result codes: 538 539**AV_ERR_OK**: The operation is successful. 540 541**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 542 543**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 544 545**AV_ERR_UNKNOWN**: An unknown error occurs. 546 547**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 548 549**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 550 551 552### OH_VideoDecoder_Reset() 553 554``` 555OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec *codec) 556``` 557 558**Description** 559 560Resets a video decoder. The decoder returns to the initial state. To continue decoding, you must call **OH_VideoDecoder_Configure** to configure the decoder again. 561 562**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 563 564**Since**: 9 565 566**Parameters** 567 568| Name| Description| 569| -------- | -------- | 570| codec | Pointer to a video decoder instance. | 571 572**Returns** 573 574Returns any of the following result codes: 575 576**AV_ERR_OK**: The operation is successful. 577 578**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 579 580**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 581 582**AV_ERR_UNKNOWN**: An unknown error occurs. 583 584**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 585 586 587### OH_VideoDecoder_SetDecryptionConfig() 588 589``` 590OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath) 591``` 592**Description** 593 594Sets the decryption configuration. This function can be called prior to **OH_VideoDecoder_Prepare**. 595 596**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 597 598**Since**: 11 599 600**Parameters** 601 602| Name| Description| 603| -------- | -------- | 604| codec | Pointer to a video decoder instance. | 605| mediaKeySession | Pointer to a media key session instance with decryption capabilities. For details, see **MediaKeySession**. | 606| 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-output), both secure and non-secure video channels are supported. In [buffer mode](../../media/avcodec/video-decoding.md#buffer-output), only non-secure video channels are supported. | 607 608**Returns** 609 610Returns any of the following result codes: 611 612**AV_ERR_OK**: The operation is successful. 613 614**AV_ERR_OPERATE_NOT_PERMIT**: 615 616 1. An internal execution error occurs. 617 2. The decoding service process is abnormal. 618 3. The media key session service is in an error state. 619 620**AV_ERR_INVALID_VAL**: 621 622 1. The value of **codec** is a null pointer or does not point to a decoder instance. 623 2. The value of **mediaKeySession** is a null pointer or invalid. 624 625**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 626 627 628### OH_VideoDecoder_SetParameter() 629 630``` 631OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 632``` 633 634**Description** 635 636Sets dynamic parameters for a video decoder. 637 638This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. 639 640**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 641 642**Since**: 9 643 644**Parameters** 645 646| Name| Description| 647| -------- | -------- | 648| codec | Pointer to a video decoder instance. | 649| format | Pointer to an **OH_AVFormat** instance. | 650 651**Returns** 652 653Returns any of the following result codes: 654 655**AV_ERR_OK**: The operation is successful. 656 657**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 658 659**AV_ERR_INVALID_VAL**: 660 661 1. The value of **codec** is a null pointer or does not point to a decoder instance. 662 2. The format is not supported. 663 664**AV_ERR_UNKNOWN**: An unknown error occurs. 665 666**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 667 668**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 669 670 671### OH_VideoDecoder_SetSurface() 672 673``` 674OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window ) 675``` 676 677**Description** 678 679Sets an output surface for a video decoder. 680 681In the initialization phase, this function must be called prior to **OH_VideoDecoder_Prepare**. In the executing state, it can be called directly. 682 683 684**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 685 686**Since**: 9 687 688**Parameters** 689 690| Name| Description| 691| -------- | -------- | 692| codec | Pointer to a video decoder instance. | 693| window | Pointer to an **OHNativeWindow** instance. For details, see [OHNativeWindow](_codec_base.md#ohnativewindow). | 694 695**Returns** 696 697Returns any of the following result codes: 698 699**AV_ERR_OK**: The operation is successful. 700 701**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 702 703**AV_ERR_OPERATE_NOT_PERMIT**: The function is called in the buffer mode. It can be called only in the surface mode. 704 705**AV_ERR_INVALID_VAL**: 706 707 1. The value of **codec** is a null pointer or does not point to a decoder instance. 708 2. The value of **window** is a null pointer. 709 710**AV_ERR_UNKNOWN**: An unknown error occurs. 711 712**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 713 714 715### OH_VideoDecoder_Start() 716 717``` 718OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec *codec) 719``` 720 721**Description** 722 723Starts 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. 724 725**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 726 727**Since**: 9 728 729**Parameters** 730 731| Name| Description| 732| -------- | -------- | 733| codec | Pointer to a video decoder instance. | 734 735**Returns** 736 737Returns any of the following result codes: 738 739**AV_ERR_OK**: The operation is successful. 740 741**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 742 743**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 744 745**AV_ERR_UNKNOWN**: An unknown error occurs. 746 747**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 748 749**AV_ERR_OPERATE_NOT_PERMIT**: 750 751 1. An internal execution error occurs. 752 2. CSC is configured, but **OH_VideoDecoder_Prepare** is not called. 753 754 755### OH_VideoDecoder_Stop() 756 757``` 758OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec *codec) 759``` 760 761**Description** 762 763Stops 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. 764 765If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. 766 767**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 768 769**Since**: 9 770 771**Parameters** 772 773| Name| Description| 774| -------- | -------- | 775| codec | Pointer to a video decoder instance. | 776 777**Returns** 778 779Returns any of the following result codes: 780 781**AV_ERR_OK**: The operation is successful. 782 783**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 784 785**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 786 787**AV_ERR_UNKNOWN**: An unknown error occurs. 788 789**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 790 791**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 792 793 794## Description of Deprecated Functions 795 796 797### OH_VideoDecoder_SetCallback() 798 799``` 800OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 801``` 802 803**Description** 804 805Sets 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**. 806 807**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 808 809**Since**: 9 810 811**Deprecated version**: 11 812 813**Substitute**: [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) 814 815**Parameters** 816 817| Name| Description| 818| -------- | -------- | 819| codec | Pointer to a video decoder instance. | 820| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md). | 821| userData | Pointer to the data on which the caller depends when executing the callback. | 822 823**Returns** 824 825Returns any of the following result codes: 826 827**AV_ERR_OK**: The operation is successful. 828 829**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 830 831**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 832 833**AV_ERR_UNKNOWN**: An unknown error occurs. 834 835**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 836 837**AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. 838 839 840### OH_VideoDecoder_RenderOutputData() 841 842``` 843OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec *codec, uint32_t index ) 844``` 845 846**Description** 847 848Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. 849 850If no output surface is configured, calling this function only frees the output buffer. 851 852**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 853 854**Since**: 9 855 856**Deprecated version**: 11 857 858**Substitute**: [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) 859 860**Parameters** 861 862| Name| Description| 863| -------- | -------- | 864| codec | Pointer to a video decoder instance. | 865| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | 866 867**Returns** 868 869Returns any of the following result codes: 870 871**AV_ERR_OK**: The operation is successful. 872 873**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 874 875**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 876 877**AV_ERR_UNKNOWN**: An unknown error occurs. 878 879**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 880 881**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 882 883 884### OH_VideoDecoder_PushInputData() 885 886``` 887OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 888``` 889 890**Description** 891 892Pushes the input buffer filled with data to a video decoder. 893 894The 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. 895 896In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. 897 898**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 899 900**Since**: 9 901 902**Deprecated version**: 11 903 904**Substitute**: [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) 905 906**Parameters** 907 908| Name| Description| 909| -------- | -------- | 910| codec | Pointer to a video decoder instance. | 911| index | Index of an input buffer. The index is obtained from [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). | 912| attr | Description information about the data in the buffer. | 913 914**Returns** 915 916Returns any of the following result codes: 917 918**AV_ERR_OK**: The operation is successful. 919 920**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 921 922**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 923 924**AV_ERR_UNKNOWN**: An unknown error occurs. 925 926**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 927 928**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 929 930 931### OH_VideoDecoder_FreeOutputData() 932 933``` 934OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 935``` 936 937**Description** 938 939Frees an output buffer of a video decoder. 940 941**System capability**: SystemCapability.Multimedia.Media.VideoDecoder 942 943**Since**: 9 944 945**Deprecated version**: 11 946 947**Substitute**: [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) 948 949**Parameters** 950 951| Name| Description| 952| -------- | -------- | 953| codec | Pointer to a video decoder instance. | 954| index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | 955 956**Returns** 957 958Returns any of the following result codes: 959 960**AV_ERR_OK**: The operation is successful. 961 962**AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. 963 964**AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. 965 966**AV_ERR_UNKNOWN**: An unknown error occurs. 967 968**AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. 969 970**AV_ERR_INVALID_STATE**: The function is called in an incorrect state. 971
