exaudio - 音频扩展库
作者：梁健
一、概述
exaudio 是 audio 的扩展库，简化了使用方法，扩展了部分应用，建议使用此库. 音频框架如下：
合宙仅Air780EHV 内置音频编解码芯片，其他支持音频的功能需要外置音频编解码芯片。
目前合宙所有的型号均需要外置音频放大器(PA)才可将音频输出。
目前在支持播放的文件格式有mp3,amr,pcm,wav 支持流式播放(仅支持pcm 格式)
支持录音格式为amr,pcm 支持流式录音(仅支持pcm录音)
二、核心示例
2.1 播放
local audio_setup_param ={
model= "es8311", -- 音频编解码类型,可填入"es8311","es8211"
i2c_id = 0, -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚
pa_ctrl = 162, -- 音频放大器电源控制管脚
dac_ctrl = 164, -- 音频编解码芯片电源控制管脚
}
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 是播放单个音频文件,如果是表则是播放多段音频文件。
}
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","es8211"
i2c_id = 0, -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚
pa_ctrl = 162, -- 音频放大器电源控制管脚
dac_ctrl = 164, -- 音频编解码芯片电源控制管脚
}
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
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 : 仅录音时有用，表示使用8000/16000/24000/32000/秒 的速度对音频进行采样
四、函数详解
exaudio.setup(audioConfigs)
功能
初始化audio,配置关于编解码芯片,音频放大器的电源,编解码芯片的采样率，采样深度相关的功能
注意事项
1. 该接口只能也只需启动一次
2. 强烈建议编解码芯片以及音频放大器的电源由模组控制，这样才能有效降低pop 音，体验更好
3. 目前仅支持8311/8211 音频编解码，其中8211 不支持录音，也无需选择I2C 接口
4. 如果选择了8311 则必须填写I2C 的端口，并在pins 工具配置 luatio
5. 如果出现:"ES8311通讯失败，请检查硬件" 的打印，请检查硬件，很大可能是焊接不良，如果解决不了，可寻求合宙官方解决
6. audioConfig 入参是一个表，有如下参数：
model = "es8311", -- dac类型: "es8311","es8211"
i2c_id = 0, -- i2c_id: 0,1
pa_ctrl = 0, -- 音频放大器电源控制管脚
dac_ctrl = 0, -- 音频编解码芯片电源控制管脚
dac_delay = 3, -- DAC启动前冗余时间(单位100ms)
pa_delay = 100, -- DAC启动后延迟打开PA的时间(单位1ms)
dac_time_delay = 600, -- 播放完毕后PA与DAC关闭间隔(单位1ms)
bits_per_sample = 16, -- 采样位深
pa_on_level = 1 -- PA打开电平 1:高 0:低
参数
model
参数含义：音频编解码芯片(音频的数模或者模数转换)
数据类型：string；
取值范围：es8311/es8211；
是否必选：必选传入此参数；
注意事项：注意大小写，必须为小写
i2c_id
参数含义：和音频编解码芯片通讯的I2C 接口；
数据类型：number；
取值范围：0,1
是否必选：如果model 选择了es8311 则必填i2c_id；
注意事项：需要通过[luatio](https://docs.openluat.com/air780epm/common/luatio/) 配置自己使用的i2c 对应的管脚映射
pa_ctrl
参数含义：主控对音频放大器芯片电源控制的管脚；
数据类型：number；
取值范围：模块的GPIO 编号范围
是否必选：非必须；
注意事项：强烈建议使用IO 控制音频放大器的电源,配合编解码的电源，模块内的算法可有效降低pop 音
dac_ctrl
参数含义：主控对音频编解码芯片电源控制的管脚；
数据类型：number；
取值范围：模块的GPIO 编号范围
注意事项：强烈建议使用IO 控制音频编解码的电源,配合音频放大器的电源，模块内的算法可有效降低pop 音
dac_delay
参数含义：DAC启动前冗余时间；
数据类型：number；
取值范围：> 0
是否必选：非必须；
注意事项：DAC启动前冗余时间,单位为100ms,如果由pop 音根据实际的情况调整，一般不用设置。
pa_delay
```lua
参数含义：DAC启动后延迟打开PA的时间；
数据类型：number；
取值范围：> 0
是否必选：非必须；
是否必选：非必须；
注意事项：DAC启动后延迟打开PA的时间,单位为1ms,如果由pop 音根据实际的情况调整，一般不用设置,常规来说是先打开音频编解码延迟一段时间后再打开音频放大器。
dac_time_delay
参数含义：播放完毕后PA与DAC关闭间隔；
数据类型：number；
取值范围：> 0
是否必选：非必须；
注意事项：播放完毕后PA与DAC关闭间隔,单位为1ms,如果由pop 音根据实际的情况调整，一般不用设置。
bits_per_sample
参数含义：采样位数；
数据类型：number；
取值范围：8，16，24
是否必选：非必须；
注意事项：位深表示每个音频采样点用多少个二进制位（bit）来存储。它反映了数字音频对模拟信号振幅（音量）的量化精度 —— 位深越大，能表示的振幅等级越多，声音细节越丰富，但是对应的数据内容就越多，默认位16bit。
pa_on_level
参数含义：音频放大器芯片电源打开电平；
数据类型：number；
取值范围：1:高 0:低
是否必选：非必须；
注意事项：音频放大器芯片电源打开的电平高还是低，一般来说都是高。
返回值
返回true ,表示成功，返回false 表示失败
示例
local audio_setup_param ={
model= "es8311", -- 音频编解码类型,可填入"es8311","es8211"
i2c_id = 0, -- i2c_id,可填入0，1 并使用pins 工具配置对应的管脚
pa_ctrl = 162, -- 音频放大器电源控制管脚
dac_ctrl = 164, -- 音频编解码芯片电源控制管脚
}
if exaudio.setup(audio_setup_param) then
log.info("音频初始化成功")
end
exaudio.play_start(playConfigs)
功能
播放文件,流式播放
注意事项
1. 支持MP3,WAV,AMR(含AMR_NB,AMR_WB)的格式的文件音频播放
2. 支持TTS 播放，但只支持中文的TTS
3. 支持流式播放，但仅仅支持PCM 数据流
6. playConfigs 入参是一个表，有如下参数：
type = 0, -- 0:文件 1:TTS 2:流式
content = nil, -- 内容/回调函数
cbFnc = nil, -- 播放完毕回调
priority = 0, -- 优先级(数值越大越高)
sampling_Rate = 16000, -- 采样率(仅流式)
sampling_Depth = 16, -- 采样位深(仅流式)
signed_or_Unsigned = true -- PCM是否有符号(仅流式)
参数
type
参数含义：播放类型,有播放文件，播放TTS，流式播放三个方法
数据类型：number；
取值范围：0,1,2；
是否必选：必选传入此参数；
content
参数含义：播放的内容，或者回调函数地址
数据类型：string,function；
取值范围：无；
是否必选：必选传入此参数；
注意事项：
1. 当播放类型选择播放文件时候，content 内容必须填写string 类型的播放路径
2. 当播放类型为tts 的时候，content 内容必须填写string 类型，tts 仅支持文字转中文，相关格式请见：https://wiki.luatos.com/chips/air780e/tts.html?highlight=tts
3. 当播放类型为流式播放的时候，content 内容必须为function ，当core 播报快结束的时候，会调用此函数，lua的应用层需要在函数执行的时候，将数据当作返回值返回给core
cbFnc
参数含义：当播放完成后，会触发此函数
数据类型：function；
取值范围：无；
是否必选：非必须传入此参数；
注意事项：目前仅会返回exaudio.PLAY_DONE(播放完成消息)，不排除后面会增加其他的事件
priority
参数含义：播放优先级
数据类型：number；
取值范围：大于等于0；
是否必选：非必须传入此参数；
注意事项：优先级高于或者正在播放的音频，会让正在播放的音频停止播放，然后播放新的音频。
sampling_Rate
参数含义：采样率
数据类型：number；
取值范围：8000 - 96000；
是否必选：当type 选择了流式播放(2),必须传入此参数,其他播放不传入此参数；
注意事项：常规的音频都是8000，或者是16000
sampling_Depth
参数含义：采样位深
数据类型：number；
取值范围：8，16，24；
是否必选：当type 选择了流式播放(2),必须传入此参数,其他播放不传入此参数；
signed_or_Unsigned
参数含义：PCM的编码类型
数据类型：boolean；
取值范围：true,false；
是否必选：非必须传入此参数；
注意事项：默认是true,即有符号
返回值
返回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(recodConfigs)
功能 开始录音，录音到文件功能以及支持PCM 的流式录音
注意事项
1. 仅仅支持AMR_NB，AMR_WB,PCM(8000,16000,24000,32000) 的格式
2. 流式录音仅仅支持PCM 格式
6. recodConfigs 入参是一个表，有如下参数：
format = 0, -- 录制格式，支持exaudio.AMR_NB，exaudio.AMR_WB,exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000
time = 5, -- 录制时间(秒)
path = nil, -- 文件路径或流式回调
cbFnc = nil -- 录音完毕回调
参数
format
参数含义：录音格式
数据类型：number；
取值范围：exaudio.AMR_NB，exaudio.AMR_WB,exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000；
是否必选：必须传入此参数；
注意事项：如果要选择流式录音，仅支持(exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000)
time
参数含义：录音市场
数据类型：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
参数含义：文件路径，或者流式录音的回调函数
数据类型：string/function；
取值范围：无；
是否必选：必须传入此参数；
注意事项：
1. 如果是录音到文件，则传入文件路径
2. 如果是流式录音，则传入回调函数地址，format仅支持(exaudio.PCM_8000,exaudio.PCM_16000,exaudio.PCM_24000,exaudio.PCM_32000)
cbFnc
参数含义：当录制完成后，会触发此函数
数据类型：function；
取值范围：无；
是否必选：非必须传入此参数；
注意事项：目前仅会返回exaudio.RECORD_DONE(录音完成消息)，不排除后面会增加其他的事件
返回值
返回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
time = 5, -- 录制时间,单位(秒)
path = recordPath, -- 如果填入的是字符串，则表示是文件路径，录音会传输到这个路径里
-- 如果填入的是函数，则表示是流式录音，录音的数据会传输到此函数内,返回的是zbuf地址，以及数据长度
}
if exaudio.setup(audio_setup_param) then
exaudio.record_start(audio_record_param)
end
exaudio.play_stop()
功能
停止播放
注意事项 无
参数 无
返回值
返回true ,表示成功，返回false 表示失败
exaudio.is_end()
功能
判断是否播放完成
注意事项 无
参数 无
返回值
返回true ,表示播放完成，返回false 表示播放未完成
exaudio.record_stop()
功能
停止录音
注意事项 无
参数 无
返回值
返回true ,表示成功，返回false 表示失败
exaudio.vol(number)
功能
设置播放音量
注意事项 无
参数
参数含义：设置播放音量
数据类型：number；
取值范围：0 - 100 ；
是否必选：必须传入此参数；
注意事项：音量太大可能会导致喇叭声音过爆，喇叭的功率需要和音频放大器的功率匹配
返回值
返回true ,表示成功，返回false 表示失败
exaudio.mic_vol(number)
功能
设置录音音量
注意事项 无
参数
参数含义：设置录音音量
数据类型：number；
取值范围：0 - 100 ；
是否必选：必须传入此参数；
返回值
返回true ,表示成功，返回false 表示失败
五、产品支持说明
780epm,780ehv,780eth,8000 全系列均支持