0. 写在前面

2024年初接触乐鑫esp32，到现在已经快两年了，总想着把看到的，用到的写下来，对自己是一个总结归纳的过程，同时也会吸引到同频的人，让前进的路走的更轻松。esp32是一个功能强大的微控制器，它的外设丰富，价格也不算高。我在esp32上运行了一些简单的程序，比如控制led闪烁、读取传感器数据等。但是，esp32的音频输出功能相对较弱，只能输出简单的音频信号。为了能够在esp32上播放更丰富的音频，我需要使用一些特殊的音频格式。而小智团队提出了P3格式，真是说什么来什么。

1. P3格式介绍

P3格式是xiaozhi-esp32项目团队开发的一种专有二进制音频格式，它的全称是P3 Audio Format，就是要解决嵌入式设备在语音交互场景中的特殊需求。与传统音频格式相比，P3具有高度优化的结构设计和极简的解码流程，特别适合ESP32这类资源受限的物联网设备。

1.1 背景

在智能语音设备开发中，开发者通常面临几个核心挑战： 存储空间有限：ESP32的Flash存储容量通常只有4-16MB；CPU资源紧张：复杂音频解码会占用大量处理能力；实时性要求高：语音交互需要低延迟响应；功耗限制严格：电池供电设备需要高效能设计。

而传统音频格式如WAV(未压缩，体积大)和MP3(解码复杂)难以同时满足这些需求，P3格式正是为解决这些痛点而生。

1.2 需要了解的技术细节

P3采用精简的二进制协议结构，其核心定义如下：

struct BinaryProtocol3 {
uint8_t type;// 音频类型标识
uint8_t reserved;// 保留字段
uint16_t payload_size; // 有效载荷大小
uint8_t payload[];// 音频数据主体
} __attribute__((packed));

音频规格参数：

参数	值	说明
采样率	16000Hz	标准语音采样率，平衡音质与效率
声道数	单声道	语音交互场景通常不需要立体声
帧时长	60ms	优化实时交互的延迟表现
编码格式	Opus	高效音频编码，低比特率下保持良好音质

1.3 与wav和mp3的对比

格式	文件大小(示例)	解码耗时	CPU占用	适用场景
WAV	1.6MB	低	低	原始音频存储
MP3	160KB	中	中高	通用音频播放
P3	80KB	极低	低	实时语音交互

2. P3格式转换工具链

xiaozhi-esp32项目提供了完整的P3音频工具链，支持从常见格式转换为P3格式。你可以在项目的scripts/p3_tools目录下找到这些工具，同时查看README.md文件了解更多使用方法。常用的几个工具如下：

• convert_audio_to_p3.py：将常见音频格式(如WAV、MP3)转换为P3格式。
• convert_p3_to_audio.py：将P3格式转换为WAV格式，主要用于调试。
• play_p3.py：直接在ESP32上播放P3文件，无需解码。
• batch_convert_gui.py：提供图形化批量转换界面，支持批量处理多个音频文件。

2.1 pycharm打开目录，创建虚拟环境

python开发环境我一直使用pycharm，这次直接用它打开项目目录，它会找到requirements.txt并提示是否创建一个虚拟环境。同意就好了。
在你的虚拟环境中安装需要的库（指定清华的源，速度更快）：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

2.2 播放p3格式的音频

虚拟环境中运行如下命令即可，非常简单：

python play_p3.py <P3文件路径>

但是运行报错：Could not find Opus library.
这是因为而Opus库的安装比较复杂吧，找到其他兄弟的方案，直接在https://github.com/ShiftMediaProject/opus/releases下载libopus_v1.4_msvc17.zip，解压并把libopus_v1.4_msvc17\bin\x64 目录下的opus.dll文件并复制到C:\Windows\System32目录下。

再次运行就好了。(扯是扯了点，但是好用就行)

python play_p3.py .\welcome.p3

3.esp32上播放p3格式的音频

我们在esp32上播放p3格式的音频，比如main函数下assets\common\success.p3，只需要调用PlaySound函数，传入Lang::Sounds::P3_SUCCESS参数即可。

PlaySound(Lang::Sounds::P3_SUCCESS);

项目资源：

• 官方项目地址：xiaozhi-esp32
• 项目文档：ESP-IDF 开发环境搭建及编译小智
• 资源也可以在公众号中获取