灯光音乐播放器

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全彩显示屏


1块


2PIN PH1.25接口喇叭


1个


USB-C电源线充电器


1个


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个


显示屏


1个


24英寸HDMI显示器

配件实物参考

../../../_images/image_S9fdb8pFNo9xrLxEBUdcWm40nUA.webp

快速上手

开发准备

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

硬件连接

显示连接

将HDMI线一端接入智能主控板的HDMI接口，另一端接入显示器的HDMI接口。

../../../_images/image_E4fWbgnWcosTlGxK6Sac8QyfnOh.webp

输入设备连接

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

../../../_images/image_Jr12bvog9o3503xuUu5ctXccnRh.webp

喇叭连接

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

../../../_images/image_DUvybFtLdoIC0OxYfFwcKuYTnEd.webp

网线连接

将网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（确保路由器已联网）。

../../../_images/image_Dx3XbVVEloWVrexpg5ccj7TIngc.webp

跳线帽连接

智能主控板左上角标有 AUTO_POWER_ON 丝印的排针，确保已经用跳线帽短接。

../../../_images/image_ESFGb0xMioXMyVxGEgGcmGQon1e.webp

16×16WS2812连接

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

../../../_images/image_FiG9bGRpxoAXnqxLT8ccC3Qmnpf.webp

电源连接

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

../../../_images/image_FjlxbpgrToeWehx5qaJcoZEKnUd.webp

项目实现

安装前置

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

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

  • 在 Quectel 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 可以退出程序）

../../../_images/image_Kt9PbncDpoXgcdxhxTqcxPL1nke.webp

灯光效果说明

注意事项：16×16 WS2812灯板排列说明

由于不同厂商的16×16 WS2812 RGB灯板在物理走线方式上可能存在差异，本项目所使用的灯板其物理排列方式如下：

  • 起始LED位置：左下角（LED 0）

  • 第一行方向：自左向右（LED 0 → LED 15）

  • 行方向：自下向上

  • 走线方式：蛇形（Serpentine）排列

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

程序内部的灯光效果（频谱方向、雨滴方向等）均基于上述排列方式进行坐标映射。

若实际使用的WS2812灯板走线方式与上述描述不一致，可能会出现显示方向颠倒或错位的情况，此时需要根据灯板实际走线方式调整LED矩阵映射配置。

mode1–频谱推进效果

mode1

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

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

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

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

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

mode2–雨滴灯光效果

mode2

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

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

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

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

技术支持与贡献

如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。

项目开源地址：https://github.com/Quectel-Pi/demo-light-music-player

欢迎提交Issue反馈问题或Pull Request贡献代码改进！