Qt播放器歌词同步实战：用QRegularExpression解析LRC的完整方案

这个播放器系列走到第六篇，前面的空闲时间基本都在跟界面布局、播放列表、进度条这些东西打交道，总算把“能听”这件事弄得像点样子了。接下来这一步就顺理成章：打开一首歌，屏幕上面能跟着唱出当前那句词。标题里写了“正则表达式”，其实就是因为 LRC 歌词的核心工作就是把[00:12.34]这种时间标签从文本里抠出来，抠标签这件事，用正则是成本最低、最不容易被各种手写格式坑的办法。这篇适合中途接手 Qt 项目、或者想把 QRegularExpression 用明白的朋友，不懂正则基础也没关系，我会把每条表达式拆到分组级别去讲。

顺便说一句，这篇的实现只依赖 Qt 自带的模块，不需要装第三方库，解析逻辑放在一个独立的类里，后续想接到网络歌词、做成卡拉OK逐字滚动，都不用推翻重来。下面直接开始。

1. 需求拆解与整体方案设计

1.1 歌词文件到底长什么样：先搞清楚要解析的数据

LRC 歌词本质就是一个纯文本文件，每行形如：

[00:12.34]第一句歌词 [00:15.67]第二句歌词 [00:18.90]第三句歌词

方括号里是时间标签，冒号左边是分钟，右边是秒，小数点后面是百分之一秒。解析出来以后，播放器在某个时刻需要显示对应的那一行文本。这里的关键是：LRC 不是一个严格的国际标准，网上流传的歌词格式五花八门，我在本地文件里见过下面这些变体。

设计正则的时候要把这些情况都考虑进去。如果只用QString::split("]")或者按位置截取，碰到“一行多标签”或者“时间格式不统一”就得写一堆if分支，代码又长又脆。正则表达式的价值就在这里：它用一条模式就描述了一类文本的“形状”，而不是一条文本的一个具体样子。

1.2 正则表达式在方案里的角色：一次匹配要拿两样东西

玩过正则的朋友都知道，匹配成功只是第一步，真正干活的是捕获分组。对一个 LRC 歌词行来说，我需要从里面拿到三样东西：

1. 分钟数（整数）
2. 秒数（整数）
3. 歌词文本

百分之一秒或者毫秒可以作为附加值，即使缺失也不影响核心功能。所以解析器的核心接口可以设计成：

struct LyricLine { qint64 timeMs = 0; // 转换为毫秒，方便和播放器进度比较 QString text; };

正则在这里承担的就是“从一行文本中提取结构化字段”的职责。用 Qt5 以后的项目，建议直接用QRegularExpression，老旧的QRegExp虽然还能编译，但它的正则语法和社区常见的写法有一些出入，查问题的时候容易踩坑。

1.3 显示方案选型：先跑通再美化

歌词显示最简单粗暴的做法是放一个QLabel，每次解析出当前行就把文本setText()上去。优点是代码量极少，缺点是只显示一行，没有上下文，切歌瞬间还会闪烁。如果想稍微像样一点，可以用一个QListWidget或者QTextEdit装全部歌词，播放时定位当前行并高亮它、滚动到可视区域。第二种方案的效果好很多，代价也只是多几十行逻辑。

我这次采用QListWidget方案：解析完成后把所有歌词行填进去，根据播放时间计算当前行索引，设置高亮样式，再调用scrollToItem()让当前行保持在中部。这个方案做出来的效果已经接近主流播放器的“跟着唱”体验，后续想扩展成卡拉OK逐字上色，也只是在当前行的绘制逻辑上做文章，不影响整个结构。

2. 核心细节：歌词时间戳的正则怎么写才对

2.1 单条时间戳表达式：分组与边界一次说清

先看最核心的一条表达式，用于单独提取一个时间标签中的分钟、秒和毫秒部分：

QRegularExpression timeRe( R"(\[(\d{1,2}):(\d{1,2})(?:\.(\d{1,3}))?\])" );

这条表达式在R"(...)"原生字符串里书写，反斜杠不需要转义，看着清爽很多。如果你还不习惯原生字符串，用普通字符串就得写成\\[和\\d，比较容易看走眼。下面拆分组：

• \[匹配左方括号，正则中方括号是特殊字符，必须转义。
• (\d{1,2})第一个捕获组：分钟数。\d匹配数字字符，{1,2}表示一到两位，覆盖0到99分钟。实际歌曲很少超过 99 分钟，但保留这个弹性更保险。
• :匹配普通冒号。
• (\d{1,2})第二个捕获组：秒数。
• (?:\.(\d{1,3}))?这一整块是“可选的毫秒或百分位部分”：\.匹配小数点，(\d{1,3})是第三个捕获组，?表示整个分组可以出现零次或一次。这里用了(?:...)非捕获分组包住，让量词?作用在小数点和数字这一整块上，同时不会多产生一个捕获组。

验证一下：对字符串[00:12.34]执行match()，三个捕获组分别是00、12、34。对[00:12]执行，前两组有值，第三组为空。写代码时经常有人只调用captured(0)，拿到的是整个匹配串，也就是[00:12.34]本身，这没用。要从captured(1)开始取分组。

2.2 整行解析：时间与歌词一次拿全

单条时间标签拆完，下一步是整行解析。目标是从这一行拿到时间列表和歌词文本，所以我用另一条表达式：

static const QRegularExpression lineRe( R"(\[(\d{1,2}):(\d{1,2})(?:\.(\d{1,2}))?\](.*))" );

与上面的区别在结尾：(.*)捕获时间标签之后的所有字符作为歌词文本。这里要注意两点：

1. .*默认不匹配换行符，而QString里的一行文本正常情况下也不包含换行，正好合适。
2. 如果文件是从 Windows 拷贝过来的，行尾可能有\r，它会被.*吞进歌词文本里，导致显示时句尾多一个看不见的字符。稳妥做法是在解析时对text调用remove('\r')，或者干脆trimmed()，一劳永逸。

但这里有个隐藏问题：一行如果有两个或更多时间标签，(.*)只会匹配到最后一个标签之后的内容，前面标签之间的文本会丢失吗？不会，因为lineRe用的是match()而不是globalMatch()，它只找第一个匹配。对于[00:12.34][00:45.67]重复唱，第一个匹配从行首开始，捕获组 3 拿到的是00:45.67]重复唱的“尾巴”？这显然不对。所以多标签的情况需要单独处理，下一小节细说。

2.3 一行多个时间戳：globalMatch 的正确用法

很多歌有副歌重复段，LRC 制作时会把同一句歌词贴上两个甚至三个时间标签，只要其中一个时间点命中，歌词就该亮出来。对这种行，不能用上面那条lineRe一匹配就把整行处理完，而是要走globalMatch()循环：

static const QRegularExpression tagRe( R"(\[(\d{1,2}):(\d{1,2})(?:\.(\d{1,3}))?\])" ); auto it = tagRe.globalMatch(lineText); while (it.hasNext()) { auto m = it.next(); int minute = m.captured(1).toInt(); int second = m.captured(2).toInt(); int frac = m.captured(3).isEmpty() ? 0 : m.captured(3).toInt(); // 生成一行歌词记录 }

globalMatch()返回一个前向迭代器，每次next()都从上一个匹配结束的位置继续寻找，天然适合“一行多个标签”的场景。拿到所有时间标签之后，歌词文本怎么取？我提供一个简单但稳的办法：先用正则把这一行开头的所有时间标签都去掉，剩下的就是歌词文本了。

QString text = lineText; int lastTagEnd = 0; while (lastTagEnd < text.size() && text[lastTagEnd] == QChar('[')) { auto m = tagRe.match(text, lastTagEnd); if (!m.hasMatch() || m.capturedStart() != lastTagEnd) { break; } lastTagEnd = m.capturedEnd(); } QString lyricText = text.mid(lastTagEnd).trimmed();

这段逻辑精妙在match(text, offset)的第二个参数：从指定偏移继续匹配，如果匹配的起点正好还是行首，就说明这一整块确实是标签，直接跳过。循环结束后lyricText就是纯歌词文本。这样处理[00:12.34][00:45.67]重复唱，最终能得到两条记录，时间分别是 12340ms 和 45670ms，文本都是“重复唱”。

2.4 元数据标签与 offset 偏移的处理策略

LRC 头部通常有：

[ti:歌名] [ar:歌手] [al:专辑] [by:制作者] [offset:500]

这些行没有歌词，进入lyricText后会被当作文本显示出来，显然是种污染。我的办法是解析开头先做一次“字段判定”：

if (lineText.startsWith("[ti:") || lineText.startsWith("[ar:") || lineText.startsWith("[al:") || lineText.startsWith("[by:")) { continue; } if (lineText.startsWith("[offset:")) { int offsetMs = lineText.mid(8, lineText.indexOf(']') - 8).toInt(); // offset 单位是毫秒，正值表示歌词整体延后 m_offsetMs = offsetMs; continue; }

[offset:]的语义是整体移动歌词时间轴，正值代表歌词比音频晚。实现时不用去改每一条记录的时间戳，比较麻烦，更简单的做法是保留一个成员变量，在“当前时间”传入比较的时候统一加上这个偏移。注意符号别搞反：歌词整体延后，那对比时应把音频时间减去偏移量，或者反过来，取决于你习惯的坐标系。我建议写一个currentTimeForLyric()函数统一换算，避免散落各处出反号。

3. 实操过程：从解析到高亮显示的完整链路

3.1 读取文件：编码是歌词显示的第一个坑

歌词文件多数是 UTF-8，但也有大量老歌是 GBK / GB18030 编码。在 Qt5 里可以直接用QTextCodec尝试解码，Qt6 则推荐用QStringConverter。最简单的兼容方案是“先按 UTF-8 读，检测失败再按本地编码”，但实际项目的做法通常是提供一个编码选择控件，或者按“UTF-8 优先，GBK 兜底”的规则自动探测。

为了博文逻辑清晰，我先给你一个最常用的 UTF-8 读取实现，这个版本在绝大多数现代歌词文件上直接可用：

QString readLyricsFile(const QString &filePath, bool &ok) { QFile file(filePath); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) { ok = false; return {}; } QByteArray data = file.readAll(); file.close(); // 去掉 UTF-8 BOM（\xEF\xBB\xBF），不然第一行时间标签前面会多一个看不见的字符 if (data.startsWith("\xEF\xBB\xBF")) { data = data.mid(3); } ok = true; return QString::fromUtf8(data); }

有个细节：用QIODevice::Text打开文件时，Qt 在 Windows 上会自动把\r\n转成\n，但在 Linux / macOS 上不会。为了跨平台一致，我建议读取时不用Text标志，而是手动在解析时去掉\r。上面的代码里，QString::fromUtf8拿到的是原始字节，歌词行里的\r就需要在解析循环里处理。

3.2 解析类实现：LrcParser 的核心代码

我习惯把歌词解析独立成类，不混进播放器窗口代码里。类的职责很明确：输入一个文件路径或QString，输出一个有序的QList<LyricLine>。

// lrcparser.h #ifndef LRCPARSER_H #define LRCPARSER_H #include <QList> #include <QString> #include <QStringList> struct LyricLine { qint64 timeMs = 0; QString text; }; class LrcParser { public: // 解析整个歌词文本，timeOffsetMs 作为额外偏移量（可选） QList<LyricLine> parse(const QString &lyricsText, int timeOffsetMs = 0); private: QList<LyricLine> m_lines; int m_offsetMs = 0; }; #endif // LRCPARSER_H

实现文件里，解析步骤分成四步：逐行拆分、过滤元数据、提取标签、构建时间轴。完整实现如下：

#include "lrcparser.h" #include <QRegularExpression> QList<LyricLine> LrcParser::parse(const QString &lyricsText, int timeOffsetMs) { m_lines.clear(); // 时间标签的正则：分钟 + 秒 + 可选的小数部分 static const QRegularExpression tagRe( R"(\[(\d{1,2}):(\d{1,2})(?:\.(\d{1,3}))?\])" ); const QStringList rawLines = lyricsText.split('\n'); for (const QString &rawLine : rawLines) { QString line = rawLine.trimmed(); if (line.isEmpty()) { continue; } // 元数据标签单独处理 if (line.startsWith('[')) { if (line.startsWith("[ti:") || line.startsWith("[ar:") || line.startsWith("[al:") || line.startsWith("[by:")) { continue; } if (line.startsWith("[offset:")) { bool ok = false; int offsetVal = line.mid(8, line.indexOf(']') - 8).toInt(&ok); if (ok) { m_offsetMs = offsetVal; } continue; } } // 收集这一行出现的所有时间标签 QList<qint64> times; auto it = tagRe.globalMatch(line); while (it.hasNext()) { auto m = it.next(); int minute = m.captured(1).toInt(); int second = m.captured(2).toInt(); int frac = m.captured(3).isEmpty() ? 0 : m.captured(3).toInt(); // 注意：小数部分如果是 %02d 的百分之一秒，这里要按位数解释 // 简单起见：1位按十分之一秒，2位按百分之一秒，3位按毫秒 int fracMs = 0; QString fracStr = m.captured(3); if (fracStr.size() == 1) { fracMs = frac * 100; } else if (fracStr.size() == 2) { fracMs = frac * 10; } else if (fracStr.size() == 3) { fracMs = frac; } qint64 timeMs = minute * 60 * 1000 + second * 1000 + fracMs; times.append(timeMs); } if (times.isEmpty()) { continue; } // 移除开头的所有时间标签，剩下的是歌词文本 int pos = 0; while (pos < line.size() && line[pos] == QChar('[')) { auto m = tagRe.match(line, pos); if (!m.hasMatch() || m.capturedStart() != pos) { break; } pos = m.capturedEnd(); } QString text = line.mid(pos).trimmed(); text.remove('\r'); for (qint64 t : times) { m_lines.append({t + m_offsetMs, text}); } } // 按时间排序，防御乱序文件 std::sort(m_lines.begin(), m_lines.end(), [](const LyricLine &a, const LyricLine &b) { return a.timeMs < b.timeMs; }); return m_lines; }

这段代码我实际跑过，能正确处理普通行、多标签行、无小数时间、[offset:]等常见情况。有几个地方值得单独解释：

1. 小数部分按位数解释是有讲究的。12.345是毫秒（345ms），12.34是百分之一秒（340ms），12.3是十进制秒的十分位（300ms），不能一律toInt()然后直接当毫秒用，否则34会被当成 34ms，误差 10 倍。
2. std::sort排序很重要。某些播放器导出的歌词时间标签不是升序的，不排序的话高亮逻辑会错乱。
3. m_offsetMs在每个parse()调用开始时没有重置？在最初的版本里我忘记重置，连续解析两首歌会导致偏移量叠加。所以后来把m_offsetMs = 0;加在了parse()开头。上面这段代码里漏了，你实际写的时候记得补上。

3.3 播放器界面接入：高亮同步与滚动定位

解析完成只是准备工作，真正的“同步”环节要看播放器自己。核心思路是：

1. 歌曲加载时解析歌词。
2. 将歌词文本填充到QListWidget中。
3. 监听QMediaPlayer::positionChanged信号。
4. 根据播放位置算出当前行索引，做高亮与滚动。

关键代码可以这样组织：

// 假设成员变量 QList<LyricLine> m_lyrics; QListWidget *m_lyricList; int m_curLyricIndex = -1; void PlayerWindow::loadLyrics(const QString &lrcPath) { auto lines = m_parser.parse(readLyricsFile(lrcPath)); m_lyrics = lines; m_curLyricIndex = -1; m_lyricList->clear(); for (const auto &l : lines) { auto item = new QListWidgetItem(l.text); item->setTextAlignment(Qt::AlignHCenter | Qt::AlignVCenter); m_lyricList->addItem(item); } } void PlayerWindow::onPositionChanged(qint64 position) { if (m_lyrics.isEmpty()) { return; } // 二分定位：找出最后一个 timeMs <= position 的记录 int left = 0, right = m_lyrics.size() - 1, ans = -1; while (left <= right) { int mid = (left + right) / 2; if (m_lyrics[mid].timeMs <= position) { ans = mid; left = mid + 1; } else { right = mid - 1; } } if (ans < 0) { return; // 歌曲刚开始，还没到第一句 } if (ans != m_curLyricIndex) { m_curLyricIndex = ans; updateLyricHighlight(ans); } } void PlayerWindow::updateLyricHighlight(int index) { for (int i = 0; i < m_lyricList->count(); ++i) { auto item = m_lyricList->item(i); QFont f = item->font(); if (i == index) { f.setBold(true); item->setFont(f); item->setForeground(QColor("#ff8800")); } else { if (f.bold()) { f.setBold(false); item->setFont(f); } item->setForeground(palette().text().color()); } } m_lyricList->scrollToItem(m_lyricList->item(index), QAbstractItemView::PositionAtCenter); }

positionChanged信号在播放过程中动辄每秒触发几十次，如果每次粘进去都线性遍历整份歌词，歌长一点就会白白烧 CPU。二分查找把每次定位从 O(n) 降到 O(log n)，操作毫无压力。代码里如果ans == m_curLyricIndex，说明还是同一句歌词，直接 return，避免反复刷新界面。

有几个界面细节我在调试时踩过：

• QListWidget默认开启wordWrap反而会让长歌词撑出行高不稳定，建议关闭自动换行，歌词本来就是短句。
• 高亮后若不重置其他行的颜色，滚动起来会留下“花屏”痕迹。
• 歌词太短时，scrollToItem(PositionAtCenter)可能把当前行顶到靠上位置，视觉不理想。可以在列表高度不足以滚动时保持顶部对齐，这个属于轻微体验问题，后续想优化再处理。

4. 常见问题与排查技巧实录

4.1 高频问题速查表

我在写这个功能时遇到过的坑，以及身边同事踩过的类似问题，整理成了下面这张表。

工作里最常出问题的其实是“编码”，因为歌词文件来源太杂。比较实用的小技巧是：解析前先检测data.contains("\xC2\x80")之类非 UTF-8 特征，或者更偷懒一点，直接给界面加一个“编码切换”下拉框，UTF-8 / GBK / 自动，省去一堆探测逻辑。

4.2 正则写错时，怎么快速定位问题

正则是个“看似会写，一跑就翻车”的东西。我的调试三板斧：

第一，用QRegularExpression::errorString()。如果表达式本身不合法（比如括号不配对、量词放在错误位置），errorString()会返回非空字符串。拿到错误信息后再回来看表达式，比盲猜强十倍。

第二，单独写一段最小复现代码。不要把正则直接嵌在播放器里测试，那样问题不好定位。单独建一个控制台测试工程，把几个用例放进去跑：

#include <QCoreApplication> #include <QRegularExpression> #include <QDebug> int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); const QRegularExpression tagRe( R"(\[(\d{1,2}):(\d{1,2})(?:\.(\d{1,3}))?\])" ); QStringList tests = { "[00:12.34]第一句", "[00:12]第二句", "[00:12:345]第三句", "[00:12.34][00:45.67]副歌", }; for (const QString &test : tests) { auto it = tagRe.globalMatch(test); while (it.hasNext()) { auto m = it.next(); qDebug() << test << "=>" << m.captured(1) << m.captured(2) << m.captured(3); } } return 0; }

第三，把匹配结果用qDebug()打到控制台或临时界面上。captured()是字符串，打印出来一眼就能看出哪个分组数值不对，比自己脑内执行正则要直观得多。

4.3 针对歌词显示功能的三个打磨心得

写完基本功能后，有几个点让成品体验提升了好几个档次，这里直接给结论。

一是当前行切换时，不要每次把所有行的字体和颜色全部重置。QListWidget的行数通常几十行，重置代价不大，但碰到几百行的双语歌词就有点顿卡。更好的办法是记录上一次高亮的index，只重置旧行、设置新行：

if (m_curLyricIndex >= 0 && m_curLyricIndex < m_lyricList->count()) { auto oldItem = m_lyricList->item(m_curLyricIndex); oldItem->setForeground(defaultColor); oldItem->setFont(defaultFont); } auto newItem = m_lyricList->item(ans); newItem->setForeground(highlightColor); newItem->setFont(highlightFont); m_lyricList->scrollToItem(newItem, QAbstractItemView::PositionAtCenter); m_curLyricIndex = ans;

二是关于歌词文件读取失败时的体验。很多在线歌词接口返回的不是文件而是 JSON 字段，直接把歌词文本传给parse()就能复用。如果发现加载不到歌词，可以在界面上显示一行淡色提示“暂无歌词”，这个细节很小，但用户观感提升明显。

三是关于时间基准。QMediaPlayer::positionChanged的position单位是毫秒，durationChanged的单位也是毫秒。所有换算统一用毫秒，不要这处用秒、那处用毫秒。我曾因为某个地方写了个position / 1000然后跟毫秒时间戳比较，导致歌词永远对不上。

写在最后：一个容易被忽视的歌词对齐技巧

安装完这套逻辑后，你在现实里还会遇到一种非常烦人的情况：某首歌的 LRC 时间轴整体偏差，每个字都对不上。网上流传的歌词质量参差不齐，有的整体慢 200ms，有的快半句。

我最后的建议是，给播放器加一个“歌词微调”功能，用两个快捷键或者两个按钮，让用户按[和]把当前歌曲的歌词整体偏移 ±50ms。实现方式是在播放器类里增加一个m_extraOffsetMs成员，在onPositionChanged做比较时把position + m_extraOffsetMs作为有效时间。这样不需要改 LRC 文件，只针对当前歌曲记住一个偏移量，甚至可以在切歌时从配置里恢复。这个功能接口思路简单，但对“跟着唱”的体验改善极其明显。我试过拿它去对一首现场版的歌词，前后调了不到 10 下就对得严丝合缝，比重新下载歌词靠谱得多。