LuatOS是物联网终端开发的轻量级工具。作为嵌入式Lua脚本运行框架，其基于Lua 5.3深度优化，适配4G-Cat.1、MCU等硬件。通过协程多任务架构和丰富开发资源，包括70+核心库、20+扩展库、1000+demo实例，实现物联网基础场景全覆盖。

一、概述

exaudio 是 audio 的扩展库，简化了使用方法，扩展了部分应用，建议使用此库. 音频框架如下：

合宙仅Air780EHV 内置音频编解码芯片，其他支持音频的功能需要外置音频编解码芯片。

• 目前合宙所有的型号均需要外置音频放大器(PA)才可将音频输出。

• 目前在支持播放的文件格式有mp3,amr,pcm,wav 支持流式播放(仅支持pcm 格式)

• 支持录音格式为amr,pcm 支持流式录音(仅支持pcm录音)

二、核心示例

2.1 播放

local audio_setup_param ={
    model= "es8311",       -- 音频编解码类型,可填入"es8311"
    i2c_id = 0,            -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚
    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"
    i2c_id = 0,            -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚
    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)

三、常量详解

1、exaudio.PLAY_DONE : 当播放音频结束时,会在回调函数返回播放完成的时间

2、exaudio.RECORD_DONE : 当录音结束时，会在回调函数返回播放完成的时间

3、exaudio.AMR_NB : 仅录音时有用，表示使用AMR_NB 方式录音

4、exaudio.AMR_WB : 仅录音时有用，表示使用AMR_WB 方式录音

5、exaudio.PCM_8000/exaudio.PCM_16000/exaudio.PCM_24000/exaudio.PCM_32000/exaudio.PCM_48000 : 仅录音时有用，表示使用8000/16000/24000/32000/48000 秒 的速度对音频进行采样

四、函数详解

4.1 exaudio.setup(audio_configs)

功能

初始化audio,配置关于编解码芯片,音频放大器的电源,编解码芯片的采样率，采样深度相关的功能

注意事项

1. 该接口只能也只需启动一次
2. 强烈建议编解码芯片以及音频放大器的电源由模组控制，这样才能有效降低pop 音，体验更好
3. 目前仅支持8311 音频编解码，
4. 如果选择了8311 则必须填写I2C 的端口，并在pins 工具配luatio
5. 如果出现:“ES8311通讯失败，请检查硬件” 的打印，请检查硬件，很大可能是焊接不良，如果解决不了，可寻求合宙官方解决
6. audio_configs 入参是一个表，有如下参数：

    model = "es8311",           -- dac类型: "es8311"；默认值为"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_configs

参数含义：音频的参数配置,参数为table类型，table内容格式说明如下：  
> {  
> 参数含义：音频编解码芯片(音频的数模或者模数转换)  
> 数据类型：string；  
> 取值范围："es8311"；  
> 是否必选：可选传入此参数；默认值为"es8311"  
> 注意事项：注意大小写，必须为小写  
> 参数名称： audio\_configs.model
> 
> 参数含义：和音频编解码芯片通讯的I2C 接口；  
> 数据类型：number；  
> 取值范围：0,1  
> 是否必选：可选传入此参数，默认值为0；如果默认值不能满足需求，则必须传入；  
> 注意事项：需要通过(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.MONO\_L（左声道），i2s.MONO\_R（右声道），i2s.STEREO（立体声）；  
> 是否必选：可选传入此参数；默认值为i2s.MODE\_LSB  
> 注意事项：I2S通信格式，i2s.MONO\_L（左声道），i2s.MONO\_R（右声道），i2s.STEREO（立体声）；默认值为i2s.MODE\_LSB  
> 参数名称： audio\_configs.i2s\_comm\_format
> 
> 参数含义：I2S通道位宽；  
> 数据类型：number；  
> 取值范围：16，32；  
> 是否必选：可选传入此参数；默认值为16  
> 注意事项：I2S通道位宽，16，32可选；默认值为16  
> 参数名称： audio\_configs.i2s\_framebit  
> }
> 
> 数据类型：table；  
> 取值范围：参考参数含义内各字段说明  
> 是否必选：可选传入此参数；  
> 注意事项：暂无；

**返回值**

返回true ,表示成功，返回false 表示失败

示例

local audio_configs ={
    model= "es8311",          -- 音频编解码类型,可填入"es8311"
    i2c_id = 0,          -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚
    pa_ctrl = 162,         -- 音频放大器电源控制管脚
    dac_ctrl = 164,        --  音频编解码芯片电源控制管脚，如果是780EHV,此处固定是20  
}
if exaudio.setup(audio_configs) then
    log.info("音频初始化成功")
end

4.2 exaudio.play_start(play_configs)

功能

播放文件,播放TTS,流式播放

注意事项

1. 支持MP3,WAV,AMR(含AMR_NB,AMR_WB)的格式的文件音频播放

2. 支持TTS 播放，但只支持中文的TTS

3. 支持流式播放，但仅仅支持PCM 数据流

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

4.3 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               -- 录音完毕回调

下面将介绍各个参数的含义以及用法

参数

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

4.4 exaudio.play_stream_write(data)

功能

流式播放时,写入音频数据接口

注意事项

流式音频数据,PCM格式,长度需要1024的倍数,可以一边网络下载音频数据,一边进行音频播放

参数

-- 参数含义：写入音频数据接口
-- 数据类型：string；
-- 取值范围：无；
-- 是否必选：必须传入此参数；
-- 注意事项：需要及时传入音频流数据，不然会导致停止播放

返回值

返回true ,表示成功，返回false 表示失败

4.5 exaudio.play_stop(stopConfigs)

功能

停止播放

注意事项

1. 必须传入配置表参数，不能省略参数
2. 根据播放类型使用不同的停止方法：
3. 流式播放（type=2）：使用audio.stop()停止
4. 文件播放（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})

4.6 exaudio.is_end()

功能

判断是否播放完成

注意事项

无

参数

无

返回值

返回true ,表示播放完成，返回false 表示播放未完成

4.7 exaudio.record_stop()

功能

停止录音

注意事项

无

参数

无

返回值

返回true ,表示成功，返回false 表示失败

4.7 exaudio.vol(play_volume)

功能

设置播放音量

注意事项

由于ES8311在未上电和初始化时音量设置无效，因此必须在 exaudio.setup(audio_configs) 初始化成功后调用，方可生效

参数

play_volume

参数含义：设置播放音量
数据类型：number；
取值范围：0 - 100 ；
是否必选：必须传入此参数；
注意事项：音量太大可能会导致喇叭声音过爆，喇叭的功率需要和音频放大器的功率匹配

返回值

返回true ,表示成功，返回false 表示失败

4.9 exaudio.mic_vol(record_volume)

功能

设置录音音量

注意事项

由于ES8311在未上电和初始化时音量设置无效，因此必须在 exaudio.setup(audio_configs) 初始化成功后调用，方可生效

参数

record_volume

参数含义：设置录音音量
数据类型：number；
取值范围：0 - 100 ；
是否必选：必须传入此参数；

返回值

返回true ,表示成功，返回false 表示失败

4.10 exaudio.finish()

功能

在流式播放模式写入最后一块数据后，通知多媒体通道已经没有更多数据需要写入了，可以防止播放音频文件异常产生pop音

适用于降低流式播放音频中播放完毕后pop音

注意事项

1. 需要固件版本号≥V2024

参数

无

返回值

local result = exaudio.finish()

result

含义说明：是否成功设置成功；
数据类型：boolean；
取值范围：true 设置成功，false 设置失败
返回示例：true -- 表示设置成功

示例

file:close()                -- 模拟音频获取完毕，关闭音频文件
-- 写入最后一块数据后，通知多媒体通道已经没有更多数据需要播放了
local result = exaudio.finish()
log.info("exaudio","通知多媒体通道数据结束：",result)

4.11 exaudio.pm(pm_mode)

功能

音频模块休眠控制

注意事项

1. 用于控制音频模块的电源管理模式
2. 通常在播放停止后调用以进入低功耗模式

参数

pm_mode

参数含义：休眠模式；
数据类型：number；
取值范围：audio.RESUME，audio.STANDBY，audio.SHUTDOWN，audio.POWEROFF；
是否必选：必须传入此参数；

模式常量	PA 状态	Codec 状态	适用场景	优缺点
audio.RESUME	开启	全功能工作	正在进行语音通话或播放音频时	-
audio.STANDBY	断电	待机（静音）	通话暂停（如等待对方回应）、需要快速恢复的场景。系统不能进低功耗状态，如果PA不可控，codec进入静音模式	优点：切换到活动状态的恢复时间短，响应快，约1S。 缺点：仍然消耗一定的电量，不适合低功耗场景
audio.SHUTDOWN	断电	可配置的codec关机状态，不可配置的codec断电，系统能进低功耗状态	长时间不需要使用音频功能，但希望保留快速恢复的能力（如监听来电）	优点：功耗低于 audio.STANDBY 模式，恢复时间约5S，比 audio.POWEROFF 短。 缺点：仍然消耗少量电量
audio.POWEROFF	断电	完全断电	长时间不需要音频功能（如纯数据传输场景），系统能进低功耗状态	优点：功耗低，适合极致低功耗场景 缺点：重新激活时需要较长的初始化时间，约10S

参数示例：audio.RESUME 工作模式；

返回值

返回true ,表示成功，返回false 表示失败

示例

-- 停止播放后进入低功耗模式
local result = exaudio.pm(audio.SHUTDOWN)
log.info("exaudio","进入低功耗模式：",result)

-- 开始播放前恢复工作模式
local result = exaudio.pm(audio.RESUME)
log.info("exaudio","恢复工作模式：",result)

五、TTS参数说明

5.1 TTS 支持的型号和版本如下

合宙4G Cat.1主推型号与固件版本对应关系

核心库名称	说明	Air780EPM/Air780EGP 1号	Air780EPM/Air780EGP 2号	Air700EGE/Air780EH/Air780EW/Air780EG 1号	Air700EGE/Air780EH/Air780EW/Air780EG 2号	Air700EGE/Air780EH/Air780EW/Air780EG 3号	Air700EGE/Air780EH/Air780EW/Air780EG 4号	Air700EGE/Air780EH/Air780EW/Air780EG 5号	Air700EGE/Air780EH/Air780EW/Air780EG 6号	Air700EGE/Air780EH/Air780EW/Air780EG 7号	Air700EGE/Air780EH/Air780EW/Air780EG 8号	Air700EGE/Air780EH/Air780EW/Air780EG 9号	Air700EGE/Air780EH/Air780EW/Air780EG 10号	Air700EGE/Air780EH/Air780EW/Air780EG 11号
固件位数说明	1-99号是32位固件；101-199号是64位固件	1号	2号	103号	104号	101号	102号	103号	104号	105号	106号	107号	108号	109号
tts	文字转语音	✗	✗	✗	✗	✓	✗	✓	✗	✓	✗	✓	✗	✗

这张表格展示了合宙 4G Cat.1 主推型号（Air780EPM/Air780EGP、Air700EGE/Air780EH/Air780EW/Air780EG 等）与固件版本的对应关系，其中核心库 1-99 号为 32 位固件、101-199 号为 64 位固件，并标注了tts（文字转语音）功能在不同版本固件下的支持情况。

5.2 TTS语音参数规则

TTS语音的参数调整,是播放的字符串的特殊格式来设置的

1. 基本格式是 [参数XXX]待播放的文本
2. 部分参数支持不同的位置多次使用, 例如 [参数1]待播放[参数2]123文本

5.2.1 原始格式（选择默认参数）

exaudio.play_start(
    {
        type = 1,
        content = "大家好,我是小宙"
    }) 

5.2.2 设置发音人

设置代码参考，发音人同时只能设置一个

--[[
 格式： [m*] (*=51~55)
 51 – 许久
 52 – 许多
 53 – 晓萍
 54 – 唐老鸭
 55 – 许宝宝 
]]
exaudio.play_start(
    {
        type = 1,
        content = "[m52]大家好,我是小宙"
    }) 

5.2.3 设置发音风格

--[[
格式： [f*] (*=0/1/2)
参数： 0 – 一字一顿
      1 – 平铺直叙
      2 – 有声有色
说明： 默认为平铺直叙风格。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[f1]大家好,我是小宙"
    }) 

5.2.4 选择语种

--[[
格式： [g*] (*=0/1/2)
参数： 0 – 自动判断
      1 – 汉语普通话
      2 – 英语语种
说明：默认语种为自动判断。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[g0]大家好,我是小宙"
    }) 

5.2.5 设置数字处理策略

--[[
格式： [n*] (*=0/1/2)
参数： 0 – 自动判断
      1 – 数字作号码处理
      2 – 数字作数值处理
说明： 默认为自动判断。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[n1]大家好12312121212"
    }) 

5.2.6 英文数字 0 的朗读设置

--[[
格式： [o*] (*=0/1)
参数： 0 – 英文数字 0 读做“O”
      1 – 英文数字 0 读做“zero”
说明： 默认为英文数字 0 读做“zero”。
注意：0 只有作为号码朗读时，标记才会生效，0 处理为数值时，一律读作 zero。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[o1]大家好12312121212"
    }) 

5.2.7 静音一段时间

--[[
格式： [p*] (*=无符号整数)
参数： * – 静音的时间长度，单位：毫秒(ms)
]]
exaudio.play_start(
    {
        type = 1,
        content = "[p2000]大家好，我是小宙"
    }) 

5.2.8 设置语速

--[[
格式： [s*] (*=0~10)
参数： * – 0-10
说明： 默认语速值为 5，语速的调节范围为默认语速的一半到两倍，即 0 的值比默认语速慢一半，10 的值比默认语速快一倍。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[s5]大家好，我是小宙"
    }) 

5.2.9 设置语调

--[[
格式： [t*] (*=0~10)
参数： * – 语调值对应到参数设置的值为 6553*（值-5），即 0 对应到-32765，5 对应到 0，10 对应到+32765
说明： 默认语调值为 5，语调的调节范围为默认语调基频下 64Hz 到上 128Hz。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[t5]大家好，我是小宙"
    }) 

5.2.10 设置音量

--[[
格式： [v*] (*=0~10)
参数： * – 音量值对应到参数设置的值为 6553*（值-5），即 0 对应到-32765，5 对应到 0，10 对应到+32765。
说明： 音量的调节范围为静音到音频设备支持的最大值，默认值 5 为中间音量。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[v5]大家好，我是小宙"
    }) 

5.2.11 设置汉语号码中“1”的读法

--[[
格式： [y*] (*=0/1)
参数： 0 – 合成号码时“1”读成“yāo”
      1 – 合成号码时“1”读成“yī”
说明： 默认合成号码时“1”读成“yāo”。
]]
exaudio.play_start(
    {
        type = 1,
        content = "[y1]110大家好[y0]110"
    }) 

六、模组支持说明

780EHM、780EHV、780EGH、780EGG, 以及 8000 全系列均支持；

780EPM, 780EGP, 700ECP 不支持。

今天就分享到这里啦！~~~