灯光音乐播放器

概述

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

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

开发资源汇总

开发配件清单

配件实物参考

开发准备

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，使能方法如下：

• 在Quec Pi H1主板上，修改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

• 在终端输入sudo qpi-config 40pin set，之后重启Quectel Pi H1主板使配置生效。

获取代码

下载代码

代码解压到设备。如果是远程访问的话，文件传输参考SCP文件拷贝

音乐文件准备

将需要播放的音乐文件（支持 MP3 / WAV 格式）拷贝至以下目录：

/home/pi/Music

程序启动后将自动扫描该目录中的音乐文件并生成播放列表。

运行程序

在项目目录下执行以下命令启动程序：

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 灯板在物理走线方式上可能存在差异，本项目所使用的灯板其物理排列方式如下：

• 起始 LED 位置：左下角（LED 0）
• 第一行方向：自左向右（LED 0 → LED 15）
• 行方向：自下向上
• 走线方式：蛇形（Serpentine）排列

即第一行从左到右排列，第二行从右到左折返，依次向上延伸。

程序内部的灯光效果（频谱方向、雨滴方向等）均基于上述排列方式进行坐标映射。
若实际使用的 WS2812 灯板走线方式与上述描述不一致，可能会出现显示方向颠倒或错位的情况，此时需要根据灯板实际走线方式调整 LED 矩阵映射配置。

mode1--频谱推进效果

该模式基于音频的 16 频段频谱分析结果：

• LED 矩阵的每一列对应一个频段能量；

• 柱状高度随频谱能量实时变化；

• 支持平滑上升、缓慢回落以及峰值保持效果；

• 在音乐节奏突变时，整体画面会产生明显的推进视觉效果。

mode2--雨滴灯光效果

该模式模拟雨滴从矩阵顶部向下坠落的视觉效果：

• 雨滴生成频率随音乐强度动态变化；

• 支持尾迹显示与背景色填充；

• 音量越大，雨滴越密集、亮度越高。