# 灯光音乐播放器

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

---

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

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

# 开发资源汇总

## 开发配件清单

| <div style="text-align: center"><br><strong>配件名称</strong><br></div> | <div style="text-align: center"><br><strong>数量</strong><br></div> | <div style="text-align: center"><br><strong>规格参数</strong><br></div> |
| --- | --- | --- |
| <div style="text-align: center"><br>Quectel Pi H1智能主控板<br></div> | <div style="text-align: center"><br>1块<br></div> | <div style="text-align: center"><br><a href="<https://detail.tmall.com/item.htm?abbucket=14&id=941006342186&pisk=geTmoNbMznSXH2abmfbjDRx_BzmRHZ_1TdUOBNBZ4TW7MIEAMNxMiLUx1CW9SNvWUG8AkIplIddeDKQAXV8l662aurrV4z5f1GJOBIFXVpdUkEnfWPbf5NkKp23KMI_17fvj5xybUs1ZWs5N3Z_yoGESl23pGQVAgXdrJFK0m5CubPJN0TRP6Tzau1JNz85fUr5auNWrZ16P7rrV7_WPT64V7oWNzQ519rzNbiPz4T1N7sW2QQll6TWN7NJwaby779YwPUkagdQZM9qy5sjcLIW2MILz9irXMTYwSU5DZtO4fPzwrsjDzD4cC9IvbBsBkC0gPZdH4a5M5XrGIMxwka8qU2S5bUJPaKhTf_xM_e_fDWaBKZvGYESu_fAAStblaelTATLlHd8c4XUhXa8dYZ--VxIOo6vwlKVg7pRJ9EsWSv2PCnCCz1YsTlXGbgJb4kzqiP1r6Ur_fi55Z9Kg1erUzpx1LbcuAmsVNsHKZbq_fi55Z9hoZkw10_1xp&rn=a0b0cde1aa6e376a9b5f96c50ceb198f&spm=a1z10.5-b-s.w4011-23773508522.57.6b936560dX8ASU&skuId=5840912585943>">Quectel Pi H1智能生态开发板</a><br></div> |
| <div style="text-align: center"><br>16×16 WS2812 RGB全彩显示屏<br></div> | <div style="text-align: center"><br>1块<br></div> | <div style="text-align: center"><br><a href="<https://detail.tmall.com/item.htm?id=712632743590&mi_id=0000-cSsASOs6q2n5cCWn27R87anJgVvvERsjmEvayYoWKM&spm=tbpc.boughtlist.suborder_itemtitle.1.220b2e8dn4a4AX>">WS2812 RGB全彩显示屏LED点阵模块点阵屏点阵模组</a><br></div> |
| <div style="text-align: center"><br>2PIN PH1.25接口喇叭<br></div> | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<https://www.waveshare.net/shop/8ohm-2W-Speaker-B.htm>">2030腔体喇叭8Ω 2W方形喇叭高音质小体积扬声器2PIN PH1.25接口</a><br></div> |
| <div style="text-align: center"><br>USB-C电源线充电器<br></div> | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<https://www.waveshare.net/shop/PSU-27W-USB-C-CN-B.htm>">27W USB Type-C接口充电器1.2米线长中规电源PD电源适用于树莓派5代</a><br></div> |
| <div style="text-align: center"><br>USB-C DP显示线/HDMI线<br></div> | <div style="text-align: center"><br>1根<br></div> | <div style="text-align: center"><br>规格：DP 1.4；线长：1m；接口：USB-C（公头）- USB-C（公头）  <br>规格：HDMI 2.0；线长：1m；接口：HDMI-A（公头）-HDMI-D（公头）<br></div> |
| <div style="text-align: center"><br>网线<br></div> | <div style="text-align: center"><br>1根<br></div> | <div style="text-align: center"><br>线长：1m；传输速率：千兆；<br></div> |
| <div style="text-align: center"><br>CPU散热风扇（可选）<br></div> | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<https://www.waveshare.net/shop/Raspberry-Pi-5-Official-Active-Cooler.htm>">树莓派5代官方原装散热器带导热贴</a><br></div> |
| <div style="text-align: center"><br>显示屏<br></div> | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br>24英寸HDMI显示器<br></div> |

## 配件实物参考

```{image} images/image_S9fdb8pFNo9xrLxEBUdcWm40nUA.webp
:width: 892px
:height: 503px
```

# 快速上手

## 开发准备

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

## 硬件连接

### 显示连接

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

```{image} images/image_E4fWbgnWcosTlGxK6Sac8QyfnOh.webp
:width: 897px
:height: 538px
:align: center
```

### 输入设备连接

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

```{image} images/image_Jr12bvog9o3503xuUu5ctXccnRh.webp
:width: 1105px
:height: 646px
:align: center
```

### 喇叭连接

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

```{image} images/image_DUvybFtLdoIC0OxYfFwcKuYTnEd.webp
:width: 777px
:height: 658px
```

### 网线连接

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

```{image} images/image_Dx3XbVVEloWVrexpg5ccj7TIngc.webp
:width: 908px
:height: 569px
:align: center
```

### 跳线帽连接

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

```{image} images/image_ESFGb0xMioXMyVxGEgGcmGQon1e.webp
:width: 541px
:height: 330px
```

### 16×16WS2812连接

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

```{image} images/image_FiG9bGRpxoAXnqxLT8ccC3Qmnpf.webp
:width: 1084px
:height: 567px
:align: center
```

### 电源连接

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

```{image} images/image_FjlxbpgrToeWehx5qaJcoZEKnUd.webp
:width: 902px
:height: 619px
: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 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***，然后将其内容修改为：

```plaintext
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主板使配置生效。

### 获取代码

[下载代码](<https://github.com/Quectel-Pi/demo-light-music-player>)

代码解压到设备。如果是远程访问的话，文件传输参考 [SCP文件拷贝](<../../../使用指南/设备连接/SCP文件拷贝/SCP文件拷贝.md>)

### 音乐文件准备

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

```plaintext
/home/pi/Music
```

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

# 应用演示

## 运行程序

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

```plaintext
cd light_music_player
```

```plaintext
sudo python3 light_music_player.py 
```

灯光效果可配置为 *mode1* 或 *mode2*，程序启动后，将自动开始播放音乐，并在16×16 WS2812 LED矩阵上显示与音乐节奏同步变化的灯光效果。

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

```{image} images/image_Kt9PbncDpoXgcdxhxTqcxPL1nke.webp
:width: 614px
:height: 135px
```

## 灯光效果说明

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_Vp8dbOLcNoSSpjxEKrBcYEO8nHh.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>mode2</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贡献代码改进！