5 audio_v2-新音频框架(仅用于理解exaudio实现)
作者:拓毅恒 | 最后修改:2026-10-27
重要说明
本文档列出
audio_v2新音频框架的底层 API,仅用于理解 exaudio.lua 扩展库的源码实现。如果要在项目中开发音频功能,请直接使用 exaudio 扩展库,不要直接调用
audio_v2底层 API。exaudio封装了audio(旧框架)和audio_v2(新框架)的差异,提供了统一、稳定的接口。详细说明请参考
exaudio.md文档。
一、概述
audio_v2 是 LuatOS 的新音频框架,提供统一的音频播放、录音、编解码和驱动管理能力。音频框架如下:
应用层(exaudio扩展库)
↓
audio_v2 新音频框架
↓
驱动层(ES8311/DAC/I2S等)
audio_v2 支持以下音频编解码器:
- RAW/PCM(原始音频数据)
- WAV(波形音频文件)
- AMR-NB / AMR-WB(自适应多速率编码)
- MP3(MPEG Audio Layer 3)
- TTS(文字转语音)
二、常量详解
2.1 驱动类型常量(用于 make_probe_id)
| 常量名 | 值 | 说明 |
| `audio_v2.DRIVER_TYPE_NONE` | 0 | 无驱动类型 |
| `audio_v2.DRIVER_TYPE_I2S` | 1 | I2S 接口驱动 |
| `audio_v2.DRIVER_TYPE_DAC` | 2 | DAC 接口驱动(仅播放) |
| `audio_v2.DRIVER_TYPE_ADC` | 3 | ADC 接口驱动(仅录音) |
| `audio_v2.DRIVER_TYPE_USB` | 4 | USB 音频驱动 |
2.2 编解码器类型常量(用于 play 的 codec_id,以及 stream 的 codec_id)
| 常量名 | 值 | 说明 |
| `audio_v2.DATA_CODEC_TYPE_RAW` | 0 | 原始音频数据 |
| `audio_v2.DATA_CODEC_TYPE_WAV` | 1 | WAV 格式 |
| `audio_v2.DATA_CODEC_TYPE_AMR_NB` | 2 | AMR-NB(窄带) |
| `audio_v2.DATA_CODEC_TYPE_AMR_WB` | 3 | AMR-WB(宽带) |
| `audio_v2.DATA_CODEC_TYPE_TTS` | 4 | TTS 文字转语音 |
| `audio_v2.DATA_CODEC_TYPE_MP3` | 5 | MP3 格式 |
| `audio_v2.DATA_CODEC_TYPE_OPUS` | 6 | OPUS 格式(需固件编入 OPUS 支持) |
| `audio_v2.DATA_CODEC_TYPE_G711_ULAW` | 7 | G711 μ-law(8kHz,电话链路常用) |
| `audio_v2.DATA_CODEC_TYPE_G711_ALAW` | 8 | G711 A-law(8kHz) |
| `audio_v2.DATA_CODEC_TYPE_VOIP_PCM` | 15 | VOIP 专用 PCM 直通编解码器(不做编解码,直接透传) |
| `audio_v2.DATA_CODEC_TYPE_G729` | 16 | G.729 8kHz(Annex A+B) |
| `audio_v2.DATA_CODEC_TYPE_G722` | 17 | G.722 16kHz 宽带(64kbps) |
| `audio_v2.DATA_CODEC_TYPE_HW` | 128(0x80) | 硬件编解码器优先模式,可以和上面的类型按位或使用 |
2.3 驱动配置常量(用于 audio_v2.config 的 config_param)
| 常量名 | 值 | 说明 |
| `audio_v2.CFG_PARAM_I2S_MODE` | 0 | I2S 模式配置参数键 |
| `audio_v2.CFG_PARAM_I2S_FRAME_BITS` | 1 | I2S 帧位宽配置参数键 |
| `audio_v2.CFG_PARAM_I2S_CHANNEL_TYPE` | 2 | I2S 通道类型配置参数键 |
| `audio_v2.CFG_PARAM_DAC_BIT_WIDTH` | 3 | DAC 位宽配置参数键 |
| `audio_v2.CFG_PARAM_ADC_DIG_GAIN` | 0x424B0101 | ADC 数字增益参数键,仅 Air8101(BK7258) 有效 |
| `audio_v2.CFG_PARAM_ADC_ANA_GAIN` | 0x424B0102 | ADC 模拟增益参数键,仅 Air8101(BK7258) 有效 |
2.4 驱动配置值常量(用于 audio_v2.config 的 config_value1)
| 常量名 | 值 | 说明 |
| `audio_v2.CFG_VALUE_I2S_MODE_I2S` | 0 | I2S 标准模式 |
| `audio_v2.CFG_VALUE_I2S_MODE_LSB` | 1 | LSB(左对齐)模式 |
| `audio_v2.CFG_VALUE_I2S_MODE_MSB` | 2 | MSB(右对齐)模式 |
| `audio_v2.CFG_VALUE_I2S_MODE_PCMS` | 3 | PCM 短帧标准 |
| `audio_v2.CFG_VALUE_I2S_MODE_PCML` | 4 | PCM 长帧标准 |
| `audio_v2.CFG_VALUE_I2S_CHANNEL_TYPE_MONO` | 0 | 单声道类型 |
| `audio_v2.CFG_VALUE_I2S_CHANNEL_TYPE_LEFT` | 0 | 左声道类型 |
| `audio_v2.CFG_VALUE_I2S_CHANNEL_TYPE_RIGHT` | 1 | 右声道类型 |
| `audio_v2.CFG_VALUE_I2S_CHANNEL_TYPE_STEREO` | 2 | 立体声类型 |
2.5 请求事件常量(用于 audio_v2.on 回调)
| 常量名 | 值 | 说明 |
| `audio_v2.REQUEST_START` | 0 | 请求开始事件 |
| `audio_v2.REQUEST_DRIVER_START` | 1 | 驱动开始事件 |
| `audio_v2.REQUEST_TTS_START` | 2 | TTS 开始事件 |
| `audio_v2.REQUEST_NEED_PLAY_INFO` | 3 | 播放需要播放信息事件 |
| `audio_v2.REQUEST_NEED_NEW_DATA` | 4 | 需要新数据事件(流式播放) |
| `audio_v2.REQUEST_GET_NEW_DATA` | 5 | 获取新数据事件(录音) |
| `audio_v2.REQUEST_DECODE_DONE` | 6 | 解码完成事件 |
| `audio_v2.REQUEST_END` | 7 | 请求结束事件 |
| `audio_v2.EXT_SRC_DONE` | 8 | 外部音频源(extern_source)解码完成事件 |
2.6 驱动参数常量(用于 get_driver_param 的 param)
| 常量名 | 值 | 说明 |
| `audio_v2.DRIVER_PARAM_TX_MAX_LEN` | 0 | 播放方向单次最大缓存长度 |
| `audio_v2.DRIVER_PARAM_RX_MAX_LEN` | 1 | 录音方向单次最大缓存长度 |
2.7 编解码器参数常量(用于 get_codec_param 的 param)
| 常量名 | 值 | 说明 |
| `audio_v2.DATA_CODEC_PARAM_ENCODE_INPUT_LEN` | 0 | 编码 1 帧需要喂入的 PCM 字节数,流式编码前先用它算好每次喂多少 |
2.8 DSP 类型常量(用于 speech 的 dsp_type)
| 常量名 | 值 | 说明 |
| `audio_v2.DSP_TYPE_SPEEXDSP` | 0 | SpeexDSP 音频处理(回声消除/降噪/AGC),也是 BSP 的默认值 |
三、函数详解
audio_v2.on(func)
功能
注册 audio 事件回调,注册 audio_v2 事件回调函数。当播放、录音或流式操作有事件发生时,会调用此回调。
参数
func
参数含义:回调方法;
数据类型:function;
取值范围:无;
是否必选:必须传入此参数;
注意事项:回调函数参数说明:
---@param int 请求索引
---@param int 事件类型,见"2.5 请求事件常量"
---@param int 附加参数,根据事件类型不同,有不同的含义,有如下组合
event和param可能出现的值:
audio_v2.REQUEST_START 开始处理请求,param无意义
audio_v2.REQUEST_NEED_NEW_DATA 需要新的数据,param无意义
audio_v2.REQUEST_GET_NEW_DATA 获取到新数据,param为本次回调获取到的驱动数据大小
audio_v2.REQUEST_DECODE_DONE 请求处理完成,param无意义
audio_v2.REQUEST_END 请求块处理完成,param无意义
参数示例:
{
--request_index
-- 参数含义:请求索引;
-- 数据类型:number;
-- 取值范围:0~255;
-- 是否必选:是;
-- 注意事项:通过audio_v2.play、audio_v2.stream等返回的请求索引;
-- 参数示例:1,请求索引1;
--event
-- 参数含义:事件类型;
-- 数据类型:number;
-- 取值范围:audio_v2.REQUEST_xxx常量;
-- 是否必选:是;
-- 注意事项:见audio_v2.REQUEST_xxx常量说明;
-- 参数示例:audio_v2.REQUEST_NEED_NEW_DATA -- 需要新数据;
--param
-- 参数含义:附加参数;
-- 数据类型:number;
-- 取值范围:根据事件类型不同而不同;
-- 是否必选:是;
-- 注意事项:根据事件类型不同,有不同的含义;
-- 参数示例:0 -- 无意义;
}
返回值
无
例子
audio_v2.on(function(request_index, event, param)
log.info(request_index, event, param)
end)
audio_v2.config(config_param, config_value1, config_value2, driver_probe_id)
功能
配置音频驱动的参数
参数
config_param
参数含义:参数索引;
数据类型:number;
取值范围:audio_v2.CFG_PARAM_xxx常量;
是否必选:必须传入此参数;
注意事项:见"2.3 驱动配置常量";
参数示例:audio_v2.CFG_PARAM_I2S_MODE,I2S模式配置参数键;
config_value1
参数含义:驱动参数值1;
数据类型:number;
取值范围:audio_v2.CFG_VALUE_xxx常量或者直接填写数值;
是否必选:必须传入此参数;
注意事项:见"2.4 驱动配置值常量";
参数示例:audio_v2.CFG_VALUE_I2S_MODE_LSB,LSB(左对齐)模式;
config_value2
参数含义:驱动参数值2;
数据类型:number;
取值范围:audio_v2.CFG_VALUE_xxx常量或者直接填写数值;
是否必选:可选传入此参数;
注意事项:见"2.4 驱动配置值常量";
参数示例:16,I2S帧位宽;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
返回值
local result = audio_v2.config(config_param, config_value1, config_value2, driver_probe_id)
含义说明:配置是否成功;
数据类型:boolean;
取值范围:true表示成功,false表示失败;
返回示例:true -- 配置成功
例子
audio_v2.config(audio_v2.CFG_PARAM_I2S_MODE, audio_v2.CFG_VALUE_I2S_MODE_LSB)
audio_v2.config(audio_v2.CFG_PARAM_I2S_FRAME_BITS, 16)
audio_v2.config(audio_v2.CFG_PARAM_I2S_CHANNEL_TYPE, audio_v2.CFG_VALUE_I2S_CHANNEL_TYPE_RIGHT)
audio_v2.config_pa_power_ctrl(pa_power_ctrl_enable, pa_power_pin, pa_power_on_level, pa_power_on_delay_time_ms, driver_probe_id)
功能
配置音频驱动的 pa 电源控制
参数
pa_power_ctrl_enable
参数含义:是否使能pa电源控制;
数据类型:boolean;
取值范围:true使能,false不使能;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:true,使能pa电源控制;
pa_power_pin
参数含义:pa电源引脚;
数据类型:number;
取值范围:模块的GPIO编号范围;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:12,GPIO12;
pa_power_on_level
参数含义:pa电源电平;
数据类型:number;
取值范围:1表示高电平,0表示低电平;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:1,高电平使能;
pa_power_on_delay_time_ms
参数含义:pa电源开启延时时间;
数据类型:number;
取值范围:0~10000;
是否必选:必须传入此参数;
注意事项:单位毫秒;
参数示例:100,延时100ms;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
返回值
local result = audio_v2.config_pa_power_ctrl(pa_power_ctrl_enable, pa_power_pin, pa_power_on_level, pa_power_on_delay_time_ms, driver_probe_id)
含义说明:配置是否成功;
数据类型:boolean;
取值范围:true表示成功,false表示失败;
返回示例:true -- 配置成功
例子
audio_v2.config_pa_power_ctrl(true, 12, 1, 100)
audio_v2.make_probe_id(tx_bus_type, tx_bus_id, rx_bus_type, rx_bus_id)
功能
合成音频驱动 id。
注意事项
1、所有产品都有默认的驱动,一般无需设置 2、只有在不想用默认驱动时需要设置(比如 Air1602 引擎板 V0004 上是 DAC+I2S2,想用 I2S2 接 ES8311,但默认是 DAC)
参数
tx_bus_type
参数含义:发送总线类型;
数据类型:number;
取值范围:audio_v2.DRIVER_TYPE_xxx常量;
是否必选:必须传入此参数;
注意事项:见audio_v2.DRIVER_TYPE_xxx常量;
参数示例:audio_v2.DRIVER_TYPE_I2S,I2S驱动类型;
tx_bus_id
参数含义:发送总线id;
数据类型:number;
取值范围:0~255;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:0,总线id为0;
rx_bus_type
参数含义:接收总线类型;
数据类型:number;
取值范围:audio_v2.DRIVER_TYPE_xxx常量;
是否必选:必须传入此参数;
注意事项:见audio_v2.DRIVER_TYPE_xxx常量;
参数示例:audio_v2.DRIVER_TYPE_I2S,I2S驱动类型;
rx_bus_id
参数含义:接收总线id;
数据类型:number;
取值范围:0~255;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:0,总线id为0;
返回值
local probe_id = audio_v2.make_probe_id(tx_bus_type, tx_bus_id, rx_bus_type, rx_bus_id)
含义说明:合成的驱动id。驱动id由4个uint8_t字段打包成uint32_t:
tx_bus_type占[7:0]位,tx_bus_id占[15:8]位,
rx_bus_type占[23:16]位,rx_bus_id占[31:24]位;
数据类型:number;
取值范围:0~4294967295(uint32_t全范围);
返回示例:65537 -- 即0x00010001,表示I2S0双工(I2S,0,I2S,0)
例子
-- 驱动id = 0x00010001 = 65537,含义:I2S总线0发送 + I2S总线0接收(I2S0双工)
probe_id = audio_v2.make_probe_id(audio_v2.DRIVER_TYPE_I2S, 0, audio_v2.DRIVER_TYPE_I2S, 0)
-- 驱动id = 0x00000002 = 2,含义:DAC总线0发送 + 无接收(DAC0单工)
probe_id = audio_v2.make_probe_id(audio_v2.DRIVER_TYPE_DAC, 0, audio_v2.DRIVER_TYPE_NONE, 0)
audio_v2.set_default_driver(driver_probe_id)
功能
设置默认驱动
参数
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~65535;
是否必选:必须传入此参数;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,驱动id为0;
返回值
local result = audio_v2.set_default_driver(driver_probe_id)
含义说明:设置是否成功;
数据类型:boolean;
取值范围:true表示成功,false表示失败;
返回示例:true -- 设置成功
例子
local driver_probe_id = audio_v2.make_probe_id(audio_v2.DRIVER_TYPE_I2S, 0, audio_v2.DRIVER_TYPE_I2S, 0)
audio_v2.set_default_driver(driver_probe_id)
audio_v2.shutdown(driver_power_off, codec_power_off, pa_power_off, driver_probe_id)
功能
音频驱动休眠控制
参数
driver_power_off
参数含义:是否关闭驱动;
数据类型:boolean;
取值范围:true关闭驱动,false不关闭驱动;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:true,关闭驱动;
codec_power_off
参数含义:是否关闭外部codec;
数据类型:boolean;
取值范围:true关闭外部codec,false不关闭外部codec;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:true,关闭外部codec;
pa_power_off
参数含义:是否关闭pa;
数据类型:boolean;
取值范围:true关闭pa,false不关闭pa;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:true,关闭pa;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
返回值
无
例子
audio_v2.shutdown(true, true, true)
audio_v2.play(path, err_stop, priority, driver_probe_id, codec_id)
功能
播放音频文件
参数
path
参数含义:播放内容;
数据类型:string/table/zbuff;
取值范围:如果是string,则表示文件名;如果是table,则表示连续播放多个文件;如果是zbuff,则表示播放zbuff中的数据;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:"/luadb/test.mp3",播放文件;
err_stop
参数含义:是否在文件解码失败后停止解码;
数据类型:boolean;
取值范围:true遇到解码错误自动停止,false遇到解码错误跳过继续播放下一个文件;
是否必选:可选传入此参数;默认true;
注意事项:只有在连续播放多个文件时才有用;
参数示例:true,解码错误自动停止;
priority
参数含义:优先级;
数据类型:number;
取值范围:0~255,值越大优先级越高;
是否必选:可选传入此参数;默认0;
注意事项:暂无;
参数示例:0,普通优先级;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
codec_id
参数含义:解码器id;
数据类型:number;
取值范围:audio_v2.DATA_CODEC_TYPE_xxx常量;
是否必选:可选传入此参数;在需要指定解码器时填写,绝大部分情况下都不需要填写;
注意事项:见audio_v2.DATA_CODEC_TYPE_xxx常量;
参数示例:audio_v2.DATA_CODEC_TYPE_MP3,MP3解码器;
返回值
local result, request_index = audio_v2.play(path, err_stop, priority, driver_probe_id, codec_id)
含义说明:result表示播放是否成功启动,request_index表示请求索引,用于后续操作;
数据类型:boolean, int;
取值范围:result为true表示成功,false表示失败;request_index为0~255;
返回示例:true, 1 -- 播放启动成功,请求索引为1
例子
audio_v2.play("/luadb/test.mp3") -- 开始播放某个文件
audio_v2.tts(text, priority, driver_probe_id)
功能
TTS 文字转语音播放
参数
text
参数含义:需要播放的内容;
数据类型:string/zbuff;
取值范围:无;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:"你好",播放文本;
priority
参数含义:优先级;
数据类型:number;
取值范围:0~255,值越大优先级越高;
是否必选:可选传入此参数;默认0;
注意事项:暂无;
参数示例:0,普通优先级;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
返回值
local result, request_index = audio_v2.tts(text, priority, driver_probe_id)
含义说明:result表示播放是否成功启动,request_index表示请求索引,用于后续操作;
数据类型:boolean, int;
取值范围:result为true表示成功,false表示失败;request_index为0~255;
返回示例:true, 1 -- 播放启动成功,请求索引为1
例子
audio_v2.tts("你好,测试一下") -- 开始播放TTS
audio_v2.stream(codec_id, sample_rate, data_bits, channel_nums, is_signed, priority, driver_probe_id)
功能
启动流式播放
参数
codec_id
参数含义:解码器id;
数据类型:number;
取值范围:audio_v2.DATA_CODEC_TYPE_xxx常量,不能留空;
是否必选:必须传入此参数;
注意事项:见audio_v2.DATA_CODEC_TYPE_xxx常量;
参数示例:audio_v2.DATA_CODEC_TYPE_RAW,原始音频数据;
sample_rate
参数含义:采样率;
数据类型:number;
取值范围:8000、16000、24000、32000、48000等;
是否必选:必须传入此参数,不能留空;
注意事项:暂无;
参数示例:16000,16K采样率;
data_bits
参数含义:数据位数;
数据类型:number;
取值范围:8、16、24、32;
是否必选:必须传入此参数,不能留空;
注意事项:暂无;
参数示例:16,16位数据;
channel_nums
参数含义:通道数;
数据类型:number;
取值范围:1(单声道)、2(立体声);
是否必选:必须传入此参数,不能留空;
注意事项:暂无;
参数示例:1,单声道;
is_signed
参数含义:是否有符号数据;
数据类型:boolean;
取值范围:true有符号数据,false无符号数据;
是否必选:可选传入此参数;默认true;
注意事项:暂无;
参数示例:true,有符号数据;
priority
参数含义:优先级;
数据类型:number;
取值范围:0~255,值越大优先级越高;
是否必选:可选传入此参数;默认0;
注意事项:暂无;
参数示例:0,普通优先级;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:nil,使用默认驱动;
返回值
local result, request_index = audio_v2.stream(codec_id, sample_rate, data_bits, channel_nums, is_signed, priority, driver_probe_id)
含义说明:result表示播放是否成功启动,request_index表示请求索引,用于后续操作;
数据类型:boolean, int;
取值范围:result为true表示成功,false表示失败;request_index为0~255;
返回示例:true, 1 -- 流式播放启动成功,请求索引为1
例子
-- 播放16000Hz, 16bit, 2ch, 有符号的PCM数据流
local result, index = audio_v2.stream(audio_v2.DATA_CODEC_TYPE_RAW, 16000, 16, 2, true, 0, nil)
audio_v2.input(request_or_source_index, data, is_end)
功能
向流式播放输入数据
参数
request_or_source_index
参数含义:请求索引或外部源索引;
数据类型:number;
取值范围:0~255;
是否必选:必须传入此参数;
注意事项:通过audio_v2.stream或者audio_v2.extern_source返回的索引;
参数示例:1,请求索引为1;
data
参数含义:输入数据;
数据类型:string/zbuff;
取值范围:无;
是否必选:可选传入此参数;如果为空,则不输入任何数据;
注意事项:如果数据是zbuff形式,写入成功后会自动删除zbuff中的数据;
参数示例:nil,不输入数据;
is_end
参数含义:是否是最后一帧数据;
数据类型:boolean;
取值范围:true是最后一帧数据,false不是最后一帧数据;
是否必选:可选传入此参数;默认false;
注意事项:暂无;
参数示例:false,不是最后一帧;
返回值
local result, write_len, free_len = audio_v2.input(request_or_source_index, data, is_end)
含义说明:result表示是否成功,write_len表示实际写入的长度,free_len表示输入缓冲的剩余空间;
数据类型:boolean, int, int;
取值范围:result为true表示成功,false表示失败;write_len为0表示未写入数据;free_len为缓冲剩余空间;
返回示例:true, 1024, 4096 -- 成功写入1024字节,剩余4096字节
例子
local result, write_len, free_len = audio_v2.input(request_index, data, is_end)
audio_v2.record(save_buffer, record_callback_cnt, codec_id, priority, sample_rate, data_bits, channel_nums, driver_probe_id)
功能
开始录音
参数
save_buffer
参数含义:保存路径;
数据类型:string/zbuff;
取值范围:string为保存成文件,zbuff为保存到buffer并回调给用户;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:"/save.amr",保存到文件;
record_callback_cnt
参数含义:录音参数;
数据类型:int;
取值范围:如果是保存文件,则为整体录音时间,单位秒;如果是保存到buffer,则为每次回调的帧数,每一帧时间由编码器决定;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:10,录音10秒或每10帧回调一次;
codec_id
参数含义:编码器id;
数据类型:int;
取值范围:audio_v2.DATA_CODEC_TYPE_xxx常量,如果留空则直接返回原始PCM数据;
是否必选:必须传入此参数;
注意事项:如果指定了codec_id,会检查sample_rate和data_bits是否符合解码器的要求;
参数示例:audio_v2.DATA_CODEC_TYPE_AMR_WB,AMR-WB编码器;
priority
参数含义:优先级;
数据类型:number;
取值范围:0~255,值越大优先级越高;
是否必选:可选传入此参数;默认0;
注意事项:暂无;
参数示例:0,普通优先级;
sample_rate
参数含义:希望的采样率;
数据类型:number;
取值范围:8000、16000、24000、32000、48000等;
是否必选:可选传入此参数;如果指定了codec_id则可以留空,由编码器自己决定;
注意事项:暂无;
参数示例:16000,16K采样率;
data_bits
参数含义:希望的数据位数;
数据类型:number;
取值范围:8、16、24、32;
是否必选:可选传入此参数;如果指定了codec_id则可以留空,由编码器自己决定;
注意事项:暂无;
参数示例:16,16位数据;
channel_nums
参数含义:希望的通道数;
数据类型:number;
取值范围:1(单声道)、2(立体声);
是否必选:可选传入此参数;如果指定了codec_id则可以留空,由编码器自己决定;
注意事项:暂无;
参数示例:1,单声道;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
返回值
local result, request_index = audio_v2.record(save_buffer, record_callback_cnt, codec_id, priority, sample_rate, data_bits, channel_nums, driver_probe_id)
含义说明:result表示录音是否成功启动,request_index表示请求索引,用于后续操作;
数据类型:boolean, int;
取值范围:result为true表示成功,false表示失败;request_index为0~255;
返回示例:true, 1 -- 录音启动成功,请求索引为1
例子
-- 录音到buffer并回调给用户,编码器为AMR_WB,优先级为0,每10帧回调一次
local result, request_index = audio_v2.record(save_buffer, 10, audio_v2.DATA_CODEC_TYPE_AMR_WB)
-- 录音到文件,编码器为AMR_WB,优先级为0,录音10秒结束
local result, request_index = audio_v2.record("/save.amr", 10, audio_v2.DATA_CODEC_TYPE_AMR_WB)
audio_v2.stop(request_index)
功能
停止播放或录音
参数
request_index
参数含义:请求索引;
数据类型:number;
取值范围:0~255;
是否必选:必须传入此参数;
注意事项:通过audio_v2.play_files,audio_v2.stream,audio_v2.speech,audio_v2.record, audio_v2.tts或者audio_v2.extern_source返回;
参数示例:1,请求索引为1;
返回值
无
例子
local result, index = audio_v2.play("/luadb/test.mp3")
audio_v2.stop(index)
audio_v2.is_all_done()
功能
检查是否所有请求都已完成
参数
无
返回值
local is_all_done = audio_v2.is_all_done()
含义说明:所有请求是否完成;
数据类型:boolean;
取值范围:true所有请求已完成,false仍有请求在运行;
返回示例:true -- 所有请求已完成
例子
is_all_done = audio_v2.is_all_done()
audio_v2.get_play_info(data, codec_id, pos)
功能
获取音频文件的播放信息
参数
data
参数含义:输入数据;
数据类型:string/zbuff;
取值范围:无;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:file_data,音频文件数据;
codec_id
参数含义:解码器id;
数据类型:number;
取值范围:audio_v2.DATA_CODEC_TYPE_xxx常量,不能留空;
是否必选:必须传入此参数;
注意事项:见audio_v2.DATA_CODEC_TYPE_xxx常量;
参数示例:audio_v2.DATA_CODEC_TYPE_MP3,MP3解码器;
pos
参数含义:当前输入数据在整个文件的位置;
数据类型:number;
取值范围:0~文件长度;
是否必选:必须传入此参数;
注意事项:单位字节;
参数示例:0,文件起始位置;
返回值
local no_error, next_pos, need_len, sample_rate, data_bits, channel_nums, is_signed = audio_v2.get_play_info(data, codec_id, pos)
含义说明:no_error表示无错误,next_pos表示需要跳转到的新位置,need_len表示需要获取的数据长度,sample_rate表示采样率,data_bits表示数据位数,channel_nums表示通道数,is_signed表示是否有符号数据;
数据类型:boolean, int, int, int, int, int, boolean;
取值范围:no_error为true表示无错误,false表示错误;返回true还需要看后续音频数据中采样率是否为0,不为0则说明获取成功了;next_pos为音频数据的真正起始位置,需要seek这个位置;need_len为还需要获取的数据长度;sample_rate为0则说明没有获取到有效信息;
返回示例:true, 0, 0, 16000, 16, 1, true -- 获取成功,16K采样率,16位,单声道,有符号
例子
local no_error, next_pos, need_len, sample_rate, data_bits, channel_nums, is_signed = audio_v2.get_play_info(data, codec_id, pos)
audio_v2.soft_volume(volume, driver_probe_id)
功能
设置软件音量增益
参数
volume
参数含义:软件音量增益;
数据类型:number;
取值范围:0~1000,值越大音量越高,默认100;
是否必选:必须传入此参数;
注意事项:1000就是10倍音量;
参数示例:75,音量增益75;
driver_probe_id
参数含义:驱动id;
数据类型:number;
取值范围:0~255;
是否必选:可选传入此参数;在不使用默认驱动时填写,绝大部分情况下都不需要填写;
注意事项:驱动id需要通过audio_v2.make_probe_id合成;
参数示例:0,使用默认驱动;
返回值
local result = audio_v2.soft_volume(volume, driver_probe_id)
含义说明:设置是否成功;
数据类型:boolean;
取值范围:true表示成功,false表示失败;
返回示例:true -- 设置成功
例子
audio_v2.soft_volume(75)
audio_v2.pause(request_index, pause)
功能
暂停或恢复某个播放 / TTS / 对讲请求。
参数
request_index
参数含义:请求索引,audio_v2.play / tts / stream / speech 的返回值;
数据类型:number;
是否必选:必须传入此参数;
参数示例:0
pause
参数含义:是否暂停;
数据类型:boolean;
是否必选:可选,默认 false(即恢复播放);
参数示例:true
返回值
无返回值(nil)。
示例
local req = audio_v2.play("/luadb/test.mp3")
sys.wait(1000)
audio_v2.pause(req, true) -- 暂停
sys.wait(2000)
audio_v2.pause(req, false) -- 恢复
注意事项
- 暂停只是停住数据消费,请求本身还在,不要再用
audio_v2.play重新开一路; - 要彻底结束用
audio_v2.stop(request_index)。
audio_v2.debug(on_off)
功能
开关 audio_v2 的调试信息输出。
参数
on_off
参数含义:true 开,false 关;
数据类型:boolean;
是否必选:必须传入此参数;
参数示例:true
返回值
无返回值(nil)。
示例
audio_v2.debug(true) -- 打开调试信息
-- ... 复现问题 ...
audio_v2.debug(false) -- 关闭
注意事项
- 调试打印会明显影响音频实时性,排查完必须关掉,不要留在量产脚本里。
audio_v2.is_busy(request_index)
功能
判断某个请求块当前是否还在处理中。
参数
request_index
参数含义:请求索引,audio_v2.play / stream / record / speech 的返回值;
数据类型:number;
是否必选:可选,默认 0;
参数示例:audio_v2.is_busy(1)
返回值
is_busy
含义说明:该请求块是否正在处理,true 表示还在跑;
数据类型:boolean;
示例
local req = audio_v2.play("/luadb/test.mp3")
-- 忙等(实际项目建议用 audio_v2.on 回调,不要在这里死等)
while audio_v2.is_busy(req) do
sys.wait(100)
end
log.info("audio", "播放结束")
注意事项
- 这是“查状态”接口,不阻塞,适合放在定时器里做状态轮询;
- 正常业务建议用
audio_v2.on的REQUEST_END事件判断结束,比轮询更省电。
audio_v2.get_play_clock(request_index)
功能
查询基于音频 DMA 实际消费量计算的播放时钟。做音画同步、字幕对时、录音回放对齐时用它,比用 sys.timer 自己数时间准。
参数
request_index
参数含义:audio_v2.play / stream 返回的请求索引;
数据类型:number;
是否必选:必须传入此参数;
参数示例:0
返回值
clock
含义说明:播放时钟表,字段如下:
played_samples 已真正播放出去的样本数
sample_rate 当前采样率
buffered_samples 还压在缓冲里没播的样本数
underruns 欠载次数(>0 说明喂数据喂慢了,会听到卡顿)
running 是否还在播放
pts_ms 换算出的播放时间戳(毫秒)
数据类型:table;
示例
local req = audio_v2.play("/luadb/test.mp3")
sys.wait(1000)
local c = audio_v2.get_play_clock(req)
log.info("audio", "已播放", c.pts_ms, "ms", "欠载", c.underruns)
-- 用 pts_ms 去对齐字幕/画面即可
注意事项
pts_ms是按实际消费量算的,比“开始播放到现在”更贴近耳朵听到的位置;underruns持续增长说明流式喂数据跟不上,要么加大每次喂的量,要么降低码率。
audio_v2.make_head(record_codec_id, total_len, sample_rate, data_bits, channel_nums)
功能
给一段录音数据生成文件头(WAV 头之类),把裸数据变成能被电脑直接播放的文件。
参数
record_codec_id
参数含义:录音编码器 id,见 audio_v2.DATA_CODEC_TYPE_XXX;
数据类型:number;
是否必选:必须传入此参数,绝对不可以留空;
参数示例:audio_v2.DATA_CODEC_TYPE_WAV
total_len
参数含义:音频数据的实际总长度(不含头),单位字节;
数据类型:number;
是否必选:必须传入此参数;
参数示例:32000
sample_rate
参数含义:采样率;
数据类型:number;
是否必选:可选;固定采样率的编码器可以留空,由编码器自己决定;
参数示例:16000
data_bits
参数含义:数据位宽,8/16/24/32;
数据类型:number;
是否必选:可选;固定位宽的编码器可以留空;
参数示例:16
channel_nums
参数含义:通道数,1/2;
数据类型:number;
是否必选:可选;固定通道数的编码器可以留空;
参数示例:1
返回值
result, head
result 含义说明:成功返回 true,失败返回 false;数据类型:boolean;
head 含义说明:生成的头信息字节串,失败返回 nil;数据类型:string;
示例
-- 录完音后先写头,再写数据
local total = #pcm_data
local ok, head = audio_v2.make_head(audio_v2.DATA_CODEC_TYPE_WAV, total, 16000, 16, 1)
if ok then
local f = io.open("/luadb/rec.wav", "wb")
f:write(head)
f:write(pcm_data)
f:close()
end
注意事项
- 头里的长度字段是按
total_len写死的,所以必须先知道总长度再生成头; 边录边写文件时要录完回头补头,或者预留头位置后回写; - 编码器不支持生成头时(如 AMR 有自己的存储格式),会返回 false + nil。
audio_v2.stop_driver(driver_probe_id)
功能
同步停止空闲音频驱动的数据传输,但保留驱动供电和 I2C 配置。适合“暂时不用音频,但不想重新初始化 codec”的场合。
参数
driver_probe_id
参数含义:驱动 id,由 audio_v2.make_probe_id 合成;
数据类型:number;
是否必选:可选,默认使用当前驱动;
参数示例:audio_v2.make_probe_id(audio_v2.DRIVER_TYPE_I2S, 0, audio_v2.DRIVER_TYPE_I2S, 0)
返回值
result
含义说明:无活动请求且驱动已停止返回 true;
数据类型:boolean;
示例
audio_v2.stop(request_index) -- 先停请求
audio_v2.stop_driver() -- 再停驱动,codec 仍然供电
注意事项
- 与
audio_v2.shutdown的区别:shutdown会按参数决定是否给 codec/PA 断电,本接口不断电; - 还有活动请求时调用不会强行中断,会返回 false。
audio_v2.get_driver_info()
功能
获取当前固件里注册了多少个音频驱动,以及默认驱动是哪一个。
参数
无
返回值
all_nums, default_driver_index
all_nums 含义说明:注册的音频驱动总数;数据类型:number;
default_driver_index 含义说明:默认音频驱动的索引,从 0 开始;数据类型:number;
示例
local all_nums, default_driver_index = audio_v2.get_driver_info()
log.info("audio", "驱动总数", all_nums, "默认驱动索引", default_driver_index)
注意事项
- 多 codec(例如板上同时有 ES8311 和 USB 声卡)时才需要关心这个接口,单 codec 产品一般用默认驱动即可。
audio_v2.get_driver_id(index)
功能
按索引取音频驱动的 id,配合 print_probe_id 使用可以打印出某个驱动的完整配置。
参数
index
参数含义:驱动索引,从 0 开始;
数据类型:number;
是否必选:必须传入此参数;
参数示例:0
返回值
driver_id
含义说明:驱动 id(probe id),可以直接传给其他需要 driver_probe_id 的接口;
数据类型:number;
示例
local all_nums, default_driver_index = audio_v2.get_driver_info()
local driver_probe_id = audio_v2.get_driver_id(default_driver_index)
log.info("audio", audio_v2.print_probe_id(driver_probe_id, true))
audio_v2.get_driver_param(driver_probe_id, param)
功能
读取音频驱动的运行参数,例如播放/录音方向的单次最大缓存长度。
参数
driver_probe_id
参数含义:驱动 id,由 audio_v2.make_probe_id 合成;
数据类型:number;
是否必选:可选,留空则取默认驱动;
参数示例:0
param
参数含义:要读的参数,见 audio_v2.DRIVER_PARAM_XXX;
数据类型:number;
是否必选:必须传入此参数;
参数示例:audio_v2.DRIVER_PARAM_RX_MAX_LEN
返回值
value
含义说明:参数当前值;
数据类型:number;
示例
local max_len = audio_v2.get_driver_param(0, audio_v2.DRIVER_PARAM_RX_MAX_LEN)
log.info("audio", "录音单次最大长度", max_len)
注意事项
- 做流式录音时先读一次
DRIVER_PARAM_RX_MAX_LEN,可以知道一次最多能喂多大一块,避免越界。
audio_v2.print_probe_id(driver_probe_id, is_string)
功能
把一个 probe id 拆开,打印出它的发送/接收总线类型和总线号。排查“声音从哪个总线出来”时最有用。
参数
driver_probe_id
参数含义:驱动 id,由 audio_v2.make_probe_id 合成;
数据类型:number;
是否必选:必须传入此参数;
参数示例:audio_v2.make_probe_id(audio_v2.DRIVER_TYPE_I2S, 0, audio_v2.DRIVER_TYPE_I2S, 0)
is_string
参数含义:返回值形式;
数据类型:boolean;
是否必选:可选;
注意事项:true 返回字符串(如 "I2S"),false 返回常量名;
参数示例:true
返回值
tx_bus_type, tx_bus_id, rx_bus_type, rx_bus_id
含义说明:发送总线类型 / 发送总线号 / 接收总线类型 / 接收总线号;
数据类型:any;
示例
local probe_id = audio_v2.make_probe_id(audio_v2.DRIVER_TYPE_I2S, 0, audio_v2.DRIVER_TYPE_I2S, 0)
local tx_type, tx_id, rx_type, rx_id = audio_v2.print_probe_id(probe_id, true)
log.info("audio", "TX", tx_type, tx_id, "RX", rx_type, rx_id)
audio_v2.config_codec_power_ctrl(codec_power_ctrl_enable, codec_power_pin, codec_power_on_level, codec_ready_after_wakeup_time_ms, codec_power_off_delay_time_ms, driver_probe_id)
功能
配置 codec 的电源控制(用哪个 GPIO 给 codec 供电、什么电平开、开多久后 codec 才稳定、关电前留多少余量)。
参数
codec_power_ctrl_enable
参数含义:是否使能 codec 电源控制;
数据类型:boolean;
是否必选:必须传入此参数;
参数示例:true
codec_power_pin
参数含义:codec 电源控制引脚;
数据类型:number;
是否必选:使能时必填;
参数示例:11
codec_power_on_level
参数含义:开电电平,1 高电平,0 低电平;
数据类型:number;
是否必选:使能时必填;
参数示例:1
codec_ready_after_wakeup_time_ms
参数含义:上电后等待多久 codec 才可用,单位毫秒;
数据类型:number;
是否必选:可选;
参数示例:200
codec_power_off_delay_time_ms
参数含义:关电前延时,单位毫秒;
数据类型:number;
是否必选:可选;
参数示例:10
driver_probe_id
参数含义:驱动 id;不用默认驱动时才填;
数据类型:number;
是否必选:可选;
参数示例:0
返回值
result
含义说明:成功返回 true,否则 false;
数据类型:boolean;
示例
-- 用 GPIO11 高电平给 codec 供电,上电等 200ms,关电前留 10ms
audio_v2.config_codec_power_ctrl(true, 11, 1, 200, 10)
注意事项
codec_ready_after_wakeup_time_ms太短会出爆音或初始化失败,按 codec 手册的上电稳定时间来填;- 本接口只配置,不负责开关电——开关电由音频框架在播放/休眠时自动做。
audio_v2.get_codec_param(id, param)
功能
读取编解码器的参数。
参数
id
参数含义:编解码器 id,见 audio_v2.DATA_CODEC_TYPE_XXX;
数据类型:number;
是否必选:必须传入此参数;
参数示例:audio_v2.DATA_CODEC_TYPE_G711_ALAW
param
参数含义:要读的参数,见 audio_v2.DATA_CODEC_PARAM_XXX;
数据类型:number;
是否必选:必须传入此参数;
参数示例:audio_v2.DATA_CODEC_PARAM_ENCODE_INPUT_LEN
返回值
value
含义说明:参数值;
数据类型:number;
示例
-- 取 G711 A-law 编码 1 帧需要喂多少字节 PCM
local len = audio_v2.get_codec_param(audio_v2.DATA_CODEC_TYPE_G711_ALAW,
audio_v2.DATA_CODEC_PARAM_ENCODE_INPUT_LEN)
log.info("audio", "编码1帧输入长度", len)
注意事项
- 流式编码(
audio_v2.stream)时用它在循环前算好每次喂多少,避免每次喂得过多或过少导致编码器内部缓存堆积。
audio_v2.tts_pcm_start(text)
功能
启动一路 TTS 合成会话,但不播放,而是把合成出来的 PCM 数据交给脚本自己取用。
用于“TTS 音频要送网络/送对讲/自己处理”的场景,比如把文字转成音频后通过 extern_source 混进对讲通道。
参数
text
参数含义:要合成的 UTF-8 文本;
数据类型:string;
是否必选:必须传入此参数;
注意事项:空文本会返回 invalid_text;
参数示例:"你好,欢迎使用合宙模组"
返回值
result, handle_or_reason
result 含义说明:成功返回 true,失败返回 false;数据类型:boolean;
handle_or_reason 含义说明:成功时是会话句柄(userdata,后续 read/stop 都要用它);
失败时是失败原因字符串:unsupported / busy / invalid_text /
no_memory / init_failed / format_error / decode_failed;
数据类型:userdata | string;
示例
local ok, handle = audio_v2.tts_pcm_start("你好,欢迎使用合宙模组")
if not ok then
log.info("tts", "启动失败", handle)
return
end
-- 接下来循环 audio_v2.tts_pcm_read(handle, 3200) 取数据
注意事项
- 该接口需要固件编入
LUAT_USE_AUDIO_TTS_PCM,没编入时audio_v2.tts_pcm_start为 nil; - 同一时间只允许一路合成会话,第二路会返回
busy; - 会话句柄有
__gc,脚本把它置 nil 后会自动停止并释放,但建议用完显式tts_pcm_stop。
audio_v2.tts_pcm_read(handle, capacity)
功能
从 TTS 合成会话里取一段已经合成好的 PCM 数据(不阻塞等待)。
参数
handle
参数含义:tts_pcm_start 返回的会话句柄;
数据类型:userdata;
是否必选:必须传入此参数;
注意事项:句柄已被 stop/释放时会报 "released TTS session" 错误;
参数示例:handle
capacity
参数含义:本次最多取多少字节;
数据类型:number;
是否必选:可选,默认 3200;
取值范围:1 ~ 3200;
参数示例:3200
返回值
pcm, state, err
pcm 含义说明:本次取到的 PCM 数据(16kHz、有符号、小端、单声道);
暂时没有新数据时是空字符串 "";
数据类型:string;
state 含义说明:会话状态,running / done / stopping / stopped / error;
数据类型:string;
err 含义说明:正常为 nil,出错时是原因字符串(同 tts_pcm_start 的失败原因);
数据类型:string | nil;
示例
local ok, handle = audio_v2.tts_pcm_start("你好")
while ok do
local pcm, state, err = audio_v2.tts_pcm_read(handle, 3200)
if #pcm > 0 then
-- 这里可以: 写文件 / 通过 socket 发走 / extern_source 混进对讲
end
if state == "done" or state == "error" or state == "stopped" then
log.info("tts", "结束", state, err)
break
end
sys.wait(20) -- 合成是后台线程,取不到就等一会再来
end
注意事项
- 这是非阻塞读:没合成好就返回空串,不要用
while死循环猛读,要配sys.wait; - 最后一段数据可能和
done状态一起返回,所以拿到done时还要再处理一次返回的pcm; - 单次最多 3200 字节,超了会直接报参数错误。
audio_v2.tts_pcm_stop(handle)
功能
停止 TTS 合成会话,释放底层资源。
参数
handle
参数含义:tts_pcm_start 返回的会话句柄;
数据类型:userdata;
是否必选:必须传入此参数;
参数示例:handle
返回值
result
含义说明:调用后总是返回 true(停止是幂等的,重复调用不报错);
数据类型:boolean;
示例
audio_v2.tts_pcm_stop(handle)
handle = nil
注意事项
- 停止是幂等的,中断合成、提前退出时直接调即可;
- 停止后句柄不能再用,再调
tts_pcm_read会报错。
audio_v2.speech(record_codec_id, save_buffer, record_callback_cnt, play_codec_id, one_play_block_len, sample_rate, data_bits, channel_nums, driver_probe_id, dsp_type)
功能
开启全双工模式(边说边听),用于对讲、免提通话这类场景。录音和播放同时跑,录音数据通过 save_buffer 回调给脚本,播放数据由脚本喂进来。
参数
record_codec_id
参数含义:录音编码器 id;
数据类型:number;
是否必选:可选;留空则直接返回原始 PCM 数据;
注意事项:不留空时会校验 sample_rate / data_bits 是否符合该编码器要求;
参数示例:audio_v2.DATA_CODEC_TYPE_AMR_WB
save_buffer
参数含义:录音数据回调时用来保存数据的 buffer;
数据类型:zbuff;
是否必选:必须传入此参数;
参数示例:local save_buffer = zbuff.create(3200)
record_callback_cnt
参数含义:每多少帧回调一次;
数据类型:number;
是否必选:可选;
注意事项:每帧时长由编码器决定,AMR-WB 一帧 20ms,传 10 就是 200ms 回调一次;
参数示例:10
play_codec_id
参数含义:播放解码器 id;
数据类型:number;
是否必选:可选;留空则与录音编码器相同;
参数示例:audio_v2.DATA_CODEC_TYPE_AMR_WB
one_play_block_len
参数含义:播放时单块数据长度;
数据类型:number;
是否必选:可选;
参数示例:640
sample_rate / data_bits / channel_nums
参数含义:采样率 / 位宽 / 通道数;
数据类型:number;
是否必选:可选;指定了 codec_id 后可留空,由编码器决定;
参数示例:16000 / 16 / 1
driver_probe_id
参数含义:驱动 id;不用默认驱动时才填;
数据类型:number;
是否必选:可选;
参数示例:0
dsp_type
参数含义:DSP 类型,见 audio_v2.DSP_TYPE_XXX;
数据类型:number;
是否必选:可选;留空由 BSP 决定(默认 SpeexDSP,带回声消除/降噪);
参数示例:audio_v2.DSP_TYPE_SPEEXDSP
返回值
result, request_index
result 含义说明:成功返回 true,否则 false;数据类型:boolean;
request_index 含义说明:请求索引,后续暂停/恢复/停止、加外部音源都用它;数据类型:number;
示例
local save_buffer = zbuff.create(3200)
-- 录音用 AMR-WB,每 10 帧回调一次
local result, request_index = audio_v2.speech(audio_v2.DATA_CODEC_TYPE_AMR_WB, save_buffer, 10)
log.info("speech", result, request_index)
-- 录音数据在 audio_v2.on 的 REQUEST_GET_NEW_DATA 事件里从 save_buffer 取
注意事项
- 全双工对 CPU 和音频驱动要求高,不是所有 BSP 都支持;
- 对讲时
dsp_type留空走 SpeexDSP,回声消除是默认开着的——用扬声器+麦克风的免提场景必须保留; - 停止时用
audio_v2.stop(request_index)。
audio_v2.extern_source(request_index, source, is_add_record, codec_id, is_error_stop, sample_rate, data_bits, channel_nums, is_signed)
功能
在对讲(speech)或播放中混入额外的音频源。典型用法:对讲时给对方播一段提示音、或者把 TTS 合成的 PCM 插进通话里。
参数
request_index
参数含义:audio_v2.speech 返回的请求索引;
数据类型:number;
是否必选:必须传入此参数;
参数示例:request_index
source
参数含义:输入数据;
数据类型:table / string / zbuff / boolean;
取值范围:table = 播放文件(即使只播一个文件也必须用 table 包起来,如 {"/test.mp3"})
string = 播放 TTS 文本
zbuff = 播放音频数据
true = 启用流模式播放(此时必须指定 codec_id)
是否必选:必须传入此参数;
参数示例:{"/test_16k.mp3"}
is_add_record
参数含义:加到哪里;
数据类型:boolean;
是否必选:可选,默认 false;
注意事项:false 加到播放通道(对方能听到),true 加到录音通道(只有自己这侧的数据里带上);
参数示例:false
codec_id
参数含义:解码器 id;
数据类型:number;
是否必选:可选;留空则根据输入数据自动判断;流模式(source = true)时必须指定;
参数示例:audio_v2.DATA_CODEC_TYPE_MP3
is_error_stop
参数含义:解码失败后是否停止;
数据类型:boolean;
是否必选:可选,默认 true;
注意事项:只在连续播放多个文件时有意义;
参数示例:true
sample_rate / data_bits / channel_nums / is_signed
参数含义:采样率 / 位宽 / 通道数 / 是否有符号;
数据类型:number / number / number / boolean;
是否必选:可选;但**解码器指定为 RAW 时,前三个不能留空**;
参数示例:16000 / 16 / 1 / true
返回值
result, source_index
result 含义说明:成功返回 true,否则 false;数据类型:boolean;
source_index 含义说明:外部音频源索引,用于后续停止这个音源;数据类型:number;
示例
local result, request_index = audio_v2.speech(audio_v2.DATA_CODEC_TYPE_AMR_WB, save_buffer, 10)
-- 对讲过程中,给对端插播一段提示音
audio_v2.extern_source(request_index, {"/test_16k.mp3"})
注意事项
- 额外音频的参数必须和对讲的参数一致(采样率、位宽、通道数),否则会失败而且不会有任何报错提示——这是最容易踩的坑;
- 想插播 TTS 就传字符串文本,想插播内存里的 PCM 就传 zbuff +
codec_id = DATA_CODEC_TYPE_RAW并写清采样率/位宽/声道; - 外部音源解码完成会触发
audio_v2.EXT_SRC_DONE事件。
四、ES8311 编解码器驱动 API
audio_v2_es8311_drv 是 ES8311 硬件编解码芯片的底层驱动,通过 require("es8311") 加载。
audio_v2_es8311_drv.init(i2c_id, voltage)
功能
初始化 ES8311 芯片
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:0,使用I2C0;
voltage
参数含义:电平设置;
数据类型:number;
取值范围:不传为3.3V,0x01为1.8V;
是否必选:可选传入此参数;
注意事项:Air8201等特殊板型需要1.8V电平;
参数示例:0x01,1.8V电平;
例子
-- 默认3.3V电平
audio_v2_es8311_drv.init(i2c_id)
-- 1.8V电平(Air8201等特殊板型)
audio_v2_es8311_drv.init(i2c_id, 0x01)
audio_v2_es8311_drv.set_sample_rate(i2c_id, sample_rate, mclk_div)
功能
设置 ES8311 采样率
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
参数示例:0,使用I2C0;
sample_rate
参数含义:采样率值;
数据类型:number;
取值范围:8000、16000等;
是否必选:必须传入此参数;
参数示例:16000,16K采样率;
mclk_div
参数含义:MCLK分频系数;
数据类型:number;
取值范围:256、512等;
是否必选:必须传入此参数;
参数示例:256,MCLK分频256;
例子
audio_v2_es8311_drv.set_sample_rate(i2c_id, 16000, 256)
audio_v2_es8311_drv.set_data_bits(i2c_id, bits_per_sample)
功能
设置 ES8311 采样位深
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
参数示例:0,使用I2C0;
bits_per_sample
参数含义:采样位深;
数据类型:number;
取值范围:16、24、32;
是否必选:必须传入此参数;
参数示例:16,16位数据;
audio_v2_es8311_drv.set_format(i2c_id)
功能
设置 ES8311 音频数据格式
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
参数示例:0,使用I2C0;
audio_v2_es8311_drv.resume(i2c_id)
功能
恢复 ES8311 工作状态
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
参数示例:0,使用I2C0;
audio_v2_es8311_drv.set_voice_vol(i2c_id, vol)
功能
设置 ES8311 播放音量
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
参数示例:0,使用I2C0;
vol
参数含义:音量值;
数据类型:number;
取值范围:0~100;
是否必选:必须传入此参数;
参数示例:70,音量70;
audio_v2_es8311_drv.set_mic_vol(i2c_id, vol)
功能
设置 ES8311 麦克风录音音量
参数
i2c_id
参数含义:I2C接口ID;
数据类型:number;
取值范围:0、1;
是否必选:必须传入此参数;
参数示例:0,使用I2C0;
vol
参数含义:麦克风音量值;
数据类型:number;
取值范围:0~100;
是否必选:必须传入此参数;
参数示例:65,麦克风音量65;