# audioFFT

**Repository Path**: ccgaofeng/audio-fft

## Basic Information

- **Project Name**: audioFFT
- **Description**: 这是一个基于 **ROS 2** 和 **ESP32** 的分布式音频频谱显示系统。项目采用 C++ 进行全栈开发（ESP32 Firmware + ROS 2 Node），旨在实现高实时性的音频可视化，并具备工业级的“边缘离线降级”机制。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ROS 2 Distributed Audio Spectrum Display (C++ Edition)

这是一个基于 **ROS 2** 和 **ESP32** 的分布式音频频谱显示系统。项目采用 C++ 进行全栈开发（ESP32 Firmware + ROS 2 Node），旨在实现高实时性的音频可视化，并具备工业级的“边缘离线降级”机制。

当前仓库包含 **树莓派端 C++ FFT 测试程序** 与 **Python 频谱可视化脚本**，用于本地验证 FFT 与可视化流程；ESP32 固件与 ROS 2 工作空间为规划中。

## 下载后如何运行 (Quick Start)

在另一台电脑克隆本仓库后，按以下步骤操作即可编译并运行。

1. **克隆仓库**
   ```bash
   git clone <仓库URL> && cd audioFFT
   ```

2. **安装依赖**  
   详见 [INSTALL.md](INSTALL.md)。简要步骤:
   - 系统依赖 (C++ 编译): `sudo apt-get install -y libsndfile1-dev libfftw3-dev`
   - Python 依赖 (可选, 用于实时可视化): `pip install -r requirements.txt` (建议在 venv 中执行)

3. **编译 C++ 程序**  
   任选其一:
   - CMake: `mkdir -p build && cd build && cmake .. && make`，可执行文件在 `build/piAudioFFT_test`
   - Makefile: 在项目根目录执行 `make`，可执行文件为 `./piAudioFFT_test`

4. **运行**
   - 仅处理音频并输出到控制台: `./piAudioFFT_test audio/086_welcome.mp3`
   - 输出 CSV: `./piAudioFFT_test audio/086_welcome.mp3 --csv fft.csv`
   - 实时 Python 可视化: `./piAudioFFT_test audio/086_welcome.mp3 --python visualize_spectrum.py`  
     (若用 CMake 构建, 请使用 `./build/piAudioFFT_test ...` 并确保在项目根目录执行, 以便 `audio/` 与 `visualize_spectrum.py` 路径正确)

5. **测试用音频**  
   仓库内 `audio/` 目录下可放置 WAV/MP3 文件, 例如 `audio/086_welcome.mp3`。`fft.csv` 为程序生成的示例输出 (使用 `--csv fft.csv` 时)。

## 🏗 架构概览 (Architecture)

系统由**上位机**（ROS 2 Agent & Processor）和**下位机**（ESP32 Edge Node）组成，通过 Micro-ROS (Wi-Fi UDP) 通信。

*   **Mode A: 在线模式 (Online Mode)**
    *   ESP32 采集音频 -> 上传至 ROS 2 -> 树莓派执行 FFT (FFTW3) -> 下发频谱数据 -> ESP32 显示。
    *   *优势:* 利用上位机强大算力，可扩展复杂的视觉算法。
*   **Mode B: 离线/降级模式 (Fallback Mode)**
    *   ESP32 检测到连接断开 -> 执行本地简易 FFT -> 直接显示。
    *   *优势:* 保证设备在网络故障时仍能独立工作（Fail-Safe）。

## 🛠 硬件清单 (Hardware)

*   **上位机:** Raspberry Pi 5 (Ubuntu 24.04 / ROS 2 Jazzy)
*   **MCU:** ESP32-WROOM-32 开发板
*   **音频传感器:** INMP441 (I2S 全向麦克风)
*   **显示:** WS2812B 柔性点阵屏 (8x32 推荐)
*   **电源:** 5V 3A+ 电源适配器 (WS2812 功耗较大，请勿仅靠 USB 供电)

## 📂 目录结构 (Directory Structure)

当前仓库 (C++ 测试与 Python 可视化) 结构如下。ESP32/ROS2 相关目录为规划中。

```text
.
├── Source/
│   └── piAudioFFT_test.cpp   # 树莓派端 C++ FFT 测试 (FFTW3, libsndfile)
├── audio/                    # 测试用音频文件 (如 086_welcome.mp3)
├── CMakeLists.txt            # CMake 构建配置
├── Makefile                  # Make 构建
├── visualize_spectrum.py     # Python 实时频谱可视化 (从 stdin 读 JSON)
├── requirements.txt         # Python 依赖
├── INSTALL.md                # 依赖安装与构建、运行说明
├── .cursorrules              # Cursor AI 辅助编程规则
└── ReadMe.md                 # 本文件
```

规划中的结构 (待实现):

```text
esp32_firmware/               # ESP32 端代码 (PlatformIO Project)
ros2_ws/                      # 树莓派端 ROS 2 工作空间
```