【从零开始的Qt开发指南】（二十二）Qt 音视频开发宝典：从音频播放到视频播放器的实战全攻略

_OP_CHEN2026-01-15 14:05

目录

​编辑

前言

[一、Qt 音视频开发核心认知](#一、Qt 音视频开发核心认知)

[1.1 为什么选择 Qt 音视频 API？](#1.1 为什么选择 Qt 音视频 API？)

[1.2 核心准备工作](#1.2 核心准备工作)

[1.3 关键概念澄清](#1.3 关键概念澄清)

[二、Qt 音频开发：从简单音效到高级播放](#二、Qt 音频开发：从简单音效到高级播放)

[2.1 QSound：轻量级音频播放（仅支持 WAV）](#2.1 QSound：轻量级音频播放（仅支持 WAV）)

[2.1.1 核心 API 解析](#2.1.1 核心 API 解析)

[2.1.2 实战案例：按钮点击音效播放](#2.1.2 实战案例：按钮点击音效播放)

[步骤 1：创建项目与配置](#步骤 1：创建项目与配置)

[步骤 2：准备音频资源](#步骤 2：准备音频资源)

[步骤 3：UI 设计](#步骤 3：UI 设计)

[步骤 4：代码实现](#步骤 4：代码实现)

头文件（widget.h）

源文件（widget.cpp）

[步骤 5：运行效果](#步骤 5：运行效果)

关键说明

[2.2 QMediaPlayer：高级音频播放（支持多格式）](#2.2 QMediaPlayer：高级音频播放（支持多格式）)

[2.2.1 核心 API 解析](#2.2.1 核心 API 解析)

[2.2.2 实战案例：多功能音频播放器](#2.2.2 实战案例：多功能音频播放器)

[步骤 1：项目配置](#步骤 1：项目配置)

[步骤 2：UI 设计](#步骤 2：UI 设计)

[步骤 3：代码实现](#步骤 3：代码实现)

头文件（widget.h）

源文件（widget.cpp）

[步骤 4：运行效果](#步骤 4：运行效果)

关键说明

[三、Qt 视频开发：构建完整视频播放器](#三、Qt 视频开发：构建完整视频播放器)

[3.1 核心 API 与类分工](#3.1 核心 API 与类分工)

[3.1.1 核心类分工](#3.1.1 核心类分工)

[3.1.2 核心API 补充（视频相关）](#3.1.2 核心API 补充（视频相关）)

[3.2 实战案例：完整视频播放器](#3.2 实战案例：完整视频播放器)

[步骤 1：项目配置](#步骤 1：项目配置)

[步骤 2：UI 设计](#步骤 2：UI 设计)

[步骤 3：代码实现](#步骤 3：代码实现)

头文件（widget.h）

源文件（widget.cpp）

[步骤 4：运行效果](#步骤 4：运行效果)

关键说明

[四、Qt 音视频开发常见问题与避坑指南](#四、Qt 音视频开发常见问题与避坑指南)

[4.1 音频 / 视频无法播放](#4.1 音频 / 视频无法播放)

[4.2 界面卡顿](#4.2 界面卡顿)

[4.3 音频 / 视频不同步](#4.3 音频 / 视频不同步)

[4.4 全屏切换异常](#4.4 全屏切换异常)

[4.5 资源释放问题](#4.5 资源释放问题)

总结

前言

在 Qt 开发生态中，音视频功能是构建富交互应用的重要组成部分 ------ 无论是简单的音效反馈、背景音乐播放，还是复杂的视频播放器、多媒体展示系统，Qt 都提供了简洁高效的解决方案。Qt 通过QSound、QMediaPlayer、QVideoWidget等封装类，屏蔽了不同操作系统底层音视频 API 的差异，让开发者仅凭一套代码就能实现跨平台的音视频播放功能。本文将聚焦 Qt 音视频开发的两大核心场景（音频播放、视频播放），从基础 API 解析到实战，手把手带你吃透 Qt 音视频开发，轻松应对各类多媒体应用需求！下面就让我们正式开始吧！

一、Qt 音视频开发核心认知

1.1 为什么选择 Qt 音视频 API？

传统音视频开发面临三大痛点：

  • 跨平台兼容性差：Windows 的 DirectShow、Linux 的 ALSA、macOS 的 Core Audio 接口差异巨大，需大量条件编译适配；
  • 开发门槛高：需手动处理音频解码、视频渲染、格式兼容等底层细节；
  • 集成难度大：难以与 Qt UI 框架无缝衔接，容易出现线程阻塞、界面卡顿等问题。

而 Qt 音视频 API 完美解决了这些问题：

  • 跨平台统一：一套代码适配 Windows、Linux、macOS 等主流系统，Qt 自动处理底层音视频驱动差异；
  • API 简洁易用 ：通过高层封装类（如QSound、QMediaPlayer）屏蔽复杂细节，几行代码即可实现音视频播放；
  • 无缝集成 Qt 生态：支持信号槽机制，可轻松与 UI 组件联动（如播放按钮、进度条），避免界面卡顿；
  • 格式支持全面：支持主流音视频格式（WAV、MP3、WMV、MP4 等），无需手动集成第三方解码库。

1.2 核心准备工作

在进行 Qt 音视频开发前，需完成两个关键配置：

  1. 添加多媒体模块 ：Qt 音视频功能依赖**multimedia和multimediawidgets**模块（视频播放需后者），需在项目的.pro文件中添加对应的模块：

    cpp 复制代码 
    // 音频播放仅需添加multimedia
QT += core gui multimedia
// 视频播放需同时添加multimedia和multimediawidgets
QT += core gui multimedia multimediawidgets

  2. 了解核心类关系 ：Qt 音视频模块的核心类围绕 "播放控制" 和 "渲染输出" 设计，关键类如下：

    • 音频相关 ：QSound（简单音频播放）、QMediaPlayer（高级音频播放）；
    • 视频相关 ：QMediaPlayer（音视频播放控制）、QVideoWidget（视频渲染窗口）；
    • 辅助类 ：QFileDialog（文件选择）、QVBoxLayout/QHBoxLayout（界面布局）、QPushButton（控制按钮）。

1.3 关键概念澄清

  • 音频格式限制 ：QSound类仅支持 WAV 格式音频，若需播放 MP3 等其他格式，需使用QMediaPlayer；
  • 视频渲染依赖 ：QVideoWidget是 Qt 提供的默认视频渲染组件，需依赖multimediawidgets模块；
  • 非阻塞播放：Qt 音视频播放默认采用非阻塞模式，不会阻塞 UI 线程，确保界面流畅响应；
  • 资源路径：播放本地音视频文件时，需指定正确的文件路径（绝对路径或 Qt 资源文件路径）。

二、Qt 音频开发：从简单音效到高级播放

Qt 提供了两种音频播放方案：QSound（适合简单音效播放）和**QMediaPlayer**（适合复杂音频控制）。下面分别详解其使用方法和实战案例。

2.1 QSound：轻量级音频播放（仅支持 WAV）

QSound是 Qt 中最简洁的音频播放类，适用于播放短音效（如按钮点击音效、提示音），核心优势是使用简单、无额外依赖，但仅支持 WAV 格式音频文件。

2.1.1 核心 API 解析

API 函数 功能说明 关键细节
*QSound(const QString &filename, QObject parent = nullptr) 构造函数：传入 WAV 文件路径（本地路径或资源路径） 路径错误会导致播放失败，无报错提示
void play() 开始播放音频，若已在播放则继续播放 支持重复播放，多次调用play()会叠加播放
void stop() 停止播放音频 停止后再次调用play()会从头开始播放
bool isFinished() const 判断音频是否播放完毕 仅对单次播放有效，循环播放时始终返回false

2.1.2 实战案例：按钮点击音效播放

实现功能：点击按钮时播放指定的 WAV 格式音效，支持重复点击重复播放。

步骤 1：创建项目与配置

  • 新建 Qt Widgets Application 项目，基类选择QWidget；

  • 在.pro文件中添加multimedia模块：

    复制代码 
    QT += core gui multimedia
步骤 2：准备音频资源
  • 将 WAV 格式音频文件（如click.wav）复制到项目目录下；
  • （可选）将音频文件添加到 Qt 资源文件（.qrc）中，方便项目打包：
    1. 右键项目 → Add New → Qt → Qt Resource File，创建res.qrc；
    2. 打开res.qrc，添加前缀（如/audio），然后添加文件，选择本地的click.wav。
步骤 3：UI 设计
  • 打开widget.ui，拖入一个QPushButton（命名为btn，文本改为 "播放音效"）；
  • 布局：将按钮居中显示，设置按钮大小为150x50，字体大小为 14px。
步骤 4：代码实现
头文件（widget.h）
cpp 复制代码 
#ifndef WIDGET_H
#define WIDGET_H

#include <QWidget>
#include <QSound>  // 音频播放头文件
#include <QDebug>

QT_BEGIN_NAMESPACE
namespace Ui { class Widget; }
QT_END_NAMESPACE

class Widget : public QWidget
{
    Q_OBJECT

public:
    Widget(QWidget *parent = nullptr);
    ~Widget();

private slots:
    // 按钮点击槽函数
    void on_btn_clicked();

private:
    Ui::Widget *ui;
    QSound *sound;  // 音频对象指针
};

#endif // WIDGET_H
源文件（widget.cpp）
cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);
    this->setWindowTitle("Qt音频播放示例（QSound）");
    this->resize(400, 300);

    // 初始化音频对象（两种路径方式二选一）
    // 方式1：本地文件路径（相对路径，音频文件需在项目构建目录下）
    // sound = new QSound("click.wav", this);
    // 方式2：资源文件路径（推荐，打包后无需担心路径问题）
    sound = new QSound(":/audio/click.wav", this);

    // 设置按钮样式
    ui->btn->setStyleSheet("QPushButton { font-size: 14px; }");
}

Widget::~Widget()
{
    delete ui;
}

void Widget::on_btn_clicked()
{
    if (sound)
    {
        // 播放音频
        sound->play();
        qDebug() << "音效播放中...";
    }
    else
    {
        qDebug() << "音频对象初始化失败！";
    }
}
步骤 5：运行效果
  • 点击 "播放音效" 按钮，即可播放指定的 WAV 音效；
  • 多次点击按钮，音效会重复播放（支持叠加）；
  • 控制台输出 "音效播放中..."，提示播放状态。

关键说明

  • 路径问题：若使用本地文件路径，需确保音频文件在项目的构建目录下（而非源码目录），否则会因路径错误导致播放失败；
  • 格式限制 ：QSound仅支持 WAV 格式，若需播放 MP3 等其他格式，需使用QMediaPlayer；
  • 资源文件：推荐使用 Qt 资源文件管理音频资源，避免打包后路径失效。

2.2 QMediaPlayer：高级音频播放（支持多格式）

QMediaPlayer是 Qt 提供的高级音视频播放类，支持更多音频格式（WAV、MP3、AAC 等），提供更丰富的控制功能（暂停、音量调节、进度控制等），适用于复杂音频播放场景（如背景音乐、音频播放器）。

2.2.1 核心 API 解析

API 函数 / 信号 功能说明 关键细节
void setMedia(const QMediaContent &media) 设置音频文件（本地文件或网络音频） 支持QUrl路径（本地路径需加file://前缀）
void play() 开始播放 播放前需确保setMedia已设置有效音频
void pause() 暂停播放 暂停后调用play()可继续播放
void stop() 停止播放 停止后调用play()会从头开始播放
void setVolume(int volume) 设置音量（0-100） 默认音量为 100，0 表示静音
int volume() const 获取当前音量 返回值范围 0-100
void setPosition(qint64 position) 设置播放进度（毫秒） 需在play()后调用才有效
qint64 position() const 获取当前播放进度（毫秒） 配合定时器可实现进度条更新
qint64 duration() const 获取音频总时长（毫秒） 音频加载完成后才会返回有效值
void mediaStatusChanged(QMediaPlayer::MediaStatus status) 信号：媒体状态变化 可监听音频是否加载完成（QMediaPlayer::LoadedMedia）
void stateChanged(QMediaPlayer::State state) 信号：播放状态变化 状态包括StoppedState（停止）、PlayingState（播放）、PausedState（暂停）
void positionChanged(qint64 position) 信号：播放进度变化 实时返回当前播放位置（毫秒）
void durationChanged(qint64 duration) 信号：总时长变化 音频加载完成后触发，返回总时长

2.2.2 实战案例：多功能音频播放器

实现功能：支持选择本地音频文件（MP3/WAV）、播放 / 暂停 / 停止控制、音量调节、进度条显示与拖动。

步骤 1：项目配置

在.pro文件中添加**multimedia**模块：

复制代码 
QT += core gui multimedia
步骤 2：UI 设计

打开widget.ui，添加以下控件：

  • QPushButton（3 个） ：命名为btnSelect（文本 "选择音频"）、btnPlay（文本 "播放"）、btnStop（文本 "停止"）；
  • QSlider（2 个） ：命名为sliderVolume（音量调节）、sliderProgress（进度调节）；
  • QLabel（2 个） ：命名为labVolume（文本 "音量"）、labProgress（文本 "00:00 / 00:00"）；
  • 布局 ：
    1. 顶部：btnSelect、btnPlay、btnStop 水平布局；
    2. 中间：labVolume与sliderVolume 水平布局，labProgress与sliderProgress 垂直布局；
    3. 整体：垂直布局，控件间距设置为 10px。
步骤 3：代码实现
头文件（widget.h）
cpp 复制代码 
#ifndef WIDGET_H
#define WIDGET_H

#include <QWidget>
#include <QMediaPlayer>  // 高级音频播放头文件
#include <QMediaContent>
#include <QFileDialog>
#include <QTimer>
#include <QTime>
#include <QDebug>

QT_BEGIN_NAMESPACE
namespace Ui { class Widget; }
QT_END_NAMESPACE

class Widget : public QWidget
{
    Q_OBJECT

public:
    Widget(QWidget *parent = nullptr);
    ~Widget();

private slots:
    // 选择音频文件
    void on_btnSelect_clicked();
    // 播放/暂停按钮
    void on_btnPlay_clicked();
    // 停止按钮
    void on_btnStop_clicked();
    // 音量调节
    void on_sliderVolume_valueChanged(int value);
    // 进度条拖动（释放时设置进度）
    void on_sliderProgress_sliderReleased();
    // 媒体状态变化
    void onMediaStatusChanged(QMediaPlayer::MediaStatus status);
    // 播放状态变化
    void onStateChanged(QMediaPlayer::State state);
    // 播放进度更新
    void onPositionChanged(qint64 position);
    // 总时长更新
    void onDurationChanged(qint64 duration);

private:
    Ui::Widget *ui;
    QMediaPlayer *player;  // 音频播放器对象
    QString currentAudioPath;  // 当前选中的音频文件路径
    bool isPlaying;  // 播放状态标记
};

#endif // WIDGET_H
源文件（widget.cpp）
cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
    , isPlaying(false)
{
    ui->setupUi(this);
    this->setWindowTitle("Qt高级音频播放器（QMediaPlayer）");
    this->resize(600, 200);

    // 初始化音频播放器
    player = new QMediaPlayer(this);

    // 初始化控件
    ui->sliderVolume->setRange(0, 100);  // 音量范围0-100
    ui->sliderVolume->setValue(80);       // 默认音量80
    ui->sliderProgress->setRange(0, 0);  // 进度条初始范围0-0（无音频时）
    ui->btnPlay->setEnabled(false);       // 未选择音频时，播放按钮禁用
    ui->btnStop->setEnabled(false);       // 未选择音频时，停止按钮禁用

    // 设置控件样式
    ui->btnSelect->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; }");
    ui->btnPlay->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; }");
    ui->btnStop->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; }");
    ui->labProgress->setStyleSheet("QLabel { font-size: 12px; }");
    ui->labVolume->setStyleSheet("QLabel { font-size: 12px; }");

    // 连接信号槽
    connect(player, &QMediaPlayer::mediaStatusChanged, this, &Widget::onMediaStatusChanged);
    connect(player, &QMediaPlayer::stateChanged, this, &Widget::onStateChanged);
    connect(player, &QMediaPlayer::positionChanged, this, &Widget::onPositionChanged);
    connect(player, &QMediaPlayer::durationChanged, this, &Widget::onDurationChanged);
}

Widget::~Widget()
{
    delete ui;
}

// 选择音频文件
void Widget::on_btnSelect_clicked()
{
    // 弹出文件选择对话框，过滤音频文件
    QString filePath = QFileDialog::getOpenFileName(
        this,
        "选择音频文件",
        QCoreApplication::applicationDirPath(),
        "音频文件 (*.wav *.mp3 *.aac *.flac)"
    );

    if (!filePath.isEmpty())
    {
        currentAudioPath = filePath;
        // 设置音频文件（QUrl需加file://前缀）
        player->setMedia(QMediaContent(QUrl::fromLocalFile(filePath)));
        // 启用播放和停止按钮
        ui->btnPlay->setEnabled(true);
        ui->btnStop->setEnabled(true);
        // 更新标签显示文件名
        QString fileName = filePath.split("/").last();
        this->setWindowTitle(QString("Qt高级音频播放器 - %1").arg(fileName));
        qDebug() << "选中音频文件：" << filePath;
    }
}

// 播放/暂停按钮
void Widget::on_btnPlay_clicked()
{
    if (currentAudioPath.isEmpty())
        return;

    if (isPlaying)
    {
        // 暂停播放
        player->pause();
        ui->btnPlay->setText("播放");
    }
    else
    {
        // 开始播放
        player->play();
        ui->btnPlay->setText("暂停");
    }
    isPlaying = !isPlaying;
}

// 停止按钮
void Widget::on_btnStop_clicked()
{
    player->stop();
    ui->btnPlay->setText("播放");
    ui->sliderProgress->setValue(0);
    ui->labProgress->setText("00:00 / 00:00");
    isPlaying = false;
}

// 音量调节
void Widget::on_sliderVolume_valueChanged(int value)
{
    player->setVolume(value);
    qDebug() << "当前音量：" << value;
}

// 进度条拖动（释放时设置进度）
void Widget::on_sliderProgress_sliderReleased()
{
    if (player->duration() > 0)
    {
        // 获取拖动后的进度值（毫秒）
        qint64 newPosition = ui->sliderProgress->value();
        // 设置播放进度
        player->setPosition(newPosition);
        qDebug() << "设置播放进度：" << newPosition << "毫秒";
    }
}

// 媒体状态变化（监听音频是否加载完成）
void Widget::onMediaStatusChanged(QMediaPlayer::MediaStatus status)
{
    if (status == QMediaPlayer::LoadedMedia)
    {
        qDebug() << "音频加载完成，总时长：" << player->duration() << "毫秒";
    }
    else if (status == QMediaPlayer::InvalidMedia)
    {
        qDebug() << "音频文件无效或格式不支持！";
        QMessageBox::warning(this, "警告", "音频文件无效或格式不支持！");
    }
}

// 播放状态变化
void Widget::onStateChanged(QMediaPlayer::State state)
{
    switch (state)
    {
    case QMediaPlayer::StoppedState:
        qDebug() << "播放停止";
        break;
    case QMediaPlayer::PlayingState:
        qDebug() << "正在播放";
        break;
    case QMediaPlayer::PausedState:
        qDebug() << "播放暂停";
        break;
    default:
        break;
    }
}

// 播放进度更新（实时更新进度条和标签）
void Widget::onPositionChanged(qint64 position)
{
    if (player->duration() > 0)
    {
        // 更新进度条
        ui->sliderProgress->setValue(position);
        // 转换进度为分:秒格式
        QTime currentTime = QTime::fromMSecsSinceStartOfDay(position);
        QTime totalTime = QTime::fromMSecsSinceStartOfDay(player->duration());
        QString progressText = QString("%1:%2 / %3:%4")
                              .arg(currentTime.minute(), 2, 10, QChar('0'))
                              .arg(currentTime.second(), 2, 10, QChar('0'))
                              .arg(totalTime.minute(), 2, 10, QChar('0'))
                              .arg(totalTime.second(), 2, 10, QChar('0'));
        // 更新进度标签
        ui->labProgress->setText(progressText);
    }
}

// 总时长更新（设置进度条最大值）
void Widget::onDurationChanged(qint64 duration)
{
    if (duration > 0)
    {
        ui->sliderProgress->setRange(0, duration);
    }
}
步骤 4：运行效果
  • 点击 "选择音频" 按钮，选择本地的 MP3 或 WAV 文件；
  • 点击 "播放" 按钮，音频开始播放，进度条实时更新，标签显示当前进度 / 总时长；
  • 拖动进度条可调整播放进度，释放鼠标后跳转到对应位置；
  • 拖动音量滑块可调节音量，范围 0-100；
  • 点击 "暂停" 按钮可暂停播放，再次点击继续播放；
  • 点击 "停止" 按钮，播放停止，进度条重置为 0。

关键说明

  • 格式支持 ：QMediaPlayer支持 MP3、WAV、AAC、FLAC 等主流音频格式，无需额外解码库；
  • 路径处理 ：使用QUrl::fromLocalFile(filePath)将本地路径转换为 Qt 支持的QMediaContent格式；
  • 进度更新 ：通过positionChanged信号实时更新进度条，避免手动轮询；
  • 状态监听 ：通过mediaStatusChanged信号监听音频加载状态，处理无效文件场景。

三、Qt 视频开发：构建完整视频播放器

Qt 视频播放基于**QMediaPlayer（音视频控制）和QVideoWidget**（视频渲染），支持本地视频文件播放、视频渲染、播放控制等功能，适用于构建简单视频播放器、多媒体展示系统等场景。

3.1 核心 API 与类分工

3.1.1 核心类分工

  • QMediaPlayer：核心控制类，负责视频文件加载、播放 / 暂停 / 停止控制、音量调节、进度控制等；
  • QVideoWidget：视频渲染类，提供视频播放窗口，支持设置播放尺寸、全屏显示等；
  • 辅助控件 ：QPushButton（控制按钮）、QSlider（进度 / 音量调节）、QFileDialog（文件选择）。

3.1.2 核心API 补充（视频相关）

类 API 函数 功能说明
QMediaPlayer *void setVideoOutput(QVideoWidget output) 将视频输出绑定到QVideoWidget，实现视频渲染
QVideoWidget void setMinimumSize(const QSize &size) 设置视频播放窗口最小尺寸
QVideoWidget void setFullScreen(bool fullScreen) 设置全屏播放（true为全屏，false为窗口模式）
QVideoWidget bool isFullScreen() const 判断是否为全屏模式
QVideoWidget *void keyPressEvent(QKeyEvent event) 重写按键事件，支持 ESC 退出全屏

3.2 实战案例：完整视频播放器

实现功能：支持选择本地视频文件（WMV、MP4 等）、播放 / 暂停 / 停止控制、音量调节、进度控制、全屏播放。

步骤 1：项目配置

在.pro文件中添加**multimedia和multimediawidgets**模块：

cpp 复制代码 
QT += core gui multimedia multimediawidgets

步骤 2：UI 设计

打开widget.ui，设计如下界面：

  • 视频渲染区 ：QVideoWidget（命名为videoWidget），作为视频播放窗口；
  • 控制区 ：
    1. QPushButton（3 个）：btnSelect（选择视频）、btnPlay（播放 / 暂停）、btnStop（停止）、btnFullScreen（全屏）；
    2. QSlider（2 个）：sliderVolume（音量调节）、sliderProgress（进度调节）；
    3. QLabel（2 个）：labVolume（音量）、labProgress（进度显示）；
  • 布局 ：
    1. 顶部：videoWidget 占满大部分区域，设置最小尺寸600x400；
    2. 底部：控制按钮、音量调节、进度条、进度标签 水平布局，间距 10px；
    3. 整体：垂直布局，videoWidget与控制区上下排列。

步骤 3：代码实现

头文件（widget.h）
cpp 复制代码 
#ifndef WIDGET_H
#define WIDGET_H

#include <QWidget>
#include <QMediaPlayer>
#include <QMediaContent>
#include <QVideoWidget>
#include <QFileDialog>
#include <QTimer>
#include <QTime>
#include <QKeyEvent>
#include <QDebug>
#include <QMessageBox>

QT_BEGIN_NAMESPACE
namespace Ui { class Widget; }
QT_END_NAMESPACE

class Widget : public QWidget
{
    Q_OBJECT

public:
    Widget(QWidget *parent = nullptr);
    ~Widget();

protected:
    // 重写按键事件，支持ESC退出全屏
    void keyPressEvent(QKeyEvent *event) override;

private slots:
    // 选择视频文件
    void on_btnSelect_clicked();
    // 播放/暂停按钮
    void on_btnPlay_clicked();
    // 停止按钮
    void on_btnStop_clicked();
    // 全屏按钮
    void on_btnFullScreen_clicked();
    // 音量调节
    void on_sliderVolume_valueChanged(int value);
    // 进度条拖动（释放时设置进度）
    void on_sliderProgress_sliderReleased();
    // 媒体状态变化
    void onMediaStatusChanged(QMediaPlayer::MediaStatus status);
    // 播放状态变化
    void onStateChanged(QMediaPlayer::State state);
    // 播放进度更新
    void onPositionChanged(qint64 position);
    // 总时长更新
    void onDurationChanged(qint64 duration);
    // 全屏状态变化
    void onFullScreenChanged(bool isFullScreen);

private:
    Ui::Widget *ui;
    QMediaPlayer *player;          // 音视频播放器对象
    QString currentVideoPath;      // 当前选中的视频文件路径
    bool isPlaying;                // 播放状态标记
    bool isFullScreen;             // 全屏状态标记
};

#endif // WIDGET_H
源文件（widget.cpp）
cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
    , isPlaying(false)
    , isFullScreen(false)
{
    ui->setupUi(this);
    this->setWindowTitle("Qt视频播放器");
    this->resize(800, 600);

    // 初始化音视频播放器
    player = new QMediaPlayer(this);
    // 将视频输出绑定到QVideoWidget
    player->setVideoOutput(ui->videoWidget);

    // 初始化控件
    ui->videoWidget->setMinimumSize(600, 400);  // 视频窗口最小尺寸
    ui->sliderVolume->setRange(0, 100);        // 音量范围0-100
    ui->sliderVolume->setValue(80);             // 默认音量80
    ui->sliderProgress->setRange(0, 0);         // 进度条初始范围0-0
    // 禁用未选择视频时的控制按钮
    ui->btnPlay->setEnabled(false);
    ui->btnStop->setEnabled(false);
    ui->btnFullScreen->setEnabled(false);

    // 设置控件样式
    ui->btnSelect->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; margin: 0 5px; }");
    ui->btnPlay->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; margin: 0 5px; }");
    ui->btnStop->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; margin: 0 5px; }");
    ui->btnFullScreen->setStyleSheet("QPushButton { font-size: 12px; padding: 5px 10px; margin: 0 5px; }");
    ui->labProgress->setStyleSheet("QLabel { font-size: 12px; margin: 0 10px; }");
    ui->labVolume->setStyleSheet("QLabel { font-size: 12px; margin: 0 10px; }");
    ui->sliderVolume->setFixedWidth(100);        // 音量滑块宽度
    ui->videoWidget->setStyleSheet("background-color: black;");  // 视频窗口默认黑色背景

    // 连接信号槽
    connect(player, &QMediaPlayer::mediaStatusChanged, this, &Widget::onMediaStatusChanged);
    connect(player, &QMediaPlayer::stateChanged, this, &Widget::onStateChanged);
    connect(player, &QMediaPlayer::positionChanged, this, &Widget::onPositionChanged);
    connect(player, &QMediaPlayer::durationChanged, this, &Widget::onDurationChanged);
    // 监听全屏状态变化（Qt 5.14+支持）
    connect(ui->videoWidget, &QVideoWidget::fullScreenChanged, this, &Widget::onFullScreenChanged);
}

Widget::~Widget()
{
    delete ui;
}

// 重写按键事件：ESC退出全屏
void Widget::keyPressEvent(QKeyEvent *event)
{
    if (event->key() == Qt::Key_Escape && isFullScreen)
    {
        ui->videoWidget->setFullScreen(false);
    }
    QWidget::keyPressEvent(event);
}

// 选择视频文件
void Widget::on_btnSelect_clicked()
{
    // 弹出文件选择对话框，过滤视频文件
    QString filePath = QFileDialog::getOpenFileName(
        this,
        "选择视频文件",
        QCoreApplication::applicationDirPath(),
        "视频文件 (*.wmv *.mp4 *.avi *.mov *.mkv)"
    );

    if (!filePath.isEmpty())
    {
        currentVideoPath = filePath;
        // 设置视频文件
        player->setMedia(QMediaContent(QUrl::fromLocalFile(filePath)));
        // 启用控制按钮
        ui->btnPlay->setEnabled(true);
        ui->btnStop->setEnabled(true);
        ui->btnFullScreen->setEnabled(true);
        // 更新窗口标题为文件名
        QString fileName = filePath.split("/").last();
        this->setWindowTitle(QString("Qt视频播放器 - %1").arg(fileName));
        qDebug() << "选中视频文件：" << filePath;
    }
}

// 播放/暂停按钮
void Widget::on_btnPlay_clicked()
{
    if (currentVideoPath.isEmpty())
        return;

    if (isPlaying)
    {
        // 暂停播放
        player->pause();
        ui->btnPlay->setText("播放");
    }
    else
    {
        // 开始播放
        player->play();
        ui->btnPlay->setText("暂停");
    }
    isPlaying = !isPlaying;
}

// 停止按钮
void Widget::on_btnStop_clicked()
{
    player->stop();
    ui->btnPlay->setText("播放");
    ui->sliderProgress->setValue(0);
    ui->labProgress->setText("00:00:00 / 00:00:00");
    isPlaying = false;
}

// 全屏按钮
void Widget::on_btnFullScreen_clicked()
{
    isFullScreen = !isFullScreen;
    ui->videoWidget->setFullScreen(isFullScreen);
}

// 音量调节
void Widget::on_sliderVolume_valueChanged(int value)
{
    player->setVolume(value);
    qDebug() << "当前音量：" << value;
}

// 进度条拖动（释放时设置进度）
void Widget::on_sliderProgress_sliderReleased()
{
    if (player->duration() > 0)
    {
        qint64 newPosition = ui->sliderProgress->value();
        player->setPosition(newPosition);
        qDebug() << "设置播放进度：" << newPosition << "毫秒";
    }
}

// 媒体状态变化
void Widget::onMediaStatusChanged(QMediaPlayer::MediaStatus status)
{
    if (status == QMediaPlayer::LoadedMedia)
    {
        qDebug() << "视频加载完成，总时长：" << player->duration() << "毫秒";
    }
    else if (status == QMediaPlayer::InvalidMedia)
    {
        qDebug() << "视频文件无效或格式不支持！";
        QMessageBox::warning(this, "警告", "视频文件无效或格式不支持！");
        // 禁用控制按钮
        ui->btnPlay->setEnabled(false);
        ui->btnStop->setEnabled(false);
        ui->btnFullScreen->setEnabled(false);
    }
}

// 播放状态变化
void Widget::onStateChanged(QMediaPlayer::State state)
{
    switch (state)
    {
    case QMediaPlayer::StoppedState:
        qDebug() << "播放停止";
        break;
    case QMediaPlayer::PlayingState:
        qDebug() << "正在播放";
        break;
    case QMediaPlayer::PausedState:
        qDebug() << "播放暂停";
        break;
    default:
        break;
    }
}

// 播放进度更新
void Widget::onPositionChanged(qint64 position)
{
    if (player->duration() > 0)
    {
        // 更新进度条
        ui->sliderProgress->setValue(position);
        // 转换进度为 时:分:秒 格式
        QTime currentTime = QTime::fromMSecsSinceStartOfDay(position);
        QTime totalTime = QTime::fromMSecsSinceStartOfDay(player->duration());
        QString progressText = QString("%1:%2:%3 / %4:%5:%6")
                              .arg(currentTime.hour(), 2, 10, QChar('0'))
                              .arg(currentTime.minute(), 2, 10, QChar('0'))
                              .arg(currentTime.second(), 2, 10, QChar('0'))
                              .arg(totalTime.hour(), 2, 10, QChar('0'))
                              .arg(totalTime.minute(), 2, 10, QChar('0'))
                              .arg(totalTime.second(), 2, 10, QChar('0'));
        // 更新进度标签
        ui->labProgress->setText(progressText);
    }
}

// 总时长更新
void Widget::onDurationChanged(qint64 duration)
{
    if (duration > 0)
    {
        ui->sliderProgress->setRange(0, duration);
        // 初始化进度标签
        QTime totalTime = QTime::fromMSecsSinceStartOfDay(duration);
        QString progressText = QString("00:00:00 / %1:%2:%3")
                              .arg(totalTime.hour(), 2, 10, QChar('0'))
                              .arg(totalTime.minute(), 2, 10, QChar('0'))
                              .arg(totalTime.second(), 2, 10, QChar('0'));
        ui->labProgress->setText(progressText);
    }
}

// 全屏状态变化
void Widget::onFullScreenChanged(bool isFullScreen)
{
    this->isFullScreen = isFullScreen;
    if (isFullScreen)
    {
        ui->btnFullScreen->setText("退出全屏");
        // 隐藏控制区外的其他控件（可选）
        ui->labVolume->hide();
        ui->sliderVolume->hide();
    }
    else
    {
        ui->btnFullScreen->setText("全屏播放");
        // 显示隐藏的控件
        ui->labVolume->show();
        ui->sliderVolume->show();
    }
}

步骤 4：运行效果

  • 点击 "选择视频" 按钮，选择本地的 WMV、MP4、AVI 等视频文件；
  • 点击 "播放" 按钮，视频在videoWidget中开始播放，音频同步输出，进度条实时更新；
  • 拖动进度条可调整播放进度，释放鼠标后跳转到对应位置；
  • 拖动音量滑块可调节音量，范围 0-100；
  • 点击 "暂停" 按钮可暂停播放，再次点击继续播放；
  • 点击 "停止" 按钮，播放停止，进度条重置为 0；
  • 点击 "全屏播放" 按钮，视频进入全屏模式，控制区部分控件隐藏，ESC 键可退出全屏。

关键说明

  • 视频格式支持 ：QMediaPlayer+QVideoWidget支持 WMV、MP4、AVI、MOV、MKV 等主流视频格式，若遇到不支持的格式，可能需要安装额外的解码器（如 LAV Filters）；
  • 全屏控制 ：通过QVideoWidget::setFullScreen()实现全屏切换，重写keyPressEvent支持 ESC 退出全屏；
  • 视频窗口样式 ：默认视频窗口为黑色背景，可通过setStyleSheet设置边框、背景色等；
  • 性能优化：Qt 视频播放默认采用硬件加速（若系统支持），避免卡顿，适合播放高清视频。

四、Qt 音视频开发常见问题与避坑指南

4.1 音频 / 视频无法播放

常见原因与解决方案：

  1. 模块未添加 ：忘记在.pro文件中添加multimedia（音频）或multimediawidgets（视频）模块，需重新添加并重新编译；
  2. 文件路径错误：路径中包含中文或特殊字符，或文件未在指定路径下，建议使用绝对路径或 Qt 资源文件；
  3. 格式不支持 ：QSound仅支持 WAV 格式，若播放 MP3 需使用QMediaPlayer；视频格式不支持时，需安装对应解码器；
  4. 文件损坏：音频 / 视频文件本身损坏，可尝试用其他播放器验证文件完整性。

4.2 界面卡顿

问题：播放音视频时，UI 界面响应缓慢、拖动窗口卡顿。

解决方案：

  • 避免在 UI 线程中执行耗时操作（如文件解析、大数据处理）；
  • 确保音视频播放采用非阻塞模式（Qt 默认），不调用waitForFinished()等阻塞函数；
  • 减少进度更新频率，避免positionChanged信号触发过于频繁（可通过定时器节流）。

4.3 音频 / 视频不同步

问题：视频播放进度与音频不一致。

解决方案：

  • 确保使用QMediaPlayer同时控制音视频，避免分开控制音频和视频；
  • 检查视频文件本身是否存在音视频不同步问题（用其他播放器验证）；
  • 避免在positionChanged信号中执行复杂逻辑，确保进度更新及时。

4.4 全屏切换异常

问题：点击全屏按钮后，视频窗口未铺满屏幕或控件显示异常。

解决方案：

  • 确保QVideoWidget的布局设置正确，未被其他控件遮挡；
  • 全屏切换时隐藏不必要的控件，避免布局错乱；
  • 重写resizeEvent函数，处理窗口大小变化时的视频窗口适配。

4.5 资源释放问题

问题：频繁切换音视频文件后，内存占用持续增加。

解决方案：

  • 切换文件前，调用player->stop()停止当前播放；
  • 切换文件时，设置player->setMedia(QMediaContent())清空当前媒体；
  • 避免重复创建QMediaPlayer对象，一个应用程序建议共用一个实例。

总结

掌握 Qt 音视频开发，能让你轻松应对各类多媒体应用场景（如播放器、教育软件、多媒体展示系统）。建议多动手实践，结合实际项目需求灵活运用相关 API，遇到问题时查阅 Qt 官方文档或调试工具排查。如果你有任何问题或需要进一步探讨高级功能，欢迎在评论区留言交流！

相关推荐
FAFU_kyp2 小时前
Rust 字符串与切片
开发语言·后端·rust
oioihoii2 小时前
从C++到C#的转型完全指南
开发语言·c++·c#
Ashley_Amanda2 小时前
Python入门知识点梳理
开发语言·windows·python
区区一散修2 小时前
Java进阶 6. 集合
java·开发语言
学嵌入式的小杨同学2 小时前
C 语言实战：动态规划求解最长公共子串（连续），附完整实现与优化
数据结构·c++·算法·unity·游戏引擎·代理模式
-凌凌漆-2 小时前
【JS】JavaScript Promise
开发语言·javascript·ecmascript
羊村积极分子懒羊羊2 小时前
python课程三月二十九号粗略总结
开发语言·python
時肆4852 小时前
Linux命令创意组合大赛：管道里的魔法
开发语言·性能优化
Traced back2 小时前
C#/.NET 常用控件、属性、方法和语句大全(或许全)
开发语言·c#·.net
热门推荐
01GitHub 镜像站点02网站改了域名，如何查找？03Linux下V2Ray安装配置指南04Labelme从安装到标注：零基础完整指南05AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南06安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）07UV安装并设置国内源08百度网盘偷偷给电脑“降频”？09Claude Code Skills 实用使用手册102025-04-03 Latex学习1——本地配置Latex + VScode环境