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