ESP8266Audio 库设置

ESP8266Audio 库设置

概述

本节详细介绍 ESP8266Audio 库的配置和使用方法。学习完成后，您将能够：

• 理解 ESP8266Audio 库的核心类和对象模型
• 配置 I2S 引脚定义和输出参数
• 创建音频输出对象和音频生成器对象
• 构建基本的音频播放程序

前置要求

在开始本节之前，请确保：

• 已完成音频库依赖安装
• I2S 模块已正确接线
• 已创建一个 ESP32 基础工程

Library Architecture

Object Model

ESP8266Audio 库采用”管道”架构，通过连接不同的对象类型实现音频流处理：

AudioFileSource ──→ AudioGenerator ──→ AudioOutput
  (输入源)            (解码器)           (输出设备)

三种核心对象的角色：

对象类型	作用	常见实现类
AudioFileSource	提供音频数据源	HTTPStream、HTTPSStream、SPIFFS
AudioGenerator	解码音频数据	MP3、AAC、FLAC、WAV
AudioOutput	输出解码后的音频	I2S、DAC、PWM

对象连接流程图

HTTP 音频流服务器
      │
      ▼
AudioFileSourceHTTPStream ──────→ 连接网络 → 接收音频流数据
      │
      ▼
AudioGeneratorMP3 ──────────────→ 解码 MP3 帧 → PCM 音频数据
      │
      ▼
AudioOutputI2S ─────────────────→ 通过 I2S 总线 → DAC → 扬声器

Core Class Reference

AudioOutputI2S

I2S 音频输出类，负责将 PCM 音频数据通过 I2S 接口发送到外部 DAC。

关键方法：

方法	参数	说明
SetPinout(bclk, lrc, dout)	GPIO 引脚号	设置 I2S 引脚映射
SetVolume(volume)	0-250（默认范围）	设置输出音量
begin()	无	初始化 I2S 接口
stop()	无	停止音频输出
SetGain(gain)	0.0-4.0	设置数字增益（超出可能导致失真）

AudioFileSourceHTTPStream

HTTP 音频流源类，从网络获取音频数据。

关键方法：

方法	参数	说明
open(url)	音频流 URL	打开 HTTP 连接并开始流式接收
close()	无	关闭连接
SetReconnect(tries, delay_ms)	重试次数、延迟	设置断线重连参数

AudioGeneratorMP3

MP3 音频解码器，将 MP3 帧数据解码为 PCM 格式。

关键方法：

方法	参数	说明
begin(file_source, output)	输入源、输出对象	开始解码和播放
loop()	无	定期调用以维持播放
stop()	无	停止解码
isRunning()	无	检查是否正在播放
GetAudioData(info)	AudioInfo 结构体	获取当前音频信息

Basic Audio Playback Sketch

Basic Radio Player

#include <Arduino.h>
#include <WiFi.h>
#include <AudioOutputI2S.h>
#include <AudioGeneratorMP3.h>
#include <AudioFileSourceHTTPStream.h>

// WiFi 配置
const char* ssid = "您的WiFi名称";
const char* password = "您的WiFi密码";

// I2S 引脚定义
#define I2S_BCLK  26
#define I2S_LRCK  25
#define I2S_DIN   22

// 音频流 URL（网络电台）
const char* radioURL = "http://stream.url/your-radio-station.mp3";

// 对象声明
AudioGeneratorMP3 *mp3;
AudioFileSourceHTTPStream *file;
AudioOutputI2S *output;

void setup() {
  Serial.begin(115200);

  // 连接 WiFi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("正在连接 WiFi...");
  }
  Serial.println("WiFi 已连接");

  // 创建 I2S 输出对象
  output = new AudioOutputI2S();
  output->SetPinout(I2S_BCLK, I2S_LRCK, I2S_DIN);
  output->SetVolume(50);  // 设置音量 (0-250)
  output->begin();

  // 创建音频文件源（HTTP 流）
  file = new AudioFileSourceHTTPStream();
  file->open(radioURL);

  // 创建 MP3 解码器并开始播放
  mp3 = new AudioGeneratorMP3();
  mp3->begin(file, output);

  Serial.println("开始播放网络电台");
}

void loop() {
  // 维持音频播放（必须周期性调用）
  if (mp3->isRunning()) {
    if (!mp3->loop()) {
      mp3->stop();
      Serial.println("播放结束");
    }
  } else {
    // 播放结束后延时并尝试重连
    delay(1000);
  }
}

说明：

• 定义了 I2S 引脚映射（BCLK、LRCK、DIN）
• 创建三个核心对象：文件源、解码器、输出设备
• loop() 函数中必须周期性调用 mp3->loop()
• 如果流结束，可以重新连接并继续播放

Getting Stream Information

ESP8266Audio 库提供多种辅助方法来获取当前音频流信息：

// 获取流标题
Serial.printf("流标题: %s\n", file->getStreamTitle());

// 获取流信息
Serial.printf("流信息: %s\n", file->getStreamInfo());

// 获取音频格式信息（需在 begin() 之后调用）
AudioOutputI2S::AudioInfo info;
output->GetAudioInfo(info);
Serial.printf("采样率: %d Hz\n", info.sample_rate);
Serial.printf("位深: %d bit\n", info.bits_per_sample);
Serial.printf("声道数: %d\n", info.channels);

Configuration Options

I2S Pin Configuration

// 标准配置（GPIO 22、25、26）
output->SetPinout(26, 25, 22);

// 配置为不同的引脚
// output->SetPinout(BCLK_PIN, LRCK_PIN, DOUT_PIN);
output->SetPinout(14, 12, 13);  // 例如使用 GPIO 14、12、13

Volume Control Configuration

// 音量控制（0-250）
output->SetVolume(0);    // 静音
output->SetVolume(50);   // 低音量
output->SetVolume(128);  // 中等音量（默认）
output->SetVolume(200);  // 大音量
output->SetVolume(250);  // 最大音量

注意：音量值超过 200 时，部分音频流可能出现削波失真。建议根据实际播放效果调整。

I2S Sample Rate Configuration

// 设置 I2S 采样率（默认 16000）
output->SetOutputModeMono(true);  // 强制单声道输出
// 注：将自动匹配音频文件的采样率

Multi-Format Audio Support

Supporting Multiple Audio Formats

#include <AudioGeneratorMP3.h>
#include <AudioGeneratorAAC.h>
#include <AudioGeneratorFLAC.h>
#include <AudioGeneratorWAV.h>

// 根据格式选择解码器
AudioGenerator* selectDecoder(const char* format) {
  if (strcmp(format, "mp3") == 0) {
    return new AudioGeneratorMP3();
  } else if (strcmp(format, "aac") == 0) {
    return new AudioGeneratorAAC();
  } else if (strcmp(format, "flac") == 0) {
    return new AudioGeneratorFLAC();
  } else if (strcmp(format, "wav") == 0) {
    return new AudioGeneratorWAV();
  }
  return nullptr;
}

故障排除

问题 1: 编译时 “AudioGeneratorMP3.h: No such file”

症状: 编译提示找不到头文件

原因: 库安装不完整或路径错误

解决方案:

// 检查包含路径是否正确
#include <AudioOutputI2S.h>        // 而不是 AudioOutputI2S.hpp
#include <AudioGeneratorMP3.h>     // 确保文件名正确
#include <AudioFileSourceHTTPStream.h>

问题 2: 播放时扬声器无声音但 WiFi 已连接

症状: Serial 输出显示播放中，但扬声器无声音

原因:

• I2S 引脚配置与接线不匹配
• 音量设置为 0
• 音频格式不受支持

解决方案:

1. 验证 SetPinout() 参数与实际接线一致
2. 确保 SetVolume(50) 或更高
3. 检查音频流 URL 是否为支持的格式

Summary

本节介绍了 ESP8266Audio 库的核心配置：

1. 对象架构：AudioFileSource → AudioGenerator → AudioOutput 管道模式
2. 三种核心对象：音频文件源（HTTP 流）、解码器（MP3/AAC）、输出设备（I2S）
3. 引脚配置：通过 SetPinout(bclk, lrc, dout) 设置 I2S 引脚
4. 播放循环：loop() 中必须周期性调用解码器的 loop() 方法