Audio 开发指导_Rev1.1

1 修订记录

版本	日期	作者	审核	修订内容
Rev1.0	2026-01-29	sxx	zlc	创建文档

2 简介

本文档介绍 LTE-EC71X Audio 接口 API 情况，API 接口位于 liot_audio2.h 文件声明。

Audio 接口是集成 I2S 数据传输类的 Codec 设备音频接口的封装。目前适配了 ES8311、TM8211、ES8374、ES8375 硬件驱动。

2.1 Audio 音频控制逻辑

在接收到音频初始化时首先会匹配 Codec 类型并进行 Codec 硬件初始化，如 ES8311 先通过 I2C 配置相关寄存器，然后初始化 I2S 总线，再创建音频播放队列。音频播放属于异步播放，在调用 Liot_AudioPlay() 后会创建备份到音频播放队列中进行播放，理论上队列长度无上限，由系统申请内存上限决定。

MP3 和 PCM 播放则先对数据源进行解码然后放到音频播放队列中。

2.2 I2S 播放原理介绍

I2S（Inter-IC Sound）是音频专用的串行数字通信总线，专门用来在芯片之间传输数字音频数据。

MCLK：主时钟（系统音频时钟，常用 256× 采样率）
BCLK (SCK)：位时钟，每跳变一次传输 1bit
LRCK (WS)：声道时钟。低电平 = 左声道；高电平 = 右声道
SDIN/SDOUT：音频数据串行线

工作逻辑:

以采样率（如 44.1K、48KHz）为基础，WS 每秒切换对应次数声道；
在每个 WS 周期内，BCLK 逐位移位输出 16/24/32 位的音频采样数据；
发送端按时钟串行发数据，接收端同步采样解析，分离左右声道，还原数字音频；
只传纯音频数据流，命令、配置用另外的 I2C/SPI 控制。

3 API 函数概览

函数	说明
`Liot_AudioInit`	音频初始化接口
`Liot_AudioDeInit`	音频去初始化接口
`Liot_AudioSetVolume`	设置软件音量
`Liot_AudioGetVolume`	获取软件音量
`Liot_AudioSetCodecVolume`	设置 Codec 硬件音量
`Liot_AudioGetCodecVolume`	获取 Codec 硬件音量
`Liot_AudioSetMicVolume`	设置麦克风音量
`Liot_AudioSetVolMode`	设置音量步进模式
`Liot_AudioPlay`	播放 PCM 音频数据
`Liot_AudioRecord`	录制音频
`Liot_AudioPlayPause`	播放暂停
`Liot_AudioPlayResume`	播放恢复
`Liot_AudioPlayFile`	播放音频文件（PCM）
`Liot_AudioWaitPlayFinish`	等待播放完成
`Liot_AudioStop`	停止播放
`Liot_AudioPlayMp3File`	播放 MP3 文件
`Liot_AudioPlayMp3`	播放内存中的 MP3 数据
`Liot_AudioPlayWavFile`	播放 WAV 文件
`Liot_AudioPlayWav`	播放内存中的 WAV 数据
`Liot_AudioMp3StreamStart`	启动 MP3 流式播放会话
`Liot_AudioMp3StreamPlay`	向流式解码器送入 MP3 数据
`Liot_AudioMp3StreamStop`	停止 MP3 流式播放

4 类型说明

4.1 Liot_AudErr_e

枚举定义：

typedef enum {
    L_AUD_ERR_SUCCESS  = 0,
    L_AUD_ERR_EXECUTE,
    L_AUD_ERR_INVALID_PARAM,
    L_AUD_ERR_OPEN,
    L_AUD_ERR_CONFIG,
    L_AUD_ERR_PULL_SET,
    L_AUD_ERR_CALLBACK,
    L_AUD_ERR_LEVEL_TRIGGER,
    L_AUD_ERR_NOMEM,
    L_AUD_ERR_FILE,
} Liot_AudErr_e;

枚举说明

变量	说明
L_AUD_ERR_SUCCESS	执行成功
L_AUD_ERR_EXECUTE	通用异常错误
L_AUD_ERR_INVALID_PARAM	输入参数无效
L_AUD_ERR_OPEN	打开失败
L_AUD_ERR_CONFIG	配置接口失败
L_AUD_ERR_PULL_SET	设置上拉失败
L_AUD_ERR_NOMEM	内存不足
L_AUD_ERR_FILE	文件操作失败

4.2 Liot_AudDevice_e

枚举定义：

typedef enum {
    L_AUD_DEV_NONE,
    L_AUD_TM8211,
    L_AUD_ES8311,
    L_AUD_ES8374,
    L_AUD_ES8375,
    L_AUD_DEV_MAX,
} Liot_AudDevice_e;

枚举说明

变量	说明
L_AUD_DEV_NONE	无音频设备
L_AUD_TM8211	TM8211
L_AUD_ES8311	ES8311
L_AUD_ES8374	ES8374
L_AUD_ES8375	ES8375
L_AUD_DEV_MAX	音频设备枚举最大值

4.3 Liot_AudSample_e

采样率。

枚举定义：

typedef enum
{
    L_AUD_08K_SAMPLES,
    L_AUD_16K_SAMPLES,
    L_AUD_22K_SAMPLES,
    L_AUD_24K_SAMPLES,
    L_AUD_32K_SAMPLES,
    L_AUD_44K_SAMPLES,
    L_AUD_48K_SAMPLES,
    L_AUD_96K_SAMPLES,
} Liot_AudSample_e;

枚举说明

变量	说明
L_AUD_08K_SAMPLES	8KHz 采样率
L_AUD_16K_SAMPLES	16KHz 采样率
L_AUD_22K_SAMPLES	22.05KHz 采样率
L_AUD_24K_SAMPLES	24KHz 采样率
L_AUD_32K_SAMPLES	32KHz 采样率
L_AUD_44K_SAMPLES	44.1KHz 采样率
L_AUD_48K_SAMPLES	48KHz 采样率
L_AUD_96K_SAMPLES	96KHz 采样率

4.4 Liot_AudFrameSize_e

数据帧格式。

枚举定义：

typedef enum
{
    L_AUD_FRAMESIZE_16_16 = 0,
    L_AUD_FRAMESIZE_16_32 = 1,
    L_AUD_FRAMESIZE_24_32 = 2,
    L_AUD_FRAMESIZE_32_32 = 3,
} Liot_AudFrameSize_e;

枚举说明

变量	说明
L_AUD_FRAMESIZE_16_16	16_16 帧格式，位宽 16，每帧 16bit
L_AUD_FRAMESIZE_16_32	16_32 帧格式，位宽 32，每帧 16bit
L_AUD_FRAMESIZE_24_32	24_32 帧格式，位宽 32，每帧 24bit
L_AUD_FRAMESIZE_32_32	32_32 帧格式，位宽 32，每帧 32bit

4.5 Liot_AudMode_e

音频数据格式。

枚举定义：

typedef enum
{
    L_AUD_MODE_MSB,
    L_AUD_MODE_LSB,
    L_AUD_MODE_I2S,
    L_AUD_MODE_PCM,
} Liot_AudMode_e;

枚举说明

变量	说明
L_AUD_MODE_MSB	音频数据左对齐
L_AUD_MODE_LSB	音频数据右对齐
L_AUD_MODE_I2S	I2S 数据流格式
L_AUD_MODE_PCM	PCM 数据流格式

4.6 Liot_AudRole_e

Codec 主从模式。

枚举定义：

typedef enum
{
    L_AUD_ROLE_MASTER,
    L_AUD_ROLE_SLAVE,
} Liot_AudRole_e;

枚举说明

变量	说明
L_AUD_ROLE_MASTER	Codec 作为主机模式
L_AUD_ROLE_SLAVE	Codec 作为从机模式

4.7 Liot_AudChannel_e

音频声道。

枚举定义：

typedef enum
{
    L_AUD_DUAL = 1,
    L_AUD_MONO_LEFT,
    L_AUD_MONO_RIGHT,
} Liot_AudChannel_e;

枚举说明

变量	说明
L_AUD_DUAL	双声道音频
L_AUD_MONO_LEFT	单声道左
L_AUD_MONO_RIGHT	单声道右

4.8 Liot_AudState_e

音频状态。

枚举定义：

typedef enum
{
    L_AUD_STA_DEINIT,
    L_AUD_STA_IDLE,
    L_AUD_STA_PLAYING,
    L_AUD_STA_PAUSE,
    L_AUD_STA_RESUME,
    L_AUD_STA_STOP,
} Liot_AudState_e;

枚举说明

变量	说明
L_AUD_STA_DEINIT	音频未初始化状态
L_AUD_STA_IDLE	音频空闲状态
L_AUD_STA_PLAYING	音频播放中状态
L_AUD_STA_PAUSE	音频暂停状态
L_AUD_STA_RESUME	音频恢复状态
L_AUD_STA_STOP	音频停止状态

4.9 Liot_AudEvent_e

音频播放事件（回调使用）。

枚举定义：

typedef enum {
    L_AUD_EVT_ERROR   = -1,
    L_AUD_EVT_START   = 0,
    L_AUD_EVT_PAUSE   = 1,
    L_AUD_EVT_FINISH  = 2,
    L_AUD_EVT_CLOSE   = 3,
    L_AUD_EVT_RESUME  = 4,
} Liot_AudEvent_e;

枚举说明

变量	说明
L_AUD_EVT_ERROR	播放异常
L_AUD_EVT_START	播放开始
L_AUD_EVT_PAUSE	播放暂停
L_AUD_EVT_FINISH	播放完成
L_AUD_EVT_CLOSE	播放通道关闭
L_AUD_EVT_RESUME	播放恢复

4.10 Liot_AudVolStep_e

音量步进模式。

枚举定义：

typedef enum {
    L_AUD_VOL_STEP_0_1 = 0,
    L_AUD_VOL_STEP_0_01,
} Liot_AudVolStep_e;

枚举说明

变量	说明
L_AUD_VOL_STEP_0_1	音量步进 0.1
L_AUD_VOL_STEP_0_01	音量步进 0.01

4.11 Liot_AudHwConfig_t

硬件配置结构体。

结构体定义：

typedef struct
{
    int8_t i2cNum;
    int8_t i2sNum;
    int8_t paGpioNum;
    Liot_AudDevice_e codecType;
    Liot_AudChannel_e channel;
    Liot_AudRole_e role;
    Liot_AudMode_e mode;
    Liot_AudFrameSize_e frameSize;
    Liot_AudSample_e samples;
    Liot_AudCb_t callback;
    void *cbContext;
} Liot_AudHwConfig_t;

结构体变量说明

变量	说明
i2cNum	音频通信使用 I2C 号
i2sNum	音频通信使用 I2S 号
paGpioNum	PA 控制引脚的 GPIO 号
codecType	音频 Codec 类型
channel	音频声道通道
role	Codec 角色
mode	数据流格式
frameSize	数据帧格式
samples	采样率
callback	音频事件回调（可为 NULL）
cbContext	回调用户上下文

5 API 函数详解

5.1 Liot_AudioInit

音频初始化。

声明

Liot_AudErr_e Liot_AudioInit(Liot_AudHwConfig_t *config);

参数

config： [In] 音频格式配置。

返回值

错误码，见 Liot_AudErr_e。

5.2 Liot_AudioDeInit

音频去初始化。

声明

Liot_AudErr_e Liot_AudioDeInit(void);

参数

无。

返回值

错误码，见 Liot_AudErr_e。

5.3 Liot_AudioSetVolume

设置软件音量（0-100）。

声明

Liot_AudErr_e Liot_AudioSetVolume(int Volume);

参数

Volume： [In] 音量值（0-100）。

返回值

错误码，见 Liot_AudErr_e。

5.4 Liot_AudioGetVolume

获取当前软件音量。

声明

Liot_AudErr_e Liot_AudioGetVolume(int *Volume);

参数

Volume： [Out] 音量值。

返回值

错误码，见 Liot_AudErr_e。

5.5 Liot_AudioSetCodecVolume

设置 Codec 硬件音量寄存器。

声明

Liot_AudErr_e Liot_AudioSetCodecVolume(int Volume);

参数

Volume： [In] 音量值（范围依 Codec 而定）。

返回值

错误码，见 Liot_AudErr_e。

5.6 Liot_AudioGetCodecVolume

获取 Codec 硬件音量寄存器值。

声明

Liot_AudErr_e Liot_AudioGetCodecVolume(int *Volume);

参数

Volume： [Out] 音量值。

返回值

错误码，见 Liot_AudErr_e。

5.7 Liot_AudioSetMicVolume

设置麦克风音量值。

声明

Liot_AudErr_e Liot_AudioSetMicVolume(uint8_t micGain, int micVolume);

参数

micGain： [In] 麦克风增益。
micVolume： [In] 麦克风音量值。

返回值

错误码，见 Liot_AudErr_e。

5.8 Liot_AudioSetVolMode

设置音量步进模式。

声明

Liot_AudErr_e Liot_AudioSetVolMode(Liot_AudVolStep_e mode);

参数

mode： [In] 步进模式，见 Liot_AudVolStep_e。

返回值

错误码，见 Liot_AudErr_e。

5.9 Liot_AudioPlay

播放 PCM 音频数据（异步）。

声明

Liot_AudErr_e Liot_AudioPlay(uint8_t* data, int datalen);

参数

data： [In] 播放的数据。
datalen： [In] 数据长度（字节）。

返回值

错误码，见 Liot_AudErr_e。

5.10 Liot_AudioRecord

录音（阻塞，直到 datalen 字节录满）。

声明

Liot_AudErr_e Liot_AudioRecord(uint8_t* data, int datalen);

参数

data： [Out] 录音缓冲区。
datalen： [In] 缓冲区长度（字节）。

返回值

错误码，见 Liot_AudErr_e。

5.11 Liot_AudioPlayPause

播放暂停。

声明

Liot_AudErr_e Liot_AudioPlayPause(void);

参数

无。

返回值

错误码，见 Liot_AudErr_e。

5.12 Liot_AudioPlayResume

暂停恢复。

声明

Liot_AudErr_e Liot_AudioPlayResume(void);

参数

无。

返回值

错误码，见 Liot_AudErr_e。

5.13 Liot_AudioPlayFile

播放音频文件（PCM 裸流）。

声明

Liot_AudErr_e Liot_AudioPlayFile(char* fileName);

参数

fileName： [In] 文件路径。

返回值

错误码，见 Liot_AudErr_e。

5.14 Liot_AudioWaitPlayFinish

等待当前队列中的音频播放完毕。

声明

Liot_AudErr_e Liot_AudioWaitPlayFinish(int timeout);

参数

timeout： [In] 超时秒数，或 LIOT_WAIT_FOREVER。

返回值

错误码，见 Liot_AudErr_e。

5.15 Liot_AudioStop

立即停止播放并清空队列。

声明

Liot_AudErr_e Liot_AudioStop(void);

参数

无。

返回值

错误码，见 Liot_AudErr_e。

5.16 Liot_AudioPlayMp3File

播放 MP3 文件。

声明

Liot_AudErr_e Liot_AudioPlayMp3File(char* fileName);

参数

fileName： [In] 文件路径。

返回值

错误码，见 Liot_AudErr_e。

5.17 Liot_AudioPlayMp3

播放内存中的 MP3 数据。

声明

Liot_AudErr_e Liot_AudioPlayMp3(uint8_t* data, int datalen);

参数

data： [In] MP3 数据缓冲区。
datalen： [In] 数据长度（字节）。

返回值

错误码，见 Liot_AudErr_e。

5.18 Liot_AudioPlayWavFile

播放 WAV 文件。

声明

Liot_AudErr_e Liot_AudioPlayWavFile(char* fileName);

参数

fileName： [In] 文件路径。

返回值

错误码，见 Liot_AudErr_e。

5.19 Liot_AudioPlayWav

播放内存中的 WAV 数据（含 WAV 头）。

声明

Liot_AudErr_e Liot_AudioPlayWav(uint8_t* data, int datalen);

参数

data： [In] WAV 数据缓冲区（含 44 字节头）。
datalen： [In] 数据总长度（字节）。

返回值

错误码，见 Liot_AudErr_e。

5.20 Liot_AudioMp3StreamStart

启动 MP3 流式播放会话，只需初始化一次解码器。

声明

Liot_AudErr_e Liot_AudioMp3StreamStart(void);

参数

无。

返回值

错误码，见 Liot_AudErr_e。

5.21 Liot_AudioMp3StreamPlay

向流式解码器送入一段 MP3 数据并解码播放。

声明

Liot_AudErr_e Liot_AudioMp3StreamPlay(uint8_t* data, int datalen);

参数

data： [In] MP3 数据片段。
datalen： [In] 数据长度（字节）。

返回值

错误码，见 Liot_AudErr_e。

5.22 Liot_AudioMp3StreamStop

停止 MP3 流式播放并释放解码器资源。

声明

Liot_AudErr_e Liot_AudioMp3StreamStop(void);

参数

无。

返回值

错误码，见 Liot_AudErr_e。

6 代码示例

示例代码参考 LSDK\examples\demo\src\demo_audio.c 文件。

#include "liot_type.h"
#include "liot_audio.h"
#include "liot_log.h"
#include "liot_os.h"
#include "liot_gpio2.h"

#define TEST_PLAY
//#define TEST_RECORD

#ifdef TEST_PLAY
__attribute__((aligned(16))) uint8_t audio16k_16[] = {
    //音频源码
}
#endif

#ifdef TEST_RECORD
#define TEST_CACHE_LEN (1280)
__attribute__((aligned(16))) uint8_t audioRecord[TEST_CACHE_LEN] = {0};
#endif

void liot_audio_demo_thread(void *argv)
{
    liot_rtos_task_sleep_ms(2000);

    Liot_AonPowerCtl(TRUE);
    Liot_SetVoltage(L_DOMAIN_ALL, L_VOLT_3_30V);

    Liot_AudHwConfig_t cfg = {
        .i2cNum    = 1,
        .i2sNum    = 0,
        .paGpioNum = 0,
        .codecType = L_AUD_ES8311,
        .channel   = L_AUD_MONO_RIGHT,
        .role      = L_AUD_ROLE_SLAVE,
        .mode      = L_AUD_MODE_I2S,
        .frameSize = L_AUD_FRAMESIZE_16_16,
        .samples   = L_AUD_16K_SAMPLES,
    };

    liot_trace("Liot_AudioInit");
    Liot_AudioInit(&cfg);

    liot_trace("Liot_AudioSetVolume");
    Liot_AudioSetVolume(50);
    Liot_AudioSetMicVolume(8, 200);

    while(1)
    {
        #ifdef TEST_PLAY
        liot_trace("Liot_AudioPlay ...");
        Liot_AudioPlay(audio16k_16, sizeof(audio16k_16));
        liot_rtos_task_sleep_ms(5000);
        #endif

        #ifdef TEST_RECORD
        liot_trace("Liot_AudioRecord ...");
        Liot_AudioRecord(audioRecord, TEST_CACHE_LEN);
        Liot_AudioPlay(audioRecord, TEST_CACHE_LEN);
        liot_rtos_task_sleep_ms(1);
        #endif
    }
    Liot_AudioDeInit();
    liot_rtos_task_delete(0);
}