# 灯光音乐播放器

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

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

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

# 开发资源汇总

## 开发配件清单

| **配件名称** | **数量** | **规格参数** |
| --- | --- | --- |
| Quectel Pi M2智能主控板 | <div style="text-align: center"><br>1块<br></div> | Quectel Pi M2智能生态开发板 |
| 16×16 WS2812 RGB全彩显示屏 | <div style="text-align: center"><br>1块<br></div> | [WS2812 RGB全彩显示屏LED点阵模块点阵屏点阵模组](<https://detail.tmall.com/item.htm?id=712632743590&mi_id=0000-cSsASOs6q2n5cCWn27R87anJgVvvERsjmEvayYoWKM&spm=tbpc.boughtlist.suborder_itemtitle.1.220b2e8dn4a4AX>) |
| 2Pin PH1.25接口喇叭 | <div style="text-align: center"><br>1个<br></div> | [2030腔体喇叭8Ω 2W方形喇叭高音质小体积扬声器2PIN PH1.25接口](<https://www.waveshare.net/shop/8ohm-2W-Speaker-B.htm>) |
| 电源适配器 | <div style="text-align: center"><br>1个<br></div> | [27W USB Type-C接口充电器1.2米线长中规电源PD电源适用于树莓派5代](<https://www.waveshare.net/shop/PSU-27W-USB-C-CN-B.htm>) |
| HDMI A 型对公线 | <div style="text-align: center"><br>1根<br></div> | HDMI 2.0；线长1 m；接口：HDMI-A（公头）-HDMI-A（公头） |
| 网线 | <div style="text-align: center"><br>1根<br></div> | 线长：1米；传输速率：千兆； |
| HDMI显示器 | <div style="text-align: center"><br>1个<br></div> | 24英寸HDMI显示器 |

## 配件实物参考

```{image} images/image_LSnmbOsxTowEO9xIE5IcUIEYnAh.webp
:width: 1047px
:height: 620px
:align: center
```

# 快速上手

## 开发准备

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

## 硬件连接

### 接口外设连接

```{image} images/image_Ni0RbiX6io4dW9xEhGScnxRQnjh.webp
:width: 627px
:height: 463px
:align: center
```

1. **显示连接**：HDMI线一端接主控板HDMI接口，另一端接显示器HDMI接口；

2. **网络连接**：千兆网线一端接主控板千兆网口，另一端接路由器网口（替代方案：通过Wi-Fi接入同一局域网）；

3. **输入设备连接**：USB键盘、鼠标接入主控板的两个USB-A接口，无线输入设备则将接收器插入USB口即可；

4. **供电连接**：USB-A电源线的USB-A端接电源适配器，USB-C端接入主控板标注 **POWER IN** 的电源口。

### 16×16 WS2812连接

16×16 WS2812 RGB全彩显示屏通过 **SPI接口** 与Quectel Pi M2智能主控板连接，其数据输入端应连接至Quectel Pi M2的对应引脚（接线方式见下图）。

```{image} images/image_TJkvbcBNTo7PRLx5kfuclDb1nxd.webp
:width: 733px
:height: 383px
:align: center
```

## 项目实现

### 安装前置

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

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

- **ffmpeg**：用于将MP3、WAV等格式的音频文件解码为PCM数据流，供音频播放与实时分析使用。

### 获取代码

前往 [GitHub仓库](<https://github.com/Quectel-Pi/demo-light-music-player>) 获取代码，并下载到Quectel Pi M2。若为远程访问，文件传输方法请参考 [SCP文件拷贝](<../../../使用指南/设备连接/SCP文件拷贝/SCP文件拷贝.md>)。

### 音乐文件准备

将音乐文件（支持MP3和WAV格式）复制到用户的Music目录下，如：*/home/pi/Music*。

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

# 应用演示

## 运行程序

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

```bash
cd demo-light_music_player/src
sudo python3 light_music_player.py 
```

灯光效果可配置为 *mode1* 或 *mode2*，程序启动后，将自动播放音乐，并在16×16 WS2812 RGB全彩显示屏上显示随音乐节奏变化的灯光效果。

运行程序后，终端提示按键操作（*n* 切换下一首,*u* 切换上一首,*q* 或 *Ctrl+C* 可以退出程序）

```{image} images/image_H2izb06Qmo7V1ox93BgcZxyInjd.webp
:width: 601px
:height: 69px
:align: center
```

## 灯光效果说明

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

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

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

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

- **行方向**：自下向上

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

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

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

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

### **mode1频谱推进效果**

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_Xnl9bZsy5oz8S9xQO9ZcaHqtnpd.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>1</strong>
  </div>
</div>


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

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

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

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

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

### **mode2雨滴灯光效果**

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_GvwxblNYMoqVHWxoXvaczrbTnTe.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>2</strong>
  </div>
</div>


该模式模拟雨滴从显示屏顶部向下坠落的视觉效果：

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

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

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

# 技术支持与贡献

如在使用过程中遇到问题，欢迎在 [移远官方论坛](<https://forumschinese.quectel.com/c/quectel-pi/58>) 提交技术咨询，移远技术支持团队将及时为您解答。

项目开源地址：[https://github.com/Quectel-Pi/demo-light-music-player](<https://github.com/Quectel-Pi/demo-light-music-player>)

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