xref: /docs/en/application-dev/reference/apis-avcodec-kit/_audio_codec.md

# AudioCodec


## Overview

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

**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 Multipurpose Internet Mail Extension (MIME) 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 \*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. To continue encoding or decoding, you must call **Configure** to configure the codec again. | 
| 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 \*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) | Pushes the input buffer filled with data to an audio codec. | 
| [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. | 


## 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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**

Returns the 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.

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

**Since**: 11

**Parameters**

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

**Returns**

Returns the 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.

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

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | 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) 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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.

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

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an **OH_AVCodec** instance.| 
| index | 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) otherwise.


### OH_AudioCodec_GetOutputDescription()

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

**Description**

Obtains the description information about the output data of an audio codec.


The caller 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**

Returns the 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 | Output parameter. Pointer to an instance of the Boolean type. The value **true** means that the codec instance is valid, and **false** means the opposite.| 

**Returns**

Returns **AV_ERR_OK** if the operation is successful; returns 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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**

Pushes the input buffer filled with data to an audio codec.

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.

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

**Since**: 11

**Parameters**

| Name| Description| 
| -------- | -------- |
| codec | Pointer to an **OH_AVCodec** instance.| 
| index | Index of an input buffer.| 

**Returns**

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


### 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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. 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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**

Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode).

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

**AV_ERR_INVALID_VAL** is returned if the **OH_AVCodec** instance is a null pointer or invalid, or the **mediaKeySystemInfo** instance is a null pointer or invalid.

**AV_ERR_INVALID_STATE** if 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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**

Returns **AV_ERR_OK** if the operation is successful; returns 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**

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