4 audio-音频播放和录音

作者：拓毅恒　|　最后修改：2026-04-13

一、概述

audio 核心库是指合宙的 LuatOS 通过对 es8311 编解码器进行配置以及传输，从而实现录音，播放音频，播放 TTS（文字转语音）功能，由于此核心库开发较早，历史包袱导致参数过多，使用非常不方便，建议使用 exaudio 扩展库。

重要概念解释：

1.1 硬件 DAC&ADC

也常称为 codec(编码器) ，decoder(解码器) 音频的编解码芯片，合宙目前仅支持"es8311"，其中 es8311 支持模拟音频转数据音频的输入，即为录音，也支持数据音频转为模拟音频的输出，即为播放。

1.2 采样率：

决定 “声音会不会漏了高频细节”（比如没抓住小鸟叫），采样率越高，细节越丰富，但是占用的空间也越大

1.3 位深：

决定 “声音的音量变化会不会生硬”（比如能不能分清小声说话和轻声咳嗽），使用 bit 表示，表示单次采样，模拟量使用数据量保存的位数，位数越高质量越高，占用空间越大

1.4 流式播放

一边传输音频数据，一边进行播放，适合一些对实时性要求较高的场景，或者需要对音频进行编码的场景，详情请见: codec 核心库

1.5 流式录音

一边录音，一边上传数据，适合对录音实时性要求较高或者需要对音频进行编码的场景，详情请见 codec 核心库。

1.6 es8311 功能简介

es8311 支持音频的编码和解码，即支持录音和播放，此外，es8311 还支持打电话功能

780EHV 模块内部集成了 es8311，方便客户使用音频相关功能，并使用 GPIO20 控制 es8311 的使能；Air8000 以及 Air780 系列其他型号内部不含 es8311，需要外挂，相关硬件设计请见，合宙音频配件板

1.7 audio、exaudio、codec 三个库文件的区别和联系

audio、codec 是核心库，可以调用的最底层的代码，exaudio 是扩展库
audio 库和 exaudio 库都是实现了录音和播放，但是 exaudio 使用更加简单，去掉了历史原因造成的 audio 的冗余参数
codec 库是实现了音频数据的编码和解码，不会对音频直接播放，audio 和 exaudio 可以对编解码后的音频进行播放

1.8 audio 核心库使用相关组合关系图

如图所示，audio 核心库大致可以分为如下几种组合关系，用户可根据所需功能自行搭配

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、由于 audio 核心库使用起来比较复杂，所以目前已经不推荐使用 audio 核心库，而是推荐使用 exaudio 扩展库来开发音频应用，exaudio 扩展库的使用参考：exaudio - API

4、此处仅仅简单地列举 audio 核心库中少数 api 的使用方法，供大家学习理解使用

-- 音频回调处理
local function audio_callback(id, event, point)
    if event == audio.MORE_DATA then
        log.info("流式播放，需要通过audio.write,写入要播放的数据",audio.write("xxxx"))
    elseif event == audio.DONE then
        log.info("播放完成")       
    elseif event == audio.RECORD_DATA then
        log.info("流式录音数据过来了")   
    elseif event == audio.RECORD_DONE then
        log.info("录音完成")   
    end
end
-- 回调函数设置
audio.on(0,audio_callback)
-- 音频硬件特性控制，包括DAC,PA 的电平和时序控制
audio.config(0, pa_pin, pa_on_level, power_delay, pa_delay, power_pin)
--硬件输出通道参数设置
audio.setBus(0, audio.BUS_I2S,{chip = "es8311",i2cid = i2c_id , i2sid = i2s_id})      

-- 播放参数设置
audio.start(0, audio.PCM, 1, 16000, 16)
-- 音量设置
audio.vol(0, 50)
-- 设置audio 工作模式
audio.pm(0,audio.RESUME)

三、常量详解

这些常量用于 audio 库的各种配置和操作，在脚本代码中不需要声明，可直接调用。

3.1 音频格式常量

这些常量用于指定音频数据的格式：

audio.PCM

常量含义：PCM音频格式；
数据类型：number；
示例代码：audio.start(0, audio.PCM, 1, 16000, 16, true)

3.2 音频事件常量

这些常量用于 audio.on() 回调函数中的事件类型

audio.MORE_DATA

常量含义：需要更多音频数据进行流式播放；
数据类型：number；
注意事项：当音频播放快要完成时触发，需要在回调中调用 audio.write() 写入新的音频数据；
示例代码：
local function audio_callback(id, event, point)
    if event == audio.MORE_DATA then
        audio.write(0, audio_data)
    end
end

audio.DONE

常量含义：音频播放或录音完成；
数据类型：number；
注意事项：当音频播放结束或录音完成时触发；
示例代码：
local function audio_callback(id, event, point)
    if event == audio.DONE then
        log.info("音频播放完成")
    end
end

audio.RECORD_DATA

常量含义：收到录音数据（流式录音）；
数据类型：number；
注意事项：仅在流式录音模式下触发，需要通过回调函数处理录音数据；
示例代码：
local function audio_callback(id, event, point)
    if event == audio.RECORD_DATA then
        local buff = point == 0 and pcm_buff0 or pcm_buff1
        local len = point == 0 and pcm_buff0:used() or pcm_buff1:used()
        -- 处理录音数据
    end
end

audio.RECORD_DONE

常量含义：录音完成；
数据类型：number；
注意事项：当录音过程结束时触发；
示例代码：
local function audio_callback(id, event, point)
    if event == audio.RECORD_DONE then
        log.info("录音完成")
    end
end

3.3 休眠模式常量

这些常量用于 audio.pm() 函数的休眠模式

audio.RESUME

常量含义：音频工作模式，PA和Codec全功能工作；
数据类型：number；
注意事项：适用于正在进行语音通话或播放音频的场景；
示例代码：audio.pm(0, audio.RESUME)

audio.STANDBY

常量含义：音频待机模式，PA断电，Codec待机（静音）；
数据类型：number；
注意事项：适用于通话暂停等需要快速恢复的场景，功耗高于SHUTDOWN模式；
示例代码：audio.pm(0, audio.STANDBY)

audio.SHUTDOWN

常量含义：音频关机模式，PA断电，可配置的Codec关机；
数据类型：number；
注意事项：适用于长时间不需要音频功能但希望保留快速恢复能力的场景；
示例代码：audio.pm(0, audio.SHUTDOWN)

audio.POWEROFF

常量含义：音频完全断电模式，PA和Codec完全断电；
数据类型：number；
注意事项：适用于极致低功耗场景，重新激活需要较长的初始化时间；
示例代码：audio.pm(0, audio.POWEROFF)

四、函数详解

4.1 配置相关

配置相关函数用于音频硬件配置、参数设置和事件注册。

audio.config(id, paPin, onLevel, dacDelay, paDelay, dacPin, dacLevel, dacTimeDelay)

功能

配置音频硬件参数。

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0 --音频通道0

paPin

参数含义：PA(音频放大器)控制IO；
数据类型：number；
取值范围：具体硬件环境支持的GPIO；
是否必选：非必须传入此参数；
注意事项：如果不传入则不对pa进行任何控制
参数示例：20 --GPIO20 控制PA 的打开或者关闭

onLevel

参数含义：PA(音频放大器)打开时的电平；
数据类型：number；
取值范围：0(低电平打开PA)，1(高电平打开PA)
是否必选：非必须传入此参数；
注意事项：
        1. 需要根据具体硬件设计来选择0或者1；
        2. 默认是1，高电平打开PA
参数示例：1 --高电平打开PA

dacDelay

参数含义：在DAC(es8311,780EPV 内置8311)启动前插入的冗余时间，单位100ms；
数据类型：number；
取值范围：>0；
是否必选：非必须传入此参数；
注意事项：
        1. 需要根据具体环境调节数值，以消除POP音，默认值为5(即为500ms)；
        2. 调试pop音的时候，需要判断是播放器有声音还是播放后有声音；
           播放前有声音，将 dacDelay 和 paDelay 设置为10，测试是否有pop音，然后逐步减少，达到最佳播放效率
           播放后有声音，将 dacTimeDelay 设置为100，测试是否有pop音，然后逐步减少，达到最佳播放效率
参数示例：1 --表示在DAC启动前插入100ms的冗余时间

paDelay

参数含义：在DAC(es8311,780EHV 内置8311)启动后，延迟多长时间打开PA(音频放大器)，单位1ms；
数据类型：number；
取值范围：>0；
是否必选：非必须传入此参数；
注意事项：
        1. 需要根据具体环境调节数值，以消除POP音，默认值为5(即为500ms)；
        2. 调试pop音的时候，需要判断是播放器有声音还是播放后有声音；
           播放前有声音，将 dacDelay 和 paDelay 设置为10，测试是否有pop音，然后逐步减少，达到最佳播放效率
           播放后有声音，将 dacTimeDelay 设置为100，测试是否有pop音，然后逐步减少，达到最佳播放效率
参数示例：10 --启动dac后等待10ms再打开pa

dacPin

参数含义：外部dac电源控制IO；
数据类型：number；
取值范围：具体硬件环境支持的GPIO；
是否必选：非必须传入此参数；
注意事项：如果没有填入此值，则不会对外部dac 进行任何供电动作
参数示例：0 --GPIO0 控制codec（如ES8311）的打开或者关闭

dacLevel

参数含义：DAC(音频编解码codec，比如ES8311)打开时的电平；
数据类型：number；
取值范围：0(低电平打开DAC)，1(高电平打开DAC)；
是否必选：非必须传入此参数；
注意事项：默认为1(默认拉高)；
参数示例：1 --高电平打开DAC

dacTimeDelay

参数含义：音频播放完毕时，PA与DAC关闭的时间间隔；
数据类型：number；
单位：1ms；
是否必选：可选；
注意事项：
        1. 需要根据具体环境调节数值，以消除POP音，默认为0ms；
        2. 调试pop音的时候，需要判断是播放器有声音还是播放后有声音；
           播放前有声音，将 dacDelay 和 paDelay 设置为10，测试是否有pop音，然后逐步减少，达到最佳播放效率
           播放后有声音，将 dacTimeDelay 设置为100，测试是否有pop音，然后逐步减少，达到最佳播放效率
参数示例：10 --音频播放完毕后，PA与DAC关闭的时间间隔10ms；

返回值

无

示例

audio.config(0, 25, 1, 6, 200)        --PA控制脚是GPIO25，高电平打开

audio.setBus(id, bus_type, config_table)

功能

配置音频 DAC（编解码器）

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

bus_type

参数含义：总线类型；
数据类型：number；
取值范围：audio.BUS_I2S；
是否必选：必须传入此参数；
注意事项：仅支持audio.BUS_I2S；
参数示例：audio.BUS_I2S，I2S 方式驱动音频DAC(编解码器) ；

config_table

参数含义：DAC配置参数；
数据类型：table；
取值范围：{
         -- 参数含义：dac 芯片名称；
         -- 数据类型：string；
         -- 取值范围：仅支持"es8311"；
         -- 是否必选：必选传入此参数；
         -- 注意事项：暂无；
         -- 参数示例："es8311",表示使用的DAC是8311；
        chip=, 
         -- 参数含义：使用的i2c id 的编号；
         -- 数据类型：number；
         -- 取值范围：0，1；
         -- 是否必选：必选传入此参数；
         -- 注意事项：暂无；
         -- 参数示例：0,使用I2C0 进行通信；
        i2cid,  
         -- 参数含义：使用的I2S id 编号；
         -- 数据类型：number；
         -- 取值范围：0；
         -- 是否必选：必选传入此参数
         -- 注意事项：暂无；
         -- 参数示例：0，使用I2S 0 通道进行通信；
        i2sid=0, 
}；
是否必选：必须传入此参数；
注意事项：根据实际情况写入i2cid值；
参数示例：audio.BUS_I2S，I2S 方式驱动音频DAC(编解码器) ；

返回值

local result = audio.setBus(id, bus_type, config_table)

result

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

例子

audio.setBus(0, audio.BUS_I2S, {chip="es8311",i2cid=0,i2sid=0})    --通道0的硬件输出通道设置为I2S

audio.vol(id, value)

功能

设置播放音量

注意事项

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

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

value

参数含义：音量，百分比，1%~100%，默认值100%，就是不调节；
数据类型：number；
取值范围：1~100；
是否必选：必须传入此参数；
注意事项：需要根据实际的硬件配置，如果设置过大可能造成声音过曝，或者电流供应不上的问题；
参数示例：80，80% 的音量 ；

返回值

local result = audio.vol(id, value)

result

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

例子

local result = audio.vol(0, 90)    --通道0的音量调节到90%

audio.micVol(id, value)

功能

设置 mic 音量

注意事项

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

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

value

参数含义：录制音量，百分比，1%~1000%，默认值100%，就是不调节；
数据类型：number；
取值范围：1~100；
是否必选：必须传入此参数；
注意事项：需要更具实际情况调节；
参数示例：80，80% 的音量 ；

返回值

local result = audio.micVol(id, value)

result

含义说明：设置麦克风音量的结果；
数据类型：boolean；
取值范围：true 表示成功，false 表示失败；
返回示例：true -- 麦克风音量设置成功

例子

local result = audio.micVol(0, 90)    --录音音量调节到90%

audio.on(id, callback)

功能

注册音频事件回调函数

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

callback

参数含义：音频事件的回调函数；
数据类型：function；
取值范围：无；
是否必选：必须传入此参数；
注意事项：此函数必须使用,用于接收音频事件，包括；
参数示例：
{
 --id
-- 参数含义：I2S的通道号；
-- 数据类型：number；
-- 取值范围：0；
-- 是否必选：必须传入此参数；
-- 注意事项：仅支持0；
-- 参数示例：0，通道0 ；

 --event
 --参数含义：标识当前的发送或者接受数据情况；
 --数据类型：boolean；
 --取值范围：true 收到数据，false 发送数据完毕；
 --是否必选：是；
 --注意事项：
 -- 1. 当buff 为 true 的时候，表示收到数据，收到的数据存放在i2s.recv 的buffer 里面
 -- 2. 当buff 为 false 的时候，表示发送数据完毕
 --参数示例：true -- 收到数据

  --point
 --参数含义：标识当前的发送或者接受数据情况；
 --数据类型：boolean；
 --取值范围：true 收到数据，false 发送数据完毕；
 --是否必选：是；
 --注意事项：
 -- 1. 当buff 为 true 的时候，表示收到数据，收到的数据存放在i2s.recv 的buffer 里面
 -- 2. 当buff 为 false 的时候，表示发送数据完毕
 --参数示例：true -- 收到数据
}

返回值

无

例子

local function audio_callback(id, event, point)
    if event == audio.MORE_DATA then
        log.info("流式播放，需要通过audio.write,写入要播放的数据",audio.write("xxxx"))
    elseif event == audio.DONE then
        log.info("播放完成")       
    elseif event == audio.RECORD_DATA then
        log.info("收到录音数据地址为：",buff,"长度为",len) -- 使用方法见audio.record 函数
    elseif event == audio.RECORD_DONE then
        log.info("录音完成")   
    end
end

-- 回调函数设置
audio.on(0,audio_callback)

audio.pm(id,pm_mode)

功能

休眠控制（一般会自动调用 RESUME 模式）

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

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 工作模式；

返回值

local result = audio.pm(id,pm_mode)

result

含义说明：设置休眠模式的结果；
数据类型：boolean；
取值范围：true 表示成功，false 表示失败；
返回示例：true -- 休眠模式设置成功

例子

local result = audio.pm(0,audio.RESUME) --工作模式

4.2 检查相关

检查相关函数用于获取音频状态、错误信息和调试信息。

audio.getError(id)

功能

获取最近一次播放结果

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

返回值

local result = audio.getError(id)

result

参数含义：播放结果；
数据类型：boolean；
取值范围：true 表示成功，false 表示失败；
是否必选：必须接收此参数；
参数示例：true --播放成功

user_stop

参数含义：是否是用户停止；
数据类型：boolean；
取值范围：true 表示用户停止，false 表示未停止；
是否必选：必须接收此参数；
参数示例：true --用户停止

file_no

参数含义：第几个文件失败了，从1开始；
数据类型：number；
取值范围：> 0 ；
是否必选：必须接收此参数；
注意事项：只有audio.play 的 path 参数是表（表示播放多个文件）才有效；
参数示例：4 --第四个文件播放失败；

例子

local result, user_stop, file_no = audio.getError(0)

audio.isEnd(id)

功能

检查音频通道是否播放结束

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

返回值

local result = audio.isEnd(id)

result

含义说明：音频通道播放状态；
数据类型：boolean；
取值范围：true表示播放结束，false表示正在播放；
返回示例：true -- 播放已结束

例子

local is_end = audio.isEnd(0)    --是否播放结束

audio.debug(on_off)

功能

配置调试信息输出

参数

on_off

参数含义：打开或者关闭音频调试输出；
数据类型：boolean；
取值范围：true 打开调试信息输出，false 关闭调试信息输出；
是否必选：必须传入此参数；
注意事项：无；
参数示例：true -- 打开调试信息输出

返回值

无

例子

audio.debug(true)     --  打开调试信息输出

4.3 播放相关

播放相关函数，用于音频播放控制。

audio.play(id, path, errStop)

功能

播放音频文件或者停止播放（可以是文件或 TTS）

注意事项：

播放完成后，会回调一个 audio.DONE 消息
可以用 pause 来暂停或者恢复
audio.play(0) 即为停止播放，可以停止文件或 TTS

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

path

参数含义：文件名，如果是table，则表示连续播放多个文件；
数据类型：string/table/nil；
取值范围：无；
是否必选：可选，为空则表示停止播放；
注意事项：
        1. 支持MP3,AMR,WAV格式
        2. 如果是string 表示播放音频文件，
        3. 如果是table 表示连续播放多个音频文件，适合云喇叭等应用，相较于单个播放，中间不会产生停顿的感觉
        4. 如果是nil,则表示停止播放
        5. 只有停止之后，才可以开始新的播放，停止的结束事件为audio.on 返回audio.DONE事件；
参数示例：
        1. "/luadb/hello.mp3",播放/luadb/hello.mp3 路径下的mp3 文件；
        2. {"/luadb/hello.mp3"，"/ram/yes.amr","/ram/yes.wav"} ,表示依次播放列表类的文件
        3. nil，表示停止正在播放的音频

errStop

参数含义：是否在文件解码失败后停止播放；
数据类型：boolean；
取值范围：true 停止播放，false 继续播放；
是否必选：可选，为空则表示停止播放；
注意事项：
1. 仅path为table的时候(即连续播放)，此参数才有价值；
2. 当为true时候遇到解码错误自动停止
3. 默认为true
参数示例：true -- 播放列表内播放遇解码错误，立即停止播放

返回值

local result = audio.play(id, path, errStop)

result

含义说明：播放音频文件的结果；
数据类型：boolean；
取值范围：true 表示成功，false 表示失败；
返回示例：true -- 音频文件播放成功

例子

audio.play(0, "/luadb/hello.mp3")        --开始播放文件
audio.play(0, {"/luadb/hello.mp3", "/ram/yes.amr","/ram/yes.wav"})        --连续播放多个文件
audio.play(0)                --停止播放

audio.pause(id, pause)

功能

暂停或恢复播放

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

pause

参数含义：暂停或恢复；
数据类型：boolean；
取值范围：true 暂停播放，false 恢复播放；
是否必选：必须传入此参数；
注意事项：无；
参数示例：true -- 暂停播放

返回值

local result = audio.pause(id, pause)

result

含义说明：暂停或恢复播放的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 暂停/恢复播放成功

例子

local result = audio.pause(0, true)    --暂停播放
local result = audio.pause(0, false)   --恢复播放

audio.playStop(id)

功能

停止播放音频文件，等同于 audio.play(id)

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

返回值

local result = audio.playStop(id)

result

含义说明：停止播放的结果；
数据类型：boolean；
取值范围：true 表示成功，false 表示失败；
返回示例：true -- 停止播放成功

例子

local result = audio.playStop(0)    --停止播放音频文件

audio.tts(id, text)

功能

播放或暂停播放 TTS 文本转语音

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0；
参数示例：0，音频通道0 ；

text

参数含义：要播放的文本；
数据类型：string；
取值范围：有效的文本字符串；
是否必选：可选，不填即为停止播放TTS；
注意事项：支持中文和英文文本；
参数示例："你好，世界" --要播放的文本

返回值

local result = audio.tts(id, text)

result

含义说明：播放TTS的结果；
数据类型：boolean；
取值范围：true 表示成功，false 表示失败；
返回示例：true -- TTS播放成功

例子

local result = audio.tts(0, "你好，世界")    --播放TTS文本
audio.tts(0) --停止播放TTS文本

audio.start(id, audio_format, num_channels, sample_rate, bits_per_sample, is_signed)

功能

启动一个音频通道，仅用于流式播放。

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0，不可以传入其他的参数；
参数示例：0，音频通道0 ；

audio_format

参数含义：播放的音频格式；
数据类型：number；
取值范围：audio.PCM；
是否必选：必须传入此参数；
注意事项：仅支持audio.PCM；
参数示例：audio.PCM 代表PCM音频数据 ；

num_channels

参数含义：声音通道数；
数据类型：number；
取值范围：1；
是否必选：必须传入此参数；
注意事项：仅支持1个音频通道，此处必须填入1；
参数示例：1 表示一个音频通道；

sample_rate

参数含义：采样频率；
数据类型：number；
取值范围：8000,16000,24000,32000,48000,20050,44100；
是否必选：必须传入此参数；
注意事项：参数的取值，需要和音频源文件一致；
参数示例：8000 代表每秒对音频源采样8000次 ；

bits_per_sample

参数含义：采样位数,用多少个二进制位（0 和 1）来描述 "单个采样点的振幅大小"（即音量高低）；
数据类型：number；
取值范围：8，16，24；
是否必选：必须传入此参数；
注意事项：参数的取值，需要和音频源文件一致；
参数示例：16,表示每次采样的时候，使用16位数据来保存音频数据 ；

is_signed

参数含义：播放的音频源，是否有符号；
数据类型：boolean；
取值范围：true 有符号，false 无符号；
是否必选：必须传入此参数；
注意事项：参数的取值，需要和音频源文件一致，一般来说都是有符号，即为true；
参数示例：true -- 音频文件有符号；

返回值

local result = audio.start(id, audio_format, num_channels, sample_rate, bits_per_sample, is_signed)

result

含义说明：音频通道启动的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 音频通道启动成功

示例

local function audio_callback(id, event, point)  -- 音频回调处理
    if event == audio.MORE_DATA then
        audio.write(0,"xxxx")    --  当快要播完的时候，需要尽快写入数据
    end
end

audio.on(0, audio_callback)     -- 回调函数
audio.start(0, audio.PCM, 1, 16000, 16, true) --启动一个音频通道

audio.write(id, data)

功能

向音频通道中写入音频数据，用于播放

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0，不可以传入其他的参数；
参数示例：0，音频通道0；

data

参数含义：播放的音频流数据；
数据类型：string；
取值范围：音频数据流；
是否必选：必须传入此参数；
注意事项：需要配合audio.start 函数使用，仅仅支持流式播放，数据来源可以从文件或者网络获取；
参数示例："xxxxx"，音频数据流；

返回值

local result = audio.write(id, data)

result

含义说明：向音频通道写入数据的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 写入数据成功

示例

audio.write(0, "xxxxxx")

audio.finish(id)

功能

写入最后一块数据后，通知多媒体通道已经没有更多数据需要播放了

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0，不可以传入其他的参数；
参数示例：0，音频通道0 ；

返回值

local result = audio.finish(id)

result

含义说明：结束音频播放的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 结束音频播放成功

示例

local file = io.open("/luadb/test.pcm", "rb")   -- 模拟流式播放音源，实际的音频数据来源也可以来自网络或者本地存储
while true do
    local read_data = file:read(buffer_size)  --  读取文件，模拟流式音频源
    if read_data  == nil then
        file:close()                -- 模拟音频获取完毕，关闭音频文件
        -- 本API需要用V2024固件！！！ 
        -- 写入数据完毕后，通知多媒体通道已经没有更多数据需要播放了
        -- 开启后可以有效的降低pop音
        exaudio.finish()
        break
    end
end

audio.stop(id)

功能

停止指定的多媒体通道

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0，不可以传入其他的参数；
参数示例：0，音频通道0 ；

返回值

local result = audio.stop(id)

result

含义说明：停止音频播放的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 音频播放停止成功

示例

audio.start(0, audio.PCM, 1, 16000, 16, true) --启动一个音频通道
...
-- 其他逻辑代码
...
audio.stop(0)    --停止音频通道0的播放

audio.record(id, record_type, record_time, amr_quailty, path, nil, buff0, buff1,channelCount)

功能

录音

注意事项

1. 仅仅支持 AMR_NB，AMR_WB，PCM（8000,16000,24000,32000,48000）的格式

2. 流式录音仅仅支持 PCM 格式

3. 实测距离3米能清晰录音，距离5米能听到声音但杂音较多。测试环境：麦克风音量100，播放音量70、测试使用 demo/audio/record_amr_file 文件

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0，不可以传入其他的参数；
参数示例：0，音频通道0 ；

record_type

参数含义：录音音频格式；
数据类型：number；
取值范围：audio.AMR,audio.AMR_NB,audio.AMR_WB,audio.PCM；
是否必选：必须传入此参数；
注意事项：此接口可以实现流式录音，但是仅仅支持PCM格式,audio.AMR和audio.AMR_NB同样作用
参数示例：audio.AMR_NB，录制的音频是audio.AMR_NB格式 ；

record_time

参数含义：录制时长；
数据类型：number(单位秒)；
取值范围：大于或等于0；
是否必选：必须传入此参数；
注意事项：如果使用的是0，则表示一直录
参数示例：3，表示录制3秒的音频 ；

amr_quailty

参数含义：音频质量；
数据类型：number；
取值范围：0 - 8；
是否必选：必须传入此参数；
注意事项：
1. 音频质量是综合了采样率和位深，如果设置了音频质量，那么audio.start设置的采样率和位深，将会失效。
2. 此参数仅在record_type的值audio.AMR,audio.AMR_NB,audio.AMR_WB 有效,
3. 如果是AMR_NB,范围是0~7，建议值为7。如果是audio.AMR_WB,范围是0~8,值越大消耗的空间越多,音质越高,默认0；
参数示例：7，表示 audio.AMR_NB 的音频质量为7 ；

path

参数含义：录音文件的存储位置；
数据类型：string/nil；
取值范围：string/nil；
是否必选：必须传入此参数；
注意事项：如果填入的是路径，则支持audio.AMR,audio.AMR_NB,audio.AMR_WB,PCM 三种格式，如果是nil 则表示流式录音，需要通过audio.on 的回调函数来获取录音的数据；

参数示例："/ram/xxx.amr" 表示录制的音频存在/ram/xxx.amr 文件中；

reserved

参数含义：无意义参数；
数据类型：nil；
取值范围：nil；
是否必选：必须传入此参数；
注意事项：历史原因导致此参数无意义,此参数固定填写nil；
参数示例：nil，固定填写参数；

buff0

参数含义：流式录音存放的地址0；
数据类型：zbuff；
取值范围：zbuff对象的地址；
是否必选：path 为nil 的时候，必须传入此参数；
注意事项：zbuff0 设置的大小为16000，需要和buff1 同时填入，并保持buff 大小一样，录音会轮番向着两个buff 发送数据；
参数示例：zbuff0，创建zbuff0返回的对象；

buff1

参数含义：流式录音存放的地址1；
数据类型：number；
取值范围：zbuff1 的地址；
是否必选：path 为nil 的时候，必须传入此参数；
注意事项：zbuff1 设置的大小为16000，需要和buff0 同时填入，并保持buff 大小一样，录音会轮番向着两个buff 发送数据；
参数示例：zbuff1，创建zbuff1返回的地址  ；

返回值

local result = audio.record(id, record_type, record_time, amr_quailty, path, nil, buff0, buff1,channelCount)

result

含义说明：启动录音的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 录音启动成功

示例 1: 录制到文件

audio.record(0, audio.AMR_NB, 5, 7, "/ram/xxx.amr")

示例 2: 流式录音

local function audio_callback(id, event, point) -- 音频回调处理
    if event == audio.RECORD_DATA then
        if type(audio_record_param.path) == "function" then
            local buff, len = point == 0 and pcm_buff0 or pcm_buff1,
                             point == 0 and pcm_buff0:used() or pcm_buff1:used()
            audio_record_param.path(buff, len)
           log.info("收到录音数据地址为："，buff,"长度为",len)
        end
    end
end

pcm_buff0 = zbuff.create(16000)
pcm_buff1 = zbuff.create(16000)
audio.record(0, audio.PCM, 5, amr_quailty, nil, nil, pcm_buff0, pcm_buff1) -- 保存路径为nil 的时候，将会开启流式录音

audio.recordStop(id)

功能

停止录音

注意：audio 的回调函数返回 audio.RECORD_DONE 的 event 才是真正的结束

参数

id

参数含义：音频通道；
数据类型：number；
取值范围：仅支持0；
是否必选：必须传入此参数；
注意事项：目前仅支持0，不可以传入其他的参数；
参数示例：0，音频通道0 ；

返回值

local result = audio.recordStop(id)

result

含义说明：停止录音的结果；
数据类型：boolean；
取值范围：true 成功，false 失败；
返回示例：true -- 录音停止成功

示例

audio.recordStop(id)

五、产品支持说明

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

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

724，722，720，820，795 也不支持。