QC++ / Qt 学习之路

案例:音乐播放器

QMediaPlayer 播放列表、可拖动进度条、音量与播放状态机

实战第 47 / 48 章第六篇 · 案例实战

#这个案例做什么

写一个能日常听歌的桌面播放器:从本地添加音频文件形成播放列表,双击就能播;底部是播放控制条(上一首 / 播放暂停 / 下一首 / 进度条 / 音量),进度条既能显示进度也能拖着跳转、点哪跳哪;支持顺序播放、单曲循环、随机三种模式,切换上一首时如果当前播放超过 3 秒则跳回开头(和主流播放器一致的细节);读取 ID3 标签显示标题与艺术家,封面图有的话就显示出来;退出时记住音量、播放列表和上次听到第几秒,下次打开接着听。这个案例的核心是播放状态机——Qt 6 的多媒体 API 是完全异步的,几乎所有操作都要靠信号驱动。

音乐播放器 文件 编辑 播放 帮助 添加 删除 清空 搜索歌曲… 播放列表 6 首 01 起风了 05:24 02 平凡之路 04:58 03 夜空中最亮的星 04:05 04 晴天 04:29 05 海阔天空 05:12 06 蓝莲花 04:36 专辑封面 夜空中最亮的星 逃跑计划 专辑:世界 · 2023 01:23 / 04:05 音量 62% 随机播放 单曲循环 就绪 · 6 首 · 总时长 32:04 Qt Widgets · QMediaPlayer QListWidget 播放列表 QLabel 专辑封面 QSlider 播放进度 QPushButton 控制
播放器界面结构——左侧播放列表 + 右侧封面 / 底部控制条

功能清单:

  • 播放核心: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 章 元对象系统与信号槽

#项目结构

Text
musicplayer/
├── CMakeLists.txt
└── src/
    ├── main.cpp
    ├── seekslider.h
    ├── seekslider.cpp      # 支持点击定位的进度条
    ├── mainwindow.h
    └── mainwindow.cpp      # 播放器核心、列表、控制条、持久化
CMake
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:

C++
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():解码失败、文件不存在都会走这里,一定要处理,否则用户点了没反应却不知道为什么。
C++
// 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;      // 用户正在拖动进度条
};
C++
// 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 信号在拖动期间依然会到达,必须用标志位挡掉,否则进度条会像抽搐一样来回跳。

C++
// 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;
};
C++
// 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 的预览值):

C++
// 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() 只负责把它和列表、封面按垂直布局拼起来。这样做的好处是控制条的构造逻辑(图标、信号连接)与摆放位置解耦,后面想把它移到顶部或者做成浮动条,都不用改控制条本身。

C++
// 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 表示已消费——否则切歌时会把上一首的位置带到新歌上。

C++
// 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();
}
C++
// 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 判断。

#练习

  1. 实现三种播放模式切换:加一个 QAction(循环切换顺序 / 单曲循环 / 随机),图标与提示文字跟着变,随机模式用 QRandomGenerator::global()->bounded() 取下一首;注意随机时不要连续抽到同一首。
  2. 加"添加到列表后自动排重并排序":用 QCollator(自然排序)对文件名排序,插入前用 QSet<QString> 判断重复。
  3. 实现拖拽添加:主窗口 setAcceptDrops(true),重写 dragEnterEvent(检查 mimeData()->hasUrls() 且后缀是音频)与 dropEvent(遍历 urls() 取 toLocalFile() 加入列表)。
  4. 加一个"音量曲线":把 QSlider 的线性值 0–100 映射成感知音量(v/100 的平方),并在状态栏显示百分比;同时给 SeekSlider 加键盘支持(左右键快退快进 5 秒)。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。