# K230 audio API reference

## Overview

### Overview

The audio module is a highly integrated module designed to meet the multimedia business needs of the k230 platform. It is composed of multiple sub-modules, including audio input (AI), audio output (AO), audio encoding (AENC), and audio decoding (ADEC). It also has a built-in audio codec. A low-coupling architecture design is adopted between each sub-module to achieve efficient and stable data flow transmission.

#### Detailed description of submodule functions

- **Audio Input Module (AI)**: This module has flexible interface compatibility and supports two interface standards: I2S (Inter-IC Sound) and PDM (Pulse Density Modulation). In terms of data processing, PDMA (Peripheral Direct Memory Access) technology is used to achieve fast memory copying to ensure efficient transmission of audio data. It can handle input signals from different types of audio sources, including digital microphones using PDM or I2S interfaces, as well as analog microphones connected through I2S interfaces.

- **Built-in audio codec**: The module integrates an audio codec, which not only can complete the basic audio signal conversion function, but also has a built-in audio3a algorithm implemented through software. This algorithm covers functions such as echo cancellation (AEC), noise reduction (ANR), and automatic gain control (AGC), which can effectively enhance audio quality and provide users with a clear and pure audio experience.

- **Audio Output Module (AO)**: Supports I2S interface and also uses PDMA for memory copy operations. This module has a wide range of device connection capabilities. It can connect to external digital speakers and directly output digital audio signals. It can also use an audio codec to convert digital audio signals into analog signals and then output them to adapt to different types of audio playback devices.

- **Audio encoding and decoding module (AENC and ADEC)**: The audio encoding and decoding module (AENC/ADEC) provides standardized encoding and decoding capabilities for audio data processing. It natively supports the two mainstream audio formats G711 and Opus, which can meet the audio encoding and decoding needs in different scenarios. It also has flexible expansion capabilities to adapt to diverse business application scenarios.
G711 is a classic universal audio coding standard in the industry. It adopts pulse code modulation (PCM) compression method. It has simple coding and decoding algorithms, low processing delay, and strong compatibility. It is widely adapted to various basic audio communication and collection and playback scenarios. It has high operation stability and can be quickly integrated and used without complex configuration;
Opus is a new generation of open source high-efficiency audio coding format that combines low latency and high compression ratio. It supports audio coding from narrowband to full-band. It can still maintain excellent audio quality at low bit rates. It is also suitable for mid-to-high-end application scenarios such as real-time voice calls and audio streaming transmission that have requirements for both latency and sound quality. It has outstanding flexibility and practicality.
The module design follows an extensible architecture, provides a standardized open extension interface, supports users to register custom external codecs according to business needs, quickly expands the encoding and decoding capabilities of more audio formats, breaks the limitations of native formats, fully meets various differentiated and customized audio processing needs, and adapts to richer industry application scenarios.

#### Scenario application

For example, in a voice call scenario, each sub-module of the audio module works together to form a complete audio processing and transmission link. The specific process is as follows:

1. **Audio Input Module (AI)**: This module is responsible for collecting local audio data. Whether it is a signal from a digital microphone or an analog audio codec, it can be accurately captured. The audio input module also supports 3A processing (automatic gain control, echo cancellation and noise suppression) to improve audio quality and ensure that the output audio signal is clear and pure.
1. **Audio encoding module (AENC)**: Encode the collected audio data according to the G711 format to reduce the amount of data and facilitate efficient transmission in the network.
1. **Network transmission**: The encoded audio data is sent to the remote device through the network.
1. **Audio decoding module (ADEC)**: After the remote device receives the audio encoded data, it transmits it to the audio decoding module, decodes the encoded data, and restores the original audio signal.
1. **Audio Output Module (AO)**: The decoded audio signal is played through the audio output module, thereby achieving clear reproduction of the remote sound.

Through the above working mode, the audio module achieves efficient and stable audio data processing and transmission in voice call services, providing users with a high-quality voice communication experience.

![img](https://kendryte-download.canaan-creative.com/developer/pictures/b96e2ea6fe9536e76af33afe46b2069e.png)

### Functional Description

#### Audio input module (AI)

The core function of the audio input module (AI) is to configure and enable audio input devices and obtain audio frame data from them. This module supports two protocol interfaces, I2S and PDM, to meet different audio collection needs.

##### I2S audio interface

- **Number of channels**: Supports simultaneous collection of up to 2 channels of dual-channel audio to achieve high-quality stereo audio collection.
- **Sampling Parameters**:
  - **Sample Rate**: Supports 8kHz, 12kHz, 16kHz, 24kHz, 32kHz, 44.1kHz, 48kHz, 96kHz and 192kHz. Users can choose the appropriate sampling rate according to the actual application scenario.
  - **Sampling Accuracy**: Three options are provided: 16bit, 24bit and 32bit, suitable for scenarios with different sound quality requirements.
- **IO configuration and working mode**:
  - **IO Configuration**: Supports 2 sets of configurable input/output IO pins for transmitting I2S audio data.
  - **Working Mode**: Supports full-duplex mode, which can input and output audio data at the same time.

##### PDM audio interface

- **Number of channels**: Supports simultaneous collection of up to 8 channels of mono audio, suitable for multi-audio source collection scenarios.
- **Sampling Parameters**:
  - **Bit width and sampling clock frequency**: Support PDM audio input, 1 bit width, sampling clock frequency is 0.256MHz, 0.384MHz, 0.512MHz, 0.768MHz, 1.024MHz, 1.4112MHz, 1.536MHz, 2.048MHz, 2.8224MHz, 3. 072MHz, 4.096MHz, 5.6448MHz, 6.144MHz, 12.288MHz, 24.576MHz, the input PCM audio sampling rate is 8kHz, 12kHz, 16kHz, 24kHz, 32kHz, 44.1kHz, 48kHz, 96kHz, 192kHz.
  - **PCM Audio Sample Rate**: Supports 8kHz, 12kHz, 16kHz, 24kHz, 32kHz, 44.1kHz, 48kHz, 96kHz and 192kHz.
  - **Sampling precision**: Supports three sampling precisions of 16bit, 24bit and 32bit.
  - **Oversampling rate**: Supports 128, 64, and 32 times oversampling to improve audio resolution and signal-to-noise ratio.
- **IO Configuration and Channel Mode**:
  - **IO quantity**: Supports 1 - 4 IO pins for inputting PDM audio data.
  - **Channel Mode**: Supports 1 - 8 PDM channels, supports PDM left and right mono mode and dual channel mode.

#### Audio output module (AO)

The main function of the audio output module (AO) is to enable the audio output device and send audio frame data to the corresponding output channel. This module only supports I2S protocol interface.

##### I2S audio interface

- **Number of channels**: Supports simultaneous output of up to 2 channels of dual-channel audio to achieve high-quality stereo audio output.
- **Sampling Parameters**:
  - **Sample Rate**: Supports 8kHz, 12kHz, 16kHz, 24kHz, 32kHz, 44.1kHz, 48kHz, 96kHz and 192kHz, ensuring sample rate compatibility of input and output audio data.
  - **Sampling Accuracy**: Supports three sampling accuracies of 16bit, 24bit and 32bit to ensure the integrity and consistency of audio data.
- **IO configuration and working mode**:
  - **IO Configuration**: Supports 2 sets of configurable input/output IO pins for transmitting I2S audio data.
  - **Working Mode**: Supports full-duplex mode, allowing simultaneous input and output operations of audio data.

#### audio link

##### Audio signal conversion basics

Audio codec (Codec) plays a key role in the audio link, and k230 has a built-in audio codec (Codec). When the analog microphone receives the sound signal, the audio Codec will convert these analog signals into pulse code modulation (PCM) data that conforms to the I2S format, and then input it to the I2S interface of the audio module. Instead, when the I2S interface outputs PCM data, the audio codec converts it back to an analog signal and outputs it. In this mode, data transmission uses the sdi0 and sdo0 interfaces of I2S instead of the digital IO interface.

##### I2S interface connection method

The I2S interface has strong flexibility. It can be directly connected to an off-chip digital microphone to collect audio signals, or it can be connected to a power amplifier (PA) to amplify and output the processed audio signals. There are two groups of I2S interfaces to choose from, namely sdi0, sdo0 and sdi1, sdo1. Users can select the appropriate interface group based on actual hardware connection requirements and system design.

##### PDM microphone input method

For off-chip pulse density modulation (PDM) microphones, the audio module provides up to 4 input data interfaces, which can input up to 8 channels of PDM data at the same time to meet the needs of multi-channel audio collection.

##### Alternative audio link options

In order to meet the needs of different users, the system provides a variety of audio link solutions:

- **Option 1: 3 groups of PDM inputs + 1 group of I2S inputs + 2 groups of I2S outputs**
  - 3 sets of PDM input channels, multiple PDM microphones can be connected for audio collection.
  - 1 set of I2S input channels, which can use the built-in audio Codec or connect to off-chip I2S devices.
  - 2 sets of I2S output channels for outputting processed audio signals.

- **Option 2: 4 groups of PDM inputs + 2 groups of I2S outputs**
  - 4 sets of PDM input channels, capable of connecting more PDM microphones for audio collection.
  - 2 sets of I2S output channels for outputting processed audio signals.

- **Option 3: 2 groups of I2S inputs + 2 groups of PDM inputs + 2 groups of I2S outputs**
  - 2 sets of I2S input channels and 2 sets of PDM input channels can connect different types of audio input devices at the same time.
  - 2 sets of I2S output channels for outputting processed audio signals.

##### Hardware instructions

The K230 board comes with an onboard microphone and a 3.5mm headphone jack. Users can use the built-in audio Codec to test the input and output functions of a set of I2S audio and the related functions of the audio codec. If you need to use richer audio input and output functions, such as 2 sets of I2S audio input and output and 4 sets of PDM audio input functions, you need to design and make an audio daughter board yourself.

## API Reference

### Audio input

This function module provides the following APIs:

- [kd_mpi_ai_set_pub_attr](#kd_mpi_ai_set_pub_attr)
- [kd_mpi_ai_get_pub_attr](#kd_mpi_ai_get_pub_attr)
- [kd_mpi_ai_enable](#kd_mpi_ai_enable)
- [kd_mpi_ai_disable](#kd_mpi_ai_disable)
- [kd_mpi_ai_enable_chn](#kd_mpi_ai_enable_chn)
- [kd_mpi_ai_disable_chn](#kd_mpi_ai_enable_chn)
- [kd_mpi_ai_get_frame](#kd_mpi_ai_get_frame)
- [kd_mpi_ai_release_frame](#kd_mpi_ai_release_frame)
- [kd_mpi_ai_set_vqe_attr](#kd_mpi_ai_set_vqe_attr)
- [kd_mpi_ai_get_vqe_attr](#kd_mpi_ai_get_vqe_attr)

#### kd_mpi_ai_set_pub_attr

Description

Set AI device properties.

Syntax

k_s32 kd_mpi_ai_set_pub_attr([k_audio_dev](#k_audio_dev) ai_dev, const [k_aio_dev_attr](#k_aio_dev_attr) \*attr);

Parameters

| Parameter Name | Description | Input/Output |
|----------|-------------------|-----------|
| ai_dev | Audio device number. | Input |
| attr | AI device attribute pointer. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

Notes

None

Example

```c
k_aio_dev_attr aio_dev_attr;
memset(&aio_dev_attr,0,sizeof(aio_dev_attr));
aio_dev_attr.audio_type = KD_AUDIO_INPUT_TYPE_I2S;
aio_dev_attr.kd_audio_attr.i2s_attr.sample_rate = 44100;
aio_dev_attr.kd_audio_attr.i2s_attr.bit_width = KD_AUDIO_BIT_WIDTH_16
aio_dev_attr.kd_audio_attr.i2s_attr.chn_cnt = 2;
aio_dev_attr.kd_audio_attr.i2s_attr.i2s_mode = K_STANDARD_MODE;
aio_dev_attr.kd_audio_attr.i2s_attr.frame_num = 25;
aio_dev_attr.kd_audio_attr.i2s_attr.point_num_per_frame = 44100/25;
aio_dev_attr.kd_audio_attr.i2s_attr.i2s_type = K_AIO_I2STYPE_INNERCODEC;
if (K_SUCCESS != kd_mpi_ai_set_pub_attr(0, &aio_dev_attr))
{
printf("kd_mpi_ai_set_pub_attr failed\n");
return K_FAILED;
}
if (K_SUCCESS != kd_mpi_ai_enable(0))
{
printf("kd_mpi_ai_set_pub_attr failed\n");
return K_FAILED;
}
if (K_SUCCESS != kd_mpi_ai_enable_chn(0, 0))
{
printf("kd_mpi_ai_set_pub_attr failed\n");
return K_FAILED;
}
```

#### kd_mpi_ai_get_pub_attr

Description

Get AI device properties.

Syntax

k_s32 kd_mpi_ai_get_pub_attr([k_audio_dev](#k_audio_dev) ai_dev, [k_aio_dev_attr](#k_aio_dev_attr) \*attr);

Parameters

| Parameter Name | Description | Input/Output |
|----------|------------------|-----------|
| ai_dev | Audio device number. | Input |
| attr | AI device attribute pointer. | Output |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

#### kd_mpi_ai_enable

Description

Enable ai device.

Syntax

k_s32 kd_mpi_ai_enable([k_audio_dev](#k_audio_dev) ai_dev);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ai_dev | Audio device number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

#### kd_mpi_ai_disable

Description

Disable AI devices.

Syntax

k_s32 kd_mpi_ai_disable([k_audio_dev](#k_audio_dev) ai_dev);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ai_dev | Audio device number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

#### kd_mpi_ai_enable_chn

Description

Enable ai channel.

Syntax

k_s32 kd_mpi_ai_enable_chn([k_audio_dev](#k_audio_dev) ai_dev,[k_ai_chn](#k_ai_chn) ai_chn);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ai_dev | Audio device number. | Input |
| ai_chn | Audio channel number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

#### kd_mpi_ai_disable_chn

Description

Disable ai channel.

Syntax

k_s32 kd_mpi_ai_disable_chn([k_audio_dev](#k_audio_dev) ai_dev,[k_ai_chn](#k_ai_chn) ai_chn);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ai_dev | Audio device number. | Input |
| ai_chn | Audio channel number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

#### kd_mpi_ai_get_frame

Description

Get the audio frame.

Syntax

k_s32 kd_mpi_ai_get_frame([k_audio_dev](#k_audio_dev) ai_dev,[k_ai_chn](#k_ai_chn) ai_chn,[k_audio_frame](#k_audio_frame)\*frame, k_u32 milli_sec);

Parameters

| Parameter Name | Description | Input/Output |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------|
| ai_dev | Audio device number. | Input |
| ai_chn | Audio channel number. | Input |
| frame | Audio frame data. | Output |
| milli_sec | Timeout for getting data. -1 indicates blocking mode and waits when there is no data; 0 indicates non-blocking mode and returns an error when there is no data; >0 indicates blocking milli_sec milliseconds and returns an error when timeout occurs. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

Notes

- The value of milli_sec must be greater than or equal to -1. When equal to -1, blocking mode is used to obtain data. When equal to 0, non-blocking mode is used to obtain data.

Obtain data in blocking mode. When it is greater than 0, after blocking milli_sec milliseconds, if there is no data, a timeout will be returned and an error will be reported.

- Before obtaining audio frame data, the corresponding AI channel must be enabled first.

Example

```c
k_audio_frame audio_frame;
while(true)
{
//get frame
if (K_SUCCESS != kd_mpi_ai_get_frame(dev_num, channel, &audio_frame, 1000))
{
printf("=========kd_mpi_ai_get_frame timeout\n");
continue ;
}
//process frame
process_frame(&audio_frame);
//release frame
kd_mpi_ai_release_frame(dev_num, channel, &audio_frame);
}
```

#### kd_mpi_ai_release_frame

Description

Release the audio frame.

Syntax

k_s32 kd_mpi_ai_release_frame([k_audio_dev](#k_audio_dev) ai_dev,[k_ai_chn](#k_ai_chn) ai_chn,const [k_audio_frame](#k_audio_frame) *frame);[Parameter]

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ai_dev | Audio device number. | Input |
| ai_chn | Audio channel number. | Input |
| frame | Audio frame data. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

#### kd_mpi_ai_set_vqe_attr

Description

Set properties related to AI's sound quality enhancement function.

Syntax

k_s32 kd_mpi_ai_set_vqe_attr([k_audio_dev](#k_audio_dev) ai_dev, [k_ai_chn](#k_ai_chn) ai_chn, const [k_ai_vqe_enable](#k_ai_vqe_enable) vqe_enable);

Parameters

| Parameter Name | Description | Input/Output |
|------------|-----------------------------------------------------------|-----------|
| ai_dev | Audio device number. | Input |
| ai_chn | Audio channel number. | Input |
| vqe_enable | Sound quality enhancement enable flag. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h

Library File: libai.a

Notes

The sampling precision supported by audio 3a is 16bit, and agc only supports 8k/16k/32k/48k.

#### kd_mpi_ai_get_vqe_attr

Description

Get the properties related to AI's sound quality enhancement function.

Syntax

k_s32 kd_mpi_ai_get_vqe_attr([k_audio_dev](#k_audio_dev) ai_dev, [k_ai_chn](#k_ai_chn) ai_chn, [k_ai_vqe_enable](#k_ai_vqe_enable) vqe_enable);

Parameters

| Parameter Name | Description | Input/Output |
|------------|---------------------------------------------------------------|-----------|
| ai_dev | Audio device number. | Input |
| ai_chn | Audio channel number. | Input |
| vqe_enable | Sound quality enhancement enable flag pointer. | Output |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

### Audio output

This function module provides the following APIs:

- [kd_mpi_ao_set_pub_attr](#kd_mpi_ao_set_pub_attr)
- [kd_mpi_ao_get_pub_attr](#kd_mpi_ai_get_pub_attr)
- [kd_mpi_ao_enable](#kd_mpi_ao_enable)
- [kd_mpi_ao_disable](#kd_mpi_ao_disable)
- [kd_mpi_ao_enable_chn](#kd_mpi_ao_enable_chn)
- [kd_mpi_ao_disable_chn](#kd_mpi_ao_disable_chn)
- [kd_mpi_ao_send_frame](#kd_mpi_ao_send_frame)

#### kd_mpi_ao_set_pub_attr

Description

Set AO device properties.

Syntax

k_s32 kd_mpi_ao_set_pub_attr([k_audio_dev](#k_audio_dev) ao_dev, const [k_aio_dev_attr](#k_aio_dev_attr) *attr);

Parameters

| Parameter Name | Description | Input/Output |
|----------|-------------------|-----------|
| ao_dev | Audio device number. | Input |
| attr | AO device attribute pointer. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ao_api.h
- Library File: libao.a

Notes

None

Example

```c
k_aio_dev_attr ao_dev_attr;
memset(&ao_dev_attr,0,sizeof(ao_dev_attr));
ao_dev_attr.audio_type = KD_AUDIO_OUTPUT_TYPE_I2S;
ao_dev_attr.kd_audio_attr.i2s_attr.sample_rate = 48000;
ao_dev_attr.kd_audio_attr.i2s_attr.bit_width = KD_AUDIO_BIT_WIDTH_24;
ao_dev_attr.kd_audio_attr.i2s_attr.chn_cnt = 2;
ao_dev_attr.kd_audio_attr.i2s_attr.i2s_mode = K_RIGHT_JUSTIFYING_MODE;
ao_dev_attr.kd_audio_attr.i2s_attr.frame_num = 15;
ao_dev_attr.kd_audio_attr.i2s_attr.point_num_per_frame = 48000/25;
ao_dev_attr.kd_audio_attr.i2s_attr.i2s_type = K_AIO_I2STYPE_EXTERN;
if (K_SUCCESS != kd_mpi_ao_set_pub_attr(0, &ao_dev_attr))
{
printf("kd_mpi_ao_set_pub_attr failed\n");
return K_FAILED;
}

if (K_SUCCESS != kd_mpi_ai_enable(0))
{
printf("kd_mpi_ai_enable failed\n");
return K_FAILED;
}

if (K_SUCCESS != kd_mpi_ai_enable_chn(0,1))
{
printf("kd_mpi_ai_enable_chn failed\n");
return K_FAILED;
}
```

#### kd_mpi_ao_get_pub_attr

Description

Get AO device properties.

Syntax

k_s32 kd_mpi_ao_get_pub_attr([k_audio_dev](#k_audio_dev) ao_dev, [k_aio_dev_attr](#k_aio_dev_attr) *attr);

Parameters

| Parameter Name | Description | Input/Output |
|----------|------------------|-----------|
| ao_dev | Audio device number. | Input |
| attr | AO device attribute pointer. | Output |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ao_api.h
- Library File: libao.a

#### kd_mpi_ao_enable

Description

Enable ao device.

Syntax

k_s32 kd_mpi_ao_enable([k_audio_dev](#k_audio_dev) ao_dev);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ao_dev | Audio device number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ao_api.h
- Library File: libao.a

#### kd_mpi_ao_disable

Description

Disable ao devices.

Syntax

k_s32 kd_mpi_ao_disable([k_audio_dev](#k_audio_dev) ao_dev);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ao_dev | Audio device number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ao_api.h
- Library File: libao.a

#### kd_mpi_ao_enable_chn

Description

Enable ao channel.

Syntax

k_s32 kd_mpi_ao_enable_chn([k_audio_dev](#k_audio_dev) ao_dev,[k_ao_chn](#k_ao_chn) ao_chn);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ao_dev | Audio device number. | Input |
| ao_chn | Audio channel number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ao_api.h
- Library File: libao.a

#### kd_mpi_ao_disable_chn

Description

Disable ao channel.

Syntax

k_s32 kd_mpi_ao_disable_chn([k_audio_dev](#k_audio_dev) ao_dev,[k_ao_chn](#k_ao_chn) ao_chn);

Parameters

| Parameter Name | Description | Input/Output |
|----------|---------------|-----------|
| ao_dev | Audio device number. | Input |
| ao_chn | Audio channel number. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ao_api.h
- Library File: libao.a

#### kd_mpi_ao_send_frame

Description

Send ao frame data.

Syntax

k_s32 kd_mpi_ao_send_frame

([k_audio_dev](#k_audio_dev) ao_dev,[k_ao_chn](#k_ao_chn) ao_chn,const [k_audio_frame](#k_audio_frame)*frame,k_s32 milli_sec);

Parameters

| Parameter Name | Description | Input/Output |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------|
| ao_dev | Audio device number. | Input |
| ao_chn | Audio channel number. | Input |
| frame | Audio frame data pointer. | Input |
| milli_sec | Timeout for sending data. -1 indicates blocking mode and waits when there is no data; 0 indicates non-blocking mode and returns an error when there is no data; >0 indicates blocking milli_sec milliseconds and returns an error when timeout occurs. | Input |

Return Value

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_ai_api.h
- Library File: libai.a

Notes

- The value of milli_sec must be greater than or equal to -1. When equal to -1, blocking mode is used to obtain data. When equal to 0, non-blocking mode is used to obtain data.

Obtain data in blocking mode. When it is greater than 0, after blocking milli_sec milliseconds, if there is no data, a timeout will be returned and an error will be reported.

- Before sending audio frame data, the corresponding AO channel must be enabled first.

Example

```c
k_audio_frame audio_frame;
k_s32 ret = 0;
while (true)
{
//get ai frame
ret = kd_mpi_ai_get_frame(0, 0, &audio_frame, 1000);
if (K_SUCCESS != ret)
{
printf("=========kd_mpi_ai_get_frame timeout\n");
continue ;
}
//send ai frame to ao
ret = kd_mpi_ao_send_frame(0, 1, &audio_frame, 0);
if (K_SUCCESS != ret)
{
printf("=======kd_mpi_ao_send_frame failed\n");
}
//release ai frame
kd_mpi_ai_release_frame(0, 0, &audio_frame);
}
```

### audio encoding

Audio encoding mainly implements functions such as creating encoding channels, sending audio frame encoding, and obtaining encoding streams. The audio encoding part provides g711a/u and opus encoding, which currently only supports 16-bit sampling accuracy.

This function module provides the following APIs:

- [kd_mpi_aenc_register_encoder](#kd_mpi_aenc_register_encoder): Register encoder.
- [kd_mpi_aenc_unregister_encoder](#kd_mpi_aenc_unregister_encoder): Unregister the encoder.
- [kd_mpi_aenc_create_chn](#kd_mpi_aenc_create_chn): Create encoding channel
- [kd_mpi_aenc_destroy_chn](#kd_mpi_aenc_destroy_chn): Destroy encoding channel
- [kd_mpi_aenc_send_frame](#kd_mpi_aenc_send_frame): Send audio encoded audio frame
- [kd_mpi_aenc_get_stream](#kd_mpi_aenc_get_stream): Get the audio encoding stream
- [kd_mpi_aenc_release_stream](#kd_mpi_aenc_release_stream): Release the audio encoding stream

#### kd_mpi_aenc_register_encoder

- 【describe】

Register the encoder.

- 【grammar】

k_s32 kd_mpi_aenc_register_encoder(k_s32 \*handle, const [k_aenc_encoder](#k_aenc_encoder) \*encoder);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------|---------------|
| handle | Register handle. | Output |
| encoder | Encoder attribute structure. | Input |

- 【illustrate】

The user registers an encoder with the AENC module by passing in the encoder attribute structure and returns the registration sentence

handle, the user can finally unregister the encoder by registering the handle.

The AENC module can register up to 20 encoders, and it has registered G711.a, G711.u, and opus encoders.

The same encoding protocol does not allow repeated registration of encoders. For example, if a G711 encoder has been registered, another one is not allowed.

Register another G711 encoder

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

#### kd_mpi_aenc_unregister_encoder

- 【describe】

Log out of the encoder.

- 【grammar】

k_s32 kd_mpi_aenc_unregister_encoder(k_s32 handle);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|-------------|---------------|
| handle | Unregister handle. | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

#### kd_mpi_aenc_create_chn

- 【describe】

Create an audio encoding channel.

- 【grammar】

k_s32 kd_mpi_aenc_create_chn([k_aenc_chn](#k_aenc_chn) aenc_chn, const [k_aenc_chn_attr](#k_aenc_chn_attr) \*attr);

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------------------------------------------------|---------------|
| aenc_chn | Channel number. Value range: [0, [AENC_MAX_CHN_NUM](#aenc_max_chn_nums)). | Input |
| attr | Audio encoding channel attribute pointer. | Input |

- 【illustrate】

The buffer size is in frames, and the value range is [2, [K_MAX_AUDIO_FRAME_NUM](#k_max_audio_frame_num). It is recommended to configure it to be more than 10. A buffer configuration that is too small may cause frame loss and other abnormalities. Each encoding channel configures the queue size according to the buffer size to cache encoding frame data.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

#### kd_mpi_aenc_destroy_chn

- 【describe】

Destroy the audio encoding channel.

- 【grammar】

k_s32 kd_mpi_aenc_destroy_chn([k_aenc_chn](#k_aenc_chn) aenc_chn);

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------------------------------------------------|---------------|
| aenc_chn | Channel number. Value range: [0, [AENC_MAX_CHN_NUM](#aenc_max_chn_nums)). | Input |

- 【illustrate】

None

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

#### kd_mpi_aenc_send_frame

- 【describe】

Send audio encoded frames.

- 【grammar】

k_s32 kd_mpi_aenc_send_frame([k_aenc_chn](#k_aenc_chn) aenc_chn,const [k_audio_frame](#k_audio_frame) \*frame);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|---------------------------------------------------|---------------|
| aenc_chn | Channel number.  Value range: [0, AENC_MAX_CHN_NUM).  enter | Input |
| frame | Audio frame structure pointer. | Input |

- 【illustrate】

The audio encoding and sending code stream is a non-blocking interface. If the audio code stream cache is full, failure will be returned directly. This interface is used by users to actively send audio frames for encoding. If the AENC channel has been bound to AI through the system binding interface, it is not necessary or recommended to adjust this interface. When calling this interface to send audio encoding audio frames, the corresponding encoding channel must be created first.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

#### kd_mpi_aenc_get_stream

- 【describe】

Get the audio encoding stream.

- 【grammar】

k_s32 kd_mpi_aenc_get_stream([k_aenc_chn](#k_aenc_chn) aenc_chn, [k_audio_stream](#k_audio_stream) \*stream, k_s32 milli_sec);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| aenc_chn | Channel number.  Value range: [0, AENC_MAX_CHN_NUM). | Input |
| stream | Obtained audio code stream. | Output |
| milli_sec | The timeout time for obtaining data -1 indicates blocking mode and waits when there is no data; 0 indicates non-blocking mode and returns an error when there is no data; \>0 indicates blocking s32MilliSec milliseconds and returns an error when timeout occurs. | Input |

- 【illustrate】

The channel must be created before the code stream can be obtained. Otherwise, failure will be returned directly. If the code stream is

If the channel is destroyed, failure will be returned immediately.

The value of s32MilliSec must be greater than or equal to -1. When it is equal to -1, blocking mode is used to obtain data. When it is equal to 0, data is obtained.

Use non-blocking mode to obtain data. When it is greater than 0, block s32MilliSec for milliseconds. If there is no data, a timeout will be returned.

and an error is reported.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

#### kd_mpi_aenc_release_stream

- 【describe】

Release the audio encoding stream.

- 【grammar】

k_s32 kd_mpi_aenc_release_stream([k_aenc_chn](#k_aenc_chn) aenc_chn, const [k_audio_stream](#k_audio_stream) \*stream);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|----------------------------------------------|---------------|
| aenc_chn | Channel number.  Value range: [0, AENC_MAX_CHN_NUM). | Input |
| stream | Obtained audio code stream. | Output |

- 【illustrate】

None

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

- Header File: mpi_aenc_api.h
- Library File: libaenc.a

### audio decoding

Audio decoding mainly implements functions such as decoding channels, sending audio stream decoding, and obtaining decoded audio frames.

The audio codec part provides g711a/u and opus decoding, and temporarily supports 16bit sampling accuracy.

This function module provides the following APIs:

- [kd_mpi_adec_register_decoder](#kd_mpi_adec_register_decoder): Register decoder
- [kd_mpi_adec_unregister_decoder](#kd_mpi_adec_unregister_decoder): Unregister decoder
- [kd_mpi_adec_create_chn](#kd_mpi_adec_create_chn): Create audio decoding channel
- [kd_mpi_adec_destroy_chn](#kd_mpi_adec_destroy_chn): Destroy audio decoding channel
- [kd_mpi_adec_send_stream](#kd_mpi_adec_send_stream): Send the audio code stream to the audio decoding channel
- [kd_mpi_adec_clr_chn_buf](#kd_mpi_adec_clr_chn_buf): Clear the current audio data cache in the ADEC channel.
- [kd_mpi_adec_get_frame](#kd_mpi_adec_get_frame): Get audio decoding frame data
- [kd_mpi_adec_release_frame](#kd_mpi_adec_release_frame): Release audio decoding frame data

#### kd_mpi_adec_register_decoder

- 【describe】

Register decoder.

- 【grammar】

k_s32 kd_mpi_adec_register_decoder(k_s32 \*handle, const [k_adec_decoder](#k_adec_decoder) \*decoder);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------|---------------|
| handle | Register handle. | Output |
| decoder | Decoder attribute structure. | Input |

- 【illustrate】

The user registers a decoder with the ADEC module by passing in the decoder attribute structure and returns the registration handle. The user can finally unregister the decoder through the registration handle. The ADEC module can register up to 20 decoders, and has already registered G711a, G711u, and opus decoders. The same decoding protocol does not allow repeated registration of decoders. For example, if a G711 decoder has been registered, registration of another G711 decoder is not allowed.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

Header File: mpi_adec_api.h

Library File: libadec.a

#### kd_mpi_adec_unregister_decoder

- 【describe】

Unregister the decoder.

- 【grammar】

k_s32 kd_mpi_adec_unregister_decoder(k_s32 handle);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|-------------|---------------|
| handle | Unregister handle. | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】
- Header File: mpi_adec_api.h
- Library File: libadec.a

#### kd_mpi_adec_create_chn

- 【describe】

Create an audio decoding channel.

- 【grammar】

k_s32 kd_mpi_adec_create_chn([k_adec_chn](#k_adec_chn) adec_chn, const [k_adec_chn_attr](#k_adec_chn_attr) \*attr);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|---------------------------------------------------------------------|---------------|
| adec_chn | Channel number.  Value range: [0, [ADEC_MAX_CHN_NUM](#adec_max_chn_nums)). | Input |
| attr | Channel attribute pointer. | Input |

- 【illustrate】

The protocol type specifies the decoding protocol of the channel, which currently supports G711 and opus. Some properties of audio decoding need to match the output device properties, such as sampling rate, frame length (number of sample points per frame), etc. The buffer size is in frames, and the value range is [2, [K_MAX_AUDIO_FRAME_NUM](#k_max_audio_frame_num). It is recommended to configure it to more than 10. A buffer configuration that is too small may cause frame loss and other abnormalities. This interface can only be used before the channel is created (or after it is destroyed). If the channel has been created, it returns that the channel has been created.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

Requirements

Header File: mpi_adec_api.h

Library File: libadec.a

#### kd_mpi_adec_destroy_chn

- 【describe】

Destroy the audio decoding channel.

- 【grammar】

k_s32 kd_mpi_adec_destroy_chn([k_adec_chn](#k_adec_chn) adec_chn);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------------------------------------------------|---------------|
| adec_chn | Channel number. Value range: [0, [ADEC_MAX_CHN_NUM](#adec_max_chn_nums)). | Input |

- 【illustrate】

None

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】
- Header File: mpi_adec_api.h
- Library File: libadec.a

#### kd_mpi_adec_send_stream

- 【describe】

Send the audio code stream to the audio decoding channel.

- 【grammar】

k_s32 kd_mpi_adec_send_stream(k_adec_chn adec_chn,const k_audio_stream \*stream,k_bool block);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------------------------------|---------------|
| adec_chn | Channel number.  Value range: [0, [ADEC_MAX_CHN_NUM](#adec_max_chn_nums)). | Input |
| stream | Audio stream. | Input |
| block | Blocking flag.  HI_TRUE: blocking.  HI_FALSE: non-blocking. | Input |

- 【illustrate】

When sending data, you must ensure that the channel has been created, otherwise failure will be returned directly. If the channel is destroyed during the data sending process, failure will be returned immediately. Supports blocking or non-blocking mode for sending code stream. When the code stream is sent in blocking mode, if the Buffer used to cache the decoded audio frame is full, this interface call will be blocked until the decoded audio frame data is removed or the ADEC channel is destroyed.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: mpi_adec_api.h

Library File: libadec.a

#### kd_mpi_adec_clr_chn_buf

- 【describe】

Clear the current audio data cache in the ADEC channel.

- 【grammar】

k_s32 kd_mpi_adec_clr_chn_buf([k_adec_chn](#k_adec_chn) adec_chn);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------------------------------------------------|---------------|
| adec_chn | Channel number. Value range: [0, [ADEC_MAX_CHN_NUM](#adec_max_chn_nums)). | Input |

- 【illustrate】

It is required that the decoding channel has been created. If the channel has not been created, an error code that does not exist in the channel will be returned.

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: mpi_adec_api.h

Library File: libadec.a

#### kd_mpi_adec_get_frame

- 【describe】

Get the audio decoding frame data.

- 【grammar】

k_s32 kd_mpi_adec_get_frame([k_adec_chn](#k_adec_chn) adec_chn, [k_audio_frame](#k_audio_frame) \*frame, k_s32 milli_sec);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------|---------------|
| adec_chn | Audio decoding channel. | Input |
| frame_info | Audio frame data structure output | Output |
| block | Whether to obtain in blocking mode | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: mpi_adec_api.h

Library File: libadec.a

#### kd_mpi_adec_release_frame

- 【describe】

Release the acquired audio decoding frame data.

- 【grammar】

k_s32 kd_mpi_adec_release_frame([k_adec_chn](#k_aenc_chn) adec_chn, const [k_audio_frame](#k_audio_frame) \*frame);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
|--------------|--------------------------|---------------|
| adec_chn | Audio decoding channel. | Input |
| frame_info | Audio frame data structure output | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: mpi_adec_api.h

Library File: libadec.a

### Built-in Audio Codec

The built-in Audio Codec mainly provides operations on hardware devices through ioctl. In the cmd of the provided ioctl, some

cmd users do not need to call it and can directly use the default value when the module is loaded. The ioctl call implements reading and writing of the built-in Audio Codec register.

The current version's control operations for audio codec mainly include: adc digital and analog volume, dac digital/analog volume, and adc/dac mute control. Among them, the control operations of sampling rate, sampling accuracy, i2s alignment mode are automatically completed by the user by calling the api interface kernel of ai and ao (the kernel code automatically implements the operation of the codec hardware device), and no ioctl interface is provided for control.

Built-in Audio Codec standard function cmd:

- [k_acodec_set_gain_micl](#k_acodec_set_gain_micl): Left channel input analog gain control
- [k_acodec_set_gain_micr](#k_acodec_set_gain_micr): Right channel input analog gain control
- [k_acodec_set_adcl_volume](#k_acodec_set_adcl_volume): Left channel input digital volume control
- [k_acodec_set_adcr_volume](#k_acodec_set_adcr_volume): Right channel input digital volume control
- [k_acodec_set_alc_gain_micl](#k_acodec_set_alc_gain_micl): Analog gain control of alc left channel input
- [k_acodec_set_alc_gain_micr](#k_acodec_set_alc_gain_micr): Analog gain control of alc right channel input
- [k_acodec_set_gain_hpoutl](#k_acodec_set_gain_hpoutl): Left channel output analog volume control
- [k_acodec_set_gain_hpoutr](#k_acodec_set_gain_hpoutr): Right channel output analog volume control
- [k_acodec_set_dacl_volume](#k_acodec_set_dacl_volume): Left channel output digital volume control
- [k_acodec_set_dacr_volume](#k_acodec_set_dacr_volume): Right channel output digital volume control
- [k_acodec_set_micl_mute](#k_acodec_set_micl_mute): Left channel input mute control
- [k_acodec_set_micr_mute](#k_acodec_set_micr_mute): Right channel input mute control
- [k_acodec_set_dacl_mute](#k_acodec_set_dacl_mute): Left channel output mute control
- [k_acodec_set_dacr_mute](#k_acodec_set_dacr_mute): Right channel output mute control
- [k_acodec_get_gain_micl](#k_acodec_get_gain_micl): Get the left channel input analog gain value
- [k_acodec_get_gain_micr](#k_acodec_get_gain_micr): Get the right channel input analog gain value
- [k_acodec_get_adcl_volume](#k_acodec_get_adcl_volume): Get the left channel input digital volume value
- [k_acodec_get_adcr_volume](#k_acodec_get_adcr_volume): Get the right channel input digital volume value
- [k_acodec_get_alc_gain_micl](#k_acodec_get_alc_gain_micl): Get the analog gain value of the alc left channel input
- [k_acodec_get_alc_gain_micr](#k_acodec_get_alc_gain_micr): Get the analog gain value of alc right channel input
- [k_acodec_get_gain_hpoutl](#k_acodec_get_gain_hpoutl): Get the left channel output analog volume value
- [k_acodec_get_gain_hpoutr](#k_acodec_get_gain_hpoutr): Get the right channel output analog volume value
- [k_acodec_get_dacl_volume](#k_acodec_get_dacl_volume): Get the left channel output digital volume value
- [k_acodec_get_dacr_volume](#k_acodec_get_dacr_volume): Get the right channel output digital volume value
- [k_acodec_reset](#k_acodec_reset): Volume reset

#### k_acodec_set_gain_micl

- 【describe】

Left channel input analog gain control

- 【grammar】

int ioctl (int fd, k_acodec_set_gain_micl, k_u32 \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_gain_micl | ioctl number | Input |
| arg | unsigned integer pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range is 0db, 6db, 20db, 30db.

#### k_acodec_set_gain_micr

- 【describe】

Right channel input analog gain control

- 【grammar】

int ioctl (int fd, k_acodec_set_gain_micr, k_u32 \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_gain_micr | ioctl number | Input |
| arg | unsigned integer pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range is 0db, 6db, 20db, 30db.

#### k_acodec_set_adcl_volume

- 【describe】

Left channel input digital gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_adcl_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_adcl_volume | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-97,30]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_set_adcr_volume

- 【describe】

Right channel input digital gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_adcr_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_adcr_volume | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-97,30]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_set_alc_gain_micl

- 【describe】

Left channel alc input analog gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_alc_gain_micl, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| -------------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_alc_gain_micl | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-18,28.5]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_set_alc_gain_micr

- 【describe】

Right channel alc input analog gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_alc_gain_micr, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| -------------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_alc_gain_micr | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-18,28.5]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_set_gain_hpoutl

- 【describe】

Left channel output analog gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_gain_hpoutl, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_gain_hpoutl | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-39,6]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_set_gain_hpoutr

- 【describe】

Right channel output analog gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_gain_hpoutr, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_gain_hpoutr | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-39,6]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_set_dacl_volume

- 【describe】

Left channel output digital gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_dacl_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_dacl_volume | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-120,7]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_set_dacr_volume

- 【describe】

Right channel output digital gain control.

- 【grammar】

int ioctl (int fd, k_acodec_set_dacr_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_dacr_volume | ioctl number | Input |
| arg | signed floating point pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-120,7]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_set_micl_mute

- 【describe】

Left channel input mute control.

- 【grammar】

int ioctl (int fd, k_acodec_set_micl_mute, k_bool \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_micl_mute | ioctl number | Input |
| arg | bool pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Value range: K_TRUE to mute, K_FALSE to cancel mute.

#### k_acodec_set_micr_mute

- 【describe】

Right channel input mute control.

- 【grammar】

int ioctl (int fd, k_acodec_set_micr_mute, k_bool \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_micr_mute | ioctl number | Input |
| arg | bool pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Value range: K_TRUE to mute, K_FALSE to cancel mute.

#### k_acodec_set_dacl_mute

- 【describe】

Left channel output mute control.

- 【grammar】

int ioctl (int fd, k_acodec_set_dacl_mute, k_bool \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_dacl_mute | ioctl number | Input |
| arg | bool pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Value range: K_TRUE to mute, K_FALSE to cancel mute.

#### k_acodec_set_dacr_mute

- 【describe】

Right channel output mute control.

- 【grammar】

int ioctl (int fd, k_acodec_set_dacr_mute, k_bool \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_set_dacr_mute | ioctl number | Input |
| arg | bool pointer | Input |

- 【return value】

| Return Value | Description |
|--------|----------------------|
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Value range: K_TRUE to mute, K_FALSE to cancel mute.

#### k_acodec_get_gain_micl

- 【describe】

Get the left channel input analog gain value.

- 【grammar】

int ioctl (int fd, k_acodec_get_gain_micl, k_u32 \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_gain_micl | ioctl number | Input |
| arg | unsigned integer pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The obtained analog gain range is 0db, 6db, 20db, 30db.

#### k_acodec_get_gain_micr

- 【describe】

Get the right channel input analog gain value.

- 【grammar】

int ioctl (int fd, k_acodec_get_gain_micr, k_u32 \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ---------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_gain_micr | ioctl number | Input |
| arg | unsigned integer pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The obtained analog gain range is 0db, 6db, 20db, 30db.

#### k_acodec_get_adcl_volume

- 【describe】

Get the left channel input digital volume value

- 【grammar】

int ioctl (int fd, k_acodec_get_adcl_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_adcl_volume | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-97,30]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_get_adcr_volume

- 【describe】

Get the right channel input digital gain control value.

- 【grammar】

int ioctl (int fd, k_acodec_get_adcr_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_adcr_volume | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-97,30]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_get_alc_gain_micl

- 【describe】

Get the left channel alc input analog gain value.

- 【grammar】

int ioctl (int fd, k_acodec_set_alc_gain_micl, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| -------------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_alc_gain_micl | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-18,28.5]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_get_alc_gain_micr

- 【describe】

Get the right channel alc input analog gain value.

- 【grammar】

int ioctl (int fd, k_acodec_get_alc_gain_micr, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| -------------------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_alc_gain_micr | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-18,28.5]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_get_gain_hpoutl

- 【describe】

Get the left channel output analog gain value.

- 【grammar】

int ioctl (int fd, k_acodec_get_gain_hpoutl, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_gain_hpoutl | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-39,6]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_get_gain_hpoutr

- 【describe】

Gets the right channel output analog gain control.

- 【grammar】

int ioctl (int fd, k_acodec_get_gain_hpoutr, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_gain_hpoutr | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

The analog gain range is `[-39,6]`. The greater the value, the greater the volume, in 1.5db increments.

#### k_acodec_get_dacl_volume

- 【describe】

Get the left channel output digital gain value.

- 【grammar】

int ioctl (int fd, k_acodec_get_dacl_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_dacl_volume | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-120,7]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_get_dacr_volume

- 【describe】

Get the right channel output digital gain value.

- 【grammar】

int ioctl (int fd, k_acodec_get_dacr_volume, float \*arg);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| ------------------------ | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_get_dacr_volume | ioctl number | Input |
| arg | signed floating point pointer | Output |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

Analog gain range `[-120,7]`, the larger the value, the louder the volume, in 0.5db increments.

#### k_acodec_reset

- 【describe】

Volume reset: including adc, dac, alc digital analog gain.

- 【grammar】

int ioctl (int fd, k_acodec_reset, ...);

- 【parameter】

| **Parameter name** | **describe** | **Input/Output** |
| -------------- | ------------------------- | ------------- |
| fd | Audio Codec device file descriptor | Input |
| k_acodec_reset | ioctl number | Input |

- 【return value】

| Return Value | Description |
| ------ | -------------------- |
| 0 | Success |
| non-0 | Failure, please refer to the error code for its value. |

- 【need】

Header File: k_acodec_comm.h

Library File: libacodec.a

- 【Notice】

None

## data type

### Audio input and output

Audio input and output related data types and data structures are defined as follows:

- [k_audio_type](#k_audio_type): Define the audio input and output type.
- [k_audio_dev](#k_audio_dev): Defines the audio device.
- [k_ai_chn](#k_ai_chn): Define ai channel.
- [k_ao_chn](#k_ao_chn): Define ao channel.
- [K_MAX_AUDIO_FRAME_NUM](#k_max_audio_frame_num): Defines the maximum number of audio decoding cache frames.
- [k_audio_bit_width](#k_audio_bit_width): Defines the audio sampling precision.
- [k_audio_snd_mode](#k_audio_snd_mode): Defines the audio channel mode.
- [k_audio_pdm_oversample](#k_audio_pdm_oversample): Define pdm oversampling.
- [k_aio_dev_attr](#k_aio_dev_attr): Defines the audio input and output device attribute structure.
- [k_audio_pdm_attr](#k_audio_pdm_attr): Define pdm audio input properties.
- [k_i2s_work_mode](#k_i2s_work_mode): Define i2s working mode.
- [k_audio_i2s_attr](#k_audio_i2s_attr): Define i2s audio input properties.
- [k_aio_i2s_type](#k_aio_i2s_type): Define i2s docking device type.
- [k_audio_frame](#k_audio_frame): Defines the audio frame structure.
- [k_ai_vqe_enable](#k_ai_vqe_enable): Defines the audio input sound quality enhancement configuration information structure.

#### k_audio_type

Description

Define audio input and output types.

definition

```c
typedef enum {
KD_AUDIO_INPUT_TYPE_I2S = 0,//i2s in
KD_AUDIO_INPUT_TYPE_PDM = 1,//pdm in
KD_AUDIO_OUTPUT_TYPE_I2S = 2,//i2s out
} k_audio_type;
```

Notes

Audio input includes i2s and pdm, and audio output is only i2s.

Related Data Types and Interfaces

None

#### k_audio_dev

Description

Define the audio device.

definition

**typedef k_u32 k_audio_dev;**

Notes

ai module, k_audio_dev takes values ​​0 and 1, where 0 is i2s audio input and 1 is pdm audio input.

In the ao module, the value of k_audio_dev is fixed to 0, which is i2s audio output.

#### k_ai_chn

Description

Define ai audio channel.

definition

**typedef k_u32 k_ai_chn;**

Notes

I2s audio input, there are 2 groups in total, the value range is `[0,1]`.

pdm audio input, there are 4 groups in total, the value range is `[0,3]`.

#### k_ao_chn

Description

Define ao audio channel.

definition

**typedef k_u32 k_ao_chn;**

Notes

I2s audio output, there are 2 groups in total, the value range is `[0,1]`.

#### K_MAX_AUDIO_FRAME_NUM

Description

Defines the maximum number of audio decoding buffer frames.

definition

\#define K_MAX_AUDIO_FRAME_NUM 50

#### k_audio_bit_width

Description

- Defines the audio sampling precision.

definition

```c
typedef enum {
KD_AUDIO_BIT_WIDTH_16 = 0, /* 16bit width */
KD_AUDIO_BIT_WIDTH_24 = 1, /* 24bit width */
KD_AUDIO_BIT_WIDTH_32 = 2, /* 32bit width */
} k_audio_bit_width;
```

Notes

None

Related Data Types and Interfaces

None

#### k_audio_snd_mode

Description

- Define the channel mode.

definition

```c
typedef enum {
KD_AUDIO_SOUND_MODE_MONO = 0, /* mono */
KD_AUDIO_SOUND_MODE_STEREO = 1, /* stereo */
} k_audio_snd_mode;
```

#### k_audio_pdm_oversample

Description

Define pdm oversampling.

definition

```c
typedef enum
{
KD_AUDIO_PDM_INPUT_OVERSAMPLE_32 = 0,
KD_AUDIO_PDM_INPUT_OVERSAMPLE_64 ,
KD_AUDIO_PDM_INPUT_OVERSAMPLE_128 ,
} k_audio_pdm_oversample;
```

#### k_audio_pdm_attr

Description

Define pdm audio input properties.

definition

```c
typedef struct {
k_u32 chn_cnt; /* channle number on FS,i2s valid value:1/2,pdm valid value:1/2/3/4*/
k_audio_sample_rate rate;
k_audio_bit_width width;
k_audio_snd_mode mode;
k_audio_pdm_oversample oversample;
k_u32 frame_num; /* frame num in buf[2,K_MAX_AUDIO_FRAME_NUM] */
k_u32 point_num_per_frame;
} k_audio_pdm_attr;
```

member

| member name | Description |
|---------------------|-----------------------------------------------------|
| chn_cnt | Number of channels supported.  Supports 1-4 channels, and the channels must be enabled continuously. |
| sample_rate | Sampling rate: support 8k\~192k |
| bit_width | Sampling accuracy: support 16/24/32 |
| snd_mode | Audio channel mode. Supports mono and dual channels. |
| pdm_oversample | Oversampling: Supports 32, 64, and 128 times oversampling. |
| frame_num | The number of cached frames is `[2,K_MAX_AUDIO_FRAME_NUM]`. |
| point_num_per_frame | The number of sampling points per frame. |

Notes

None

Related Data Types and Interfaces

None

#### k_audio_i2s_attr

Description

Define i2s audio input properties.

definition

```c
typedef struct
{
k_u32 chn_cnt; /* channle number on FS,i2s valid value:1/2,pdm valid value:1/2/3/4 */
k_u32 sample_rate; /* sample rate 8k ~192k */
k_audio_bit_width bit_width;
k_audio_snd_mode snd_mode; /* momo or stereo */
k_i2s_in_mono_channel  mono_channel;/* use mic input or headphone input */
k_i2s_work_mode   i2s_mode;  /*i2s work mode*/
k_u32 frame_num; /* frame num in buf[2,K_MAX_AUDIO_FRAME_NUM] */
k_u32 point_num_per_frame;
k_aio_i2s_type type;
} k_audio_i2s_attr;
```

member

| member name | Description |
| ------------------- | ---------------------------------------------------- |
| chn_cnt | Number of channels supported.  Supports 1-2 channels. |
| sample_rate | Sampling rate: support 8k~192k |
| bit_width | Sampling accuracy: support 16/24/32 |
| snd_mode | Audio channel mode. Supports mono and dual channels. |
| mono_channel | Mono source selection. 0:mic input, 1:headphone input |
| I2s_mode | I2s working mode: supports Philips mode, left-aligned mode, right-aligned mode. |
| frame_num | The number of cached frames is `[2,K_MAX_AUDIO_FRAME_NUM]`. |
| point_num_per_frame | The number of sampling points in each frame is `[sample_rate/100,sample_rate]`. |
| i2s_type | i2s docking device type: built-in codec or external device. |

Notes

The number of sampling points per frame point_num_per_frame and the value of the sampling rate sample_rate determine the hardware generation

The frequency of interruptions. Too high frequency will affect the performance of the system and interact with other services. It is recommended that these two parameters

The value of the number satisfies the calculation formula: (point_num_per_frame *1000)/ sample_rate >=10 (interrupted 100 times), for example, in sampling

When the frequency is 16000Hz, it is recommended to set the number of sampling points to be greater than or equal to 160.

Related Data Types and Interfaces

None

#### k_i2s_work_mode

Description

Define i2s working mode.

definition

```c
typedef enum
{
K_STANDARD_MODE = 1,
K_RIGHT_JUSTIFYING_MODE = 2,
K_LEFT_JUSTIFYING_MODE = 4
} k_i2s_work_mode;
```

Notes

None

Related Data Types and Interfaces

None

#### k_aio_dev_attr

Description

Define the audio input and output device property structure.

definition

```c
typedef struct {
k_audio_type type;
union
{
k_audio_pdm_attr pdm_attr;
k_audio_i2s_attr i2s_attr;
} kd_audio_attr;
} k_aio_dev_attr;
```

member

| member name | Description |
|---------------|--------------|
| audio_type | Audio type. |
| kd_audio_attr | Audio property settings |

Notes

None

Related Data Types and Interfaces

None

#### k_aio_i2s_type

Description

Define i2s docking device type.

definition

```c
typedef enum
{
K_AIO_I2STYPE_INNERCODEC = 0, /* AIO I2S connect inner audio CODEC */
K_AIO_I2STYPE_EXTERN,/* AIO I2S connect extern hardware */
} k_aio_i2s_type;
```

Notes

The built-in audio codec always uses the 0th group of i2s channels, and the 1st group of i2s channels still uses the external codec.

Related Data Types and Interfaces

None

#### k_audio_frame

Description

Define the audio frame structure.

definition

```c
typedef struct {
k_audio_bit_width bit_width;
k_audio_snd_mode snd_mode;
void* virt_addr;
k_u64 phys_addr;
k_u64 time_stamp; /* audio frame time stamp */
k_u32 seq; /* audio frame seq */
k_u32 len; /* data lenth per channel in frame */
k_u32 pool_id;
} k_audio_frame;
```

member

| member name | Description |
|------------|----------------------------|
| bit_width | Sampling accuracy. |
| snd_mode | Audio channel mode. |
| virt_addr | Audio frame data virtual address. |
| phys_addr | Audio frame data physical address. |
| time_stamp | Audio frame timestamp in μs. |
| seq | Audio frame number. |
| len | Audio frame length, in bytes. |
| pool_id | Audio frame buffer pool ID. |

Notes

None

Related Data Types and Interfaces

None

#### k_ai_vqe_enable

Description

Defines the audio input sound quality enhancement configuration information structure.

definition

typedef struct
{
    k_bool aec_enable;
    k_u32 aec_echo_delay_ms;//The time difference between speaker broadcast time and mic recording (100-500ms)
    k_bool agc_enable;
    k_bool ans_enable;
}k_ai_vqe_enable;

member

| member name | Description |
|----------|----------------------------|
| aec_enable | Echo suppression is enabled. |
| aec_echo_delay_ms | The length of the echo cancellation filter is recommended to be 100-500ms. That is, the time difference between the speaker broadcast time and the mic recording time. The specific size of this parameter needs to be fine-tuned. Failure to adjust it will directly affect the echo cancellation effect. |
| agc_enable | Automatic gain enabled. |
| ans_enable | Audio noise reduction enabled. |

Notes

None

Related Data Types and Interfaces

None

#### k_i2s_in_mono_channel

Description

- Mono source.

definition

```c
typedef enum
{
    KD_I2S_IN_MONO_RIGHT_CHANNEL = 0,  //mic input
    KD_I2S_IN_MONO_LEFT_CHANNEL = 1,   //hp input
} k_i2s_in_mono_channel;
```

### audio codec

Audio codec related data types and data structures are defined as follows:

[k_payload_type](#k_payload_type)

[k_aenc_encoder](#k_aenc_encoder)

[k_aenc_chn_attr](#k_aenc_chn_attr)

[AENC_MAX_CHN_NUMS](#aenc_max_chn_nums)

[K_MAX_ENCODER_NAME_LEN](#k_max_encoder_name_len)

[k_aenc_chn](#k_aenc_chn)

[k_audio_stream](#k_audio_stream)

[k_adec_chn_attr](#k_adec_chn_attr)

[k_adec_decoder](#k_adec_decoder)

[K_MAX_DECODER_NAME_LEN](#k_max_decoder_name_len)

[ADEC_MAX_CHN_NUMS](#adec_max_chn_nums)

#### k_payload_type

Description

Defines the audio and video payload type enumeration.

definition

```c
typedef enum {
K_PT_PCMU = 0,
K_PT_1016 = 1,
K_PT_G721 = 2,
K_PT_GSM = 3,
K_PT_G723 = 4,
K_PT_DVI4_8K = 5,
K_PT_DVI4_16K = 6,
K_PT_LPC = 7,
K_PT_PCMA = 8,
K_PT_G722 = 9,
K_PT_S16BE_STEREO = 10,
K_PT_S16BE_MONO = 11,
K_PT_QCELP = 12,
K_PT_CN = 13,
K_PT_MPEGAUDIO = 14,
K_PT_G728 = 15,
K_PT_DVI4_3 = 16,
K_PT_DVI4_4 = 17,
K_PT_G729 = 18,
K_PT_G711A = 19,
K_PT_G711U = 20,
K_PT_G726 = 21,
K_PT_G729A = 22,
K_PT_LPCM = 23,
K_PT_CelB = 25,
K_PT_JPEG = 26,
K_PT_CUSM = 27,
K_PT_NV = 28,
K_PT_PICW = 29,
K_PT_CPV = 30,
K_PT_H261 = 31,
K_PT_MPEGVIDEO = 32,
K_PT_MPEG2TS = 33,
K_PT_H263 = 34,
K_PT_SPEG = 35,
K_PT_MPEG2VIDEO = 36,
K_PT_AAC = 37,
K_PT_WMA9STD = 38,
K_PT_HEAAC = 39,
K_PT_PCM_VOICE = 40,
K_PT_PCM_AUDIO = 41,
K_PT_MP3 = 43,
K_PT_ADPCMA = 49,
K_PT_AEC = 50,
K_PT_X_LD = 95,
K_PT_H264 = 96,
K_PT_D_GSM_HR = 200,
K_PT_D_GSM_EFR = 201,
K_PT_D_L8 = 202,
K_PT_D_RED = 203,
K_PT_D_VDVI = 204,
K_PT_D_BT656 = 220,
K_PT_D_H263_1998 = 221,
K_PT_D_MP1S = 222,
K_PT_D_MP2P = 223,
K_PT_D_BMPEG = 224,
K_PT_MP4VIDEO = 230,
K_PT_MP4AUDIO = 237,
K_PT_VC1 = 238,
K_PT_JVC_ASF = 255,
K_PT_D_AVI = 256,
K_PT_DIVX3 = 257,
K_PT_AVS = 258,
K_PT_REAL8 = 259,
K_PT_REAL9 = 260,
K_PT_VP6 = 261,
K_PT_VP6F = 262,
K_PT_VP6A = 263,
K_PT_SORENSON = 264,
K_PT_H265 = 265,
K_PT_VP8 = 266,
K_PT_MVC = 267,
K_PT_PNG = 268,
K_PT_AMR = 1001,
K_PT_MJPEG = 1002,
K_PT_AMRWB = 1003,
K_PT_PRORES = 1006,
K_PT_OPUS = 1007,
K_PT_BUTT
} k_payload_type;
```

Notes

None

Related Data Types and Interfaces

None

#### k_aenc_encoder

Description

Define the encoder attribute structure.

definition

```c
typedef struct {
k_payload_type k_u32 max_frame_len;
k_char name[K_MAX_ENCODER_NAME_LEN];
k_s32 (func_open_encoder)(void encoder_attr,void *encoder);
k_s32 (func_enc_frame)(void *encoder,const k_audio_frame *data,k_u8 *outbuf, k_u32 *out_len);
k_s32 (*func_close_encoder)(void *encoder);
} k_aenc_encoder;

```

member

| member name | Description |
|--------------------|-------------------------|
| type | Encoding protocol type. |
| max_frame_len | Maximum code stream length. |
| name | Encoder name. |
| func_open_encoder | Open the encoder's function pointer. |
| func_enc_frame | The function pointer to encode. |
| func_close_encoder | Close the encoder's function pointer. |

Notes

None

Related Data Types and Interfaces

None

#### k_aenc_chn_attr

Description

Define the encoder channel attribute structure.

definition

```c
typedef struct {
k_payload_type type;
k_u32 point_num_per_frame;
k_u32 buf_size; // buf size[2,K_MAX_AUDIO_FRAME_NUM]
} k_aenc_chn_attr;
```

member

| member name | Description |
|---------------------|---------------------------------------------------------------------------------------------------------|
| type | Audio encoding protocol type. |
| point_num_per_frame | The frame length corresponding to the audio encoding protocol (the audio frame length received during encoding is less than or equal to this frame length and can be encoded). |
| buf_size | Audio encoding buffer size.  Value range: `[2, K_MAX_AUDIO_FRAME_NUM]`, in frames. |

Notes

None

Related Data Types and Interfaces

None

#### AENC_MAX_CHN_NUMS

Description

Defines the maximum number of encoding channels.

definition

\#define AENC_MAX_CHN_NUMS 4

Notes

None

Related Data Types and Interfaces

None

#### K_MAX_ENCODER_NAME_LEN

Description

Defines the maximum length of audio encoder names.

definition

\#define K_MAX_ENCODER_NAME_LEN 25

Notes

None

Related Data Types and Interfaces

None

#### k_aenc_chn

Description

Defines the encoding channel type.

definition

typedef k_u32 k_aenc_chn;

Notes

None

Related Data Types and Interfaces

None

#### k_audio_stream

Description

Define the code stream structure.

definition

```c
typedef struct {
void *stream; /* the virtual address of stream */
k_u64 phys_addr; /* the physics address of stream */
k_u32 len; /* stream lenth, by bytes */
k_u64 time_stamp; /* frame time stamp */
k_u32 seq; /* frame seq, if stream is not a valid frame,seq is 0 */
} k_audio_stream;
```

member

| member name | Description |
|------------|------------------------------|
| stream | Audio stream data pointer |
| phys_addr | The physical address of the audio stream. |
| len | Audio stream length. The unit is byte. |
| time_stamp | Audio stream timestamp. |
| seq | Audio stream serial number. |

Notes

None

Related Data Types and Interfaces

None

#### k_adec_chn_attr

Description

Define the decoder channel attribute structure.

definition

```c
typedef struct {
k_payload_type payload_type;
k_u32 point_num_per_frame;
k_u32 buf_size; /* buf size[2~K_MAX_AUDIO_FRAME_NUM] */
} k_adec_chn_attr;
```

member

| member name | Description |
|---------------------|---------------------------------------------------------------------------------------------------------|
| type | Audio decoding protocol type. |
| point_num_per_frame | Frame length corresponding to the audio decoding protocol |
| buf_size | Audio encoding buffer size.  Value range: `[2, K_MAX_AUDIO_FRAME_NUM]`, in frames. |

Notes

Some properties of audio decoding need to match the output device properties, such as sampling rate, frame length (samples per frame

number of points) etc.

Related Data Types and Interfaces

None

#### k_adec_decoder

Description

Define the decoder attribute structure.

definition

```c
typedef struct {
k_payload_type payload_type;
k_char name[K_MAX_DECODER_NAME_LEN];
k_s32 (func_open_decoder)(void *decoder_attr, void **decoder);
k_s32 (*func_dec_frame)(void *decoder, k_u8 **inbuf, k_s32 *left_byte, k_u16*outbuf, k_u32 *out_len, k_u32 *chns);
k_s32 (*func_get_frame_info)(void *decoder, void *info);
k_s32 (*func_close_decoder)(void *decoder);
k_s32 (*func_reset_decoder)(void *decoder);
} k_adec_decoder;
```

member

| member name | Description |
|---------------------|-----------------------------------------|
| type | Decoding protocol type. |
| name | Decoder name. |
| func_open_decoder | Open the function pointer of the decoder. |
| func_get_frame_info | Function pointer to obtain audio frame information. |
| func_close_decoder | Function pointer to close the decoder. |
| func_reset_decoder | Clear the cache buffer and reset the decoder's function pointer. |

Notes

None

Related Data Types and Interfaces

None

#### K_MAX_DECODER_NAME_LEN

Description

Defines the maximum length of audio codec names.

definition

\#define K_MAX_DECODER_NAME_LEN 25

Notes

None

Related Data Types and Interfaces

None

#### ADEC_MAX_CHN_NUMS

Description

Defines the maximum number of decoding channels.

definition

\#define ADEC_MAX_CHN_NUMS 4

Notes

None

Related Data Types and Interfaces

None

#### k_adec_chn

Description

Define decoding channel type.

definition

typedef k_u32 k_adec_chn;

Notes

None

Related Data Types and Interfaces

None

## error code

### Audio input API error code

| error code | Macro definition | Description |
|----------|------------------------|-----------------------------|
| 0xA0158001 | K_ERR_AI_INVALID_DEVID | Invalid audio input device number |
| 0xA0158002 | K_ERR_AI_INVALID_CHNID | The audio input channel number is invalid |
| 0xA0158003 | K_ERR_AI_ILLEGAL_PARAM | Audio input parameter setting is invalid |
| 0xA0158004 | K_ERR_AI_NOT_ENABLED | Audio input device or channel is not enabled |
| 0xA0158005 | K_ERR_AI_NULL_PTR | Input parameter null pointer error |
| 0xA0158006 | K_ERR_AI_NOT_CFG | Audio input device properties not set |
| 0xA0158007 | K_ERR_AI_NOT_SUPPORT | Operation not supported |
| 0xA0158008 | K_ERR_AI_NOT_PERM | Operation not allowed |
| 0xA0158009 | K_ERR_AI_NO_MEM | Failed to allocate memory |
| 0xA015800A | K_ERR_AI_NO_BUF | Insufficient audio input buffering |
| 0xA015800B | K_ERR_AI_BUF_EMPTY | Audio input buffer is empty |
| 0xA015800C | K_ERR_AI_BUF_FULL | Audio input buffer is full |
| 0xA015800D | K_ERR_AI_NOT_READY | Audio input system not initialized |
| 0xA015800E | K_ERR_AI_BUSY | Audio input system busy |