案例:音乐播放器
QMediaPlayer 播放列表、可拖动进度条、音量与播放状态机
#这个案例做什么
写一个能日常听歌的桌面播放器:从本地添加音频文件形成播放列表,双击就能播;底部是播放控制条(上一首 / 播放暂停 / 下一首 / 进度条 / 音量),进度条既能显示进度也能拖着跳转、点哪跳哪;支持顺序播放、单曲循环、随机三种模式,切换上一首时如果当前播放超过 3 秒则跳回开头(和主流播放器一致的细节);读取 ID3 标签显示标题与艺术家,封面图有的话就显示出来;退出时记住音量、播放列表和上次听到第几秒,下次打开接着听。这个案例的核心是播放状态机——Qt 6 的多媒体 API 是完全异步的,几乎所有操作都要靠信号驱动。
功能清单:
- 播放核心:
QMediaPlayer+QAudioOutput,支持 mp3 / wav / flac / m4a / ogg; - 播放列表:
QFileDialog批量添加、拖拽添加、双击播放、右键移除、清空; - 进度条:可拖动跳转、点击定位,拖动期间不跳动,显示当前时间 / 总时长;
- 音量:
QSlider调节 + 静音按钮,音量值持久化; - 播放控制:上一首 / 播放暂停 / 下一首,三种播放模式(顺序 / 单曲循环 / 随机);
- 元数据:读取标题、艺术家、专辑与封面图,没有标签时退回文件名;
- 持久化:
QSettings记住列表、音量、上次位置与播放模式。
#用到的知识点
| 知识点 | 出处 |
|---|---|
QMediaPlayer / QAudioOutput / QAudio | 第四篇第 10 章 进程通信与系统级功能(多媒体) |
QMediaMetaData 元数据与封面 | 第四篇第 10 章 进程通信与系统级功能 |
QUrl::fromLocalFile 本地文件定位 | 第三篇第 5 章 Qt 核心数据类型 |
QSlider 与自定义点击定位 | 第三篇第 6 章 常用基础控件 |
QStyle::sliderValueFromPosition 与自绘 | 第四篇第 4 章 自定义控件与 QSS |
QListWidget 列表控件 | 第三篇第 6 章 常用基础控件 |
QFileDialog / QInputDialog | 第四篇第 1 章 对话框与交互 |
QSettings 状态持久化 | 第四篇第 6 章 文件与数据持久化 |
QRandomGenerator 随机播放 | 第三篇第 5 章 Qt 核心数据类型 |
布局管理、QMainWindow、快捷键 | 第三篇第 7、8 章 |
| 信号槽与异步状态机 | 第三篇第 3 章 元对象系统与信号槽 |
#项目结构
musicplayer/
├── CMakeLists.txt
└── src/
├── main.cpp
├── seekslider.h
├── seekslider.cpp # 支持点击定位的进度条
├── mainwindow.h
└── mainwindow.cpp # 播放器核心、列表、控制条、持久化cmake_minimum_required(VERSION 3.16)
project(MusicPlayer LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)
# 多媒体是独立模块,必须显式声明;部署时别忘了它的插件
find_package(Qt6 REQUIRED COMPONENTS Widgets Multimedia)
qt_add_executable(MusicPlayer
src/main.cpp
src/seekslider.cpp
src/seekslider.h
src/mainwindow.cpp
src/mainwindow.h
)
target_link_libraries(MusicPlayer PRIVATE
Qt6::Widgets
Qt6::Multimedia
)
if(MSVC)
target_compile_options(MusicPlayer PRIVATE /utf-8)
endif()#核心实现
#播放器核心:一切都是异步的
Qt 6 里 QMediaPlayer 不再自带音频输出设备,必须显式配一个 QAudioOutput:
m_output = new QAudioOutput(this);
m_player = new QMediaPlayer(this);
m_player->setAudioOutput(m_output);之后调用 setSource() 只是"开始加载",媒体不会立刻就绪。所以千万不要写"设置源 → 立刻 setPosition() → play()"这种同步代码,位置会被忽略。所有后续动作都挂在信号上:
durationChanged(qint64):时长已知了,此时才能设置进度条范围;positionChanged(qint64):播放中持续触发,驱动进度条与剩余时间;playbackStateChanged():在StoppedState/PlayingState/PausedState之间切换,用来切换按钮图标;mediaStatusChanged():EndOfMedia表示自然播放结束,是自动切下一首的唯一正确时机(不要用StoppedState判断,因为它也可能来自用户点击停止);errorOccurred():解码失败、文件不存在都会走这里,一定要处理,否则用户点了没反应却不知道为什么。
// src/mainwindow.h
#pragma once
#include <QMainWindow>
#include <QStringList>
class QMediaPlayer;
class QAudioOutput;
class QListWidget;
class QLabel;
class QSlider;
class QAction;
class QToolButton;
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
explicit MainWindow(QWidget *parent = nullptr);
~MainWindow() override;
protected:
void closeEvent(QCloseEvent *event) override;
private:
enum PlayMode { Sequential, RepeatOne, Shuffle };
void buildUi();
void buildControls();
void addFiles();
void removeSelected();
void playAt(int row);
void step(int delta);
void togglePlayPause();
void updateControls();
void updateTrackInfo();
void updateMeta();
void loadSettings();
void saveSettings() const;
static QString formatTime(qint64 ms);
QMediaPlayer *m_player = nullptr;
QAudioOutput *m_output = nullptr;
QListWidget *m_list = nullptr;
QLabel *m_cover = nullptr;
QLabel *m_info = nullptr;
QLabel *m_time = nullptr;
QSlider *m_seek = nullptr; // 实际类型是 SeekSlider
QWidget *m_controlBar = nullptr; // 底部控制条容器
QSlider *m_volume = nullptr;
QAction *m_play = nullptr;
QAction *m_mute = nullptr;
QStringList m_files;
int m_current = -1;
PlayMode m_mode = Sequential;
qint64 m_pendingPosition = -1; // 待跳转的续听位置
bool m_seeking = false; // 用户正在拖动进度条
};// src/mainwindow.cpp(播放器核心)
#include "mainwindow.h"
#include <QAudioOutput>
#include <QCloseEvent>
#include <QFileDialog>
#include <QHBoxLayout>
#include <QImage>
#include <QLabel>
#include <QListWidget>
#include <QMediaMetaData>
#include <QMediaPlayer>
#include <QMessageBox>
#include <QPushButton>
#include <QRandomGenerator>
#include <QSettings>
#include <QSlider>
#include <QStandardPaths>
#include <QStatusBar>
#include <QStyle>
#include <QToolButton>
#include <QVBoxLayout>
#include <QtMath>
#include "seekslider.h"
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
{
// 音频输出设备与播放器是两个对象,音量属于输出设备
m_output = new QAudioOutput(this);
m_player = new QMediaPlayer(this);
m_player->setAudioOutput(m_output);
buildControls(); // 先造控制条,buildUi 会用到 m_controlBar
buildUi();
// ---- 状态机:所有界面更新都由信号驱动 ----
connect(m_player, &QMediaPlayer::playbackStateChanged,
this, [this](QMediaPlayer::PlaybackState) { updateControls(); updateTrackInfo(); });
connect(m_player, &QMediaPlayer::positionChanged, this, [this](qint64 pos) {
// 用户拖动时不要回写滑块,否则进度会被"拉回去"
if (!m_seeking)
m_seek->setValue(int(pos));
m_time->setText(QStringLiteral("%1 / %2").arg(formatTime(pos),
formatTime(m_player->duration())));
});
connect(m_player, &QMediaPlayer::durationChanged, this, [this](qint64 dur) {
m_seek->setRange(0, int(dur));
// 续听位置要在媒体真正加载完之后才生效
if (m_pendingPosition >= 0 && dur > 0) {
m_player->setPosition(m_pendingPosition);
m_pendingPosition = -1;
}
});
connect(m_player, &QMediaPlayer::mediaStatusChanged,
this, [this](QMediaPlayer::MediaStatus status) {
if (status == QMediaPlayer::EndOfMedia) {
if (m_mode == RepeatOne) {
m_player->setPosition(0);
m_player->play();
} else {
step(1);
}
}
if (status == QMediaPlayer::LoadedMedia)
updateMeta();
});
connect(m_player, &QMediaPlayer::errorOccurred,
this, [this](QMediaPlayer::Error, const QString &err) {
statusBar()->showMessage(QStringLiteral("播放失败:%1").arg(err), 5000);
});
loadSettings();
}
QString MainWindow::formatTime(qint64 ms)
{
if (ms < 0) ms = 0;
const qint64 sec = ms / 1000;
return QStringLiteral("%1:%2")
.arg(sec / 60, 2, 10, QLatin1Char('0'))
.arg(sec % 60, 2, 10, QLatin1Char('0'));
}
void MainWindow::togglePlayPause()
{
if (m_files.isEmpty()) { addFiles(); return; }
if (m_player->playbackState() == QMediaPlayer::PlayingState)
m_player->pause();
else
m_player->play();
}
void MainWindow::playAt(int row)
{
if (row < 0 || row >= m_files.size()) return;
m_current = row;
m_list->setCurrentRow(row);
// 必须用 fromLocalFile:直接 QUrl(path) 会被当成相对路径或非法 URL
m_player->setSource(QUrl::fromLocalFile(m_files.at(row)));
m_player->play();
updateTrackInfo();
}
void MainWindow::step(int delta)
{
if (m_files.isEmpty()) return;
if (m_mode == Shuffle) {
playAt(QRandomGenerator::global()->bounded(m_files.size()));
return;
}
// 主流播放器的细节:播放过 3 秒后按"上一首"是回到本曲开头
if (delta < 0 && m_player->position() > 3000) {
m_player->setPosition(0);
return;
}
const int next = (m_current + delta + m_files.size()) % m_files.size();
playAt(next);
}
void MainWindow::updateControls()
{
const bool playing = m_player->playbackState() == QMediaPlayer::PlayingState;
m_play->setIcon(style()->standardIcon(playing ? QStyle::SP_MediaPause
: QStyle::SP_MediaPlay));
m_play->setText(playing ? QStringLiteral("暂停") : QStringLiteral("播放"));
}
void MainWindow::updateTrackInfo()
{
if (m_current < 0) return;
const QFileInfo fi(m_files.value(m_current));
m_info->setText(QStringLiteral("<b>%1</b>").arg(fi.completeBaseName()));
setWindowTitle(QStringLiteral("%1 — 音乐播放器").arg(fi.completeBaseName()));
}#进度条:能拖、能点、拖动时不跳
QSlider 默认行为是"点击滑块之外的轨道只前进一格",对进度条来说完全不够用。解决方案是自己算位置:QStyle::sliderValueFromPosition(min, max, pos - handleRect...) 是 Qt 提供的标准工具函数,它会把像素坐标按方向(水平/垂直)、布局方向(RTL)和滑块长度正确换算成数值,比自己写 (x - left) / width * max 健壮得多。
拖动时的互斥是关键:给 QSlider 加上 sliderPressed / sliderReleased / sliderMoved 三个信号的配合——按下时置 m_seeking = true 并只更新文字,松开时才真正 setPosition() 跳转。positionChanged 信号在拖动期间依然会到达,必须用标志位挡掉,否则进度条会像抽搐一样来回跳。
// src/seekslider.h
#pragma once
#include <QSlider>
// 点击即定位、拖动时预览的进度条
class SeekSlider : public QSlider
{
Q_OBJECT
public:
explicit SeekSlider(QWidget *parent = nullptr);
protected:
void mousePressEvent(QMouseEvent *event) override;
void mouseMoveEvent(QMouseEvent *event) override;
void mouseReleaseEvent(QMouseEvent *event) override;
private:
// 像素坐标 → 数值,处理了水平/垂直与 RTL 布局
int valueFromPos(const QPoint &pos) const;
bool m_dragging = false;
};// src/seekslider.cpp
#include "seekslider.h"
#include <QMouseEvent>
#include <QStyle>
#include <QStyleOptionSlider>
SeekSlider::SeekSlider(QWidget *parent) : QSlider(parent)
{
setOrientation(Qt::Horizontal);
setRange(0, 0);
setSingleStep(1000);
setPageStep(10000);
}
int SeekSlider::valueFromPos(const QPoint &pos) const
{
QStyleOptionSlider opt;
initStyleOption(&opt);
const QRect groove = style()->subControlRect(QStyle::CC_Slider, &opt,
QStyle::SC_SliderGroove, this);
const QRect handle = style()->subControlRect(QStyle::CC_Slider, &opt,
QStyle::SC_SliderHandle, this);
// 减去半个滑块,让点击位置对准滑块中心而不是滑块左缘
int pixel = orientation() == Qt::Horizontal ? pos.x() - handle.width() / 2
: pos.y() - handle.height() / 2;
return style()->sliderValueFromPosition(minimum(), maximum(),
pixel - groove.left(),
groove.width(),
opt.upsideDown);
}
void SeekSlider::mousePressEvent(QMouseEvent *event)
{
if (event->button() != Qt::LeftButton) { QSlider::mousePressEvent(event); return; }
m_dragging = true;
// 先跳到点击位置再交给基类处理,这样接着拖动是顺滑的
setValue(valueFromPos(event->pos()));
emit sliderPressed();
emit sliderMoved(value());
QSlider::mousePressEvent(event);
event->accept();
}
void SeekSlider::mouseMoveEvent(QMouseEvent *event)
{
if (m_dragging)
emit sliderMoved(valueFromPos(event->pos()));
QSlider::mouseMoveEvent(event);
}
void SeekSlider::mouseReleaseEvent(QMouseEvent *event)
{
if (m_dragging) {
m_dragging = false;
emit sliderReleased();
}
QSlider::mouseReleaseEvent(event);
}把滑块接到播放器上时,拖动期间要只更新文字、不更新滑块(用 sliderMoved 的预览值):
// src/mainwindow.cpp(控制条组装)
void MainWindow::buildControls()
{
m_seek = new SeekSlider(this);
m_seek->setObjectName(QStringLiteral("seek"));
// 拖动期间:只刷新时间文字,滑块位置由用户控制
connect(m_seek, &QSlider::sliderPressed, this, [this] { m_seeking = true; });
connect(m_seek, &QSlider::sliderMoved, this, [this](int value) {
m_time->setText(QStringLiteral("%1 / %2").arg(formatTime(value),
formatTime(m_player->duration())));
});
// 松手才真正跳转,避免拖动过程中每帧都 seek 导致解码器爆音
connect(m_seek, &QSlider::sliderReleased, this, [this] {
m_player->setPosition(m_seek->value());
m_seeking = false;
});
m_volume = new QSlider(Qt::Horizontal, this);
m_volume->setRange(0, 100);
m_volume->setFixedWidth(90);
// QAudioOutput 的音量是 0.0~1.0 的浮点数
m_volume->setValue(qRound(m_output->volume() * 100));
connect(m_volume, &QSlider::valueChanged, this, [this](int v) {
m_output->setVolume(v / 100.0);
m_output->setMuted(false);
m_mute->setChecked(false);
});
m_mute = new QAction(style()->standardIcon(QStyle::SP_MediaVolume),
QStringLiteral("静音"), this);
m_mute->setCheckable(true);
connect(m_mute, &QAction::toggled, this, [this](bool on) {
m_output->setMuted(on);
m_mute->setIcon(style()->standardIcon(on ? QStyle::SP_MediaVolumeMuted
: QStyle::SP_MediaVolume));
});
auto *prev = new QAction(style()->standardIcon(QStyle::SP_MediaSkipBackward),
QStringLiteral("上一首"), this);
prev->setShortcut(QKeySequence(Qt::Key_Up));
connect(prev, &QAction::triggered, this, [this] { step(-1); });
m_play = new QAction(style()->standardIcon(QStyle::SP_MediaPlay),
QStringLiteral("播放"), this);
m_play->setShortcut(QKeySequence(Qt::Key_Space));
connect(m_play, &QAction::triggered, this, &MainWindow::togglePlayPause);
auto *next = new QAction(style()->standardIcon(QStyle::SP_MediaSkipForward),
QStringLiteral("下一首"), this);
next->setShortcut(QKeySequence(Qt::Key_Down));
connect(next, &QAction::triggered, this, [this] { step(1); });
auto *bar = new QWidget(this);
auto *h = new QHBoxLayout(bar);
h->setContentsMargins(8, 4, 8, 4);
m_time = new QLabel(QStringLiteral("0:00 / 0:00"), bar);
m_time->setFixedWidth(110);
auto *btnPrev = new QToolButton(bar); btnPrev->setDefaultAction(prev);
auto *btnPlay = new QToolButton(bar); btnPlay->setDefaultAction(m_play);
auto *btnNext = new QToolButton(bar); btnNext->setDefaultAction(next);
auto *btnMute = new QToolButton(bar); btnMute->setDefaultAction(m_mute);
h->addWidget(btnPrev);
h->addWidget(btnPlay);
h->addWidget(btnNext);
h->addWidget(m_seek, 1);
h->addWidget(m_time);
h->addWidget(btnMute);
h->addWidget(m_volume);
m_controlBar = bar; // 由 buildUi 把它加进主布局
}#界面骨架:列表 + 封面 + 控制条
m_controlBar 是在 buildControls() 里组装好的独立 QWidget,buildUi() 只负责把它和列表、封面按垂直布局拼起来。这样做的好处是控制条的构造逻辑(图标、信号连接)与摆放位置解耦,后面想把它移到顶部或者做成浮动条,都不用改控制条本身。
// src/mainwindow.cpp(界面骨架)
void MainWindow::buildUi()
{
m_list = new QListWidget(this);
m_list->setSelectionMode(QAbstractItemView::ExtendedSelection);
m_list->setAlternatingRowColors(true);
m_list->setWordWrap(false);
connect(m_list, &QListWidget::itemDoubleClicked, this, [this](QListWidgetItem *item) {
playAt(m_list->row(item));
});
// 列表支持拖拽加入:拖入的是文件路径
m_list->setAcceptDrops(false);
m_list->setContextMenuPolicy(Qt::ActionsContextMenu);
auto *open = new QAction(QStringLiteral("添加文件"), this);
open->setShortcut(QKeySequence::Open);
connect(open, &QAction::triggered, this, &MainWindow::addFiles);
m_list->addAction(open);
auto *del = new QAction(QStringLiteral("移除"), this);
del->setShortcut(QKeySequence::Delete);
connect(del, &QAction::triggered, this, &MainWindow::removeSelected);
m_list->addAction(del);
m_cover = new QLabel(this);
m_cover->setFixedSize(180, 180);
m_cover->setAlignment(Qt::AlignCenter);
m_cover->setStyleSheet(QStringLiteral("background:#1c1e23;color:#7a7f8a;"));
m_cover->setText(QStringLiteral("无封面"));
m_info = new QLabel(this);
m_info->setAlignment(Qt::AlignLeft | Qt::AlignVCenter);
m_info->setWordWrap(true);
auto *side = new QWidget(this);
auto *sideLayout = new QVBoxLayout(side);
sideLayout->addWidget(m_cover, 0, Qt::AlignTop | Qt::AlignHCenter);
sideLayout->addSpacing(12);
sideLayout->addWidget(m_info, 0, Qt::AlignTop);
sideLayout->addStretch(1);
auto *top = new QWidget(this);
auto *h = new QHBoxLayout(top);
h->setContentsMargins(6, 6, 6, 0);
h->addWidget(m_list, 1);
h->addWidget(side);
// 控制条在最底部,横跨整个窗口
auto *central = new QWidget(this);
auto *v = new QVBoxLayout(central);
v->setContentsMargins(0, 0, 0, 0);
v->addWidget(top, 1);
v->addWidget(m_controlBar);
setCentralWidget(central);
statusBar()->showMessage(QStringLiteral("用 Ctrl+O 添加音频文件"));
resize(760, 480);
}#播放列表、元数据与持久化
列表项上存两样东西:Qt::UserRole 存路径,文本显示"标题 — 艺术家"。元数据是异步获取的,只有 LoadedMedia 之后 metaData() 才有内容;QMediaMetaData::ThumbnailImage 返回的是 QImage(也可能是 QPixmap),要用 QVariant::canConvert 判断类型再取,直接 value<QImage>() 在有些后端上会拿到空图。
续听位置的还原必须等媒体加载完:把位置存进 m_pendingPosition,在 durationChanged 里首次拿到时长时再 setPosition(),然后置 -1 表示已消费——否则切歌时会把上一首的位置带到新歌上。
// src/mainwindow.cpp(列表与持久化)
void MainWindow::addFiles()
{
const QStringList paths = QFileDialog::getOpenFileNames(
this, QStringLiteral("添加音频文件"),
QStandardPaths::writableLocation(QStandardPaths::MusicLocation),
QStringLiteral("音频文件 (*.mp3 *.wav *.flac *.m4a *.ogg *.aac);;所有文件 (*)"));
if (paths.isEmpty()) return;
for (const QString &path : paths) {
if (m_files.contains(path)) continue; // 去重,避免重复添加
m_files.append(path);
auto *item = new QListWidgetItem(QFileInfo(path).completeBaseName());
item->setData(Qt::UserRole, path);
item->setToolTip(path);
m_list->addItem(item);
}
// 首次添加就自动播放第一首
if (m_current < 0 && !m_files.isEmpty())
playAt(0);
}
void MainWindow::removeSelected()
{
// 必须从后往前删,否则前面的删除会让后面的行号失效
const QList<QListWidgetItem *> items = m_list->selectedItems();
QList<int> rows;
for (QListWidgetItem *it : items) rows << m_list->row(it);
std::sort(rows.begin(), rows.end(), std::greater<int>());
for (int row : std::as_const(rows)) {
if (row == m_current) {
m_player->stop();
m_current = -1;
m_pendingPosition = -1;
}
m_files.removeAt(row);
delete m_list->takeItem(row);
}
}
void MainWindow::updateMeta()
{
if (m_current < 0) return;
const QMediaMetaData meta = m_player->metaData();
const QString title = meta.value(QMediaMetaData::Title).toString();
const QString artist = meta.value(QMediaMetaData::ContributingArtist).toString();
const QString album = meta.value(QMediaMetaData::AlbumTitle).toString();
const QString fallback = QFileInfo(m_files.value(m_current)).completeBaseName();
const QString name = title.isEmpty() ? fallback : title;
m_info->setText(artist.isEmpty()
? QStringLiteral("<b>%1</b>").arg(name.toHtmlEscaped())
: QStringLiteral("<b>%1</b><br><small>%2</small>")
.arg(name.toHtmlEscaped(), artist.toHtmlEscaped()));
// 封面:元数据可能给 QImage 也可能给 QPixmap,两边都要能接
const QVariant cover = meta.value(QMediaMetaData::ThumbnailImage);
QImage img;
if (cover.canConvert<QImage>()) img = cover.value<QImage>();
else if (cover.canConvert<QPixmap>()) img = cover.value<QPixmap>().toImage();
if (!img.isNull()) {
m_cover->setPixmap(QPixmap::fromImage(img).scaled(
m_cover->size() * devicePixelRatioF(), Qt::KeepAspectRatio,
Qt::SmoothTransformation));
}
if (auto *it = m_list->item(m_current)) {
it->setText(artist.isEmpty() ? name
: QStringLiteral("%1 — %2").arg(name, artist));
if (!album.isEmpty()) it->setToolTip(album);
}
}
void MainWindow::loadSettings()
{
QSettings settings;
const int vol = settings.value(QStringLiteral("volume"), 60).toInt();
m_output->setVolume(vol / 100.0);
m_volume->setValue(vol);
m_mode = static_cast<PlayMode>(
settings.value(QStringLiteral("mode"), int(Sequential)).toInt());
const QStringList files = settings.value(QStringLiteral("files")).toStringList();
for (const QString &path : files) {
if (!QFileInfo::exists(path)) continue; // 文件可能已经删了
m_files.append(path);
auto *item = new QListWidgetItem(QFileInfo(path).completeBaseName());
item->setData(Qt::UserRole, path);
item->setToolTip(path);
m_list->addItem(item);
}
// 恢复上次位置:只记录,等媒体加载完再由 durationChanged 应用
const int row = settings.value(QStringLiteral("current"), -1).toInt();
const qint64 pos = settings.value(QStringLiteral("position"), 0).toLongLong();
if (row >= 0 && row < m_files.size()) {
m_current = row;
m_list->setCurrentRow(row);
m_pendingPosition = pos;
m_player->setSource(QUrl::fromLocalFile(m_files.at(row)));
updateTrackInfo(); // 加载但不自动播放
}
}
void MainWindow::saveSettings() const
{
QSettings settings;
settings.setValue(QStringLiteral("volume"), m_volume->value());
settings.setValue(QStringLiteral("mode"), int(m_mode));
settings.setValue(QStringLiteral("files"), m_files);
settings.setValue(QStringLiteral("current"), m_current);
settings.setValue(QStringLiteral("position"), m_player->position());
// 路径存在 QSettings 里是 QStringList,读写都自动类型安全
}
void MainWindow::closeEvent(QCloseEvent *event)
{
saveSettings();
QMainWindow::closeEvent(event);
}
MainWindow::~MainWindow()
{
// 析构前先停,避免对象销毁时后台解码线程还在回调
m_player->stop();
}// src/main.cpp
#include <QApplication>
#include <QCoreApplication>
#include "mainwindow.h"
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QCoreApplication::setOrganizationName(QStringLiteral("QtTutorial"));
QCoreApplication::setApplicationName(QStringLiteral("MusicPlayer"));
MainWindow w;
w.show();
return app.exec();
}#关键细节与踩坑
1. 一切就绪前不要操作播放器。 setSource() 只是开始加载,这时 duration() 是 -1,setPosition() 会被忽略。想续听必须把位置存起来,等 durationChanged 首次给出正值时再跳转。同理 play() 之后立刻读 metaData() 也拿不到内容,要等 LoadedMedia。
2. 点了没声音,但也不报错。 最常见的是缺后端插件:Qt 6 的 Multimedia 在 Linux 上依赖 GStreamer(还要装 gst-plugins-good/bad/ugly 才有 mp3 解码),Windows 上依赖 WMF,macOS 上是 AVFoundation。运行时会输出 No decoder available for format 之类的警告。一定要连上 errorOccurred 信号把 errorString() 显示出来,否则用户只会觉得"软件坏了"。部署时用 windeployqt / macdeployqt 会自动带上插件,Linux 则要提示用户装 GStreamer。
3. 进度条抽搐、拖动时自己往回跳。 positionChanged 在拖动期间照常到来,会把用户刚拖到的位置覆盖掉。用 m_seeking 标志位挡住回写;并且只在 sliderReleased 时真正 setPosition(),不要挂在 sliderMoved 上——拖动过程中每帧都 seek 会让解码器频繁重定位,声音会咔咔响。
4. 点击进度条只跳一小格。 QSlider 的默认行为是点击轨道移动一页。用 QStyle::sliderValueFromPosition 换算,别自己写比例公式——那个函数处理了垂直方向、RTL 布局和滑块宽度,自写版本在 RTL 语言下会左右颠倒。还要注意减去半个滑块宽度,否则点击位置整体偏右。
5. 自动切下一首时不灵,或者停了也切歌。 playbackStateChanged 到 StoppedState 不等于"播放完了",用户点停止、切歌、出错都会走到。判断自然播放结束的唯一正确时机是 mediaStatusChanged 到 EndOfMedia。另外 EndOfMedia 之后如果不主动 setSource() 或 play(),播放器会停在末尾。
6. 切歌时时长显示成上一首的。 duration() 不会因为换源立刻归零。切歌时手动把进度条范围重置(setRange(0, 0))并清空时间文字,等 durationChanged 再填上,否则会短暂显示错误的时长。
#还能怎么扩展
- QML 版本:把
QMediaPlayer包成一个QObject子类暴露给 QML(用Q_PROPERTY+Q_INVOKABLE,第五篇第 3 章),界面换成MediaPlayer+AudioOutput的 QML 类型,配合ProgressBar与Slider,几百行就能得到现代化的界面;C++ 的播放逻辑原样复用。 - 音频可视化:Qt 6 没有内置频谱接口,可以用
QAudioSink开一路输出旁路做 FFT,或者自己实现一个QAudioSink+QIODevice抓取 PCM 数据送 FFT(用kissfft或自己写基 2 的 FFT),用第四篇第 5 章的QPainter画柱状频谱。 - 歌词滚动:解析
.lrc文件得到时间轴,用positionChanged驱动QStandardItemModel高亮当前行,配合QFontMetrics做平滑滚动;这一步可以直接复用第六篇第 3 章的 Model/View 写法。 - 均衡器与音效:Qt 6 暂无内置 EQ,可以接入第三方(如
QAudioSink旁路 DSP),或者用QAudioOutput::setVolume做软件音量曲线(人对音量的感知是对数的,线性滑块调起来前半段几乎没变化,建议按v²或 dB 映射)。 - 媒体库:用 SQLite(第四篇第 7 章)存歌曲路径、时长、标签、播放次数,启动时批量读取,配合
QSortFilterProxyModel做按艺术家/专辑分类的浏览视图。
#小结
- Qt 6 里
QMediaPlayer必须显式挂一个QAudioOutput,音量属于输出设备而不是播放器;播放失败要连errorOccurred把原因显示给用户,并确认目标平台装了对应的多媒体后端插件。 - 所有操作都是异步的:时长、元数据、位置恢复都要等对应信号,绝不能"设置源后立刻操作"。
- 判断"播放结束"用
mediaStatusChanged的EndOfMedia,不要用StoppedState。 - 进度条要自己实现点击定位(
QStyle::sliderValueFromPosition),并在拖动期间用标志位阻止回写、松手才 seek。 - 封面元数据可能返回
QImage也可能返回QPixmap,取值前要用canConvert判断。
#练习
- 实现三种播放模式切换:加一个
QAction(循环切换顺序 / 单曲循环 / 随机),图标与提示文字跟着变,随机模式用QRandomGenerator::global()->bounded()取下一首;注意随机时不要连续抽到同一首。 - 加"添加到列表后自动排重并排序":用
QCollator(自然排序)对文件名排序,插入前用QSet<QString>判断重复。 - 实现拖拽添加:主窗口
setAcceptDrops(true),重写dragEnterEvent(检查mimeData()->hasUrls()且后缀是音频)与dropEvent(遍历urls()取toLocalFile()加入列表)。 - 加一个"音量曲线":把
QSlider的线性值 0–100 映射成感知音量(v/100的平方),并在状态栏显示百分比;同时给SeekSlider加键盘支持(左右键快退快进 5 秒)。