灯光音乐播放器

2026-01-07

灯光音乐播放器是一个基于 Quectel Pi H1 单板电脑的多媒体演示项目。
该项目通过播放本地音乐文件，并对音频信号进行实时分析，驱动 16×16 WS2812 RGB LED 矩阵 显示与音乐节奏同步变化的灯光效果，实现音乐与灯光的联动展示。

本项目主要用于展示 Quectel Pi H1 在音频处理、SPI 外设控制以及多线程实时显示方面的能力，可作为音乐可视化、氛围灯及 LED 显示类应用的参考示例。

开发资源汇总

开发配件清单

配件名称	数量	规格参数
Quectel Pi H1 单板电脑	1块	Quectel Pi H1智能生态开发板
16×16WS2812 RGB全彩显示屏	1块	ws2812 RGB全彩显示屏LED点阵模块点阵屏点阵模组
2PIN PH1.25接口喇叭	1个	2030腔体喇叭8Ω 2W方形喇叭高音质小体积扬声器 2PIN PH1.25接口
USB-C 电源线充电器	1个	27W USB Type-C接口充电器 1.2米线长中规电源PD电源适用于树莓派5代
USB-C DP 显示线 /HDMI 线	1根	规格：DP 1.4；线长：1m；接口：USB-C（公头）- USB-C（公头）规格：HDMI 2.0；线长：1m；接口：HDMI-A（公头）-HDMI-D（公头）
网线	1根	线长：1m；传输速率：千兆；
CPU 散热风扇（可选）	1个	树莓派5代官方原装散热器带导热贴
显示屏	1个	24英寸HDMI显示器

配件实物参考

快速上手

开发准备

Quectel Pi H1单板电脑出厂默认搭载 Debian 13 系统镜像，因此无需再次烧录镜像，仅需按照如下步骤操作即可。

硬件连接

显示连接

将 HDMI 线一端接入单板电脑的 HDMI 接口，另一端接入显示器的 HDMI 接口。

输入设备连接

将 USB 键盘、鼠标接入单板电脑的两个 USB-A 接口上，若用无线输入设备，将接收器插入 USB 口即可。

喇叭连接

将2PIN PH1.25接口的喇叭连接到板子的扬声器输出。

网线连接

将网线一端接入单板电脑的千兆网口，另一端接入路由器的网口（确保路由器已联网）。

跳线帽连接

单板电脑左上角标有AUTO_POWER_ON丝印的排针，确保已经用跳线帽短接。

16×16WS2812连接

16×16 WS2812 RGB LED 显示屏通过 SPI 接口 与 Quectel Pi H1 单板电脑连接，将WS2812的数据输入端连接至Quectel Pi H1的对应接口引脚。

电源连接

将 USB-A 电源线的 USB-A 端接入电源适配器，USB-C 端接入单板电脑的电源口（通常标注POWER IN）。

项目实现

安装前置

确认有网络连接后，打开终端输入命令：

sudo apt update && sudo apt install -y pulseaudio-utils python3-numpy python3-spidev ffmpeg

上述命令将更新软件源并安装项目运行所需的一些库，具体包括：

pulseaudio-utils：提供 pacat 等音频工具，用于在系统中播放解码后的 PCM 音频数据；
python3-numpy：用于音频信号的 FFT 频谱分析和数值计算，支持频谱灯光效果显示；
python3-spidev：提供 Python 访问 SPI 接口的能力，用于驱动 WS2812 RGB LED 矩阵；
ffmpeg：用于将 MP3 / WAV 等音频文件解码为 PCM 数据流，供音频播放与实时分析使用。

配置40Pin接口配置文件

为保证Quectel Pi H1主板和16×16 WS2812能够通信上，需要使能40pin上的spi10，使能方法如下：

在QuecPi主板上，修改qpi-config.ini配置文件。请先执行以下命令打开文件：vi /etc/qpi-config/qpi-config.ini，然后将其内容修改为：

i2c9=enable
spi10=enable
uart12_2w=enable
i2c13=enable
#need pull up gpio47 in you app when use spi14
spi14=disable
led_red_trigger=none
led_blue_trigger=none
led_green_trigger=heartbeat
led_red_brightness=0
led_blue_brightness=0
led_green_brightness=100