6 exaudio-音频播放和录音
作者：拓毅恒 | 最后修改：2026-07-16
一、概述
exaudio 是 audio 的扩展库，简化了使用方法，扩展了部分应用，建议使用此库. 音频框架如下：
合宙仅Air780EHV 内置音频编解码芯片，其他支持音频的功能需要外置音频编解码芯片。
目前合宙所有的型号均需要外置音频放大器(PA)才可将音频输出。
目前在支持播放的文件格式有mp3,amr,wav 支持流式播放的格式有mp3,amr,pcm,wav
支持录音格式为amr,pcm 支持流式录音(仅支持pcm录音)
音频损坏时的播放状态可参考 音频系统测试各种音频时播放状态总结
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/multimedia/audio
2.1 播放
local audio_setup_param ={
model= "es8311", -- 音频编解码类型,可填入"es8311"、"tm8211"
i2c_id = 0, -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚(ES8311需要，TM8211不需要)
pa_ctrl = 162, -- 音频放大器电源控制管脚
dac_ctrl = 164, -- 音频编解码芯片电源控制管脚，如果是780EHV,此处固定是20
}
local audio_play_param ={
type= 0, -- 播放类型，有0，播放文件，1.播放tts 2. 流式播放
-- 如果是播放文件,支持mp3,amr,wav格式
-- 如果是tts,内容格式见:https://docs.openluat.com/air780epm/common/tts/
-- 流式播放，仅支持PCM 格式音频,如果是流式播放，则sampling_rate, sampling_depth,signed_or_unsigned 必填写
content = "/luadb/1.mp3", -- 如果播放类型为0时，则填入string 是播放单个音频文件,如果是表则是播放多段音频文件,当播放类型为1的时候,表示的是播放路径
}
local function audio_task()
if exaudio.setup(audio_setup_param) then
exaudio.play_start(audio_play_param) -- 仅仅支持task 中运行
end
end
sys.taskInitEx(audio_task, taskName)
2.2 录音
local audio_setup_param ={
model= "es8311", -- dac类型,可填入"es8311"、"tm8211"
i2c_id = 0, -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚(ES8311需要，TM8211不需要)
pa_ctrl = 162, -- 音频放大器电源控制管脚
dac_ctrl = 164, -- 音频编解码芯片电源控制管脚，，如果是780EHV,此处固定是20
}
local recordPath = "/record.amr"
local audio_record_param ={
format= exaudio.AMR_WB, -- 录制格式，有exaudio.AMR_NB,exaudio.AMR_WB,exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000,exaudio.PCM_48000
time = 5, -- 录制时间,单位(秒)
path = recordPath, -- 如果填入的是字符串，则表示是文件路径，录音会传输到这个路径里
-- 如果填入的是函数，则表示是流式录音，录音的数据会传输到此函数内,返回的是zbuf地址，以及数据长度
}
local taskName = "task_audio"
local function audio_task()
sys.wait(100)
if exaudio.setup(audio_setup_param) then
exaudio.record_start(audio_record_param)
end
end
sys.taskInitEx(audio_task, taskName)
三、常量详解
exaudio 模块常量（新旧框架均可使用）
-
exaudio.PLAY_DONE : 当播放音频结束时,会在回调函数返回播放完成的时间
-
exaudio.RECORD_DONE : 当录音结束时，会在回调函数返回播放完成的时间
-
exaudio.AMR_NB : 仅录音时有用，表示使用AMR_NB方式录音
-
exaudio.AMR_WB : 仅录音时有用，表示使用AMR_WB方式录音
-
exaudio.PCM_8000 / exaudio.PCM_16000 / exaudio.PCM_24000 / exaudio.PCM_32000 / exaudio.PCM_48000 : 仅录音时有用，表示使用对应采样率进行录音
旧音频框架（audio）专有常量
-
audio.RESUME : 恢复音频模块工作模式，开始播放前调用
-
audio.SHUTDOWN : 休眠模式，系统可进低功耗
新音频框架（audio_v2）专有常量
-
audio_v2.DRIVER_TYPE_NONE : 无驱动类型
-
audio_v2.DRIVER_TYPE_I2S : I2S驱动类型
-
audio_v2.DRIVER_TYPE_DAC : DAC驱动类型，用于播放输出
-
audio_v2.DRIVER_TYPE_ADC : ADC驱动类型，用于录音输入
-
audio_v2.DRIVER_TYPE_USB : USB声卡驱动类型
四、函数详解
exaudio.setup(audio_configs)
功能
初始化audio,配置关于编解码芯片,音频放大器的电源,编解码芯片的采样率，采样深度相关的功能
注意事项
1. 该接口只能也只需启动一次
2. 强烈建议编解码芯片以及音频放大器的电源由模组控制，这样才能有效降低pop 音，体验更好
3. 目前支持 ES8311、TM8211 音频编解码和内置DAC三种类型
4. 如果选择了8311 则必须填写I2C 的端口，并在pins 工具配置 luatio
5. 如果出现:"ES8311通讯失败，请检查硬件" 的打印，请检查硬件，很大可能是焊接不良，如果解决不了，可寻求合宙官方解决
6. audio_configs 入参是一个表，有如下参数：
model = "es8311", -- dac类型: "es8311"、"tm8211"或"dac"；默认值为"es8311"
i2c_id = 0, -- i2c_id: 0,1；默认值为0
pa_ctrl = nil, -- 音频放大器电源控制管脚，默认值为nil，表示不使用管脚控制
dac_ctrl = nil, -- 音频编解码芯片电源控制管脚，默认值为nil，表示不使用管脚控制
dac_delay = nil, -- DAC启动前冗余时间(单位100ms)，默认为nil，使用audio核心库的默认参数（核心库中为5，表示500ms）
pa_delay = nil, -- DAC启动后延迟打开PA的时间(单位1ms)，默认为nil，使用audio核心库的默认参数（核心库中为5，表示5ms）
dac_time_delay = nil, -- 播放完毕后PA与DAC关闭间隔(单位1ms)，默认为nil，使用audio核心库的默认参数（核心库中为0，表示0ms）
pa_on_level = nil, -- PA打开电平 1:高 0:低，默认为nil，使用audio核心库的默认参数（核心库中为1）
dac_on_levl = nil -- DAC打开电平 1:高 0:低，默认为nil，使用audio核心库的默认参数（核心库中为1）
channel = 1, -- 音频通道 1:单声道，2:双声道；默认值为1,可选值为1,2
i2s_mode = 0, -- I2S模式 0:主机 1:从机
i2s_sample = 16000, -- I2S采样率 8000,16000,24000,32000,48000,20050,44100可选（如有录音需求，需跟录音采样率保持一致）
bits_per_sample = 16, -- I2S采样位深 8，16，24，32可选（如有录音需求，需跟录音采样位深保持一致）
i2s_comm_format = i2s.MODE_LSB, -- I2S通信格式: i2s.MONO_L（左声道），i2s.MONO_R（右声道），i2s.STEREO（立体声）
i2s_framebit = 16, -- I2S通道位宽 16，32可选
audio_mode = "auto", -- 音频框架版本: "auto"用默认, "new"新框架, "old"旧框架；
codec_voltage = 1, -- ES8311编解码器电平: 1=3.3V(默认), 0=1.8V(Air8201等特殊板型)
下面将介绍各个参数的含义以及用法
参数 audio_configs
参数含义：音频的参数配置,参数为table类型，table内容格式说明如下：
{
参数含义：音频编解码芯片(音频的数模或者模数转换)
数据类型：string；
取值范围："es8311"、"tm8211"、"dac"；
是否必选：可选传入此参数；默认值为"es8311"
注意事项：1. 注意大小写，必须为小写；2. ES8311需要配置i2c_id，TM8211无需I2C；3. TM8211自动使用MODE_MSB格式
参数名称： audio_configs.model参数含义：和音频编解码芯片通讯的I2C 接口；
数据类型：number；
取值范围：0,1
是否必选：ES8311必选，TM8211和DAC模式无需配置；默认值为0
注意事项：1. 仅ES8311需要配置，TM8211无需I2C；2. 需要通过(https://docs.openluat.com/air780epm/common/luatio/) 配置自己使用的i2c 对应的管脚映射
参数名称： audio_configs.i2c_id参数含义：主控对音频放大器芯片电源控制的管脚GPIO ID；
数据类型：number；
取值范围：模块的GPIO 编号范围
是否必选：可选传入此参数；如果没有传入或者传入nil，则表示不使用GPIO控制音频放大器芯片的电源
注意事项：强烈建议使用IO 控制音频放大器的电源,配合编解码的电源，模块内的算法可-- 有效降低pop 音
参数名称： audio_configs.pa_ctrl参数含义：主控对音频编解码芯片电源控制的管脚GPIO ID；
数据类型：number；
取值范围：模块的GPIO 编号范围
是否必选：可选传入此参数；如果没有传入或者传入nil，则表示不使用GPIO控制音频编解码芯片的电源
注意事项：强烈建议使用IO 控制音频编解码的电源,配合音频放大器的电源，模块内的算法可有效降低pop 音
参数名称： audio_configs.dac_ctrl参数含义：DAC启动前冗余时间；
数据类型：number；
取值范围：> 0
是否必选：可选传入此参数；默认值为5，表示500ms
注意事项：DAC启动前冗余时间,单位为100ms,如果有pop音，根据实际的情况调整，一般不用设置。
参数名称： audio_configs.dac_delay参数含义：DAC启动后延迟打开PA的时间；
数据类型：number；
取值范围：> 0
是否必选：可选传入此参数；默认值为5，表示5ms
注意事项：DAC启动后延迟打开PA的时间,单位为1ms,如果由pop 音根据实际的情况调整
一般不用设置,常规来说是先打开音频编解码延迟一段时间后再打开音频放大器。
参数名称： audio_configs.pa_delay参数含义：播放完毕后PA与DAC关闭间隔；
数据类型：number；
取值范围：> 0
是否必选：可选传入此参数；默认值为0，表示0ms
注意事项：播放完毕后PA与DAC关闭间隔,单位为1ms,如果有pop 音,根据实际的情况调整，一般不用设置。
参数名称： audio_configs.dac_time_delay参数含义：音频放大器芯片电源打开电平；
数据类型：number；
取值范围：1:高 0:低
是否必选：可选传入此参数；默认值为1
注意事项：音频放大器芯片电源打开的电平高还是低，一般来说都是高。
参数名称： audio_configs.pa_on_level参数含义：音频编解码芯片电源打开电平；
数据类型：number；
取值范围：1:高 0:低
是否必选：可选传入此参数；默认值为1
注意事项：音频编解码芯片电源打开的电平高还是低，一般来说都是高。
参数名称： audio_configs.dac_on_level参数含义：音频通道；
数据类型：number；
取值范围：1:单声道，2:双声道；
是否必选：可选传入此参数；默认值为1,可选值为1,2
注意事项：音频通道，1:单声道，2:双声道；默认值为1,可选值为1,2
参数名称： audio_configs.channel参数含义：I2S模式；
数据类型：number；
取值范围：0:主机，1:从机；
是否必选：可选传入此参数；默认值为0
注意事项：I2S模式，0:主机模式，1:从机模式；默认值为0
参数名称： audio_configs.i2s_mode参数含义：I2S采样率，录音、流式播放需设置对应采样率；
数据类型：number；
取值范围：8000,16000,24000,32000,48000,20050,44100；
是否必选：可选传入此参数；默认值为16000
注意事项：
I2S采样率，8000,16000,24000,32000,48000,20050,44100可选；默认值为16000
2. 录音场景：当使用exaudio.record_start()进行录音时，录音的PCM格式（如exaudio.PCM_16000）
必须与i2s_sample和bits_per_sample设置保持一致
3. 流式播放场景：当使用exaudio.play_start()进行流式播放时，sampling_rate和sampling_depth参数
必须与i2s_sample和bits_per_sample设置保持一致，避免音频数据格式不一致导致的播放异常
参数名称： audio_configs.i2s_sample参数含义：I2S采样位深；
数据类型：number；
取值范围：8，16，24，32；
是否必选：可选传入此参数；默认值为16
注意事项：
1. I2S采样位深，8，16，24，32可选；默认值为16
2. 录音场景：当使用exaudio.record_start()进行录音时，录音的PCM格式（如exaudio.PCM_16000）
必须与i2s_sample和bits_per_sample设置保持一致
3. 流式播放场景：当使用exaudio.play_start()进行流式播放时，sampling_rate和sampling_depth参数
必须与i2s_sample和bits_per_sample设置保持一致，避免音频数据格式不一致导致的播放异常
参数名称： audio_configs.bits_per_sample参数含义：I2S通信格式；
数据类型：number；
取值范围：i2s.MODE_LSB, i2s.MODE_MSB, i2s.MODE_I2S；
是否必选：可选传入此参数；ES8311默认MODE_LSB，TM8211默认MODE_MSB
注意事项：1. ES8311使用MODE_LSB格式；2. TM8211使用MODE_MSB格式(自动设置)；3. 如需自定义可传入i2s.MODE_LSB/MODE_MSB/MODE_I2S
参数名称： audio_configs.i2s_comm_format参数含义：I2S通道位宽；
数据类型：number；
取值范围：16，32；
是否必选：可选传入此参数；默认值为16
注意事项：I2S通道位宽，16，32可选；默认值为16
参数名称： audio_configs.i2s_framebit参数含义：音频框架版本选择，仅780EXX系列和8000系列有效，其他型号强制新框架；
数据类型：string；
取值范围："auto"用默认、"new"强制新框架、"old"强制旧框架；
是否必选：可选传入此参数；默认值为"auto"
注意事项：1. 8101和160X系列仅支持新框架，此参数无效；2. "new"指新音频框架，"old"指旧音频框架
参数名称： audio_configs.audio_mode参数含义：ES8311编解码器电平选择；
数据类型：number；
取值范围：1(3.3V，默认)，0(1.8V)；
是否必选：可选传入此参数；默认值为1
注意事项：Air8201等特殊板型ES8311使用1.8V电平，需设置codec_voltage=0
参数名称： audio_configs.codec_voltage
}数据类型：table；
取值范围：参考参数含义内各字段说明
是否必选：可选传入此参数；
注意事项：暂无；
返回值
返回true ,表示成功，返回false 表示失败
示例
-- ES8311 配置示例
local audio_configs ={
model= "es8311", -- 音频编解码类型
i2c_id = 0, -- i2c_id,ES8311需要配置
pa_ctrl = 162, -- 音频放大器电源控制管脚
dac_ctrl = 164, -- 音频编解码芯片电源控制管脚
}
-- TM8211 配置示例
local audio_configs_tm8211 ={
model= "tm8211", -- 音频编解码类型
-- i2c_id 无需配置，TM8211不需要I2C
pa_ctrl = 26, -- 音频放大器电源控制管脚
dac_ctrl = 2, -- 音频编解码芯片电源控制管脚
-- TM8211自动使用MODE_MSB格式，无需手动设置i2s_comm_format
}
if exaudio.setup(audio_configs) then
log.info("音频初始化成功")
end
exaudio.play_start(play_configs)
功能
播放文件,播放TTS,流式播放
注意事项
1. 支持MP3,WAV,AMR(含AMR_NB,AMR_WB)的格式的文件音频播放
2. 当播放多个音频的时候，需要注意音频文件的格式、采样率、声道数、位深 必须一致 ，否则会播放异常
3. 支持TTS 播放，但只支持中文的TTS
4. 支持流式播放，但仅仅支持PCM 数据流
5. 播放音频时 不能进 飞行模式。
6. play_configs 入参是一个表，有如下参数：
type = 0, -- 0:文件 1:TTS 2:流式
content = nil, -- 播放内容/路径
cbfnc = nil, -- 播放完毕回调
priority = 0, -- 优先级(数值越大越高)
sampling_rate = 16000, -- 采样率(仅流式)
sampling_depth = 16, -- 采样位深(仅流式)
signed_or_unsigned = true -- PCM是否有符号(仅流式)
下面将介绍各个参数的含义以及用法
参数
play_configs
参数含义：播放参数，参数为table类型，table内容格式说明如下：
{
参数含义：播放类型,有播放文件，播放TTS，流式播放三个方法
数据类型：number；
取值范围：0(播放文件),1(播放TTS),2(流式播放)；
是否必选：必选传入此参数；
参数名称： play_configs.type参数含义：播放的内容，或者回调函数地址
数据类型：string或者function或者table或者nil；
取值范围：无；
是否必选：必选传入此参数；
注意事项：1. 当播放类型选择播放文件时候，content 内容必须填写string 或者table类型的播放路径
1.1 当播放单个音频的时候，需要填入string 类型，表示播放路径
1.2 当播放多个音频的时候，需要填入table 类型，table 的元素全为字符串，内容为播放路径
注意：多文件播放要求所有音频文件的格式、采样率、声道数、位深必须一致
2. 当播放类型为tts 的时候，
2.1 当content 填写string 类型，tts 仅支持文字转普通话
相关格式请见：https://docs.openluat.com/air780epm/common/tts/
2.2 当content 填写为nil的时候，表示停止播放TTS 播放
3. 当播放类型为流式播放的时候，不需要填写此处
参数名称： play_configs.content参数含义：当播放完成后，会触发此函数
数据类型：function；
取值范围：无；
是否必选：非必须传入此参数；
注意事项：目前仅会返回exaudio.PLAY_DONE(播放完成消息)，不排除后面会增加其他的事件,回调函数如下:
local function cbfnc(event)
if event == exaudio.PLAY_DONE then
log.info("播放完成",exaudio.is_end())
end
end
参数名称： play_configs.cbfnc参数含义：播放优先级
数据类型：number；
取值范围：大于等于0；
是否必选：非必须传入此参数；
注意事项：优先级高于或者正在播放的音频优先级，会让正在播放的音频停止播放，然后播放新的音频
如果小于或者等于正在播放的音频优先级，此次播放请求将被忽略。
参数名称： play_configs.priority ,参数含义：采样率
数据类型：number；
取值范围：8000,16000,24000,32000,48000,20050,44100；
是否必选：当type 选择了流式播放(2),必须传入此参数,其他播放不传入此参数；
注意事项：常规的音频都是8000，或者是16000
参数名称： play_configs.sampling_rate参数含义：采样位深
数据类型：number；
取值范围：8，16，24；
是否必选：当type 选择了流式播放(2),必须传入此参数,其他播放不传入此参数；
参数名称： play_configs.sampling_depth参数含义：PCM的编码类型
数据类型：boolean；
取值范围：true,false；
是否必选：非必须传入此参数；
注意事项：默认是true,即有符号
参数名称： play_configs.signed_or_unsigned
}数据类型：table；
取值范围：参考参数含义内各字段说明
是否必选：可选传入此参数；
注意事项：暂无；
返回值
返回true ,表示成功，返回false 表示失败
示例
local audio_play_param ={
type= 0, -- 播放类型，有0，播放文件，1.播放tts 2. 流式播放
-- 如果是播放文件,支持mp3,amr,wav格式
-- 如果是tts,内容格式见:https://wiki.luatos.com/chips/air780e/tts.html?highlight=tts
-- 流式播放，仅支持PCM 格式音频,如果是流式播放，则sampling_rate, sampling_depth,signed_or_unsigned 必填写
content = "/luadb/1.mp3", -- 如果播放类型为0时，则填入string 是播放单个音频文件,如果是表则是播放多段音频文件。
cbfnc = play_end, -- 播放完毕回调函数
}
if exaudio.setup(audio_setup_param) then
exaudio.play_start(audio_play_param)
end
exaudio.record_start(recod_configs)
功能
开始录音，录音到文件功能以及支持PCM 的流式录音
注意事项
1. 仅仅支持 AMR_NB，AMR_WB，PCM（8000,16000,24000,32000,48000）的格式
2. 流式录音仅仅支持 PCM 格式
3. recod_configs 入参是一个表，有如下参数：
format = exaudio.AMR_NB, -- 录制格式，支持exaudio.AMR_NB，exaudio.AMR_WB,exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000,exaudio.PCM_48000
time = 5, -- 录制时间(秒)
path = nil, -- 文件路径或流式回调
cbfnc = nil -- 录音完毕回调
4. 实测距离3米能清晰录音，距离5米能听到声音但杂音较多。测试环境：麦克风音量100，播放音量70、测试使用 demo/audio/record_amr_file 文件
下面将介绍各个参数的含义以及用法
参数
recod_configs
参数含义：播放参数，参数为table类型，table内容格式说明如下：
{
参数含义：录音格式
数据类型：number；
取值范围：exaudio.AMR_NB，exaudio.AMR_WB，exaudio.PCM_8000，exaudio.PCM_16000，exaudio.PCM_24000，
exaudio.PCM_32000，exaudio.PCM_48000；
是否必选：必须传入此参数；
注意事项：1. 如果是录音到文件支持上述取值范围都支持，要注意的是，如果选择exaudio.AMR_WB,则需要固件支持volte 功能
2. 如果要选择流式录音，仅支持
(exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000,exaudio.PCM_48000)
参数名称： recod_configs.format参数含义：录音时长
数据类型：number；
取值范围：>0 (单位1s)；
是否必选：必须传入此参数；
注意事项：时间越大，录制文件越大，在setup位数深为16的情况下：
1. 如果选择AMR_NB,大约为1.2KB/S
2. 如果选择AMR_WB,大约为2.4KB/S
3. 如果选择PCM_8000，大约为15KB/S
4. 如果选择PCM_16000，大约为30KB/S
5. 如果选择PCM_24000，大约为45KB/S
6. 如果选择PCM_32000，大约为60KB/S
7. 如果选择PCM_48000，大约为90KB/S
参数名称： recod_configs.time参数含义：文件路径，或者流式录音的回调函数
数据类型：string/function；
取值范围：无；
是否必选：必须传入此参数；
注意事项：1. 如果是录音到文件，则传入文件路径
2. 如果是流式录音，则传入回调函数地址，回调函数如下表示
local function recode_data_callback(addr,data_len)
log.info("收到音频流,地址为:",addr,"有效数据长度为:",data_len)
end
参数名称： recod_configs.path参数含义：当录制完成后，会触发此函数
数据类型：function；
取值范围：无；
是否必选：非必须传入此参数；
注意事项：目前仅会返回exaudio.RECORD_DONE(录音完成消息)，不排除后面会增加其他的事件,回调函数如下:
local function cbfnc(event)
if event == exaudio.PLAY_DONE then
log.info("播放完成",exaudio.is_end())
end
end
参数名称： recod_configs.cbfnc }数据类型：table；
取值范围：参考参数含义内各字段说明
是否必选：可选传入此参数；
注意事项：暂无；
返回值
返回true ,表示成功，返回false 表示失败
示例
local audio_record_param ={
format= exaudio.AMR_WB, -- 录制格式，有exaudio.AMR_NB,exaudio.AMR_WB,exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000,exaudio.PCM_48000
time = 5, -- 录制时间,单位(秒)
path = recordPath, -- 如果填入的是字符串，则表示是文件路径，录音会传输到这个路径里
-- 如果填入的是函数，则表示是流式录音，录音的数据会传输到此函数内,返回的是zbuf地址，以及数据长度
}
if exaudio.setup(audio_setup_param) then
exaudio.record_start(audio_record_param)
end
exaudio.play_stream_write(data)
功能
流式播放时,写入音频数据接口
注意事项
流式音频数据,PCM格式,长度需要1024的倍数,可以一边网络下载音频数据,一边进行音频播放
参数
-- 参数含义：写入音频数据接口
-- 数据类型：string；
-- 取值范围：无；
-- 是否必选：必须传入此参数；
-- 注意事项：需要及时传入音频流数据，不然会导致停止播放
返回值
返回true ,表示成功，返回false 表示失败
exaudio.play_stop(stopConfigs)
功能
停止播放
注意事项
- 必须传入配置表参数，不能省略参数
- 根据播放类型使用不同的停止方法：
- 流式播放（type=2）：使用audio.stop()停止
- 文件播放（type=0）和TTS播放（type=1）：使用audio.play()停止
参数
stopConfigs
参数含义：停止播放配置参数
数据类型：table；
取值范围：必须包含type字段；
是否必选：必须传入此参数；
注意事项：必须传入配置表，格式: {type = 0}
参数说明
{
type = 0|1|2 -- 播放类型：0=文件播放, 1=TTS播放, 2=流式播放
}
返回值
返回true ,表示成功，返回false 表示失败
示例
-- 停止TTS播放
exaudio.play_stop({type = 1})
-- 停止流式播放
exaudio.play_stop({type = 2})
-- 停止文件播放
exaudio.play_stop({type = 0})
exaudio.is_end()
功能
判断是否播放完成
注意事项
无
参数
无
返回值
返回true ,表示播放完成，返回false 表示播放未完成
exaudio.record_stop()
功能
停止录音
注意事项
无
参数
无
返回值
返回true ,表示成功，返回false 表示失败
exaudio.vol(play_volume)
功能
设置播放音量
注意事项
由于ES8311在未上电和初始化时音量设置无效，因此必须在 exaudio.setup(audio_configs) 初始化成功后调用，方可生效
参数
play_volume
参数含义：设置播放音量
数据类型：number；
取值范围：0 - 100 ；
是否必选：必须传入此参数；
注意事项：音量太大可能会导致喇叭声音过爆，喇叭的功率需要和音频放大器的功率匹配
返回值
返回true ,表示成功，返回false 表示失败
exaudio.mic_vol(record_volume)
功能
设置录音音量
注意事项
由于ES8311在未上电和初始化时音量设置无效，因此必须在 exaudio.setup(audio_configs) 初始化成功后调用，方可生效
参数
record_volume
参数含义：设置录音音量
数据类型：number；
取值范围：0 - 100 ；
是否必选：必须传入此参数；
返回值
返回true ,表示成功，返回false 表示失败
exaudio.finish()
功能
在流式播放模式写入最后一块数据后，通知多媒体通道已经没有更多数据需要写入了，可以防止播放音频文件异常产生pop音
适用于降低流式播放音频中播放完毕后pop音
注意事项
- 需要固件版本号≥V2024
参数
无
返回值
local result = exaudio.finish()
result
含义说明：是否成功设置成功；
数据类型：boolean；
取值范围：true 设置成功，false 设置失败
返回示例：true -- 表示设置成功
示例
file:close() -- 模拟音频获取完毕，关闭音频文件
-- 写入最后一块数据后，通知多媒体通道已经没有更多数据需要播放了
local result = exaudio.finish()
log.info("exaudio","通知多媒体通道数据结束：",result)
exaudio.pm(pm_mode)
功能
音频模块休眠控制
注意事项
- 用于控制音频模块的电源管理模式
- 通常在播放停止后调用以进入低功耗模式
参数
pm_mode
参数含义：休眠模式；
数据类型：number；
取值范围：audio.RESUME，audio.SHUTDOWN；
是否必选：必须传入此参数；
注意事项：
| 模式常量 | PA 状态 | Codec 状态 | 适用场景 |
|---|---|---|---|
| audio.RESUME | 开启 | 全功能工作 | 正在进行语音通话或播放音频时 |
| audio.SHUTDOWN | 断电 | 可配置的codec关机状态，不可配置的codec断电，系统能进低功耗状态 | 长时间不需要使用音频功能，但希望保留快速恢复的能力。（如监听来电） |
返回值
返回 true 表示成功，返回 false 表示失败
示例
-- 停止播放后进入低功耗模式
local result = exaudio.pm(audio.SHUTDOWN)
log.info("exaudio","进入低功耗模式：",result)
-- 开始播放前恢复工作模式
local result = exaudio.pm(audio.RESUME)
log.info("exaudio","恢复工作模式：",result)
exaudio.make_probe_id(tx_bus_type, tx_bus_id, rx_bus_type, rx_bus_id)
功能
合成音频驱动ID，用于在不使用默认驱动时，指定 driver_probe_id 参数
注意事项
1. 该接口仅在 "audio_mode = new" 新框架下有效，旧 audio 框架调用返回 nil
参数
tx_bus_type
参数含义：发送总线类型；
数据类型：int；
取值范围：audio_v2.DRIVER_TYPE_xxx 常量（NONE/I2S/DAC/ADC/USB）；
是否必选：必须传入此参数；
注意事项：I2S 双工场景，发送和接收均填 DRIVER_TYPE_I2S
参数名称： tx_bus_typetx_bus_id
参数含义：发送总线 ID；
数据类型：int；
取值范围：通常为 0；
是否必选：必须传入此参数；
参数名称： tx_bus_idrx_bus_type
参数含义：接收总线类型；
数据类型：int；
取值范围：audio_v2.DRIVER_TYPE_xxx 常量（NONE/I2S/DAC/ADC/USB）；
是否必选：必须传入此参数；
注意事项：单工场景（仅播放或仅录音），接收或发送填 DRIVER_TYPE_NONE
参数名称： rx_bus_typerx_bus_id
参数含义：接收总线 ID；
数据类型：int；
取值范围：通常为 0；
是否必选：必须传入此参数；
参数名称： rx_bus_id
返回值
成功返回驱动 ID（int），失败返回 nil
示例
-- I2S0 双工驱动（可同时播放和录音）
local pid = exaudio.make_probe_id(audio_v2.DRIVER_TYPE_I2S, 0, audio_v2.DRIVER_TYPE_I2S, 0)
-- DAC0 单工驱动（仅播放）
local pid = exaudio.make_probe_id(audio_v2.DRIVER_TYPE_DAC, 0, audio_v2.DRIVER_TYPE_NONE, 0)
exaudio.parse_audio_info(file_path, codec_id)
功能
解析音频文件头信息，获取采样率、位宽、声道数、数据起始位置等参数
注意事项
1. 仅在新音频框架下可用
2. 支持 PCM(0)、WAV(1)、AMR_NB(2)、AMR_WB(3)、MP3(5) 格式
3. PCM 格式没有文件头，直接返回默认参数：16000Hz、16bit、单声道
4. 解析失败返回 false，成功返回包含信息的 table
参数
file_path
参数含义：待解析的音频文件路径；
数据类型：string；
取值范围：有效的文件路径；
是否必选：必须传入此参数；
注意事项：文件需存在于文件系统中，如 "/luadb/test.mp3"
参数名称： file_pathcodec_id
参数含义：音频文件使用的编解码器ID；
数据类型：number；
取值范围：0=PCM, 1=WAV, 2=AMR_NB, 3=AMR_WB, 5=MP3；
是否必选：必须传入此参数；
注意事项：需与文件实际格式一致；PCM 格式无文件头，直接返回默认值
参数名称： codec_id
返回值
成功返回包含音频信息的 table，失败返回 false 或 nil
{
sample_rate = 16000, -- 采样率(Hz)
data_bits = 16, -- 采样位深
channel_nums = 1, -- 声道数
is_signed = true, -- PCM是否有符号
data_start = 0 -- 音频数据起始偏移(字节)
}
示例
local info = exaudio.parse_audio_info("/luadb/test.mp3", 5)
if info then
log.info("采样率:", info.sample_rate)
log.info("位宽:", info.data_bits)
log.info("声道数:", info.channel_nums)
end
五、版本更新说明
版本号：202607161030
1、更新时间：2026-07-16 10:30
2、更新内容
- 移除新音频框架初始化audio_v2_setup中的make_probe_id+set_default_driver操作
- 各BSP有默认驱动，无需手动设置，特殊情况可通过exaudio.set_default_driver接口设置
版本号：202607141800
1、更新时间：2026-07-14 18:00
2、更新内容
- 新增codec_voltage参数控制ES8311电平
- codec_voltage=1(默认3.3V)，codec_voltage=0(1.8V，适配Air8201等特殊板型)
版本号：202607081647
1、更新时间：2026-07-08 16:47
2、更新内容
- 移除exaudio.shutdown()接口，统一合并到exaudio.pm()中
- exaudio.pm()新增新音频框架支持：audio.SHUTDOWN→进入休眠，audio.RESUME→恢复所有
- 常量详解章节对所有常量标注框架适用范围（旧框架专有/新框架专有/均可使用）
- 新增exaudio.make_probe_id()函数，用于合成音频驱动ID
- 新增exaudio.parse_audio_info()函数，用于从音频文件解析播放信息
- 新增Air700/Air1780系列模组检测
版本号：202607021200
1、更新时间：2026-07-02 12:00
2、更新内容
- 新增exaudio.version()接口
- 支持exaudio库文件版本号管理功能，版本号的格式为：yyyymmddhhmm，表示yyyy年mm月dd日hh时mm分发布的版本
六、产品支持说明
780EHM,780EHV,780EGH,780EGG, 以及 8000 全系列均支持；
8101,160X系列支持，仅支持新音频框架。
780EPM, 780EGP, 700ECP 不支持。
724,722,720,820，795 也不支持。
七、TTS参数说明
TTS 支持的型号和版本如下
TTS语音参数规则
TTS语音的参数调整,是播放的字符串的特殊格式来设置的
- 基本格式是
[参数XXX]待播放的文本 - 部分参数支持不同的位置多次使用, 例如
[参数1]待播放[参数2]123文本
原始格式（选择默认参数）
exaudio.play_start(
{
type = 1,
content = "大家好,我是小宙"
})
设置发音人
设置代码参考，发音人同时只能设置一个
--[[
格式： [m*] (*=51~55)
51 – 许久
52 – 许多
53 – 晓萍
54 – 唐老鸭
55 – 许宝宝
]]
exaudio.play_start(
{
type = 1,
content = "[m52]大家好,我是小宙"
})
设置发音风格
--[[
格式： [f*] (*=0/1/2)
参数： 0 – 一字一顿
1 – 平铺直叙
2 – 有声有色
说明： 默认为平铺直叙风格。
]]
exaudio.play_start(
{
type = 1,
content = "[f1]大家好,我是小宙"
})
设置数字处理策略
--[[
格式： [n*] (*=0/1/2)
参数： 0 – 自动判断
1 – 数字作号码处理
2 – 数字作数值处理
说明： 默认为自动判断。
]]
exaudio.play_start(
{
type = 1,
content = "[n1]大家好12312121212"
})
静音一段时间
--[[
格式： [p*] (*=无符号整数)
参数： * – 静音的时间长度，单位：毫秒(ms)
]]
exaudio.play_start(
{
type = 1,
content = "[p2000]大家好，我是小宙"
})
设置语速
--[[
格式： [s*] (*=0~10)
参数： * – 0-10
说明： 默认语速值为 5，语速的调节范围为默认语速的一半到两倍，即 0 的值比默认语速慢一半，10 的值比默认语速快一倍。
]]
exaudio.play_start(
{
type = 1,
content = "[s5]大家好，我是小宙"
})
设置语调
--[[
格式： [t*] (*=0~10)
参数： * – 语调值对应到参数设置的值为 6553*（值-5），即 0 对应到-32765，5 对应到 0，10 对应到+32765
说明： 默认语调值为 5，语调的调节范围为默认语调基频下 64Hz 到上 128Hz。
]]
exaudio.play_start(
{
type = 1,
content = "[t5]大家好，我是小宙"
})
设置音量
--[[
格式： [v*] (*=0~10)
参数： * – 音量值对应到参数设置的值为 6553*（值-5），即 0 对应到-32765，5 对应到 0，10 对应到+32765。
说明： 音量的调节范围为静音到音频设备支持的最大值，默认值 5 为中间音量。
]]
exaudio.play_start(
{
type = 1,
content = "[v5]大家好，我是小宙"
})
设置汉语号码中“1”的读法
--[[
格式： [y*] (*=0/1)
参数： 0 – 合成号码时“1”读成“yāo”
1 – 合成号码时“1”读成“yī”
说明： 默认合成号码时“1”读成“yāo”。
]]
exaudio.play_start(
{
type = 1,
content = "[y1]110大家好[y0]110"
})