# AudioCodec

<!--Kit: AVCodec Kit-->
<!--Subsystem: Multimedia-->
<!--Owner: @mr-chencxy-->
<!--Designer: @dpy2650--->
<!--Tester: @baotianhao-->
<!--Adviser: @zengyawen-->

## Overview

The AudioCodec module provides the functions for audio encoding and decoding.

You can refer to the corresponding development guide and samples based on your development requirements.

- [Audio Encoding](../../media/avcodec/audio-encoding.md)
- [Audio Decoding](../../media/avcodec/audio-decoding.md)

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11


## Summary


### Files

| Name| Description| 
| -------- | -------- |
| [native_avcodec_audiocodec.h](native__avcodec__audiocodec_8h.md) | Declares the native APIs used for audio encoding and decoding.| 


### Functions

| Name| Description| 
| -------- | -------- |
| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_AudioCodec_CreateByMime](#oh_audiocodec_createbymime) (const char \*mime, bool isEncoder) | Creates an audio codec instance based on a [MIME](_codec_base.md#media-codec-formats) type.| 
| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_AudioCodec_CreateByName](#oh_audiocodec_createbyname) (const char \*name) | Creates an audio codec instance based on a codec name. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Destroy](#oh_audiocodec_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the internal resources of an audio codec and destroys the codec instance.| 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_RegisterCallback](#oh_audiocodec_registercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | Sets an asynchronous callback so that your application can respond to events generated by an audio codec. This function must be called prior to **Prepare**. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Configure](#oh_audiocodec_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, const [OH_AVFormat](_core.md#oh_avformat) \*format) | Configures the audio description. The audio codec is usually configured based on the audio description.| 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Prepare](#oh_audiocodec_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Prepares internal resources for an audio codec.| 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Start](#oh_audiocodec_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Starts an audio codec after it is prepared successfully.| 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Stop](#oh_audiocodec_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Stops an audio codec.| 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Flush](#oh_audiocodec_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Clears the input and output data in the internal buffer of an audio codec.| 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_Reset](#oh_audiocodec_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Resets an audio codec. The configured parameters and input and output data are cleared.<br>To continue encoding or decoding, you must call **Configure** to configure the codec again. | 
| [OH_AVFormat](_core.md#oh_avformat) \* [OH_AudioCodec_GetOutputDescription](#oh_audiocodec_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | Obtains the description information about the output data of an audio codec. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_SetParameter](#oh_audiocodec_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, const [OH_AVFormat](_core.md#oh_avformat) \*format) | Sets dynamic parameters for an audio codec. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_PushInputBuffer](#oh_audiocodec_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Notifies the audio codec that the input data has been written to the buffer identified by **index**. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_FreeOutputBuffer](#oh_audiocodec_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Frees an output buffer of an audio codec. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_IsValid](#oh_audiocodec_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | Checks whether an audio codec instance is valid.<br>This function is used to detect the codec status when a background fault is rectified or an application is switched from the background. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_SetDecryptionConfig](#oh_audiocodec_setdecryptionconfig) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, MediaKeySession \*mediaKeySession, bool secureAudio) | Sets the decryption information. | 
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_QueryInputBuffer](#oh_audiocodec_queryinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | Obtains the available input buffer of an audio codec. This function returns the result synchronously.|
| [OH_AVBuffer](_core.md#oh_avbuffer) *[OH_AudioCodec_GetInputBuffer](#oh_audiocodec_getinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Obtains the input buffer identified by **index** of an audio codec.|
| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioCodec_QueryOutputBuffer](#oh_audiocodec_queryoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | Obtains the available output buffer of an audio codec. This function returns the result synchronously.|
| [OH_AVBuffer](_core.md#oh_avbuffer) *[OH_AudioCodec_GetOutputBuffer](#oh_audiocodec_getoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | Obtains the output buffer identified by **index** of an audio codec.|

## Function Description

### OH_AudioCodec_Configure()

```
OH_AVErrCode OH_AudioCodec_Configure (OH_AVCodec *codec, const OH_AVFormat *format)
```

**Description**

Configures the audio description. The audio codec is usually configured based on the audio description. This function must be called prior to **Prepare**.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| format | Pointer to an OH_AVFormat instance, which provides the description information about the audio track to be encoded or decoded.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_CreateByMime()

```
OH_AVCodec* OH_AudioCodec_CreateByMime (const char *mime, bool isEncoder)
```

**Description**

Creates an audio codec instance based on a MIME type. This function is recommended in most cases.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 
| isEncoder | The value **true** means to create an encoder, and **false** means to create a decoder.| 

**Returns**

Pointer to an OH_AVCodec instance.


### OH_AudioCodec_CreateByName()

```
OH_AVCodec* OH_AudioCodec_CreateByName (const char *name)
```

**Description**

Creates an audio codec instance based on a codec name. 

To use this function, you must know the exact name of the codec, which can be obtained by calling [the corresponding API](_a_v_capability.md#oh_avcapability_getname).

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| name | Pointer to an audio codec name.| 

**Returns**

Pointer to an OH_AVCodec instance.


### OH_AudioCodec_Destroy()

```
OH_AVErrCode OH_AudioCodec_Destroy (OH_AVCodec *codec)
```

**Description**

Clears the internal resources of an audio codec and destroys the codec instance.

Do not repeatedly destroy the instance. Otherwise, the program may crash.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance. | 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_Flush()

```
OH_AVErrCode OH_AudioCodec_Flush (OH_AVCodec *codec)
```

**Description**

Clears the input and output data in the internal buffer of an audio codec.

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.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_FreeOutputBuffer()

```
OH_AVErrCode OH_AudioCodec_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index)
```

**Description**

Frees an output buffer of an audio codec.

You need to call this function to release the output buffer in a timely manner. Otherwise, the encoding or decoding process is blocked.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| index | Index of the [OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer).| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_GetInputBuffer()

```
OH_AVBuffer *OH_AudioCodec_GetInputBuffer(OH_AVCodec *codec, uint32_t index)
```

**Description**

Obtains the input buffer identified by **index** for an audio codec, and fills it with new data.

After the buffer is filled, call [OH_AudioCodec_PushInputBuffer](#oh_audiocodec_pushinputbuffer) with the same index to push the buffer to the codec.

After the buffer is pushed to the codec, you can no longer access the input buffer for that index.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 20

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| index | Index of the input buffer. It is obtained by calling [OH_AudioCodec_QueryInputBuffer](#oh_audiocodec_queryinputbuffer).|

**Returns**

Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.


### OH_AudioCodec_GetOutputBuffer()

```
OH_AVBuffer *OH_AudioCodec_GetOutputBuffer(OH_AVCodec *codec, uint32_t index)
```

**Description**

Obtains the output buffer identified by **index** for an audio codec.

After using the buffer, call [OH_AudioCodec_FreeOutputBuffer](#oh_audiocodec_freeoutputbuffer) to release the buffer. Once released, the buffer cannot be reused. Prolonged failure to release buffers will block the codec process.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 20

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| index | Index of the output buffer. It is obtained by calling [OH_AudioCodec_QueryOutputBuffer](#oh_audiocodec_queryoutputbuffer).|

**Returns**

Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.


### OH_AudioCodec_GetOutputDescription()

```
OH_AVFormat* OH_AudioCodec_GetOutputDescription (OH_AVCodec *codec)
```

**Description**

Obtains the **OH_AVFormat** information about the output data of an audio codec.


You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to manually release the OH_AVFormat instance in the return value.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 

**Returns**

Handle to an OH_AVFormat instance. The lifecycle of this instance is refreshed when **GetOutputDescription** is called again and destroyed when the OH_AVCodec instance is destroyed.


### OH_AudioCodec_IsValid()

```
OH_AVErrCode OH_AudioCodec_IsValid (OH_AVCodec *codec, bool *isValid)
```

**Description**

Checks whether an audio codec instance is valid.<br>This function is used to detect the codec status when a background fault is rectified or an application is switched from the background.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| isValid | Pointer to an instance of the Boolean type. The value **true** means that the codec instance is valid, and **false** means the opposite.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_Prepare()

```
OH_AVErrCode OH_AudioCodec_Prepare (OH_AVCodec *codec)
```

**Description**

Prepares internal resources for an audio codec. This function must be called after **Configure**.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_PushInputBuffer()

```
OH_AVErrCode OH_AudioCodec_PushInputBuffer (OH_AVCodec *codec, uint32_t index)
```

**Description**

Notifies the audio codec that the input data has been written to the buffer identified by **index**.

The [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer) callback reports the available input buffer and the index. After being pushed to the codec, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer) callback.

In addition, some codecs require the input of codec-specific data to initialize the encoding or decoding process.

> **NOTE**
> 
> If the return value is **AV_ERR_UNKNOWN**, the call does not take effect, and the input buffer is still in the unprocessed state. You need to handle the error according to the specific error code and then call [OH_AudioCodec_PushInputBuffer](#oh_audiocodec_pushinputbuffer) again with the same index.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| index | Index of the [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer).| 

**Returns**

One of the following result codes defined in [OH_AVErrCode](_core.md#oh_averrcode):

- **AV_ERR_OK**: The operation is successful.

- **AV_ERR_INVALID_VAL**: The input index is used or invalid. Use the index returned by the [OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer) callback.

- **AV_ERR_INVALID_STATE**: The codec state is incorrect. Before calling [OH_AudioCodec_PushInputBuffer](#oh_audiocodec_pushinputbuffer), ensure that [OH_AudioCodec_Configure](#oh_audiocodec_configure), [OH_AudioCodec_Prepare](#oh_audiocodec_prepare), and [OH_AudioCodec_Start](#oh_audiocodec_start) are successfully called in sequence.

- **AV_ERR_UNKNOWN**: The input buffer size is invalid. Ensure that the buffer size and flags are correctly set.


### OH_AudioCodec_QueryInputBuffer()

```
OH_AVErrCode OH_AudioCodec_QueryInputBuffer(OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)
```

**Description**

Obtains the index of an available input buffer for an audio codec within the specified timeout period.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 20

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| index | Pointer to the index of the input buffer obtained.|
| timeoutUs | Timeout period, in microseconds. A negative value means to wait infinitely.|

**Returns**

One of the following result codes:

- **AV_ERR_OK**: The operation is successful.

- **AV_ERR_INVALID_VAL**: The operation fails due to incorrect input parameters.

- **AV_ERR_INVALID_STATE**: The operation fails due to an invalid state, for example, the codec not being started.

- **AV_ERR_OPERATE_NOT_PERMIT**: The operation fails because the call is not allowed in asynchronous mode.

- **AV_ERR_TRY_AGAIN_LATER**: The operation fails because no available buffer is obtained within the timeout period.

### OH_AudioCodec_QueryOutputBuffer()

```
OH_AVErrCode OH_AudioCodec_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)
```

**Description**

Obtains the index of an available output buffer for an audio codec within the specified timeout period.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 20

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| index | Pointer to the index of the output buffer obtained.|
| timeoutUs | Timeout period, in microseconds. A negative value means to wait infinitely.|

**Returns**

One of the following result codes:

- **AV_ERR_OK**: The operation is successful.

- **AV_ERR_INVALID_VAL**: The operation fails due to incorrect input parameters.

- **AV_ERR_INVALID_STATE**: The operation fails due to an invalid state, for example, the codec not being started.

- **AV_ERR_OPERATE_NOT_PERMIT**: The operation fails because the call is not allowed in asynchronous mode.

- **AV_ERR_STREAM_CHANGED**: The format of the decoded output stream changes. You can call [OH_AudioCodec_GetOutputDescription](#oh_audiocodec_getoutputdescription) to obtain the new stream information.

- **AV_ERR_TRY_AGAIN_LATER**: The operation fails because no available buffer is obtained within the timeout period.

### OH_AudioCodec_RegisterCallback()

```
OH_AVErrCode OH_AudioCodec_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData)
```

**Description**

Sets an asynchronous callback so that your application can respond to events generated by an audio codec. This function must be called prior to **Prepare**.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md).| 
| userData | User-specific data.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_Reset()

```
OH_AVErrCode OH_AudioCodec_Reset (OH_AVCodec *codec)
```

**Description**

Resets an audio codec. The configured parameters and input and output data are cleared.

To continue encoding or decoding, you must call **Configure** to configure the codec again.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance. | 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_SetDecryptionConfig()

```
OH_AVErrCode OH_AudioCodec_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureAudio)
```

**Description**

Sets the decryption information.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 12

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance. | 
| mediaKeySession | Pointer to the media key session with the decryption feature. | 
| secureAudio | Whether a secure decoder is used. The value **true** means that a secure decoder is used, and **false** means the opposite.<br>Currently, the secure decoder is not supported for audio decryption. | 

**Returns**

One of the following result codes defined in [OH_AVErrCode](_core.md#oh_averrcode):

**AV_ERR_OK**: The operation is successful.

**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid, or the mediaKeySystemInfo instance is nullptr or invalid.

**AV_ERR_INVALID_STATE**: The decoder service is unavailable.


### OH_AudioCodec_SetParameter()

```
OH_AVErrCode OH_AudioCodec_SetParameter (OH_AVCodec *codec, const OH_AVFormat *format)
```

**Description**

Sets dynamic parameters for an audio codec.

This function can be called only after the codec is started. Incorrect parameter settings may cause encoding or decoding failure.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 
| format | Handle to an OH_AVFormat instance.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_Start()

```
OH_AVErrCode OH_AudioCodec_Start (OH_AVCodec *codec)
```

**Description**

Starts an audio codec after it is prepared successfully. After being started, the codec starts to report the **OH_AVCodecOnNeedInputBuffer** event.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.


### OH_AudioCodec_Stop()

```
OH_AVErrCode OH_AudioCodec_Stop (OH_AVCodec *codec)
```

**Description**

Stops an audio codec.

After the codec is stopped, you can call **Start** to start it again. If you have passed specific data in the previous **Start** for the codec, you must pass it again.

**System capability**: SystemCapability.Multimedia.Media.AudioCodec

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an OH_AVCodec instance.| 

**Returns**

**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.