灯光音乐播放器是一个基于Quectel Pi H1智能主控板的多媒体演示项目。
该项目通过播放本地音乐文件，并对音频信号进行实时分析，驱动?16 × 16 WS2812 RGB LED矩阵显示与音乐节奏同步变化的灯光效果，实现音乐与灯光的联动展示。
灯光音乐播放器是一个基于Quectel Pi H1智能主控板的多媒体演示项目。
该项目通过播放本地音乐文件，并对音频信号进行实时分析，驱动?16 × 16 WS2812 RGB LED矩阵显示与音乐节奏同步变化的灯光效果，实现音乐与灯光的联动展示。
本项目主要用于展示Quectel Pi H1在音频处理、SPI外设控制以及多线程实时显示方面的能力，可作为音乐可视化、氛围灯及LED显示类应用的参考示例。
| 配件名称 | 数量 | 规格参数 |
|---|---|---|
| Quectel Pi H1智能主控板 | 1 块 | Quectel Pi H1智能主控板 |
| 16 × 16 WS2812 RGB全彩显示屏 | 1 块 | ws2812 RGB全彩显示屏LED点阵模块点阵屏点阵模组 |
| 2PIN PH1.25接口喇叭 | 1 个 | 2030 腔体喇叭 8 Ω 2 W方形喇叭高音质小体积扬声器 2 PIN PH 1.25 接口 |
| 电源适配器 | 1 个 | 27 W USB Type-C接口充电器 1.2 米线长中规电源PD电源 适用于树莓派 5 代 |
| USB-C DP显示线/HDMI 线 | 1 根 | 规格：DP 1.4；线长：1 m；接口：USB-C（公头）- USB-C（公头） 规格：HDMI 2.0；线长：1 m；接口：HDMI-A（公头）-HDMI-D（公头） |
| 网线 | 1 根 | 线长：1 m；传输速率：千兆 |
| CPU散热风扇（可选） | 1 个 | 树莓派 5 代官方原装散热器带导热贴 |
| 显示屏 | 1 个 | 24 英寸HDMI显示器 |
Quectel Pi H1智能主控板出厂默认搭载Debian 13系统镜像，因此无需再次烧录镜像，仅需按照如下步骤操作即可。
将HDMI线一端接入智能主控板的HDMI接口，另一端接入显示器的HDMI接口。
将USB键盘、鼠标接入智能主控板的两个USB-A接口上，若用无线输入设备，将接收器插入USB口即可。
将 2 PIN PH 1.25 接口的喇叭连接到智能主控板的SPK输出。
将网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（确保路由器已联网）。
智能主控板左上角标有AUTO_POWER_ON丝印的排针，确保已经用跳线帽短接。
16 × 16 WS2812 RGB LED显示屏通过SPI 接口与Quectel Pi H1智能主控板连接，将WS2812的数据输入端连接至Quectel Pi H1的对应接口引脚。
将USB-A电源线的USB-A端接入电源适配器，USB-C端接入智能主控板的电源口（通常标注POWER IN）。
确认有网络连接后，打开终端输入命令：
上述命令将更新软件源并安装项目运行所需的一些库，具体包括：
sudo qpi-config 40pin set，之后重启Quectel Pi H1主板使配置生效。下载代码
代码解压到设备。如果是远程访问，文件传输参考SCP文件拷贝
将需要播放的音乐文件（支持MP3/WAV格式）拷贝至以下目录：
程序启动后将自动扫描该目录中的音乐文件并生成播放列表。
在项目目录下执行以下命令启动程序：
cd light_music_player
sudo python3 light_music_player.py
灯光效果可配置为mode1或mode2，程序启动后，将自动开始播放音乐，并在 16 × 16 WS2812 LED矩阵上显示与音乐节奏同步变化的灯光效果。
运行程序后，终端提示按键操作（n切换下一首，u切换上一首，q或Ctrl+C可以退出程序）。
注意事项：16 × 16 WS2812灯板排列说明
由于不同厂商的 16 × 16 WS2812 RGB灯板在物理走线方式上可能存在差异，本项目所使用的灯板其物理排列方式如下：
即第一行从左到右排列，第二行从右到左折返，依次向上延伸。
程序内部的灯光效果（频谱方向、雨滴方向等）均基于上述排列方式进行坐标映射。
若实际使用的WS2812灯板走线方式与上述描述不一致，可能会出现显示方向颠倒或错位的情况，此时需要根据灯板实际走线方式调整LED矩阵映射配置。
mode1--频谱推进效果
该模式基于音频的 16 频段频谱分析结果：
? LED矩阵的每一列对应一个频段能量；
? 柱状高度随频谱能量实时变化；
? 支持平滑上升、缓慢回落以及峰值保持效果；
? 在音乐节奏突变时，整体画面会产生明显的推进视觉效果。
mode2--雨滴灯光效果
该模式模拟雨滴从矩阵顶部向下坠落的视觉效果：
? 雨滴生成频率随音乐强度动态变化；
? 支持尾迹显示与背景色填充；
? 音量越大，雨滴越密集、亮度越高。