_video_decoder.md

# VideoDecoder


## Overview

Provides the functions for video decoding. This module may not be supported on some devices. You can call [CanIUse](../syscap.md) to check whether this module is supported on your device.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Since**
9


## Summary


### Files

  | Name| Description| 
| -------- | -------- |
| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | Declares the native APIs used for video decoding.<br>File to include: <multimedia/player_framework/native_avcodec_videodecoder.h> | 


### Functions

  | Name| Description| 
| -------- | -------- |
| [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | Creates a video decoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This API is recommended in most cases. | 
| [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | Creates a video decoder instance based on a video decoder name. To use this API, you must know the exact name of the video decoder. | 
| [OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of a video decoder and destroys the video decoder instance. | 
| [OH_VideoDecoder_SetCallback](#oh_videodecoder_setcallback) (OH_AVCodec \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | Sets an asynchronous callback so that your application can respond to events generated by a video decoder. This API must be called prior to **Prepare**. | 
| [OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) (OH_AVCodec \*codec, OHNativeWindow \*window) | Sets an output surface for a video decoder. This API must be called prior to **Prepare**. | 
| [OH_VideoDecoder_Configure](#oh_videodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | Configures a video decoder. Typically, you need to configure the attributes, which can be extracted from the container, of the video track that can be decoded. This API must be called prior to **Prepare**. | 
| [OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for a video decoder. This API must be called after **Configure**. | 
| [OH_VideoDecoder_Start](#oh_videodecoder_start) (OH_AVCodec \*codec) | Starts a video decoder. This API can be called only after the decoder is prepared successfully. After being started, the decoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. | 
| [OH_VideoDecoder_Stop](#oh_videodecoder_stop) (OH_AVCodec \*codec) | Stops a video decoder. After the decoder is stopped, you can call **Start** to start it again. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. | 
| [OH_VideoDecoder_Flush](#oh_videodecoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of a video decoder. This API invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this API, ensure that the buffers corresponding to the indexes are no longer required. | 
| [OH_VideoDecoder_Reset](#oh_videodecoder_reset) (OH_AVCodec \*codec) | Resets a video decoder. To continue decoding, you must call **Configure** and **Start** to configure and start the decoder again. | 
| [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the attributes of the output data of a video decoder. The **OH_AVFormat** instance in the return value will become invalid when this API is called again or when the **OH_AVCodec** instance is destroyed. | 
| [OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for a video decoder. This API can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. | 
| [OH_VideoDecoder_PushInputData](#oh_videodecoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | Pushes the input buffer filled with data to a video decoder. The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports available input buffers and their indexes. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) 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. | 
| [OH_VideoDecoder_RenderOutputData](#oh_videodecoder_renderoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. If no output surface is configured, calling this API only frees the output buffer. | 
| [OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of a video decoder. | 


## Function Description


### OH_VideoDecoder_Configure()

  
```
OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec * codec, OH_AVFormat * format )
```
**Description**<br>
Configures a video decoder. Typically, you need to configure the attributes, which can be extracted from the container, of the video track that can be decoded. This API must be called prior to **Prepare**.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| format | Indicates the handle to an **OH_AVFormat** instance, which provides the attributes of the video track to be decoded. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_CreateByMime()

  
```
OH_AVCodec* OH_VideoDecoder_CreateByMime (const char * mime)
```
**Description**<br>
Creates a video decoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This API is recommended in most cases.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| mime | Indicates the pointer to a MIME type. For details, see [OH_AVCODEC_MIMETYPE_VIDEO_AVC](_codec_base.md#oh_avcodec_mimetype_video_avc).| 

**Returns**

Returns the pointer to an **OH_AVCodec** instance.


### OH_VideoDecoder_CreateByName()

  
```
OH_AVCodec* OH_VideoDecoder_CreateByName (const char * name)
```
**Description**<br>
Creates a video decoder instance based on a video decoder name. To use this API, you must know the exact name of the video decoder.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| name | Indicates the pointer to a video decoder name. | 

**Returns**

Returns the pointer to an **OH_AVCodec** instance.


### OH_VideoDecoder_Destroy()

  
```
OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec * codec)
```
**Description**<br>
Clears the internal resources of a video decoder and destroys the video decoder instance.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_Flush()

  
```
OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec * codec)
```
**Description**<br>
Clears the input and output data in the internal buffer of a video decoder. This API invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this API, ensure that the buffers corresponding to the indexes are no longer required.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_FreeOutputData()

  
```
OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec * codec, uint32_t index )
```
**Description**<br>
Frees an output buffer of a video decoder.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| index | Indicates the index of an output buffer. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_GetOutputDescription()

  
```
OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec * codec)
```
**Description**<br>
Obtains the attributes of the output data of a video decoder. The **OH_AVFormat** instance in the return value will become invalid when this API is called again or when the **OH_AVCodec** instance is destroyed.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns the pointer to an **OH_AVFormat** instance.


### OH_VideoDecoder_Prepare()

  
```
OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec * codec)
```
**Description**<br>
Prepares internal resources for a video decoder. This API must be called after **Configure**.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_PushInputData()

  
```
OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec * codec, uint32_t index, OH_AVCodecBufferAttr attr )
```
**Description**<br>
Pushes the input buffer filled with data to a video decoder. The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports available input buffers and their indexes. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) 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.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| index | Indicates the index of an input buffer. | 
| attr | Indicates the attributes of the data contained in the buffer. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_RenderOutputData()

  
```
OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec * codec, uint32_t index )
```
**Description**<br>
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 API only frees the output buffer.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| index | Indicates the index of an output buffer. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_Reset()

  
```
OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec * codec)
```
**Description**<br>
Resets a video decoder. To continue decoding, you must call **Configure** and **Start** to configure and start the decoder again.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_SetCallback()

  
```
OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData )
```
**Description**<br>
Sets an asynchronous callback so that your application can respond to events generated by a video decoder. This API must be called prior to **Prepare**.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| callback | Indicates a collection of all callback functions. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 
| userData | Indicates the pointer to user-specific data. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_SetParameter()

  
```
OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format )
```
**Description**<br>
Sets dynamic parameters for a video decoder. This API can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| format | Indicates the pointer to an **OH_AVFormat** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_SetSurface()

  
```
OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window )
```
**Description**<br>
Sets an output surface for a video decoder. This API must be called prior to **Prepare**.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 
| window | Indicates the pointer to an **OHNativeWindow** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_Start()

  
```
OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec * codec)
```
**Description**<br>
Starts a video decoder. This API can be called only after the decoder is prepared successfully. After being started, the decoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.


### OH_VideoDecoder_Stop()

  
```
OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec * codec)
```
**Description**<br>
Stops a video decoder. After the decoder is stopped, you can call **Start** to start it again. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again.

@syscap SystemCapability.Multimedia.Media.VideoDecoder

**Parameters**

  | Name| Description| 
| -------- | -------- |
| codec | Indicates the pointer to an **OH_AVCodec** instance. | 

**Returns**

Returns **AV_ERR_OK** if the operation is successful.

Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails.