灯光音乐播放器¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
灯光音乐播放器是一个基于Quectel Pi H1智能主控板的多媒体演示项目。
本项目播放本地音乐文件，并实时分析音频信号，驱动16 × 16 WS2812全彩RGB LED点阵屏显示出与音乐节奏同步变化的灯光效果，实现音乐与灯光的联动。
本项目主要用于展示Quectel Pi H1智能主控板在音频处理、SPI外设控制以及多线程实时显示方面的能力，可作为音乐可视化、氛围灯及LED显示类应用的参考示例。
开发资源汇总¶
开发配件清单¶
配件名称 |
数量 |
规格参数 |
|---|---|---|
Quectel Pi H1智能主控板 |
1 |
|
16 × 16 WS2812全彩RGB LED点阵屏 |
1 |
|
2Pin PH1.25接口喇叭 |
1 |
|
电源适配器 |
1 |
|
Micro HDMI线 |
1 |
Micro HDMI 2.0；线长：1米；接口：HDMI-A（公头）转HDMI-D（公头） |
网线 |
1 |
线长：1米；传输速率：千兆 |
CPU散热风扇（可选） |
1 |
|
HDMI显示器 |
1 |
HDMI显示器 |
配件实物参考¶
快速上手¶
开发准备¶
Quectel Pi H1出厂预装Debian 13操作系统，通常无需重新烧录系统镜像。按如下步骤操作即可：
硬件连接¶
接口外设连接¶
显示连接：将Micro HDMI线一端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口。
网络连接：将网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（确保路由器已联网）。
输入设备连接：将USB键盘、鼠标接入USB接口。
供电连接：将USB-A电源线的USB-A端接入电源适配器，USB-C端接入智能主控板的电源口（通常标注 POWER IN）。
散热风扇连接：先将散热风扇的排线插入智能主控板的FAN插槽中，再将风扇的两端固定在智能主控板预留的插孔中。
喇叭连接：将2Pin PH1.25接口喇叭连接到智能主控板的SPK插槽中。
16 × 16 WS2812连接¶
16 × 16 WS2812全彩RGB LED点阵屏通过SPI接口与智能主控板连接，其数据输入端应连接至智能主控板的对应引脚,VCC和GND分别与40Pin对应的引脚相接（接线方式见下图）：
电流负载限制：16 × 16 LED点阵屏满载功耗较高。若直接通过主板Pin 2/Pin 4（5 V 端子）取电，务必在软件中将全局亮度限制在15 %以下，防止主控板过流欠压重启。
外部独立供电建议：如需更高亮度显示或长时间稳定运行，强烈建议使用外部独立5 V/ 5 A直流电源为点阵屏供电，并将外部电源的GND与智能主控板的GND引脚共地。
项目实现¶
安装前置¶
确认有网络连接后，打开终端输入如下命令：
sudo apt update && sudo apt install -y pulseaudio-utils python3-numpy python3-spidev ffmpeg
上述命令将更新本地软件包索引缓存并安装项目运行所需的底层多媒体工具与Python运行时依赖，具体包括：
pulseaudio-utils：提供 pacat 等音频工具，用于在系统中播放解码后的PCM音频数据；
python3-numpy：用于音频信号的FFT频谱分析和数值计算，支持频谱灯光效果显示；
python3-spidev：提供Python访问SPI接口的能力，用于驱动WS2812全彩RGB LED点阵屏；
ffmpeg：用于将MP3、WAV等格式的音频文件解码为PCM数据流，供音频播放与实时分析使用。
配置40-Pin接口配置文件¶
为确保智能主控板和16×16 WS2812全彩RGB LED点阵屏成功通信，需要使能40-Pin上的spi10，操作步骤如下：
在智能主控板上，执行 vi /etc/qpi-config/qpi-config.ini 打开 qpi-config.ini 配置文件，将 spi10=disable 改为 spi10=enable，具体如下：
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
在终端输入 sudo qpi-config 40pin set，之后重启智能主控板使配置生效。
获取代码¶
音乐文件准备¶
将音乐文件（支持MP3和WAV格式）复制到用户的Music目录下，如：/home/pi/Music。
# 在当前用户的家目录下创建Music目录
mkdir -p ~/Music
程序启动后将自动扫描该目录中的音乐文件并生成播放列表。
应用演示¶
运行程序¶
在项目目录下执行以下命令启动程序：
cd demo-light-music-player/src
sudo python3.13 light_music_player.py
灯光效果支持两种频谱可视化渲染模式，可通过参数指定启动模式：
模式一（默认）：sudo python3 light_music_player.py --mode1 —— 频谱柱状推移效果。
模式二：sudo python3 light_music_player.py --mode2 —— 全屏能量律动跳变效果。
灯光效果说明¶
注意事项：16×16 WS2812灯板排列
由于不同厂商的16×16 WS2812全彩RGB LED点阵屏的灯板在物理走线方式上可能存在差异，本项目所使用的灯板的物理排列方式如下：
起始LED位置：左下角（LED 0）
第一行方向：自左向右（LED 0 → LED 15）
行方向：自下向上
走线方式：蛇形（Serpentine）排列
即第一行自左向右排列，第二行自右向左折返，依次向上延伸。
程序内部的灯光效果（频谱柱状方向、能量扩散方向等动态灯效）均基于上述排列方式进行坐标映射。
若实际使用的LED点阵屏的灯板走线方式与上述描述不一致，可能出现显示方向颠倒或错位，此时需根据灯板实际走线方式调整LED矩阵映射配置。
mode1频谱推进效果¶
该模式基于音频的16频段频谱分析结果：
LED矩阵的每一列对应一个频段能量；
柱状高度随频谱能量实时变化；
支持平滑上升、缓慢回落以及峰值保持效果；
在音乐节奏突变时，整体画面会产生明显的推进视觉效果。
mode2雨滴灯光效果¶
该模式模拟雨滴从LED点阵屏顶部向下坠落的视觉效果：
雨滴生成频率随音乐强度动态变化；
支持尾迹显示与背景色填充；
音频瞬时能量（或信号强度）越大，雨滴生成越密集、动态亮度越高。
技术支持与贡献¶
如在使用过程中遇到问题，欢迎在 移远通信官方论坛 提交技术咨询，移远技术支持团队将及时为您解答。
项目开源地址：https://github.com/Quectel-Pi/demo-light-music-player
欢迎提交Issue反馈问题或Pull Request贡献代码改进！