# VideoDecoder ## Overview The VideoDecoder module provides the APIs for video decoding. For details about the development guide and sample, see [Video Decoding](../../media/avcodec/video-decoding.md). **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 The following figures show the APIs supported by each version and the APIs that can be called in different states. ![meaning](figures/meaning.PNG) ![desciption of decode api history](figures/video-decode-api.PNG) ## Summary ### Files | Name| Description| | -------- | -------- | | [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | Declares the APIs used for video decoding. | ### Functions | Name| Description| | -------- | -------- | | [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.| | [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. | | [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. | | [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.) | | [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. | | [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. | | [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). | | [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. | | [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**. | | [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. | | [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. | | [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. | | [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. | | [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. | | [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.) | | [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.) | | [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.) | | [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. | | [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. | | [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. | | [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. | | [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. | | [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. | ## Function Description ### OH_VideoDecoder_Configure() ``` OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) ``` **Description** Configures 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**. The 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. If the current platform does not support **OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY**, no error is reported and the normal decoding process is used. Parameter verification rules are as follows: | Key | Value Within the Range| Value Out of Range| No Value Configured| | -----------------------------------------------------------------------------| -------- | -------- | ------ | | OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | | OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | | OH_MD_KEY_PIXEL_FORMAT
For details, see [OH_AVPixelFormat](_core.md#oh_avpixelformat). | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | | OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | | OH_MD_KEY_ROTATION
For details, see [OH_MD_KEY_ROTATION](_codec_base.md#oh_md_key_rotation).| AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | > **NOTE** > > 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. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | format | Pointer to an **OH_AVFormat** instance, which provides the description information about the video track to be decoded. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: 1. The value of **codec** is a null pointer or does not point to a decoder instance. 2. The format is not supported. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. **AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION**: CSC is not supported. ### OH_VideoDecoder_CreateByMime() ``` OH_AVCodec* OH_VideoDecoder_CreateByMime (const char *mime) ``` **Description** Creates a video decoder instance based on a MIME type. This function is recommended in most cases. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| **Returns** Returns 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. ### OH_VideoDecoder_CreateByName() ``` OH_AVCodec* OH_VideoDecoder_CreateByName (const char *name) ``` **Description** Creates 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. For details, see [Obtaining Supported Codecs](../../media/avcodec/obtain-supported-codecs.md#creating-a-codec-with-the-specified-name). **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | name | Pointer to a video decoder name. | **Returns** Returns 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. ### OH_VideoDecoder_Destroy() ``` OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec *codec) ``` **Description** Clears the internal resources of a video decoder and destroys the decoder instance. You only need to call the function once. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. ### OH_VideoDecoder_Flush() ``` OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec *codec) ``` **Description** Clears 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. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_FreeOutputBuffer() ``` OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) ``` **Description** Frees an output buffer of a video decoder. You need to call this function to release the output buffer in a timely manner. Otherwise, the decoding process is blocked. For details, see step 13 in surface mode or step 10 in buffer mode in [Video Decoding](../../media/avcodec/video-decoding.md). **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 11 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance.| | index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: 1. The value of **codec** is a null pointer or does not point to a decoder instance. 2. The index is invalid or the same index is used consecutively. This error does not affect the subsequent decoding process. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_GetOutputDescription() ``` OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec *codec) ``` **Description** Obtains the OH_AVFormat information about the output data of a video decoder. For details, see [OH_AVFormat](_core.md#oh_avformat). The caller must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the **OH_AVFormat** instance in the return value. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns 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. ### OH_VideoDecoder_IsValid() ``` OH_AVErrCode OH_VideoDecoder_IsValid (OH_AVCodec *codec, bool *isValid ) ``` **Description** Checks whether a video decoder instance is valid. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 10 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | 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**. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. ### OH_VideoDecoder_Prepare() ``` OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec *codec) ``` **Description** Prepares internal resources for a video decoder. This function must be called after **OH_VideoDecoder_Configure**. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. **AV_ERR_OPERATE_NOT_PERMIT**: 1. An internal execution error occurs. 2. CSC is configured, but the decoder is in buffer mode. ### OH_VideoDecoder_PushInputBuffer() ``` OH_AVErrCode OH_VideoDecoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) ``` **Description** Notifies a video decoder that the buffer corresponding to the index has been filled with input data. The 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. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. This 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. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 11 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | index | Index of an input buffer. The index is obtained from [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer).| **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_RegisterCallback() ``` OH_AVErrCode OH_VideoDecoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) ``` **Description** Registers 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**. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 11 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md). | | userData | Pointer to the data on which the caller depends when executing the callback. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. ### OH_VideoDecoder_RenderOutputBuffer() ``` OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer (OH_AVCodec *codec, uint32_t index ) ``` **Description** 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. If no output surface is configured, calling this function only frees the output buffer. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 11 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer). | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_RenderOutputBufferAtTime() ``` OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs); ``` **Description** 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. If no output surface is configured, calling this function only frees the output buffer. The 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: 1. 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. 2. 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. 3. 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. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 12 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| | 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. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_Reset() ``` OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec *codec) ``` **Description** Resets a video decoder. The decoder returns to the initial state. To continue decoding, you must call **OH_VideoDecoder_Configure** to configure the decoder again. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. ### OH_VideoDecoder_SetDecryptionConfig() ``` OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath) ``` **Description** Sets the decryption configuration. This function can be called prior to **OH_VideoDecoder_Prepare**. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 11 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | mediaKeySession | Pointer to a media key session instance with decryption capabilities. For details, see **MediaKeySession**. | | 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. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_OPERATE_NOT_PERMIT**: 1. An internal execution error occurs. 2. The decoding service process is abnormal. 3. The media key session service is in an error state. **AV_ERR_INVALID_VAL**: 1. The value of **codec** is a null pointer or does not point to a decoder instance. 2. The value of **mediaKeySession** is a null pointer or invalid. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. ### OH_VideoDecoder_SetParameter() ``` OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) ``` **Description** Sets dynamic parameters for a video decoder. This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | format | Pointer to an **OH_AVFormat** instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: 1. The value of **codec** is a null pointer or does not point to a decoder instance. 2. The format is not supported. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_SetSurface() ``` OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window ) ``` **Description** Sets an output surface for a video decoder. In the initialization phase, this function must be called prior to **OH_VideoDecoder_Prepare**. In the executing state, it can be called directly. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | window | Pointer to an **OHNativeWindow** instance. For details, see [OHNativeWindow](_codec_base.md#ohnativewindow). | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_OPERATE_NOT_PERMIT**: The function is called in the buffer mode. It can be called only in the surface mode. **AV_ERR_INVALID_VAL**: 1. The value of **codec** is a null pointer or does not point to a decoder instance. 2. The value of **window** is a null pointer. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_Start() ``` OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec *codec) ``` **Description** Starts 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. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. **AV_ERR_OPERATE_NOT_PERMIT**: 1. An internal execution error occurs. 2. CSC is configured, but **OH_VideoDecoder_Prepare** is not called. ### OH_VideoDecoder_Stop() ``` OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec *codec) ``` **Description** Stops 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. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ## Description of Deprecated Functions ### OH_VideoDecoder_SetCallback() ``` OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) ``` **Description** Sets 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**. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Deprecated from**: 11 **Substitute**: [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md). | | userData | Pointer to the data on which the caller depends when executing the callback. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is not called prior to **OH_VideoDecoder_Prepare**. ### OH_VideoDecoder_RenderOutputData() ``` OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec *codec, uint32_t index ) ``` **Description** Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. If no output surface is configured, calling this function only frees the output buffer. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Deprecated from**: 11 **Substitute**: [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_PushInputData() ``` OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) ``` **Description** Pushes the input buffer filled with data to a video decoder. The 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. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Deprecated from**: 11 **Substitute**: [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | index | Index of an input buffer. The index is obtained from [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata). | | attr | Description information about the data in the buffer. | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state. ### OH_VideoDecoder_FreeOutputData() ``` OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) ``` **Description** Frees an output buffer of a video decoder. **System capability**: SystemCapability.Multimedia.Media.VideoDecoder **Since**: 9 **Deprecated from**: 11 **Substitute**: [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) **Parameters** | Name| Description| | -------- | -------- | | codec | Pointer to a video decoder instance. | | index | Index of an output buffer. The index is obtained from [OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata). | **Returns** Returns one of the following result codes: **AV_ERR_OK**: The operation is successful. **AV_ERR_NO_MEMORY**: The decoder instance has been destroyed. **AV_ERR_INVALID_VAL**: The value of **codec** is a null pointer or does not point to a decoder instance. **AV_ERR_UNKNOWN**: An unknown error occurs. **AV_ERR_OPERATE_NOT_PERMIT**: An internal execution error occurs. **AV_ERR_INVALID_STATE**: The function is called in an incorrect state.