简介：面向嵌入式Linux与Qt入门者的实践型代码包，围绕三星S3C6410开发板实现《欢乐颂》音乐播放与LED跑马灯联动，重点演示物理按键监听、蜂鸣器音频输出和GPIO控制等交互逻辑，适合作为嵌入式图形界面课程实验、课程设计或毕业设计前期练手案例。压缩包共10个文件，以cpp与h源码为主体，配有jpg界面素材、qrc资源清单及pro工程配置，整体约35KB，可直接导入Qt Creator对照阅读与编译调试。已有308人学习，说明该案例在嵌入式入门群体中具有一定参考价值。读者能从中梳理Qt信号与槽处理按键事件、通过sysfs操作GPIO点亮流水灯、将乐谱转换为蜂鸣器时序的完整思路，也能观察界面资源与工程文件的组织方式，并据此排查交叉编译、库依赖与环境配置问题，快速建立从用户界面到硬件外设的贯通认识，对刚接触开发板外设联调的读者较为友好。
1. 6410 开发板上的《欢乐颂》：这一套东西到底在跑什么
把一块 6410 开发板接上电，屏幕上是一个 Qt 窗口，点一下播放，板载蜂鸣器把《欢乐颂》一个音一个音吹出来，旁边几颗 LED 像跑马灯一样跟着节拍转。这个场景几乎是嵌入式 Linux 入门最典型的一次全链路验收：PWM 通道、设备节点、交叉编译、Qt 事件循环、界面与硬件的线程边界，全挤在一个能听能看的小工程里。这套东西不是教学幻灯片，是一份能直接在 6410 上编、能烧、能听见声音的 Qt 工程，适合刚摸到开发板、想拿一个“有声有形”的项目把链路走通的人，也适合想看看别人怎么把蜂鸣器和跑马灯塞进 Qt 线程模型里的熟手。它解决的从来不是“会不会写 Qt”，而是“从驱动节点到界面按钮这一路，哪一环最容易断”。
2. 蜂鸣器先响一声：6410 上 PWM 频率表与音符的对应
2.1 有源和无源蜂鸣器：决定这个项目能不能成立的第一个岔路口
动手之前必须先确认一件事：板子上那颗蜂鸣器是有源的还是无源的。有源蜂鸣器内部自带振荡电路，你给它直流它就响，而且只响一个固定音高，你改频率也好、改占空比也好，它都只会“滴”一声，做不出《欢乐颂》。无源蜂鸣器本质上是个电磁或者压电换能器，需要外部给它方波，方波频率决定音高，占空比影响响度和音色，这才是能演奏的硬件。
判断方法很土但很准：串一个 100Ω 电阻，直接给蜂鸣器两端加 3.3V 直流，响的是有源，不响的是无源。或者拿万用表量直流阻抗，几欧到二十几欧这种低阻抗的多半是无源，几十欧以上、内部带三极管电路的多半是有源。6410 这类板子一般把无源蜂鸣器挂在 PWM 输出脚上，靠定时器产生方波，这也是为什么整套方案能成立。
如果量出来是有源的，别急着改代码，先把蜂鸣器换掉，或者去找板上另一路 PWM 驱动的器件。这一点上翻车的人不少，代码写得再漂亮，硬件从根上就不支持变调，后面所有工作都是白费。
另外要留意驱动能力。无源蜂鸣器阻抗低，6410 的 PWM 引脚直接推是推不动的，正常板子上会有一颗三极管或者 MOS 做开关，PWM 只负责给基极送信号。如果你手上是块裸板自己搭的电路，务必补上这一级，否则不是不响就是把 IO 口拖垮。
2.2 十二平均律落到纳秒：频率表怎么算出来
音高和频率的关系是固定的，以 A4 = 440Hz 为基准，MIDI 音高编号 n 对应的频率是：
f = 440 × 2^((n − 69) / 12)C 大调《欢乐颂》主旋律只用到 1 到 5 这几个音，偶尔到高音 1，所以频率范围落在 262Hz 到 523Hz，正好是无源蜂鸣器最舒服的区间。把简谱、音名、MIDI 编号、频率和 PWM 周期列成一张表，后面写代码基本就是查表：
| 简谱 | 音名 | MIDI | 频率(Hz) | period(ns) |
|---|---|---|---|---|
| 1 | C4 | 60 | 261.6 | 3822200 |
| 2 | D4 | 62 | 293.7 | 3405300 |
| 3 | E4 | 64 | 329.6 | 3033700 |
| 4 | F4 | 65 | 349.2 | 2863400 |
| 5 | G4 | 67 | 392.0 | 2551000 |
| 6 | A4 | 69 | 440.0 | 2272700 |
| 7 | B4 | 71 | 493.9 | 2024800 |
| 1' | C5 | 72 | 523.3 | 1911100 |
注意表里最后一列是纳秒。Linux 的 PWM 子系统用纳秒描述周期，不是赫兹，也不是微秒，这一点写代码时最容易搞错量级。1e9 除以频率得到周期，整数除法会带来一点点偏差，但在 262Hz 这个量级上误差只有几个纳秒，人耳完全听不出来，不用纠结。
常见的做法是把频率表写成常量数组，索引就是简谱数字，0 号位留空当占位符。这样曲谱数组里只需要存“第几个音、占几拍”，播放时查一次表就得到频率。曲谱和频率解耦之后，换一首曲子只改曲谱数组，硬件层一行都不用动。
2.3 从命令行点响它：sysfs PWM 的三次写入顺序
在写 Qt 之前，先确认底层通路是活的。6410 的内核如果是带 PWM 子系统的版本，蜂鸣器一般会以/sys/class/pwm/pwmchipX/pwmY的形式露出来；如果是板厂自己写的驱动，也可能是/dev/pwm加一组 ioctl。先看是哪一种：
# 看内核把 PWM 暴露成什么形态 ls /sys/class/pwm/ ls /dev/pwm* /dev/buzzer* 2>/dev/null如果是 sysfs 形态，先导出通道再配置：
# 导出通道 0，如果 pwm0 目录已经存在就跳过这步 echo 0 > /sys/class/pwm/pwmchip0/export # 用 262Hz（简谱 1）点一下，period 单位是纳秒 echo 0 > /sys/class/pwm/pwmchip0/pwm0/duty_cycle echo 3822200 > /sys/class/pwm/pwmchip0/pwm0/period echo 1911100 > /sys/class/pwm/pwmchip0/pwm0/duty_cycle echo 1 > /sys/class/pwm/pwmchip0/pwm0/enable这三步的顺序不能乱。内核在写周期的时候会校验duty_cycle <= period，如果你先把一个很大的 duty 写进去再改 period，会直接返回EINVAL，现象是“命令没报错但蜂鸣器没声音”，很容易怀疑到硬件头上。所以固定套路是：先把 duty 清零，再写 period，最后写一半的 duty，再 enable。停音的时候反过来，先把 duty 置 0 再 disable，能明显减少“啪”的一声爆音。
封装成 C 函数之后，Qt 那边就只需要调一个buzzer_set_freq(hz)：
#include <stdio.h> #include <fcntl.h> #include <unistd.h> #define PWM_BASE "/sys/class/pwm/pwmchip0/pwm0" #define PWM_PERIOD PWM_BASE "/period" #define PWM_DUTY PWM_BASE "/duty_cycle" #define PWM_EN PWM_BASE "/enable" static int write_sysfs(const char *path, long value) { int fd = open(path, O_WRONLY); if (fd < 0) return -1; char buf[24]; int len = snprintf(buf, sizeof(buf), "%ld", value); int ret = (write(fd, buf, len) == len) ? 0 : -1; close(fd); return ret; } /* freq <= 0 表示静音；freq > 0 时输出 50% 占空比方波 */ int buzzer_set_freq(int freq) { if (freq <= 0) return write_sysfs(PWM_DUTY, 0); long period = 1000000000L / freq; /* 纳秒 */ write_sysfs(PWM_DUTY, 0); /* 先清 duty，避免 duty > period */ write_sysfs(PWM_PERIOD, period); write_sysfs(PWM_DUTY, period / 2); /* 50% 方波，响度最大 */ return write_sysfs(PWM_EN, 1); }buzzer_set_freq每次都会重开文件描述符，听起来很浪费，但在 6410 上单次 open/write/close 是微秒级开销，一首曲子最多几百个音，完全够用。真要抠性能，可以把三个 fd 在初始化时打开一直持有，代价是要处理设备热插拔和错误恢复，得不偿失。
占空比为什么取 50%？无源蜂鸣器在方波驱动下，能量集中在基频，50% 占空比的基频分量最强，声音最响也最干净。把占空比降到 10% 你会发现音量明显变小，音色也发虚，这个特性可以用来做“渐弱”效果，但《欢乐颂》用不上。
3. 曲谱进 Qt：音符表、绝对时间轴与播放状态机
3.1 曲谱怎么存才不容易写错
曲谱的数据结构决定了后面所有逻辑的复杂度。最省事的写法是一个结构体数组，每个元素描述一个音符：
struct Note { int degree; // 简谱级数 0~7，0 表示休止符 int eighths; // 时值，单位是八分音符 }; // 1=C4，《欢乐颂》主题，最后两个音是附点节奏 static const Note kOdeToJoy[] = { {3,2},{3,2},{4,2},{5,2}, {5,2},{4,2},{3,2},{2,2}, {1,2},{1,2},{2,2},{3,2}, {3,3},{2,1},{2,2},{0,2}, {3,2},{3,2},{4,2},{5,2}, {5,2},{4,2},{3,2},{2,2}, {1,2},{1,2},{2,2},{3,2}, {2,3},{1,1},{1,2},{0,2}, };时值单位选八分音符是有讲究的。四分音符记作 2，八分音符记作 1，附点四分音符记作 3，全曲所有时值都是整数，不用引入浮点。如果按“拍”做单位，附点节奏就变成 1.5，数组里全是小数，稍不留神就写错。这个习惯我一直在用，凡是节拍类的数据结构，都把最小单位降一档变成整数。
曲谱数组和频率表分开之后，degree到频率的换算只有一处：
// MIDI 编号表，索引即简谱级数，0 号位占位 static const int kMidi[8] = {0, 60, 62, 64, 65, 67, 69, 71}; static int freqOf(int degree) { if (degree <= 0 || degree > 7) return 0; // 休止 int midi = kMidi[degree]; return qRound(440.0 * qPow(2.0, (midi - 69) / 12.0)); }qPow和qRound是 Qt 的封装，底层就是pow和四舍五入。用公式算而不是硬编码频率，好处是以后想移调，把kMidi整张表加一个偏移量就完事，曲谱一个字都不用改。这类小设计在演示项目里看着多余，真到要改需求的时候能省一晚上。
3.2 QTimer 单定时器为什么会跑调
新手最直觉的写法是：算出一个音符该响多久，QTimer::singleShot(ms, ...)播下一个。这个写法在桌面机上跑 demo 没问题，放到 6410 上播到第三小节就开始拖拍，越往后越明显。
原因是每一次singleShot的间隔都包含了上一轮的系统调度延迟、界面重绘开销和信号槽派发时间，误差单次可能只有几毫秒，但它是累加的，几十个音符之后就是明显的节奏漂移。这在嵌入式板上尤其明显，因为 CPU 主频低、Qt 还要同时刷界面。
正确做法是抛弃“相对延时”，改成“绝对时间轴”。用一个 5ms 的粗粒度定时器轮询，每次进来都拿真实流逝时间去比对下一个音符的理论开始时刻，只要到了就发这一个音，然后把理论时刻往后推一个音符的时长：
void Player::start() { m_index = 0; m_nextTickMs = 0; m_elapsed.start(); m_timer.start(5); // 5ms 轮询，够细也不至于吃满 CPU } void Player::onTick() { const qint64 now = m_elapsed.elapsed(); while (m_index < m_noteCount && now >= m_nextTickMs) { const Note &n = m_notes[m_index]; if (n.degree == 0) m_buzzer->silence(); else m_buzzer->play(freqOf(n.degree)); emit noteStarted(m_index, n.degree); // 通知界面和跑马灯 m_nextTickMs += n.eighths * m_eighthMs; // 关键：在理论时刻上累加 ++m_index; } if (m_index >= m_noteCount) stop(); }关键在m_nextTickMs += ...这一行。累加的是理论时刻，不是now + 时长，这样单次调度延迟不会传递到下一个音符，误差被限制在一个音符之内，不会滚雪球。while循环而不是if，是为了应对偶发的长阻塞——比如界面正好在做一次重绘，5ms 的轮询晚到了 30ms，while会一次性把该发的音补齐，听感上就是一个极短的连奏，而不是整体后移。
m_eighthMs由 BPM 算出来：四分音符时长是60000 / BPM毫秒，八分音符就是30000 / BPM。BPM 取 120 时八分音符 250ms，全曲大约三十秒，这个速度用来演示刚好，太快 6410 上的界面刷新会跟不上，太慢又听不出旋律。
3.3 界面与播放解耦：信号槽、状态机和停止时的收尾
播放器类不要直接持有界面控件。常见做法是播放器只管发声和发信号，界面通过noteStarted(int index, int degree)这个信号更新当前音符的高亮，跑马灯模块也订阅同一个信号。三方互不认识，只认信号，后面想把跑马灯换成别的东西不用改播放器。
状态机至少要三个状态：停止、播放、暂停。暂停的实现有两种，一种是停掉定时器并记住m_elapsed已走的毫秒数，恢复时用m_elapsed.addPause()之类的补偿；另一种更省事，暂停时直接m_timer.stop()并把m_nextTickMs与m_elapsed.elapsed()的差值存下来，恢复时把m_elapsed重置并把这个差值补回去。前一种要改QElapsedTimer的语义，后一种只是多存一个偏移量，我更倾向后者，代码少一半。
停止时的收尾容易被忽略。直接m_timer.stop()而不处理蜂鸣器，最后一个音会一直响着不放，因为它停在 enable 状态。正确顺序是先m_buzzer->silence()（也就是把 duty 写 0），再 disable PWM，最后停定时器并复位m_index。休止符的处理也一样，宁愿把 duty 写成 0 让 PWM 继续跑，也不要频繁 enable/disable，开关瞬间的电流跳变会在喇叭上留下“啪”的爆音，安静环境下特别刺耳。
按钮的防连点也要做。播放中再点播放，如果不拦，会起两份定时器，两个时间轴同时往蜂鸣器写频率，出来的声音是乱的。最简单的办法是在start()里判断当前状态，非停止状态直接 return，同时把界面上按钮的 enabled 状态跟着状态机一起切。
4. 跑马灯与上板：LED 通路、线程边界与交叉编译
4.1 LED 的两条通路：sysfs 的 brightness 与字符设备 ioctl
6410 上的 LED 一般有两种暴露方式。一种是内核 leds 子系统，每颗灯一个目录，写brightness就能亮灭：
# 关掉内核自带的触发方式，否则手写的 brightness 会被 heartbeat 覆盖 for i in 0 1 2 3; do echo none > /sys/class/leds/led$i/trigger done # 点亮第 2 颗 echo 1 > /sys/class/leds/led2/brightness echo 0 > /sys/class/leds/led2/brightness这里第一段特别重要。很多板子的默认 trigger 是heartbeat或者timer，你写进去的 brightness 下一毫秒就被内核覆盖掉，现象是“灯闪一下然后按自己的节奏跳”，看着像驱动有问题，其实是你跟内核在抢同一个设备。先echo none把 trigger 关掉，再自己控制。
另一种是板厂自己写的字符设备，比如/dev/led，用法是 open 之后 ioctl：
#include <fcntl.h> #include <sys/ioctl.h> #include <unistd.h> #define LED_MAGIC 'L' #define LED_SET_ALL _IOW(LED_MAGIC, 1, int) /* 低 4 位对应 4 颗灯 */ static int led_fd = -1; int led_init(void) { led_fd = open("/dev/led", O_RDWR); return led_fd < 0 ? -1 : 0; } /* mask 的 bit0~bit3 对应 led0~led3，1 亮 0 灭 */ int led_set(int mask) { if (led_fd < 0) return -1; return ioctl(led_fd, LED_SET_ALL, &mask); }两种通路的取舍很简单：有 leds 子系统就用 sysfs，通用、无驱动依赖、换板子也好移植；只有字符设备就照着板厂头文件里的 ioctl 号写。_IOW里的 magic 和序号必须和驱动里一致，抄错了表现是ioctl返回 -1 但灯纹丝不动，这种错查起来最耗时间，一定要先去核对驱动源码或者板厂手册。
跑马灯的图案就三行逻辑：维护一个当前位索引，每次把1 << idx传给led_set，然后idx = (idx + 1) % 4。想要“来回扫”而不是“单向转”，就把步进方向也做成一个变量，到头了取反。
4.2 别在 GUI 线程里写设备节点
sysfs 的 write 和 ioctl 都是系统调用，在 6410 这种单核或者低频双核上，偶发的几十毫秒阻塞是完全可能的，尤其是在 SD 卡根文件系统上。如果这些调用发生在 GUI 线程里，界面就会卡一下，用户点按钮的反馈延迟肉眼可见。
规范做法是把硬件操作全部塞进一个 worker 对象，用moveToThread挪到独立线程，GUI 只发信号：
class LedWorker : public QObject { Q_OBJECT public slots: void onNoteStarted(int index, int degree) { if (degree == 0) return; // 休止符不动灯 led_set(1 << (index % 4)); // 按音符序号轮转 } void onStop() { led_set(0); } };连接的时候用Qt::QueuedConnection，跨线程自动就是队列连接，信号里的参数会被拷贝进事件队列，worker 在自己的线程里慢慢执行，GUI 立刻返回。要注意的是LedWorker里不要碰任何 QWidget，一旦跨线程操作界面控件，程序会随机崩，而且崩的位置跟真正的原因差得很远，属于典型的黑匣子问题。
跑马灯和音乐联动有两种粒度。按音符驱动最直观，每个音符亮一颗灯，视觉上和旋律一一对应，缺点是快节奏段落灯会闪得很急；按小节驱动更耐看，需要一个“第几拍”的计数器。演示项目里按音符驱动更抓眼球，代码也少，建议先用这个。
4.3 交叉编译到 6410：qmake、依赖检查和板上的环境变量
工程在桌面上qmake && make能过，不代表板上能跑。交叉编译的核心是让 qmake 用对 mkspec，让链接器找到目标板的 Qt 库：
# 工具链和板上的 Qt 路径按你实际环境替换 export PATH=/opt/toolchain/bin:$PATH export QMAKESPEC=/opt/qt4.8-arm/mkspecs/qws/linux-arm-g++ /opt/qt4.8-arm/bin/qmake ode.pro make -j4 # 验证产物架构，必须是 ARM file ode # 看动态库依赖，逐个确认板子上都有 arm-linux-readelf -d ode | grep NEEDEDfile那一步能挡掉一半的低级错误：如果输出是x86-64，说明 qmake 根本没用交叉的 mkspec，QMAKESPEC环境变量没生效，或者工程文件里硬编码了宿主机的路径。这种时候先qmake -query QT_INSTALL_LIBS看一眼指向哪儿，比翻 Makefile 快得多。
readelf看 NEEDED 是为了确认板上有没有对应版本的库。交叉编译用的 Qt 头文件和板上跑的 Qt 库必须是同一套，混用会出现version 'Qt_4' not found或者cannot open shared object file，这两种报错后面的排查章节会细说。
板上运行前还要设几个环境变量。Qt4 的嵌入式版本走 QWS，启动要带-qws；有触摸屏的板子还要告诉它输入设备在哪儿：
export LD_LIBRARY_PATH=/usr/local/qt/lib:$LD_LIBRARY_PATH export TSLIB_TSDEVICE=/dev/input/event1 export QWS_MOUSE_PROTO="tslib:/dev/input/event1" ./ode -qwsQWS_MOUSE_PROTO写成tslib:前缀是因为触摸屏要经过 tslib 做校准，直接写/dev/input/event1也能跑，但坐标会有偏移，点按钮点不准。event1这个编号不固定，插拔 USB 设备后可能变成event2，用cat /proc/bus/input/devices确认一下再填。
5. 避坑与排查：五个让人怀疑硬件的现场
5.1 现象：只有一种音，改频率怎么改都是“滴”
原因基本锁定在有源蜂鸣器，或者 PWM 引脚被复用成了普通 GPIO。前者的判断方法在第 2 章说过，直流加一下就响的是有源，换掉即可。后者要去看引脚复用寄存器，很多板子的 PWM 输出和 GPIO 是同一组脚，默认配置是 GPIO 模式，你在 sysfs 里写 period 写得很欢，实际电平根本到不了蜂鸣器。解决方法是查板子的原理图和 BSP 里的引脚配置，在启动脚本里把对应脚切成 PWM 功能，或者确认设备树里 pinctrl 已经配对。
还有一种更隐蔽的情况：设备节点存在，enable 也写进去了，但量出来没有波形。这时候拿示波器或者逻辑分析仪直接夹在蜂鸣器两端，如果一点方波都没有，问题在驱动或者引脚复用；如果有方波但频率不对，那是 period 的量级写错了——很多人习惯性把微秒当纳秒写，262Hz 写成 3822 就变成了 261kHz，人耳听不见，看起来就像“没响”。
5.2 现象：点下播放，界面先僵住一两秒才出声
原因是在 GUI 线程里做了阻塞操作。常见的是usleep用来控节奏，或者在槽函数里直接 open/write 设备节点。6410 上写 sysfs 遇到文件系统繁忙时几十毫秒很正常，串起来就是肉眼可见的卡顿。
解决办法是把硬件访问挪到 worker 线程，GUI 只发信号，用队列连接。控节奏绝对不能用usleep，那是把整个事件循环冻住，正确的做法就是第 3 章那个 5ms 轮询的定时器。改完之后界面立刻响应，音乐也照样准。
顺手检查一下有没有在跨线程直接操作控件。QLabel::setText从 worker 线程调用，在桌面上可能只是偶尔花屏，在板子上直接崩给你看，而且崩溃堆栈指向的位置通常和真正的调用点差很远，属于最难查的一类。
5.3 现象：前两小节准，第三小节开始明显拖拍
单定时器相对延时的典型症状，误差在累加。判断方法很简单，在noteStarted里打印每个音符的实际触发时刻和理论时刻，看差值是不是单调递增。如果是，那就是每隔一个音符多吃了几毫秒调度延迟。
换成第 3 章的绝对时间轴就能解决，m_nextTickMs在理论值上累加而不是在当前时刻上累加。如果换成绝对时间轴之后还是拖，那就不是调度问题，是m_eighthMs算错了，比如 BPM 当成拍/秒而不是拍/分钟，全曲慢六十分之一，听感上是“整体偏慢但不漂移”，和漂移是两种不同的病。
还有一种容易忽略的情况：板上 CPU 被别的进程占满，比如界面在跑一个很重的动画。这种时候 5ms 定时器实际可能是 30ms 才回来一次，虽然while循环能补发，但补发是一瞬间连着写好几次 PWM，听起来会有点糊。把界面动画降帧，或者把跑马灯的刷新从每音符改成每小节，能缓解不少。
5.4 现象：板上启动报version 'Qt_4' not found或找不到共享库
交叉编译用的 Qt 和板上运行的 Qt 不是同一套，版本号对不上，或者符号版本不一致。先看报错的具体库名，再用arm-linux-readelf -d看程序 NEEDED 了哪些库，逐个去板上ls确认存在。
如果库在但版本不对，说明交叉编译时链接的是宿主机上那套 Qt 的头文件和库，QMAKESPEC没生效是最常见的原因。改法是把QMAKESPEC显式指向交叉版的 mkspec，qmake 用交叉版那个二进制，编译前qmake -query核对一遍路径。
如果库对、路径不对，加-Wl,-rpath,/usr/local/qt/lib重新链接，比每次在板上手动设LD_LIBRARY_PATH省事。板上环境变量写在/etc/profile里，别只写当前终端，重启就丢。
5.5 现象：跑马灯只闪一下就不动了，或者灯按自己的节奏跳
两个不同的原因。只闪一下通常是程序里写完一次 brightness 就再没动过，或者 worker 线程里设置的索引没更新，打开日志打一行就知道。
灯自己按节奏跳，是内核的 trigger 在抢控制权。/sys/class/leds/ledX/trigger里如果当前选中项不是none，你写的 brightness 会被内核周期性覆盖。先cat trigger看一眼方括号在哪个选项上，再echo none关掉。这个坑还有个变种：某颗灯的 trigger 关了，另外几颗没关，看起来就是“灯有的听话有的不听话”，很容易误判成驱动 bug。
6. 进阶：把曲谱挪出代码，以及怎么证明它真的准
6.1 曲谱外置：一行一个音符的文本格式
曲谱硬编码在数组里，加一首歌就得重新编译、重新拷到板上，来回折腾很麻烦。更实用的做法是把曲谱放成文本文件，程序启动时解析。格式可以极简，一行一个音符，冒号前面是级数，后面是时值，0表示休止：
// 解析缓存在 QHash<QString, QVector<Note>> 里，切换曲目只换 key bool loadScore(const QString &path, QVector<Note> &out) { QFile f(path); if (!f.open(QIODevice::ReadOnly | QIODevice::Text)) return false; QTextStream in(&f); while (!in.atEnd()) { QString line = in.readLine().trimmed(); if (line.isEmpty() || line.startsWith('#')) continue; // 支持注释，方便标小节 const QStringList parts = line.split(':'); if (parts.size() != 2) continue; // 格式不对的行直接跳过，不中断 bool ok1 = false, ok2 = false; int deg = parts[0].toInt(&ok1); int len = parts[1].toInt(&ok2); if (ok1 && ok2) out.append(Note{deg, len}); } return !out.isEmpty(); }几个细节值得说。遇到格式不对的行选择跳过而不是报错退出，是为了让人在板上用vi改谱子的时候，手滑多打一个空行不至于整个程序起不来。支持#注释，可以在文件里按小节写标记，找错音的时候对着文本文件一行行数，比对着代码数组数快得多。文件路径建议走命令行参数或者QSettings，别写死，方便同时放几首曲子做切换。
按行解析的额外好处是方便做“乐谱热更新”。播放中改了文件，下次点播放自动重新读一遍，不用重启程序。演示的时候观众提一句“能换个曲子吗”，当场改两行文本就换掉了，效果比讲十分钟原理强。
6.2 三条验证路径：听、看波形、量时间
音乐这东西最怕“我感觉它对了”。要让别人信、也让自己放心，最好有三个客观的验证手段：
| 验证项 | 工具 | 判定标准 |
|---|---|---|
| 音高是否准确 | 手机频谱 App 或桌面音频软件录一段 | 基频峰值与频率表偏差在 1% 以内 |
| 有没有方波 | 示波器或几十块的逻辑分析仪接蜂鸣器两端 | 占空比接近 50%，周期与 period 设置一致 |
| 节拍是否漂移 | 程序里打日志，记录每个音符实际时刻 | 实际值与理论值差值不随时间单调增大 |
| 有没有爆音 | 安静环境戴耳机听停止和休止符处 | 没有明显的“啪”声 |
音高这条最省事，录一段旋律丢进任何能做频谱的软件，看峰值落在 262、330、392 这几个点附近就行。偏差大的话先怀疑蜂鸣器本身的一致性，廉价蜂鸣器的谐振峰可能偏几十赫兹，那就得在代码里加一个校准偏移量。
波形那条是为了把“软件没发对”和“硬件没响应”分开。如果示波器上周期正确、占空比正确，但还是没声音，那问题一定在驱动电路或者蜂鸣器本身，别再改代码了。反过来如果波形都没有，代码写得再好也白搭，直接去查引脚复用。
节拍那条最容易被跳过，但它是唯一能量化“跑不跑调”的手段。在onTick里加一行qDebug()打实际时刻和m_nextTickMs的差值，跑完整首看最大差值和趋势。差值在几十毫秒内随机跳动是正常的调度抖动，单调递增就是累积误差，两者处理方式完全不同。
我自己在这上面栽过一次，当时板子上跑得好好的，换了一块同型号的板子就明显拖拍，查了两天以为是 CPU 降频，最后发现是那块板子的 SD 卡根文件系统慢，日志写入偶尔阻塞上百毫秒。从那以后我每次做这类跟时间相关的嵌入式 Demo，都强制走一遍“打时间戳日志 + 示波器验波形”这两步，再也不靠耳朵判断。希望帮到你。
本文还有配套的精品资源，点击获取
