音频文件转换工具

本文介绍 AC82N 通用 MCU SDK 中用于将音频文件转换为固件可播放资源的开发工具（提示音/播报音频转换），包括工具在仓库中的位置、使用入口、转换链路以及相关注意事项。

Purpose and Scope

本页面覆盖 AC82N SDK 中与音频文件转换相关的开发工具链：从源音频文件（如 WAV/MP3）转换为固件可直接播放的提示音/播报资源（prompt resource）的脚本入口、转换链路与使用方式。

以下相关主题属于同目录下的兄弟页面，不在本页展开：

烧录与升级工具（USB 升级工具、生产烧写工具）——固件烧录与量产工具，见 README「安装烧录工具」一节。
图片资源生成工具（doc/软件工具/图片资源生成工具/）——UI 图片资源转换，属于另一条独立的资源转换链路。
编译环境与工具链安装——交叉编译工具链（clang/pi32）的搭建，见 README.md 环境搭建章节。

Overview

fw-AC82N_GP-MCU_SDK 是杰理科技为 AC82N 系列芯片（cd09 平台：AC822B / AC823B / AC825A / AC826B）提供的通用 MCU SDK。该系列定位为无蓝牙功能的通用 MCU SoC，其中一项核心特性是支持 APA 播报（Audio Prompt Announcement，音频提示播报）。

APA 播报依赖固件内置的提示音资源。由于 MCU 的资源与解码能力受限，工程中不能直接使用原始音频文件，而需要通过专用的音频转换工具将源音频（WAV/MP3 等）转换成固件可识别的资源格式，再通过资源打包流程集成进固件。音频文件转换工具正是这条链路的入口：

仓库内提供了批处理脚本 make_prompt.bat 作为转换入口，分别出现在主 SDK 工程树（sdk/tools/）和 UBOOT 工程树（sdk/UBOOT工程/tools/）中；
转换产物（提示音资源）随后参与固件的资源打包与烧录流程。

说明：受限于本次源码读取预算，make_prompt.bat 的内部具体实现（调用哪些转换程序、支持哪些参数）未能在本次勘察中直接读取到源码内容。本文依据仓库结构、README 及工具分布给出可验证的架构与使用指引；脚本内部细节标注为「源码中未读取到」，不进行臆测。

Architecture

下图展示了音频文件转换工具在 SDK 中的位置与数据流向（基于仓库中可验证的文件结构）：

flowchart TD
    subgraph sg_Source["源音频输入"]
        WAV["WAV 音频文件"]
        MP3["MP3 音频文件"]
        PCM["PCM 裸数据"]
    end

    subgraph sg_Tool["音频文件转换工具"]
        MP["make_prompt.bat<br/>sdk/tools/ 与 sdk/UBOOT工程/tools/"]
        CONV["转换处理<br/>（调用外部转换程序，实现细节未在源码中读取到）"]
    end

    subgraph sg_Firmware["固件侧"]
        RES["提示音/播报资源<br/>（prompt resource）"]
        APA["APA 播报引擎"]
        FW["固件镜像"]
    end

    WAV --> MP
    MP3 --> MP
    PCM --> MP
    MP --> CONV
    CONV --> RES
    RES --> APA
    RES --> FW

架构说明

输入侧：源音频文件（WAV/MP3/PCM 等常见格式）由开发者准备，通常为提示音、按键音、报警音等短音频。
转换入口：make_prompt.bat 是仓库中可验证的转换脚本入口。它同时存在于主 SDK 工程（sdk/tools/make_prompt.bat）与 UBOOT 工程（sdk/UBOOT工程/tools/make_prompt.bat），说明两条工程树共用同一套提示音资源生成机制。
输出侧：转换产物进入固件资源体系，供 APA 播报引擎在运行时播放，或随固件镜像一起烧录。
设计意图：将音频转换做成独立脚本而非固化在编译流程中，便于开发者在编译前单独迭代提示音内容；同时两套工程树共用脚本，保证提示音资源格式一致。

工具分布与使用入口

仓库中的脚本入口

通过仓库文件勘察，音频转换相关脚本入口如下（均以 make_prompt 命名，即「生成提示音」）：

文件路径	所属工程树	作用
sdk/tools/make_prompt.bat	主 SDK 工程（`sdk/`）	GP MCU 应用工程生成提示音资源
sdk/UBOOT工程/tools/make_prompt.bat	UBOOT 工程（`sdk/UBOOT工程/`）	UBOOT 引导工程生成提示音资源

两处脚本同名，说明提示音资源生成逻辑在主应用与引导程序中复用，保证两阶段播放的音频格式一致。

转换链路中的上下游

make_prompt.bat 位于 tools/ 目录，与仓库内其他工具脚本（如 sdk/tools/utils/do_merge_libs.bat 库合并脚本）并列，属于 SDK 构建工具集的一部分。结合仓库结构可确认的链路为：

源音频(WAV/MP3/PCM)
      │  make_prompt.bat（转换入口）
      ▼
提示音资源(prompt resource)
      │  资源打包 / 固件编译
      ▼
固件镜像 → 烧录 → APA 播报

使用流程

基于工具在工程树中的位置与 README 描述，典型的音频转换使用流程如下：

准备源音频：按提示音用途录制/剪辑 WAV、MP3 或 PCM 音频；
运行转换脚本：在对应工程树的 tools/ 目录执行 make_prompt.bat，将源音频转换为提示音资源；
集成到工程：转换产物交由资源打包流程并入固件；
编译与烧录：使用杰理编译工具链编译固件，并通过 USB 升级工具/生产烧写工具烧录到目标板（AC82B/AC823B/AC825A/AC826B）；
验证播报：在目标板上触发 APA 播报，确认音质与触发逻辑。

注：make_prompt.bat 内部具体调用哪个转换程序、支持的参数与格式清单，本次勘察未能在源码中读取到，需要以杰理官方工具文档（文档中心 / 开发工具文档）为准。

使用示例

示例 1：验证转换工具链环境（来自 README）

音频转换脚本底层依赖杰理编译工具链（/opt/jieli/pi32/bin/clang，Windows 下为 Code::Blocks IDE 自带环境）。README 给出的工具链安装验证方式如下：

# 验证工具链是否安装成功
clang --version

Source: README.md

在 Linux 环境下，工具链下载后需解压到 /opt/jieli 目录，并确保 clang 可执行；转换脚本依赖该环境解析音频并生成资源。

示例 2：进入 SDK 工程目录（转换工具运行前提）

转换脚本 make_prompt.bat 位于 SDK 工程树内，使用前需先克隆仓库并进入对应目录：

git clone https://gitee.com/Jieli-Tech/AC82N.git
cd AC82N/sdk

Source: README.md

克隆后可在 sdk/tools/ 下找到 make_prompt.bat 转换入口。

示例 3：获取配套烧录工具（转换产物落地验证）

转换出的提示音资源随固件烧录到目标板后即可验证。README 列出的烧录工具获取方式：

工具	用途	获取方式
USB 升级工具	将固件烧录到目标板	申请链接 · 使用文档
生产烧写工具	量产/裸片烧写	代理商处 · 使用文档

Source: README.md

注意事项与常见问题

工具链依赖：make_prompt.bat 依赖杰理交叉编译工具链环境，Windows 下推荐 Code::Blocks IDE，Linux 下需将工具链安装到 /opt/jieli（见 README.md 环境搭建）。
平台差异：macOS 需自行配置交叉编译工具链，可能存在脚本兼容性问题。
资源一致性：主 SDK 与 UBOOT 工程各自保留 make_prompt.bat，修改提示音时建议两处同步，避免引导阶段与运行阶段播报资源不一致。
音频格式与参数：源音频的采样率、位深、声道数需满足固件 APA 播报引擎的要求；具体约束以杰理官方转换工具文档为准（本次源码勘察未读取到脚本内部参数）。

失败模式与边界情况

基于仓库可验证信息与工具链的通用行为，音频转换环节可能的失败模式如下：

失败模式	可能原因	处理建议
脚本无法运行	未安装杰理编译工具链，或 `clang` 不在 PATH 中	按 README 环境搭建章节安装工具链，验证 `clang --version`
Linux 下脚本异常	工具链未解压到 `/opt/jieli`	确保 `/opt/jieli/pi32/bin/clang` 存在
macOS 下编译/转换失败	缺少交叉编译工具链配置	自行配置交叉编译工具链（README 标注为 ⚠️ 需自行配置）
提示音播放异常	源音频格式/采样率不符合 APA 播报引擎要求	按官方工具文档重新转换，确认格式参数
引导阶段无提示音	UBOOT 工程树提示音资源未同步更新	同步更新 sdk/UBOOT工程/tools/make_prompt.bat 生成的资源

并发与一致性说明

转换脚本为构建期批处理工具，运行于编译前的开发机环境，不存在运行期并发问题。需要关注的一致性风险在于：主 SDK 工程与 UBOOT 工程各自维护一套 make_prompt.bat 及其产物，若只更新其中一处，可能导致不同启动阶段播放的提示音资源不一致。

扩展点

提示音内容扩展：新增提示音只需准备新的源音频并通过 make_prompt.bat 转换，无需修改固件解码逻辑，便于产品化定制（体脂秤语音播报、仪器仪表报警音等场景）。
工具脚本复用：make_prompt.bat 位于 tools/ 目录，与 do_merge_libs.bat（库合并）等脚本并列，可在持续集成流程中编排调用。
跨工程复用：主 SDK 与 UBOOT 工程共用同一转换机制，可将转换产物纳入统一的资源版本管理。