5 audio_v2-新音频框架（仅用于理解exaudio实现）

作者：拓毅恒　|　最后修改：2026-07-16

重要说明

本文档列出 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 格式

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 位宽配置参数键

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

四、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；

5 audio_v2-新音频框架（仅用于理解exaudio实现）

一、概述

二、常量详解

2.1 驱动类型常量（用于 make_probe_id）

2.2 编解码器类型常量（用于 play 的 codec_id，以及 stream 的 codec_id）

2.3 驱动配置常量（用于 audio_v2.config 的 config_param）

2.4 驱动配置值常量（用于 audio_v2.config 的 config_value1）

2.5 请求事件常量（用于 audio_v2.on 回调）

三、函数详解

audio_v2.on(func)

audio_v2.config(config_param, config_value1, config_value2, driver_probe_id)

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)

audio_v2.make_probe_id(tx_bus_type, tx_bus_id, rx_bus_type, rx_bus_id)

audio_v2.set_default_driver(driver_probe_id)

audio_v2.shutdown(driver_power_off, codec_power_off, pa_power_off, driver_probe_id)

audio_v2.play(path, err_stop, priority, driver_probe_id, codec_id)

audio_v2.tts(text, priority, driver_probe_id)

audio_v2.stream(codec_id, sample_rate, data_bits, channel_nums, is_signed, priority, driver_probe_id)

audio_v2.input(request_or_source_index, data, is_end)

audio_v2.record(save_buffer, record_callback_cnt, codec_id, priority, sample_rate, data_bits, channel_nums, driver_probe_id)

audio_v2.stop(request_index)

audio_v2.is_all_done()

audio_v2.get_play_info(data, codec_id, pos)

audio_v2.soft_volume(volume, driver_probe_id)

四、ES8311 编解码器驱动 API

audio_v2_es8311_drv.init(i2c_id, voltage)

audio_v2_es8311_drv.set_sample_rate(i2c_id, sample_rate, mclk_div)

audio_v2_es8311_drv.set_data_bits(i2c_id, bits_per_sample)

audio_v2_es8311_drv.set_format(i2c_id)

audio_v2_es8311_drv.resume(i2c_id)

audio_v2_es8311_drv.set_voice_vol(i2c_id, vol)

audio_v2_es8311_drv.set_mic_vol(i2c_id, vol)

2.1 驱动类型常量（用于 `make_probe_id`）

2.2 编解码器类型常量（用于 `play` 的 `codec_id`，以及 `stream` 的 `codec_id`）

2.3 驱动配置常量（用于 `audio_v2.config` 的 `config_param`）

2.4 驱动配置值常量（用于 `audio_v2.config` 的 `config_value1`）

2.5 请求事件常量（用于 `audio_v2.on` 回调）