Air8101 audio 使用文档

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

一、音频功能概述

Air8101 工业引擎提供了强大的音频处理能力，支持多种音频格式的播放和录制功能。音频系统基于 exaudio 库实现，支持以下主要功能：

1. 音频文件播放：支持 MP3、WAV、AMR 等格式的音频文件播放（仅 8101B 支持）
2. 文字转语音（TTS）：支持中文语音合成功能（仅 8101B 支持）
3. 流式音频播放：支持 PCM 格式的流式音频播放
4. 录音功能：支持 AMR 和 PCM 格式的音频录制（仅 8101B 支持）

音频功能是嵌入式系统中多媒体应用的重要组成部分，掌握音频系统的使用方法对于实现语音提示、音频播放、录音等应用至关重要。

二、准备硬件环境

参考：Air8101 硬件环境清单，准备好硬件环境。

2.1 Air8101 整机开发板

Air8101 开发板提供了丰富的音频接口资源，可通过开发板上的音频接口进行连接和测试。

三、准备软件环境

3.1 工具 + 内核固件 + 脚本

1、Luatools 下载调试工具

2、Air8101/Air8101B 测试音频需要固件版本 ≥ V2018 才可播放音频 Air8101 LuatOS 固件版本。

3、luatos 需要的脚本和资源文件

• 脚本和资源文件点我浏览所有文件
• 准备好软件环境之后，接下来查看如何使用 LuaTools 烧录软件，将本篇文章中演示使用的项目文件烧录到 Air8101 开发板中。

4、lib 脚本文件：使用 Luatools 烧录时，勾选 添加默认 lib 选项，使用默认 lib 脚本文件；

3.2 API 介绍

这里仅介绍本篇文档所使用的 API，详情请查看：API - exaudio

exaudio.setup(config)

配置音频系统参数，包括声道数、采样率等

exaudio.play_start(file_path, callback)

开始播放音频文件

exaudio.play_stop()

停止音频播放

exaudio.play_tts(text, callback)

播放文字转语音内容

exaudio.play_stream_write(data, len)

写入流式音频数据

exaudio.record_start(config, callback)

开始录音

exaudio.record_stop()

停止录音

四、音频功能实现概述

本小节详细介绍 Air8101 开发板上音频各种功能模式的实现方法和核心代码逻辑。

4.1 音频文件播放功能（仅 8101B 支持）

音频文件播放功能用于播放本地存储的音频文件，支持 MP3、WAV、AMR 等格式。

4.1.1 功能定义

配置音频系统参数，播放指定路径的音频文件。

• 自动播放 sample-6s.mp3 音乐
• 支持 MP3、WAV、AMR 格式音频文件播放
• 循环播放 sample-6s.mp3 和 10.amr

4.1.2 代码示例

--[[
@module  play_file
@summary 播放文件
@version 1.0
@date    2026.06.26
@author  拓毅恒
@usage

注意：
1. Air8101使用内置DAC输出音频，无需外部音频编解码芯片
2. 需要固件版本>=V1018才可播放音频
3. 此功能需要用Air8101B来测试，Air8101不支持

本文件为播放文件的应用功能模块，核心业务逻辑为：
1、初始化后播放sample-6s.mp3
2、然后循环交替播放10.amr和sample-6s.mp3，播放间隔3秒
本文件没有对外接口，直接在main.lua中require "play_file"就可以加载运行；
]]

local exaudio = require("exaudio")

-- 音频初始化设置参数 (DAC模式)
local audio_setup_param ={
    model = "dac",            -- 音频编解码类型: "dac" 表示使用内置DAC

    pa_ctrl = 27,             -- 音频放大器电源控制管脚
    pa_on_level = 1,          -- PA打开电平
    pa_delay = 10            -- PA延时
}

-- 播放结束回调
local function play_end(event)
    if event == exaudio.PLAY_DONE then
        log.info("播放完成",exaudio.is_end())
    end
end

-- 音频播放的配置
local audio_play_param ={
    type= 0,                -- 播放类型，有0，播放文件，1.播放tts 2. 流式播放
                            -- 如果是播放文件,支持mp3,amr,wav格式
                            -- 如果是tts,内容格式见:https://docs.openluat.com/osapi/ext/exaudio/#tts_2
                            -- 流式播放，支持PCM/MP3/AMR/WAV格式,如果是流式播放，则sampling_rate, sampling_depth,signed_or_unsigned 必填写
    content = "/luadb/sample-6s.mp3",          -- 如果播放类型为0时，则填入string 是播放单个音频文件,如果是表则是播放多段音频文件。
    cbfnc = play_end,            -- 播放完毕回调函数
}

---------------------------------
---通过BOOT 按键进行播放停止操作---
---------------------------------

-- 停止按键（Air8101 boot键为GPIO0）
local function stop_audio()
    log.info("停止播放")
    exaudio.play_stop(audio_play_param)
    log.info("播放停止成功")
end
-- 按下boot 停止播放
-- gpio.setup(0, stop_audio, gpio.PULLDOWN, gpio.RISING)
-- gpio.debounce(0, 200, 1)

---------------------------------
-----主task,处理播放音频---------
---------------------------------

local index_number = 1
local function audio_task()
    log.info("开始播放音频文件")
    if exaudio.setup(audio_setup_param) then
        exaudio.vol(70)            -- 喇叭音量
        exaudio.play_start(audio_play_param) -- 仅仅支持task 中运行
        while true do
            sys.wait(3000)
            if index_number % 2 == 0 then
                exaudio.play_start({type = 0, content = "/luadb/sample-6s.mp3", cbfnc = play_end})
            else
                exaudio.play_start({type = 0, content = "/luadb/10.amr", cbfnc = play_end})
            end
            index_number = index_number + 1
        end
    end
end
sys.taskInitEx(audio_task, "task_audio")

4.2 文字转语音功能（仅 8101B 支持）

文字转语音功能将文本内容转换为语音播放，支持中文语音合成。

4.2.1 功能定义

配置 TTS 参数，播放指定的文本内容，支持音色切换。

• 播放 TTS 语音合成内容
• 自动音色切换播放
• 仅支持中文 TTS

4.2.2 代码示例

--[[
@module  play_tts
@summary 文字转语音
@version 1.0
@date    2026.06.26
@author  拓毅恒
@usage

注意：
1. Air8101使用内置DAC输出音频，无需外部音频编解码芯片
2. 需要固件版本>=V1018才可播放音频
3. 此功能需要用Air8101B来测试，Air8101不支持

本文件为TTS播放应用功能模块，核心业务逻辑为：
1、初始化后播默认TTS
2、然后循环播5种音色的TTS，间隔3秒
本文件没有对外接口，直接在main.lua中require "play_tts"就可以加载运行；
]]

local exaudio = require("exaudio")

-- 音频初始化设置参数 (DAC模式)
local audio_setup_param ={
    model = "dac",            -- 音频编解码类型: "dac" 表示使用内置DAC

    pa_ctrl = 27,             -- 音频放大器电源控制管脚
    pa_on_level = 1,          -- PA打开电平
    pa_delay = 10            -- PA延时
}

-- TTS音色列表（关于TTS音色设置请见: https://docs.openluat.com/osapi/ext/exaudio/#tts_2）
local tts_voices = {
    "[m51]支付宝到账,1千万元",   -- 许久
    "[m52]支付宝到账,1千万元",   -- 许多
    "[m53]支付宝到账,1千万元",   -- 晓萍
    "[m54]支付宝到账,1千万元",   -- 唐老鸭
    "[m55]支付宝到账,1千万元",   -- 许宝宝
}

local function play_end(event)
    if event == exaudio.PLAY_DONE then
        log.info("播放完成",exaudio.is_end())
        exaudio.play_stop({type = 1})
    end
end

local audio_play_param ={
    type = 1,                -- 播放类型: 1=播放TTS
    content = "支付宝到账,1千万元", -- 需要播放的内容
    cbfnc = play_end, -- 播放完毕回调函数
}

---------------------------------
-----主task,处理播放TTS----------
---------------------------------

local function audio_task()
    log.info("开始播放TTS")
    if exaudio.setup(audio_setup_param) then
        exaudio.vol(50)
        exaudio.play_start(audio_play_param)
        while not exaudio.is_end() do sys.wait(100) end

        -- 循环演示播放5种音色，间隔3秒
        local idx = 1
        while true do
            sys.wait(3000)
            exaudio.play_start({type = 1, content = tts_voices[idx], cbfnc = play_end})
            while not exaudio.is_end() do sys.wait(100) end
            idx = (idx % #tts_voices) + 1
        end
    end
end
sys.taskInitEx(audio_task, "task_audio")

4.3 流式音频播放功能

流式音频播放功能用于实时播放 PCM 格式的音频数据流。

4.3.1 功能定义

配置流式播放参数，通过不断写入 PCM 数据实现实时音频播放。

• 使用 test.pcm 模拟音频来源进行流式播放
• 通过流式传输不断填入播放的音频数据
• 支持 PCM/MP3/AMR/WAV 格式音频

4.3.2 代码示例

--[[
@module  play_stream
@summary 流式播放
@version 1.2
@date    2026.06.26
@author  拓毅恒
@usage

注意：
1. Air8101使用内置DAC输出音频，无需外部音频编解码芯片
2. 需要固件版本>=V1018才可播放音频

本文件为流式播放应用功能模块，核心业务逻辑为：
1、初始化后启动流式播放
2、读取test.pcm文件数据，通过exaudio.play_stream_write写入播放
3、播放task不断播放传入流式音频
本文件没有对外接口，直接在main.lua中require "play_stream"就可以加载运行；
]]

local exaudio = require("exaudio")

-- 音频初始化设置参数 (DAC模式)
local audio_setup_param ={
    model = "dac",            -- 音频编解码类型: "dac" 表示使用内置DAC

    pa_ctrl = 27,             -- 音频放大器电源控制管脚
    pa_on_level = 1,          -- PA打开电平
    pa_delay = 10            -- PA延时
}

-- 播放完成回调
local function play_end(event)
    if event == exaudio.PLAY_DONE then
        log.info("播放完成",exaudio.is_end())

    end
end 

-- 流式播放音频播放的配置
local audio_play_param ={
    codec_id = 0,                   -- 编解码器ID：0=RAW/PCM, 1=WAV, 2=AMR_NB, 3=AMR_WB, 4=TTS, 5=MP3
    type= 2,                -- 播放类型，如果是流式播放，则sampling_rate, sampling_depth,signed_or_unsigned 必填写
    cbfnc = play_end,            -- 播放完毕回调函数
    sampling_rate = 16000,  -- 采样率,仅为流式播放起作用
    sampling_depth =  16,   -- 采样位位深,仅流式播放的时候才有作用
    signed_or_unsigned = true  -- PCM 的数据是否有符号，仅为流式播放起作用
}

---------------------------------
---------模拟获取音频task---------
---------------------------------
local function audio_get_data()
    -- 等待播放初始化完成
    sys.waitUntil("AUDIO_READY")

    log.info("开始流式获取音频数据")
    local file = io.open("/luadb/test.pcm", "rb")   -- 模拟流式播放音源，实际的音频数据来源也可以来自网络或者本地存储

    -- 获取推荐的缓冲区大小
    local buffer_size = exaudio.get_stream_buffer_size() or 4096
    log.info("流式播放缓冲区大小", buffer_size)

    while true do
        local read_data = file:read(buffer_size)  --  读取文件，模拟流式音频源,需要1024 的倍数
        if read_data  == nil then
            file:close()                -- 模拟音频获取完毕，关闭音频文件
            -- 本API需要用V2024固件！！！ 
            -- 写入数据完毕后，通知多媒体通道已经没有更多数据需要播放了
            -- 开启后可以有效的降低pop音
            exaudio.finish()
            break
        end

        -- 如果读取的数据小于缓冲区大小，补充静音数据
        if #read_data < buffer_size then
            read_data = read_data .. string.rep("\0", buffer_size - #read_data)
        end

        exaudio.play_stream_write(read_data)  -- 流式写入音频数据
        sys.wait(20)                   -- 写数据需要留出时间给其他task 运行代码
    end
end

sys.taskInitEx(audio_get_data, "audio_get_data")

---------------------------------
------------通过主task------------
---------------------------------
local taskName = "task_audio"
local function audio_task()
    log.info("开始流式播报")
    if exaudio.setup(audio_setup_param) then
        if exaudio.play_start(audio_play_param) then
            log.info("播放状态",exaudio.is_end())
            sys.publish("AUDIO_READY")  -- 通知数据task可以开始读取数据
        else
            log.error("流式播放启动失败")
        end
    end
end

sys.taskInitEx(audio_task, taskName)

4.4 录音到文件功能-AMR 格式（仅 8101B 支持）

录音到文件功能支持将音频录制为 AMR 格式的文件。

4.4.1 功能定义

配置录音参数，开始录音并保存到指定文件，支持录音时长控制和播放。

• 录音到文件（AMR 格式），默认保存到/sd/record.amr
• 通过 powerkey/boot 按键开始或停止录音/播放
• 支持 5 秒录音时长，可提前结束
• 录音完成后自动播放录音文件

4.4.2 代码示例

--[[
@module  record_amr_file
@summary 录音到文件（AMR格式）
@version 1.0
@date    2026.06.26
@author  拓毅恒
@usage

注意：
1. Air8101使用内置DAC输出音频，无需外部音频编解码芯片
2. 需要固件版本>=V1018才可播放音频
3. 此功能需要用Air8101B来测试，Air8101不支持

录音到文件演示程序，按键功能：
1. Power键：开始/停止录音，停止播放
   - 空闲时按Power键开始5秒录音
   - 录音中按Power键提前结束录音
   - 播放中按Power键停止播放
2. Boot键：开始/停止播放，停止录音
   - 空闲时按Boot键播放录音文件
   - 播放中按Boot键停止播放
   - 录音中按Boot键提前结束录音

音量设置：
  播放音量：60
  录音麦克风音量：60

录音逻辑：
  录音时长为5秒，并计时
  录音过程中可以按任意键提前结束
  录音完成后自动播放录音文件

工作流程：
1. 初始化：挂载TF卡，设置音频硬件参数
2. 录音：流式录音（AMR_NB格式），实时写入TF卡
3. 播放：流式播放录音文件
4. 状态管理：互斥控制录音/播放状态
]]

local exaudio = require("exaudio")

-- TF卡配置参数（Air8101）
local sd_spi_id = 0            -- SPI接口编号
local sd_cs_pin = 32           -- TF卡片选引脚
local sd_power_pin = 50        -- TF卡电源/LDO控制引脚
local sd_mount_path = "/sd"    -- TF卡挂载路径

-- 录音文件路径（保存到TF卡）
local recordPath = sd_mount_path .. "/record.amr"

-- 硬件配置参数 (DAC模式)
local audio_setup_param ={
    model = "dac",            -- 音频编解码类型: "dac" 表示使用内置DAC

    pa_ctrl = 27,             -- 音频放大器电源控制管脚
    pa_on_level = 1,          -- PA打开电平
    pa_delay = 10            -- PA延时
}

-- 全局状态
local is_recording = false     -- 是否正在录音
local is_playing = false       -- 是否正在播放
local record_timer = nil       -- 录音计时器
local record_seconds = 0       -- 录音计时秒数

-- 音量设置
local PLAY_VOLUME = 70         -- 播放音量
local RECORD_VOLUME = 70       -- 录音麦克风音量

-- 录音时长设置（秒）
local RECORD_DURATION = 5      -- 录音时长

-- ========== 播放相关函数 ==========

-- 播放完成回调函数
local function play_end_callback(event)
    if event == exaudio.PLAY_DONE then
        log.info("播放完成")
        is_playing = false
    end
end

-- 开始播放录音文件
local function start_playback()
    log.info("录音文件路径", recordPath)

    if io.exists(recordPath) then
        local audio_play_param = {
            type = 0,
            content = recordPath,
            cbfnc = play_end_callback,
            priority = 1
        }

        local file_size = io.fileSize(recordPath)
        if file_size > 0 then
            log.info("播放录音文件", "大小:", file_size, "字节")
            is_playing = true
            local play_result = exaudio.play_start(audio_play_param)
            if not play_result then
                log.error("播放启动失败")
                is_playing = false
            else
                log.info("播放已开始")
            end
        else
            log.warn("录音文件为空，无法播放")
        end
    else
        log.warn("录音文件不存在，无法播放")
    end
end

-- 停止播放
local function stop_playback()
    if is_playing then
        log.info("停止播放")
        exaudio.play_stop({type = 0})
        is_playing = false
    end
end

-- ========== 录音相关函数 ==========

-- 停止录音计时
local function stop_record_timer()
    if record_timer then
        sys.timerStop(record_timer)
        record_timer = nil
        record_seconds = 0
    end
end

-- 停止录音
local function stop_recording()
    if is_recording then
        log.info("停止录音", "已录制:", record_seconds, "秒")
        exaudio.record_stop()
        is_recording = false
        stop_record_timer()
    end
end

-- 录音完成回调函数
local function record_end_callback(event)
    if event == exaudio.RECORD_DONE then
        is_recording = false
        local file_size = io.fileSize(recordPath)
        log.info("录音完成", "大小:", file_size, "字节")
        stop_record_timer()

        -- 使用定时器延迟500ms后播放录音文件
        sys.timerStart(start_playback, 500)
    end
end

-- 录音计时器回调
local function record_timer_callback()
    if is_recording then
        record_seconds = record_seconds + 1
        log.info("录音中...", record_seconds, "秒")
        if record_seconds >= RECORD_DURATION then
            stop_recording()
            log.info("录音时长已达", RECORD_DURATION, "秒，自动停止录音")
        end
    end
end

-- 开始录音计时
local function start_record_timer()
    record_seconds = 0
    record_timer = sys.timerLoopStart(record_timer_callback, 1000)
end

-- 开始录音
local function start_recording()
    if is_recording then
        log.info("已经在录音中")
        return false
    end

    if is_playing then
        log.info("正在播放中，停止播放")
        stop_playback()
    end

    log.info("开始录音", "时长:", RECORD_DURATION, "秒")

    -- 删除旧录音文件
    if io.exists(recordPath) then
        os.remove(recordPath)
        log.info("删除旧录音文件")
    end

    -- 设置录音麦克风音量
    exaudio.mic_vol(RECORD_VOLUME)

    local audio_record_param = {
        format = exaudio.AMR_NB,
        time = RECORD_DURATION,
        path = recordPath,
        cbfnc = record_end_callback
    }

    local record_result = exaudio.record_start(audio_record_param)
    if record_result then
        is_recording = true
        start_record_timer()
        log.info("录音已开始，按任意键可提前结束")
        return true
    else
        log.error("录音启动失败")
        return false
    end
end

-- ========== 按键处理函数 ==========

-- POWERKEY键：开始/停止录音，停止播放
local function powerkey_handler()
    log.info("按下POWERKEY键")

    if is_recording then
        stop_recording()
    elseif is_playing then
        stop_playback()
    else
        start_recording()
    end
end

-- BOOT键：开始/停止播放，停止录音
local function boot_key_handler()
    log.info("按下BOOT键")

    if is_recording then
        stop_recording()
    elseif is_playing then
        stop_playback()
    else
        start_playback()
    end
end

-- ========== 初始化设置 ==========

-- 设置POWERKEY键（开始/停止录音）
gpio.setup(29, powerkey_handler, gpio.PULLUP, gpio.FALLING)
gpio.debounce(29, 200, 1)

-- 设置BOOT键（开始/停止播放，停止录音）
gpio.setup(37, boot_key_handler, gpio.PULLUP, gpio.FALLING)
gpio.debounce(37, 200, 1)

-- ========== TF卡挂载函数 ==========

-- 挂载TF卡
local function mount_tf_card()
    log.info("开始挂载TF卡")

    -- 打开TF卡电源
    gpio.setup(sd_power_pin, 1, gpio.PULLUP)
    -- 拉高CS脚避免干扰
    gpio.setup(sd_cs_pin, 1, gpio.PULLUP)

    -- CH390 电源走的VBAT拨码开关，还有个LDO开关，对应GPIO53 ，CS脚GPIO34
    gpio.setup(53, 1, gpio.PULLUP) 
    gpio.setup(34, 1, gpio.PULLUP)

    -- little flash 电源走的VBAT拨码开关 还有个LDO开关 对应 GPIO48   CS脚GPIO49
    gpio.setup(48, 1, gpio.PULLUP)
    gpio.setup(49, 1, gpio.PULLUP)

    -- 配置SPI0引脚功能
    pins.setup(6, "SPI0_MISO")
    pins.setup(71, "SPI0_MOSI")
    pins.setup(72, "SPI0_CLK")

    -- 初始化SPI接口
    spi.setup(sd_spi_id, nil, 0, 0, 8, 400 * 1000)
    gpio.setup(sd_cs_pin, 1)

    -- 挂载TF卡，挂载失败时不自动格式化
    local mount_ok, mount_err = fatfs.mount(fatfs.SPI, sd_mount_path, sd_spi_id, sd_cs_pin, 16 * 1000 * 1000, sd_power_pin, 100, false)

    if mount_ok then
        log.info("TF卡挂载成功", "挂载路径:", sd_mount_path)

        -- 获取TF卡空间信息
        local data, err = fatfs.getfree(sd_mount_path)
        if data then
            log.info("TF卡空间信息", json.encode(data))
        else
            log.warn("获取TF卡空间信息失败", err)
        end

        return true
    else
        log.error("TF卡挂载失败", mount_err)
        return false
    end
end

-- ========== 音频主任务 ==========

local function main_audio_task()
    log.info("音频系统初始化")

    -- 先挂载TF卡
    if not mount_tf_card() then
        log.error("TF卡挂载失败，录音文件将无法保存到TF卡")
        -- 如果TF卡挂载失败，使用内部存储路径
        recordPath = "/record.amr"
    else
        log.info("TF卡挂载成功！！！")
    end

    if exaudio.setup(audio_setup_param) then
        -- 设置音量
        exaudio.vol(PLAY_VOLUME)
        exaudio.mic_vol(RECORD_VOLUME)

        log.info("音量设置", "播放:", PLAY_VOLUME, "录音:", RECORD_VOLUME)

        if io.exists(recordPath) then
            local file_size = io.fileSize(recordPath)
            log.info("找到录音文件", "大小:", file_size, "字节", "路径:", recordPath)
        else
            log.info("无录音文件", "路径:", recordPath)
        end

        log.info("按键功能说明：")
        log.info("1. Power键: 开始/停止录音，停止播放")
        log.info("2. Boot键: 开始/停止播放，停止录音")  
        log.info("3. 录音时长: ", RECORD_DURATION, "秒，可提前结束")
        log.info("4. 录音完成后自动播放")
        log.info("5. 录音文件保存到:", recordPath)
    else
        log.error("音频硬件初始化失败")
    end
end

sys.taskInit(main_audio_task)

4.5 流式录音功能-PCM 格式（仅 8101B 支持）

录音到文件功能支持将音频录制为 PCM 格式的文件。

4.5.1 功能定义

配置录音参数，开始录音并保存到指定文件，支持录音时长控制和播放。

• 录音到文件（PCM 格式），默认保存到/sd/record.pcm
• 通过 powerkey/boot 按键开始或停止录音/播放
• 支持流式录音和播放
• 支持 16kHz 采样率、16 位采样深度、有符号 PCM 数据

4.5.2 代码示例

--[[
@module  record_pcm_file
@summary 流式录音到文件功能（PCM格式）
@version 1.0
@date    2026.07.06
@author  拓毅恒
@usage

注意：
1. Air8101使用内置DAC输出音频，无需外部音频编解码芯片
2. 需要固件版本>=V1018才可播放音频
3. 此功能需要用Air8101B来测试，Air8101不支持

录音到文件演示程序，按键功能：
1. Power键：开始/停止录音，停止播放
   - 空闲时按Power键开始5秒录音
   - 录音中按Power键提前结束录音
   - 播放中按Power键停止播放
2. Boot键：开始/停止播放，停止录音
   - 空闲时按Boot键播放录音文件
   - 播放中按Boot键停止播放
   - 录音中按Boot键提前结束录音

音量设置：
  播放音量：70
  录音麦克风音量：70

录音逻辑：
  录音时长为5秒，并计时
  录音过程中可以按任意键提前结束
  录音完成后录音文件保存在TF卡或内部存储中

播放逻辑：
  使用流式播放方式播放PCM格式录音文件
  演示使用16kHz采样率、16位采样深度、有符号PCM数据
  注意：播放采样位深仅支持到24位，如果录制32位录音则无法播放，需要用电脑进行播放！！！

工作流程：
1. 初始化：挂载TF卡，设置音频硬件参数
2. 录音：流式录音，实时写入TF卡，显示写入速度统计
3. 播放：流式播放，按下BOOT按键读取文件并播放
4. 状态管理：互斥控制录音/播放状态
]]

local exaudio = require("exaudio")

-- TF卡配置参数（Air8101）
local sd_spi_id = 0            -- SPI接口编号
local sd_cs_pin = 32           -- TF卡片选引脚
local sd_power_pin = 50        -- TF卡电源/LDO控制引脚
local sd_mount_path = "/sd"    -- TF卡挂载路径

-- 录音文件路径（保存到TF卡）
local recordPath = sd_mount_path .. "/record.pcm"

-- 硬件配置参数 (DAC模式)
local audio_setup_param = {
    model = "dac",            -- 音频编解码类型: "dac" 表示使用内置DAC

    pa_ctrl = 27,             -- 音频放大器电源控制管脚
    pa_on_level = 1,          -- PA打开电平
    pa_delay = 10             -- PA延时
}

-- 全局状态
local is_recording = false     -- 是否正在录音
local is_playing = false       -- 是否正在播放
local record_timer = nil       -- 录音计时器
local record_seconds = 0       -- 录音计时秒数

-- 音量设置
local PLAY_VOLUME = 70         -- 播放音量
local RECORD_VOLUME = 70       -- 录音麦克风音量

-- 录音时长设置（秒）
local RECORD_DURATION = 5      -- 录音时长

-- ========== 播放相关函数 ==========

-- 播放完成回调函数
local function play_end_callback(event)
    if event == exaudio.PLAY_DONE then
        log.info("播放完成")
        is_playing = false
        -- 流式播放完成后，通知多媒体通道已经没有更多数据需要播放了
        exaudio.finish()
    end
end

-- 流式数据读取和写入任务
local function stream_audio_data()
    log.info("开始流式读取录音数据")
    local file = io.open(recordPath, "rb")   -- 打开录音文件进行流式播放

    if not file then
        log.error("无法打开录音文件:", recordPath)
        return
    end

    -- 获取推荐的缓冲区大小
    local buffer_size = exaudio.get_stream_buffer_size() or 4096
    log.info("流式播放缓冲区大小", buffer_size)

    while is_playing do
        local read_data = file:read(buffer_size)  -- 读取文件数据
        if read_data == nil then
            -- 文件读取完毕，关闭文件
            file:close()
            file = nil
            -- 写入数据完毕后，通知多媒体通道已经没有更多数据需要播放了
            exaudio.finish()
            log.info("流式数据读取完成")
            break
        end

        -- 如果读取的数据小于缓冲区大小，补充静音数据
        if #read_data < buffer_size then
            read_data = read_data .. string.rep("\0", buffer_size - #read_data)
        end

        exaudio.play_stream_write(read_data)  -- 流式写入音频数据
        sys.wait(20)                            -- 写数据需要留出时间给其他task运行代码
    end

    -- 如果播放被提前停止，确保文件被关闭
    if file then
        file:close()
        log.info("播放被停止，文件已关闭")
    end
end

-- 开始播放录音文件
local function start_playback()
    log.info("录音文件路径", recordPath)

    -- 如果录音文件存在，播放录音
    if io.exists(recordPath) then
        -- 播放设置
        -- 需要注意：播放采样位深仅支持到24位，如果录制32位录音则无法播放，需要用电脑进行播放！！！
        local audio_play_param = {
            type = 2,              -- 2=流式播放
            cbfnc = play_end_callback,
            priority = 1,
            sampling_rate = 16000,  -- 采样率
            sampling_depth = 16,    -- 采样位深
            signed_or_unsigned = true  -- PCM数据是否有符号
        }

        local file_size = io.fileSize(recordPath)
        if file_size > 0 then
            log.info("流式播放录音文件", "大小:", file_size, "字节")

            is_playing = true

            local play_result = exaudio.play_start(audio_play_param)
            if not play_result then
                log.error("流式播放启动失败")
                is_playing = false
            else
                log.info("流式播放已开始")
                -- 启动流式数据读取任务
                sys.taskInit(stream_audio_data)
            end
        else
            log.warn("录音文件为空，无法播放")
        end
    else
        log.warn("录音文件不存在，无法播放")
    end
end

-- 停止播放
local function stop_playback()
    if is_playing then
        log.info("停止流式播放")
        exaudio.play_stop({type = 2})  -- 停止流式播放
        is_playing = false
    end
end

-- ========== 录音相关函数 ==========

-- 停止录音计时
local function stop_record_timer()
    if record_timer then
        sys.timerStop(record_timer)
        record_timer = nil
        record_seconds = 0
    end
end

-- 停止录音
local function stop_recording()
    if is_recording then
        log.info("停止录音", "已录制:", record_seconds, "秒")
        exaudio.record_stop()
        is_recording = false
        stop_record_timer()
    end
end

-- 录音完成回调函数
local function record_end_callback(event)
    if event == exaudio.RECORD_DONE then
        is_recording = false

        local file_size = io.fileSize(recordPath)
        log.info("录音完成", "大小:", file_size, "字节")
        log.info("按下BOOT键开始播放录音文件")
        stop_record_timer()
    end
end

-- 计算时间差（毫秒）
local function calc_time_diff_ms(start_tick, end_tick)
    -- 检查溢出：Lua中超过0x7fffffff会变成负数
    if (start_tick > 0 and end_tick < 0) or (start_tick < 0 and end_tick > 0) then
        log.warn("时间计算", "mcu.ticks()溢出，无法准确计算时长")
        return nil
    end

    local diff_ticks = end_tick - start_tick
    local hz = mcu.hz()
    if hz == 0 then
        hz = 1000  -- 默认1ms一个tick
    end

    return (diff_ticks * 1000) / hz
end

-- 录音设置
local audio_record_param = {
    format = exaudio.PCM_16000,  -- 使用16kHz PCM格式
    time = RECORD_DURATION,        -- 录制时长
    path = function(buff, size)
        -- 流式回调方式将录音数据写入文件
        if buff and size > 0 then
            -- 获取当前时间
            local start_time = mcu.ticks()  -- 记录开始时间
            local file = io.open(recordPath, "ab")  -- 追加模式打开文件
            if file then
                file:write(buff:query()) -- 将缓冲区数据写入文件
                file:close()             -- 写入完成后关闭文件

                -- 计算写入速度
                local end_time = mcu.ticks()  -- 记录结束时间
                local write_time_ms = calc_time_diff_ms(start_time, end_time)

                if write_time_ms and write_time_ms > 0 then
                    local write_speed = size / (write_time_ms / 1000)  -- 字节/秒
                    log.info("TF卡写入统计",
                        "数据大小:", size, "字节,",
                        "写入耗时:", string.format("%.2f", write_time_ms), "ms,",
                        "写入速度:", string.format("%.2f", write_speed / 1024), "KB/s")
                else
                    log.info("TF卡写入统计",
                        "数据大小:", size, "字节,",
                        "写入耗时: 溢出无法计算")
                end
            else
                log.error("无法打开录音文件")
            end
        end
    end,
    cbfnc = record_end_callback  -- 录音完成回调函数
}

-- 录音计时器回调
local function record_timer_callback()
    if is_recording then
        record_seconds = record_seconds + 1
        log.info("录音中...", record_seconds, "秒")

        -- 如果达到设定时长，自动停止录音
        if record_seconds >= RECORD_DURATION then
            stop_recording()
            log.info("录音时长已达", RECORD_DURATION, "秒，自动停止录音")
        end
    end
end

-- 开始录音计时
local function start_record_timer()
    record_seconds = 0
    record_timer = sys.timerLoopStart(record_timer_callback, 1000)
end

-- 开始录音
local function start_recording()
    if is_recording then
        log.info("已经在录音中")
        return false
    end

    if is_playing then
        log.info("正在播放中，停止播放")
        stop_playback()
    end

    log.info("开始录音", "时长:", RECORD_DURATION, "秒")

    -- 清空旧录音文件（流式模式需要手动管理文件）
    if io.exists(recordPath) then
        os.remove(recordPath)
        log.info("删除旧录音文件")
    end

    -- 设置录音麦克风音量
    exaudio.mic_vol(RECORD_VOLUME)

    local record_result = exaudio.record_start(audio_record_param)
    if record_result then
        is_recording = true
        start_record_timer()
        log.info("录音已开始，按任意键可提前结束")
        return true
    else
        log.error("录音启动失败")
        return false
    end
end

-- ========== 按键处理函数 ==========

-- POWERKEY键：开始/停止录音，停止播放
local function powerkey_handler()
    log.info("按下POWERKEY键")

    if is_recording then
        log.info("正在录音中，停止录音")
        stop_recording()
    elseif is_playing then
        log.info("正在播放中，停止播放")
        stop_playback()
    else
        log.info("空闲状态，开始录音")
        start_recording()
    end
end

-- BOOT键：开始/停止播放，停止录音
local function boot_key_handler()
    log.info("按下BOOT键")

    if is_recording then
        log.info("正在录音中，停止录音")
        stop_recording()
    elseif is_playing then
        log.info("正在播放中，停止播放")
        stop_playback()
    else
        log.info("空闲状态，播放录音")
        start_playback()
    end
end

-- ========== 初始化设置 ==========

-- 设置POWERKEY键（开始/停止录音）
gpio.setup(29, powerkey_handler, gpio.PULLUP, gpio.FALLING)
gpio.debounce(29, 200, 1)

-- 设置BOOT键（开始/停止播放，停止录音）
gpio.setup(37, boot_key_handler, gpio.PULLUP, gpio.FALLING)
gpio.debounce(37, 200, 1)

-- ========== TF卡挂载函数 ==========

-- 挂载TF卡
local function mount_tf_card()
    log.info("开始挂载TF卡")

    -- 打开TF卡电源
    gpio.setup(sd_power_pin, 1, gpio.PULLUP)
    -- 拉高CS脚避免干扰
    gpio.setup(sd_cs_pin, 1, gpio.PULLUP)

    -- CH390 电源走的VBAT拨码开关，还有个LDO开关，对应GPIO53，CS脚GPIO34
    gpio.setup(53, 1, gpio.PULLUP)
    gpio.setup(34, 1, gpio.PULLUP)

    -- little flash 电源走的VBAT拨码开关，还有个LDO开关，对应GPIO48，CS脚GPIO49
    gpio.setup(48, 1, gpio.PULLUP)
    gpio.setup(49, 1, gpio.PULLUP)

    -- 配置SPI0引脚功能
    pins.setup(6, "SPI0_MISO")
    pins.setup(71, "SPI0_MOSI")
    pins.setup(72, "SPI0_CLK")

    -- 初始化SPI接口
    spi.setup(sd_spi_id, nil, 0, 0, 8, 400 * 1000)
    gpio.setup(sd_cs_pin, 1)

    -- 挂载TF卡，挂载失败时不自动格式化
    local mount_ok, mount_err = fatfs.mount(fatfs.SPI, sd_mount_path, sd_spi_id, sd_cs_pin, 16 * 1000 * 1000, sd_power_pin, 100, false)

    if mount_ok then
        log.info("TF卡挂载成功", "挂载路径:", sd_mount_path)

        -- 获取TF卡空间信息
        local data, err = fatfs.getfree(sd_mount_path)
        if data then
            log.info("TF卡空间信息", json.encode(data))
        else
            log.warn("获取TF卡空间信息失败", err)
        end

        return true
    else
        log.error("TF卡挂载失败", mount_err)
        return false
    end
end

-- ========== 音频主任务 ==========

local function main_audio_task()
    log.info("音频系统初始化")

    -- 先挂载TF卡
    if not mount_tf_card() then
        log.error("TF卡挂载失败，录音文件将无法保存到TF卡")
        -- 如果TF卡挂载失败，使用内部存储路径
        recordPath = "/record.pcm"
    else
        log.info("TF卡挂载成功！！！")
    end

    if exaudio.setup(audio_setup_param) then
        -- 设置音量
        exaudio.vol(PLAY_VOLUME)
        exaudio.mic_vol(RECORD_VOLUME)

        log.info("音量设置", "播放:", PLAY_VOLUME, "录音:", RECORD_VOLUME)

        -- 检查是否有录音文件
        if io.exists(recordPath) then
            local file_size = io.fileSize(recordPath)
            log.info("找到录音文件", "大小:", file_size, "字节", "路径:", recordPath)
        else
            log.info("无录音文件", "路径:", recordPath)
        end

        log.info("按键功能说明：")
        log.info("1. Power键: 开始/停止录音，停止播放")
        log.info("2. Boot键: 开始/停止播放，停止录音")
        log.info("3. 录音时长: ", RECORD_DURATION, "秒，可提前结束")
        log.info("4. 录音完成后按Boot键播放")
        log.info("5. 录音文件保存到:", recordPath)
    else
        log.error("音频硬件初始化失败")
    end
end

sys.taskInit(main_audio_task)

五、功能演示

5.1 音频文件播放功能演示（仅 8101B 支持）

确保 main.lua 中保留 require "play_file" 语句，注释其他功能模块

使用 Luatools 将代码烧录到 Air8101B 开发板

烧录完毕后，日志中会打印音频播放的开始和完成信息

开发板将循环播放 sample-6s.mp3 和 10.amr

5.2 文字转语音功能演示（仅 8101B 支持）

确保 main.lua 中保留 require "play_tts" 语句，注释其他功能模块

使用 Luatools 将代码烧录到 Air8101 开发板

开发板将播放 TTS 语音内容，日志中会打印 TTS 播放的开始和完成信息

demo 将自动循环播放各种音色的 TTS 语音

5.3 流式音频播放功能演示

确保 main.lua 中保留 require "play_stream" 语句，注释其他功能模块

使用 Luatools 将代码烧录到 Air8101 开发板

开发板将进行流式音频播放，日志中会显示流式播放的状态

通过按键可调节音量大小，日志中可以看到音量调节信息

5.4 录制音频并播放功能演示-AMR 格式（仅 8101B 支持）

确保 main.lua 中保留 require "record_amr_file" 语句，注释其他功能模块

使用 Luatools 将代码烧录到 Air8101 开发板

烧录完毕后会开始挂载 sd 卡，挂载成功后可以看到卡容量和录音文件保存路径

通过将 GPIO29 短接 GND，按键按下开始录音，录音完成后自动播放录音文件

录制完成后，日志中会显示播放状态信息

5.5 流式录音并播放功能演示-PCM 格式（仅 8101B 支持）

确保 main.lua 中保留 require "record_pcm_file" 语句，注释其他功能模块

使用 Luatools 将代码烧录到 Air8101 开发板

烧录完毕后会开始挂载 sd 卡，挂载成功后可以看到卡容量和录音文件保存路径

通过将 GPIO29 短接 GND，按键按下开始录音，录音完成后自动保存录音文件

录制完成后，日志中会提示按下 boot 播放录音，播放时也会显示状态信息

六、总结

本文档详细展示了 Air8101 工业引擎音频各种功能模式的实现方法和使用场景。通过这些示例，我们可以看到：

1. 音频文件播放功能：支持多种格式的音频文件播放，适用于音乐播放、语音提示等场景
2. 文字转语音功能：实现中文语音合成，适用于语音播报、智能语音交互等应用
3. 流式音频播放功能：支持实时音频数据流播放，适用于网络音频、实时通信等场景
4. 录音到文件功能：支持高质量音频录制，适用于录音笔、语音记录等应用
5. 流式录音到文件功能：实现实时音频数据采集，适用于语音识别、实时分析等高级应用

掌握这些音频功能模式，将为 Air8101 工业引擎的多媒体应用开发提供强大的支持。用户可以根据实际需求，选择合适的音频模式，实现丰富的音频处理功能。

七、常见问题

7.1 音频播放无声音问题

解决方案：

• 检查使用型号是否为 Air8101B，固件版本是否 ≥V1018
• 检查音频硬件连接是否正确
• 确认喇叭是否工作正常
• 检查音频配件板的供电和使能引脚配置是否正确
• 验证 GPIO 管脚配置是否正确

7.2 TTS 播放无声音问题

解决方案：

• 检查使用型号是否为 Air8101B，固件版本是否 ≥V1018
• 检查 TTS 播放流程是否正常触发

7.3 录音功能无法工作问题

解决方案：

• 检查使用型号是否为 Air8101B，固件版本是否 ≥V1018
• 确认麦克风硬件连接正确且完好
• 检查录音参数格式设置是否支持
• 确保存储空间充足