树莓派+传感器：列车靶场自动音乐播放系统设计与实现

1. 这篇文章真正要解决的问题

先解释一下“列车靶场”。它不是一个射击场，也不是什么军事设施，而是我自己的一个模型列车测试场地：一段铺设好的轨道沙盘，用来调试列车模型的运行速度、停车精度、自动调度逻辑。之所以叫“靶场”，是因为它就像一个可以反复试错、反复测试的试验场，所有的控制策略先在上面跑通，再拿到正式展示环境里用。

场地有了，列车也能跑了，但一个很现实的问题出现了：光有列车来回跑，整个沙盘非常安静，缺少氛围。无论是给孩子展示、参加模型展会，还是单纯自己在角落里看列车跑，都想配上合适的音乐。真正动手做的时候才会发现，这件事没有想象中简单。它不是把音箱往旁边一放，手机连蓝牙播放一首歌就完了。我希望的是：列车到站时放一段提示音，列车启动时放一段进行曲，有参观者靠近时播放对应讲解音频，甚至能按设定好的播放列表，在不同场景自动切换音乐。

这个需求如果拆开来看，本质上是一个“环境事件触发音频播放”的软硬件结合项目。它要处理的不只是“放音乐”这一个动作，还包括：

• 如何稳定地检测列车位置和状态；
• 如何把检测结果转成播放指令；
• 如何管理多首音乐，避免内存占用过高；
• 如何做到长时间运行不卡顿、不死机；
• 如何在出现故障时快速定位问题。

这篇文章会把整个实现思路、代码、配置和排错过程完整写出来。如果你也在做模型沙盘、实验展台、小型自动化展示系统，或者任何需要“传感器触发声音”的场景，这篇文章都值得读完。不需要用高成本的PLC，也不需要购买商业展项方案，用一块树莓派（或者一台普通电脑）加几个传感器就能跑起来。

2. 列车靶场音乐播放系统的核心概念

在写代码之前，先把几个关键概念理清楚。很多人在搭建这类系统时，第一个误区就是直接打开一个音频软件，手动播放。这在一分钟两分钟的场景下没有毛病，但如果列车靶场需要全天候运行，手动操作就会成为最大的瓶颈。

2.1 播放系统的四层结构

一个完整的“列车靶场音乐播放系统”，从底层到上层可以分为四层：

• 数据层：存储音乐文件、播放列表、场景配置。音乐文件可以是MP3、WAV或FLAC，播放列表可以用JSON或数据库来维护。
• 控制层：负责接收外部事件，决定“现在应该播放什么”。它是整个系统的核心，典型实现是一个常驻运行的Python服务。
• 接入层：负责感知外部环境，把物理事件转成数字信号。常见的有红外传感器、霍尔传感器、按钮、人体感应模块，也可以是网络消息（例如MQTT）。
• 输出层：负责把数字音频信号转成可听见的声音。包括USB声卡、功放、喇叭，或者直接使用带音频输出的单片机模块。

这四层不一定都需要独立硬件。例如用树莓派时，控制层和接入层可以跑在同一块板子上，输出层可以用一个USB声卡，数据层就直接放在SD卡里。但逻辑上必须拆开，否则后面扩展时会非常混乱。

2.2 两种常见设计模式

根据使用的场景，有两种音频播放触发方式值得区分：

定时播放模式

适合那些“列车运行时间完全固定”的展台。例如每隔20分钟有一趟列车经过，或者某个特定时刻需要播放对应讲解。这种模式实现最简单，只需要在控制层维护一个时间表，到点就播放。

事件触发模式

适合“列车状态不确定”的场景。例如列车经过传感器时播放提示音，有人按下按钮时播放自定义音乐，或者通过上位机下发指令控制播放。这种模式更接近真实的展示环境，也是本文重点。

实际上，项目里最好的做法是两种模式结合：基础场景用时间表，特殊互动用事件触发。这样既保证自动运行，又保留人工介入的能力。

2.3 一个容易忽略的问题：音频资源管理

如果系统里只有三五首音乐，随便怎么播放都不会出问题。但一旦音乐数量超过几十首，或者需要循环播放、穿插播放，就必须考虑资源管理。最典型的问题有两个：

• 用pygame.mixer.music.load()加载音乐时，同一时间只能加载一首。如果试图加载第二首，第一首会被替换，播放会被打断。
• 如果每次触发事件都重新加载文件，磁盘IO和CPU占用会非常明显，尤其是树莓派这类性能有限的设备。

因此，在代码设计上，需要把“音乐文件”的路径和“播放控制”分开，通过播放列表来管理，而不是在触发事件时直接硬编码。

3. 环境准备与硬件选型

这一节把硬件和软件环境一次说清楚。下面的配置以树莓派为例，但思路也适用于普通电脑，因为控制逻辑完全一样，只是传感器接入方式不同。

3.1 推荐硬件组合

如果你的手头只有一台Windows电脑，也可以先把整个控制程序在电脑上跑通，用键盘或模拟信号来测试。这时候不需要传感器，只需给程序传入模拟事件即可。

3.2 软件环境

• 操作系统：树莓派官方系统（Raspberry Pi OS）或任何Linux发行版，Windows/macOS也可以运行控制程序，但GPIO部分需要替换为模拟实现。
• Python版本：3.8以上，本文代码基于Python 3.9+语法，尽量向下兼容。
• Python依赖库：pygame、paho-mqtt、flask，如果使用GPIO则还需要gpiozero或RPi.GPIO。
• 音频播放器：这里选择pygame.mixer作为音频引擎，因为它跨平台，API简单，足够满足沙盘场景。如果你需要播放局域网内的网络音频，可以换成python-vlc。

安装依赖的命令如下：

pip install pygame paho-mqtt flask gpiozero

gpiozero是树莓派官方推荐的GPIO库，如果只是电脑模拟，可以跳过。另外建议提前用系统命令测试声卡是否正常：

speaker-test -t wav -c 2

如果能听到左右声道交替测试音，说明音频输出通路没问题。这一步非常关键，后面很多“播放没声音”的问题都是从这里排查出来的。

4. 系统架构与联动逻辑

整个系统的联动逻辑可以概括为：感知 → 判断 → 播放 → 反馈。

4.1 感知层

在列车轨道的关键位置安装传感器，例如站点、弯道、坡道。当列车经过时，传感器会产生一个电平变化。如果用红外避障模块，列车遮挡红外线时输出低电平，否则输出高电平。也可以用霍尔传感器配合安装在列车底部的小磁铁，输出数字信号。

为了简化，项目中可以把传感器接到树莓派GPIO上，轮询或中断方式读取。但要注意：传感器信号可能存在抖动，也就是短时间内多次跳变，需要在代码里做消抖，否则一首音乐会重复触发多次。

4.2 判断层

控制程序接收到传感器信号后，不能立刻播放音乐，而要先判断当前系统状态：

• 当前是否已经正在播放音乐？
• 这个事件对应的音乐是否允许打断当前音乐？
• 事件有没有重复触发？

以列车到站为例：列车到达站点，触发传感器，程序应该播放“列车到站.mp3”。如果刚好播放器在播放背景音乐，是否需要暂停背景音乐？这里我会先做个简单配置：默认不打断，等当前音乐播放完毕后再播放到站提示音。如果需要立即打断，可以设置interrupt=True。

4.3 播放层

播放层使用pygame.mixer.music加载并播放指定音乐。注意pygame.mixer.music适合播放较长的音乐文件（如MP3），而pygame.mixer.Sound适合播放较短的声音片段（如WAV）。对于音乐，使用前者更合适。

4.4 联动逻辑示例

下面是一个典型的“三传感器联动”场景：

1. 列车从车库驶出，经过“出库传感器”，播放发车音乐。
2. 列车驶入站台，经过“到站传感器”，播放到站提示音。
3. 列车停稳后，参观者按下按钮，播放对应讲解音频。

在这个场景里，每个传感器对应一个事件ID，程序通过映射表找到要播放的音乐文件。这个映射关系用YAML或JSON维护，方便后期调整。

5. 核心代码实现

下面进入实际操作。为了让代码尽量完整，我把整个系统拆成三个文件：

• config.json：音乐与事件映射配置
• player.py：控制中心，负责处理和播放逻辑
• web_control.py：Flask Web控制服务，提供手动控制和状态查询

如果要用GPIO传感器，我会单独补充一个读取GPIO的示例，放到sensor.py中。

5.1 配置文件：config.json

{ "events": { "train_depart": { "music": "music/depart.mp3", "volume": 0.8, "interrupt": false }, "train_arrive": { "music": "music/arrive.wav", "volume": 0.7, "interrupt": true }, "scene_intro": { "music": "music/intro.mp3", "volume": 0.9, "interrupt": true } }, "playlist": [ "music/background_1.mp3", "music/background_2.mp3", "music/background_3.mp3" ] }

这个配置的作用是：把事件ID和音乐文件路径解耦。以后要修改某一首音乐，只需要改配置文件，不需要改Python代码。volume是播放音量，取值范围0到1。interrupt表示这个事件是否允许打断当前正在播放的音乐。

5.2 主控制程序：player.py

下面是核心代码，建议直接复制保存为player.py。

import json import os import random import threading import time import pygame class TrainMusicPlayer: def __init__(self, config_path): pygame.mixer.init() with open(config_path, "r", encoding="utf-8") as f: self.config = json.load(f) self.events = self.config.get("events", {}) self.playlist = self.config.get("playlist", []) self.current_event_id = None self._lock = threading.Lock() self._running = True def play_event(self, event_id): """播放指定事件对应的音乐""" if event_id not in self.events: print(f"[警告] 未配置事件: {event_id}") return False event = self.events[event_id] music_path = event.get("music") volume = float(event.get("volume", 0.8)) interrupt = event.get("interrupt", False) if not os.path.exists(music_path): print(f"[错误] 音乐文件不存在: {music_path}") return False with self._lock: if pygame.mixer.music.get_busy() and not interrupt: print(f"[跳过] 正在播放其他音乐，事件 {event_id} 被忽略") return False # 设置音量并播放 pygame.mixer.music.set_volume(volume) pygame.mixer.music.load(music_path) pygame.mixer.music.play() self.current_event_id = event_id print(f"[播放] 事件 {event_id} -> {music_path}") return True def play_background(self, shuffle=True): """循环播放背景音乐""" if not self.playlist: return while self._running: try: with self._lock: pygame.mixer.music.load(random.choice(self.playlist)) pygame.mixer.music.play() self.current_event_id = "background" print(f"[播放] 背景音乐: {pygame.mixer.music.get_pos()}") except Exception as e: print(f"[错误] 背景音乐播放异常: {e}") # 等待当前播放结束，同时允许事件打断 while pygame.mixer.music.get_busy() and self._running: time.sleep(0.5) if not self._running: break time.sleep(1) def stop(self): """停止播放""" with self._lock: pygame.mixer.music.stop() self.current_event_id = None self._running = False if __name__ == "__main__": player = TrainMusicPlayer("config.json") # 模拟传感器事件 time.sleep(1) player.play_event("train_depart") time.sleep(3) player.play_event("train_arrive") time.sleep(2) player.play_event("scene_intro") time.sleep(5) player.stop()

代码关键点说明：

• 用线程锁self._lock保护播放器的状态，避免背景音乐线程和事件触发线程同时操作pygame.mixer.music造成异常。
• play_event方法中，如果当前正在播放其他音乐，并且事件不允许打断，那么该事件会被忽略。这种方法最适合“到站提示音不能打断背景音乐”的场景。
• play_background会进入一个无限循环，随机播放列表中的音乐，直到调用stop()方法。

5.3 GPIO 传感器读取示例：sensor.py

如果使用树莓派，可以用下面这段代码读取GPIO输入并触发事件。

from gpiozero import Button import time # 这里假设传感器低电平触发，对应Button库的pressed_state # 引脚可以根据实际接线调整 PIN_TRAIN_DEPART = 17 PIN_TRAIN_ARRIVE = 27 depart_btn = Button(PIN_TRAIN_DEPART, pull_up=True, bounce_time=0.2) arrive_btn = Button(PIN_TRAIN_ARRIVE, pull_up=True, bounce_time=0.2) def on_depart(): print("检测到列车出库") # 实际调用 player.play_event("train_depart") # player.play_event("train_depart") def on_arrive(): print("检测到列车到站") # player.play_event("train_arrive") depart_btn.when_pressed = on_depart arrive_btn.when_pressed = on_arrive print("GPIO监听已启动，按Ctrl+C退出") while True: time.sleep(0.1)

bounce_time=0.2是消抖时间，防止传感器因机械抖动产生多次触发。这里只演示了传感器读取逻辑，实际使用时需要把player对象传入回调函数，或者使用全局变量。

5.4 Web 手动控制接口：web_control.py

有时候并不希望完全自动运行，比如在调试时，想手动触发某段音乐。用Flask写一个简单的HTTP接口就能解决。

import json import time from flask import Flask, request, jsonify from player import TrainMusicPlayer app = Flask(__name__) player = TrainMusicPlayer("config.json") @app.route("/play", methods=["POST"]) def play(): data = request.get_json(force=True) event_id = data.get("event_id") if not event_id: return jsonify({"success": False, "message": "缺少event_id"}), 400 ok = player.play_event(event_id) return jsonify({"success": ok}) @app.route("/stop", methods=["POST"]) def stop(): player.stop() return jsonify({"success": True}) @app.route("/status", methods=["GET"]) def status(): return jsonify({ "playing": pygame.mixer.music.get_busy(), "current_event": player.current_event_id }) if __name__ == "__main__": app.run(host="0.0.0.0", port=5000)

这段代码里需要补充一个import pygame，因为状态接口中用到了它。运行时你可以在同一局域网内的任何浏览器或工具中调用接口。

curl -X POST -H "Content-Type: application/json" -d '{"event_id":"train_depart"}' http://127.0.0.1:5000/play

通过接口，你可以随时手动触发“列车出发”或“到站”音乐，非常适合现场演示前的调试。

6. 运行结果与效果验证

把上面的代码保存好，确保音乐文件路径正确，然后运行主程序：

python player.py

预期输出类似：

[播放] 事件 train_depart -> music/depart.mp3 [播放] 事件 train_arrive -> music/arrive.wav [播放] 事件 scene_intro -> music/intro.mp3

如果程序能依次播放三首音乐，并且音量、打断逻辑符合预期，说明核心播放功能已经跑通。

接下来验证GPIO联动。接线后运行sensor.py，用手模拟列车经过传感器，观察终端是否打印出对应日志。如果传感器触发正常，但音乐没有播放，需要检查：

1. 传感器引脚是否和代码中的变量一致；
2. player对象是否在回调中正确传递；
3. 配置文件中的事件ID是否与回调函数中的一致；
4. pygame.mixer.music.play()之后是否立即又被其他线程加载。

为了验证“不允许打断”的逻辑，可以先让背景音乐循环播放，再触发train_arrive（配置中interrupt: true）。如果背景音乐被切换成到站提示音，说明打断逻辑生效；如果背景音乐继续播放，可以检查配置是否加载成功。

如果是通过Web接口验证，用浏览器访问http://127.0.0.1:5000/status，会看到当前是否在播放、当前事件ID是什么。这个接口在长时间运行时非常有用，可以快速确认播放器状态。

7. 常见问题与排查方法

以上几个问题是在实际搭建中特别容易遇到的。尤其是声卡和GPIO抖动，如果一开始没有处理好，后面会浪费大量时间。

8. 最佳实践与工程建议

技术能跑通是一回事，能在现场稳定运行又是另一回事。下面是我觉得值得吸收的几个工程经验。

8.1 将配置与代码分离

上面我已经用config.json管理事件和音乐映射。在实际项目中，建议进一步把音量、播放模式、打断策略都放到配置里。这样即使不会写代码的人，也能通过修改配置文件来调整音乐播放行为。

8.2 增加日志记录

不要把print()当作最终日志，因为print在终端窗口关闭后就会丢失。推荐使用 Python 标准库logging，同时输出到控制台和文件。

import logging logging.basicConfig( level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s", handlers=[ logging.FileHandler("music_player.log", encoding="utf-8"), logging.StreamHandler() ] )

有了日志，现场出现问题后可以先看日志，而不是靠回忆。

8.3 使用看门狗机制

树莓派长时间运行，偶尔会因为电源、温度等因素出现进程挂掉。最简单的做法是用systemd把控制程序注册成服务，并配置自动重启。下面是一个示例服务文件，路径为/etc/systemd/system/train-music.service。

[Unit] Description=Train Music Player Service After=network.target sound.target [Service] ExecStart=/usr/bin/python3 /home/pi/train-music/player.py WorkingDirectory=/home/pi/train-music Restart=always RestartSec=5 User=pi [Install] WantedBy=multi-user.target

配置完成后启用服务：

sudo systemctl daemon-reload sudo systemctl enable train-music sudo systemctl start train-music

这样即使进程意外退出，系统会在5秒后自动拉起。

8.4 音频文件格式统一

不要混合使用不同码率、不同格式的音乐文件。建议统一转换为320kbps的MP3，或者无损WAV。码率过高会增加解码开销，码率过低音质又差。对于长时间播放的场景，MP3是最稳妥的选择。

8.5 GPIO事件要加冷却时间

即使设置了bounce_time，也建议在事件处理函数中加一个冷却判断。比如同一个事件在2秒内只能触发一次。

last_trigger_time = 0 def on_arrive(): global last_trigger_time now = time.time() if now - last_trigger_time < 2: return last_trigger_time = now player.play_event("train_arrive")

这个做法的好处是，即使未来更换了传感器类型，也不用担心信号抖动带来的重复触发。

9. 总结与后续学习方向

这篇内容从一个模型列车沙盘的“音乐需求”出发，完整实现了基于树莓派和Python的自动音乐播放系统。它解决的核心问题是如何把外部事件与音频播放连接起来，并且保证长时间运行的稳定性。你可以直接把它当作一套可复用的模板，应用在列车靶场、模型沙盘、展示台、科普展项等场景中。

如果你回头审视整个系统，会发现核心代码并不复杂，关键点在于事件管理和播放资源的冲突处理。pygame.mixer.music库虽然简单，但已经能覆盖绝大多数播放需求；GPIO传感器联动虽然只有几个引脚，但通过合理配置，可以扩展出非常丰富的交互体验。

后续值得深入的方向有三个：第一，把传感器换成摄像头视觉识别，用OpenCV判断列车是否到达指定位置，这样就不需要布线；第二，增加更丰富的音效控制，比如根据列车速度实时调整背景音乐音量，让音乐和列车运行状态更协调；第三，把播放服务独立成微服务，通过MQTT协议接入到更大的沙盘调度系统中，这样音乐播放就不是孤立的，而是整个自动化系统的一部分。

如果你手头也有一个类似的“靶场”项目，建议从最小版本开始：先手动用一条命令播放音乐，再用脚本触发，最后再加入传感器和Web控制。一步一步来，你会发现这个系统其实比想象中更简单。