1. 从零开始：为什么选择ESP32和百度AI做语音合成？

如果你正在捣鼓一个智能硬件项目，比如想做个会说话的天气预报盒子、一个能播报提醒的智能闹钟，或者一个简单的信息播报终端，那你大概率会遇到一个核心需求：怎么让这玩意儿“开口说话”？ 自己录？不现实，内容一变就得重录。用现成的语音芯片？灵活性太差，而且成本也不低。这时候，文字转语音（TTS） 技术就成了你的最佳拍档。

而在嵌入式领域玩TTS，ESP32 这颗芯片绝对是明星选手。它自带Wi-Fi和蓝牙，性能足够，生态成熟，关键是围绕它的音频开发框架（比如乐鑫官方的 ESP-ADF）已经非常完善，大大降低了我们处理音频流的复杂度。但光有硬件和框架还不够，我们需要一个强大、稳定且易用的TTS服务来提供“声音”。在国内，百度AI开放平台的语音合成服务 是一个经过市场验证的可靠选择。它合成速度快、音质自然、支持多种音色和参数调节，并且提供了非常清晰的API接口。

所以，把ESP32和百度AI TTS结合起来，我们就能打造一个既能在线获取海量语音内容，又能通过本地硬件稳定播放的智能语音终端。这个方案的优势在于：

  • 灵活：想播什么就合成什么，内容完全动态。
  • 成本可控：ESP32开发板价格亲民，百度AI的语音合成服务也有充足的免费额度供学习和原型开发。
  • 效果出色：得益于百度强大的AI模型，合成的语音非常接近真人，避免了机械感。

接下来，我就带你一步步深入，从环境搭建到代码实战，亲手实现这个“会说话的ESP32”。我会把过程中容易踩的坑、关键的配置参数都讲清楚，确保你跟着做就能成功。

2. 搭建舞台：ESP-ADF开发环境与音频管道初探

工欲善其事，必先利其器。在写代码之前，我们得先把“舞台”搭好。这个舞台就是 ESP-ADF（Espressif Audio Development Framework）。你可以把它理解为一个专为ESP32系列芯片打造的“音频全家桶”，里面集成了音频编解码、流处理、各种输入输出接口等一大堆轮子，我们不用从零造轮子，直接调用就行。

2.1 安装与配置ESP-ADF

首先，确保你的电脑上已经安装了ESP-IDF（乐鑫物联网开发框架）。ADF是基于IDF的。安装过程乐鑫官方文档写得很详细，这里我提几个实测中要注意的点：

  1. 推荐使用乐鑫的离线安装包：对于国内开发者，从官网下载离线安装包（比如 esp-idf-tools-setup-offline）是最快最稳的方式，能避免很多网络环境导致的问题。
  2. 注意Python环境：ESP-IDF对Python版本有要求（比如3.8以上），并且会创建自己的虚拟环境。如果你系统里有多个Python，可能会遇到冲突。我的经验是，严格按照官方指南，使用安装包提供的或它自动安装的Python环境，别用自己的。
  3. 设置环境变量：安装完成后，记得运行 export.sh（Linux/macOS）或 export.bat（Windows）来设置环境变量。很多“命令找不到”的错误都是这一步忘了做。

安装好IDF后，再来克隆ADF。打开终端，找一个合适的目录，执行：

git clone --recursive https://github.com/espressif/esp-adf.git

--recursive 参数很重要，它会同时下载子模块，避免后续编译缺东西。

进入ADF目录，同样需要设置ADF的环境变量路径。通常你会在ADF的根目录找到一个 export.sh 或 export.bat 脚本，运行它。这样，你的开发环境就同时具备了IDF和ADF的能力。

2.2 理解音频处理管道（Pipeline）

这是整个项目的核心思想，一定要先搞明白。你可以把音频数据的处理过程想象成一条自来水管道。

  • 水源（输入流）：水从哪里来？可能是水龙头（本地Flash存储的MP3文件），也可能是水库通过水管送来的水（HTTP网络音频流）。在我们的项目里，就是 http_stream（用于接收百度TTS的音频流）和 flash_tone_stream（用于播放本地音频）。
  • 净水器（解码器）：来的水可能含有杂质（不同的音频编码格式，如MP3、AAC），不能直接喝。净水器负责把水净化成标准的纯净水（PCM裸流）。对应我们的 mp3_decoder，因为百度TTS返回的是MP3格式，我们需要把它解码成ESP32能直接处理的PCM数据。
  • 水泵和水压调节（输出流）：净化后的纯净水，需要通过水泵以合适的压力送到你家每个水龙头。在这里，i2s_stream 就是水泵，它负责将PCM数据以特定的采样率、位深，通过I2S协议这个“管道”，输送给音频编解码芯片（如AC101、ES8388）。
  • 最终出水口（喇叭/耳机）：音频编解码芯片将数字信号转为模拟信号，驱动喇叭发出声音。

ESP-ADF的 esp_audio 组件，就是帮我们自动化搭建和管理这条管道的神器。我们只需要告诉它：“我要一个水源（HTTP流），接一个净水器（MP3解码器），最后用水泵（I2S）送出去”，它就能把各个“零件”连接好，数据就会自动流起来。

下面这张表帮你快速理解管道中的关键角色：

组件类型对应实物ADF中的模块在本项目中的作用
输入流 (Input Stream)水源http_stream, flash_tone_stream获取音频原始数据（来自网络或本地）
解码器 (Decoder)净水器mp3_decoder, wav_decoder等将压缩音频格式（MP3）解码为原始PCM数据
输出流 (Output Stream)水泵+管道i2s_stream将PCM数据通过I2S总线传输给音频芯片
音频芯片 (Codec)水龙头AC101, ES8388等数模转换，驱动扬声器发声

理解了这套模型，再看代码就会豁然开朗。我们接下来的所有操作，本质上都是在配置和组装这条管道。

3. 核心实战：构建ESP32音频播放器管道

理论说得差不多了，咱们直接动手写代码。我会把关键代码拆开揉碎了讲，你完全可以对照着在自己的工程里实现。

3.1 初始化硬件与创建播放器实例

一切的开始，是初始化硬件和创建那个核心的播放器（esp_audio_handle_t）。这就像建房子先打地基。

// 1. 音频板级初始化（非常重要！）
audio_board_handle_t board_handle = audio_board_init();
if (board_handle == NULL) {
    ESP_LOGE(TAG, "音频板初始化失败！检查硬件连接和驱动");
    return;
}
// 这个函数会自动初始化I2C、I2S，并配置好你所使用的音频编解码芯片（如AC101）
// 不同开发板的 audio_board_init 实现可能不同，通常在你的项目 `components` 里能找到。

// 2. 配置播放器参数
esp_audio_cfg_t cfg = DEFAULT_ESP_AUDIO_CONFIG();
// 关联音量控制句柄（这样才能用软件调音量）
cfg.vol_handle = board_handle->audio_hal;
// 设置内存优先（对于网络流播放，这个设置很关键）
cfg.prefer_type = ESP_AUDIO_PREFER_MEM;
// ！！！重点注意：采样率必须和你的音频芯片及喇叭匹配
// 很多开发板（比如常用的ESP32-LyraT）的音频电路设计，需要输出48kHz采样率才能正常发声
cfg.resample_rate = 48000;

// 3. 创建播放器实例
player = esp_audio_create(&cfg);
if (player == NULL) {
    ESP_LOGE(TAG, "创建播放器失败！");
    return;
}

踩坑提醒：cfg.resample_rate 这个参数我栽过跟头。如果你发现喇叭没声音或者全是噪音，十有八九是采样率设错了。务必查阅你的开发板原理图和音频芯片数据手册，确认其支持的标准采样率。对于大多数基于AC101或ES8388的开发板，48000 是安全值。

3.2 组装管道：添加输入、解码与输出

地基打好了，开始接水管。顺序一般是：先加输入，再加解码器，最后加输出。

// 1. 创建并添加HTTP流作为输入源（用于百度TTS）
http_stream_cfg_t http_cfg = HTTP_STREAM_CFG_DEFAULT();
http_cfg.type = AUDIO_STREAM_READER; // 声明这是一个“读取器”
http_cfg.event_handle = _http_stream_event_handle; // 设置事件回调，关键！后面详讲
audio_element_handle_t http_stream_reader = http_stream_init(&http_cfg);
esp_audio_input_stream_add(player, http_stream_reader);

// 2. 创建并添加MP3解码器（因为百度TTS返回MP3格式）
mp3_decoder_cfg_t mp3_dec_cfg = DEFAULT_MP3_DECODER_CONFIG();
esp_audio_codec_lib_add(player, AUDIO_CODEC_TYPE_DECODER, mp3_decoder_init(&mp3_dec_cfg));

// 3. 创建并添加I2S流作为输出源
i2s_stream_cfg_t i2s_cfg = I2S_STREAM_CFG_DEFAULT();
i2s_cfg.type = AUDIO_STREAM_WRITER; // 声明这是一个“写入器”
// 输出配置必须和播放器设置的采样率一致！
i2s_cfg.i2s_config.sample_rate = 48000;
// 声道格式，根据你的硬件连接选择。如果只接了一个喇叭，常用 I2S_CHANNEL_FMT_ALL_RIGHT
i2s_cfg.i2s_config.channel_format = I2S_CHANNEL_FMT_ALL_RIGHT;
i2s_cfg.i2s_config.bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT; // 位深，16位最常见
audio_element_handle_t i2s_stream_writer = i2s_stream_init(&i2s_cfg);
esp_audio_output_stream_add(player, i2s_stream_writer);

ESP_LOGI(TAG, "音频管道组装完成：HTTP -> MP3解码 -> I2S输出");

到这里，一个能处理HTTP MP3流并播放的管道就搭建好了。你可以把它理解为一个“通用播放器”，现在只差把“百度TTS的音频流”这个特定的水源接上去了。

4. 打通云端：集成百度AI语音合成服务

管道建好了，现在要解决“水”从哪里来的问题。我们需要让ESP32能够调用百度的TTS API，并把返回的音频流导入到刚才的HTTP流模块中。

4.1 获取百度AI访问令牌（Access Token）

调用任何百度AI服务，都需要一个通行证——Access Token。它是有时效的（通常30天），所以我们需要在程序中动态获取。

幸运的是，ESP-ADF已经为我们封装好了这个功能。你可以在 components/adf_utils/cloud_services/ 目录下找到 baidu_access_token.c 这个文件。使用起来非常简单：

// 你的百度AI开放平台账号的API Key和Secret Key
#define BAIDU_API_KEY "你的ApiKey"
#define BAIDU_SECRET_KEY "你的SecretKey"

char *baidu_access_token = NULL;

// 在需要调用TTS前，获取Token
if (baidu_access_token == NULL) {
    ESP_LOGI(TAG, "正在获取百度Access Token...");
    baidu_access_token = baidu_get_access_token(BAIDU_API_KEY, BAIDU_SECRET_KEY);
    if (baidu_access_token == NULL) {
        ESP_LOGE(TAG, "获取Token失败，请检查网络和API密钥！");
        // 处理错误，比如重试或进入错误状态
    } else {
        ESP_LOGI(TAG, "Token获取成功: %s", baidu_access_token);
    }
}

重要提示：这个Token是申请来的，用完之后记得在合适的时机（比如程序退出前，或者Token失效后重新获取前）用 free() 函数释放内存，防止内存泄漏。

4.2 构造HTTP请求与处理回调

这是最核心的一步。我们通过 esp_audio_sync_play 函数触发播放，而播放的URL就是百度TTS的API地址。但光有地址不行，我们需要告诉百度“合成什么话”、“用什么声音”、“说多快”。这些信息通过HTTP POST请求的Body传递。

ADF的 http_stream 提供了一个非常棒的回调机制 _http_stream_event_handle。我们可以在请求发送前（HTTP_STREAM_PRE_REQUEST 事件）拦截，并设置我们自定义的请求参数。

// 全局变量，存储要合成的文本
char *text_to_speak = "你好，世界！欢迎使用ESP32智能语音助手。";

/* HTTP流事件回调函数 */
static int _http_stream_event_handle(http_stream_event_msg_t *msg) {
    // 获取HTTP客户端句柄
    esp_http_client_handle_t client = (esp_http_client_handle_t)msg->http_client;

    switch (msg->event_id) {
        case HTTP_STREAM_PRE_REQUEST: {
            // ！！！最重要的阶段：在请求发出前，设置POST参数
            ESP_LOGI(TAG, "正在准备TTS请求参数...");

            // 确保我们有有效的Token
            if (baidu_access_token == NULL) {
                baidu_access_token = baidu_get_access_token(BAIDU_API_KEY, BAIDU_SECRET_KEY);
            }

            // 组装POST请求的Body数据
            // 参数说明：
            // tex: URL编码后的要合成的文本（最核心）
            // tok: 上面获取的Access Token
            // lan: 语言，zh中文
            // ctp: 客户端类型，2表示WebAPI
            // cuid: 设备标识，可以自定义
            // aue: 音频编码，3表示mp3格式（适合ESP32解码）
            // per: 发音人，0为女声，1为男声，还有其他特色音色可选
            // spd: 语速，0-15，5为中速
            // pit: 音调，0-15，5为中调
            // vol: 音量，0-15，5为中音量
            char post_data[1024] = {0};
            // 对文本进行URL编码是必须的，防止中文等特殊字符导致请求错误
            char *encoded_text = http_utils_assign_string(&encoded_text, text_to_speak);
            // 这里假设有一个url_encode函数，实际使用时需要实现或使用库函数
            // encoded_text = url_encode(text_to_speak);

            int data_len = snprintf(post_data, sizeof(post_data),
                                     "tex=%s&tok=%s&lan=zh&ctp=2&cuid=esp32_device&aue=3&per=0&spd=5&pit=5&vol=5",
                                     encoded_text, // 使用编码后的文本
                                     baidu_access_token);

            // 设置HTTP客户端使用POST方法
            esp_http_client_set_method(client, HTTP_METHOD_POST);
            // 设置POST数据
            esp_http_client_set_post_field(client, post_data, data_len);
            // 设置Content-Type
            esp_http_client_set_header(client, "Content-Type", "application/x-www-form-urlencoded");

            ESP_LOGI(TAG, "POST数据长度: %d", data_len);
            // free(encoded_text); // 记得释放内存
            break;
        }
        case HTTP_STREAM_ON_RESPONSE:
            ESP_LOGI(TAG, "收到服务器响应");
            // 可以在这里检查HTTP状态码，比如200表示成功
            break;
        case HTTP_STREAM_FINISH_REQUEST:
            ESP_LOGI(TAG, "HTTP请求完成");
            // 一次TTS播放完成
            break;
        // 其他事件可以根据需要处理
    }
    return ESP_OK;
}

4.3 触发播放与流程串联

最后，我们把所有环节串联起来。当需要播放某段文字时，只需做两件事：

  1. 更新要合成的文本。
  2. 调用播放函数，指向百度TTS的API地址。
// 定义一个函数来播放指定文本
void play_tts(const char *text) {
    // 1. 更新全局文本变量（注意线程安全，本例为简单演示）
    if (text_to_speak) {
        free(text_to_speak);
    }
    text_to_speak = strdup(text); // 复制字符串

    // 2. 触发播放。player会使用我们之前添加的http_stream_reader
    // 去请求这个URL，并在请求前触发回调函数设置参数。
    esp_err_t ret = esp_audio_sync_play(player, "http://tsn.baidu.com/text2audio", 0);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "播放失败: %s", esp_err_to_name(ret));
    } else {
        ESP_LOGI(TAG, "开始播放TTS: %s", text);
    }
}

// 在你的主程序或某个任务中调用
play_tts("现在时间是下午三点整。");

当 esp_audio_sync_play 被调用时，整个系统就开始运转：

  1. Player通知 http_stream_reader 去连接 tsn.baidu.com。
  2. 在连接建立、请求即将发送时，触发 HTTP_STREAM_PRE_REQUEST 事件，执行我们的回调函数。
  3. 回调函数中，我们设置了POST方法和包含Token、文本等参数的Body。
  4. 请求发出，百度服务器收到后开始合成语音，并以MP3音频流的形式返回。
  5. http_stream_reader 接收到音频流数据，送入管道。
  6. 数据经过 mp3_decoder 解码成PCM。
  7. PCM数据通过 i2s_stream_writer 发送给音频芯片。
  8. 喇叭播放出“现在时间是下午三点整。”的语音。

5. 功能扩展与调试锦囊

一个基础能跑的TTS播放器已经完成了。但想把它用到实际项目里，还得考虑更多。

5.1 播放本地音频与多源切换

我们的管道里早就添加了 flash_tone_stream，播放本地音频（比如提示音、背景音乐）就变得非常简单。你可以把MP3文件烧录到ESP32的SPIFFS文件系统里。

// 播放存储在Flash文件系统中的 /spiffs/startup.mp3 文件
esp_audio_sync_play(player, "file://spiffs/startup.mp3", 0);

ADF的 esp_audio 组件支持自动识别协议头（http://, file://, fat:// 等），并自动切换到对应的输入流进行处理。这意味着你可以在播放完一段网络TTS后，无缝切换播放本地提示音，用户体验会更好。

5.2 关键参数调优与常见问题

  • 内存不足（ESP_ERR_NO_MEM）：这是嵌入式开发永恒的话题。ESP32内存有限，尤其是在同时处理网络、音频解码时。
    • 对策：在 menuconfig 中 (idf.py menuconfig) 增大音频缓冲区的数量（Audio HAL -> Number of audio pipeline buffers）和大小。但要注意总量。
    • 优化代码：确保及时释放不再使用的内存，比如播放完成后的缓冲区、旧的Token等。
  • 网络不稳定导致播放卡顿或中断：
    • 对策：增加HTTP流的缓冲区大小（在 http_stream_cfg_t 中配置）。启用ADF内部的音频缓存机制，它可以在网络短暂中断时用缓存的数据维持播放。
    • 重试机制：在回调函数的 HTTP_STREAM_FINISH_REQUEST 事件中，如果播放未正常完成，可以加入重试逻辑。
  • 音质或语速不满意：直接调整POST参数！
    • per=4 可以尝试情感男声。
    • spd=7 会让语速更快，spd=3 更慢。
    • vol=10 提高音量。
    • 多试几组参数，找到最适合你应用场景的组合。
  • Token管理：Token有效期很长，但也不是永久的。一个稳健的做法是，在每次播放前检查Token是否为空，如果为空则获取；或者更高级一点，在 HTTP_STREAM_PRE_REQUEST 回调中，如果服务器返回了Token过期的错误码（需要解析响应头），则触发一次Token刷新，然后重新发起请求。

调试时，一定要善用 ESP_LOGI, ESP_LOGD, ESP_LOGE 这些日志输出。把关键步骤、函数返回值、内存状态都打出来看，能帮你快速定位问题所在。特别是当喇叭没声音时，顺着“网络请求成功了吗？”->“MP3解码器启动了吗？”->“I2S数据在发送吗？”->“音频芯片初始化了吗？”这个链条一步步查日志，问题总能解决。

最后，别忘了百度AI开放平台的控制台，那里可以看到你每天的请求量、是否有错误请求，对于排查“为什么请求失败了”非常有帮助。把嵌入式硬件、网络服务和云端API三者协同工作跑通，看着自己做的硬件清晰地播报出第一句话，那种成就感，就是驱动我们不断折腾的最大乐趣。

Logo
乐奇 Rokid 开放社区

更多推荐

cover

智能眼镜新品扎堆：AR、VR、MR到底怎么分？

avatar 乐奇 Rokid 开放社区
cover

AI眼镜里面有晶振吗？智能眼镜的时钟系统

avatar 乐奇 Rokid 开放社区
cover

Meta Muse 爆火：12 天下载量反超 ChatGPT，个人 AI 智能体完整使用指南

avatar 乐奇 Rokid 开放社区