基于Qt与FFmpeg构建跨平台音视频播放器：架构设计与工程实践

1. 项目概述：为什么选择Qt+FFmpeg来造轮子？

做音视频播放器，听起来像是播放器软件公司或者流媒体大厂的核心业务，离我们普通开发者很远。但如果你深入接触过C++客户端开发，尤其是需要处理多媒体内容的项目，比如视频会议、安防监控、在线教育客户端，甚至是游戏内的过场动画播放器，你迟早会碰到这个需求：如何在自己的C++程序里，稳定、高效、可控地播放一段视频？这时候，你可能会去搜现成的库，比如VLC的LibVLC，或者DirectShow、Media Foundation（Windows平台）。但很快你会发现，要么绑定太重，要么跨平台麻烦，要么定制化程度不够，无法满足你产品里那个独特的进度条、滤镜或者网络流协议。

这就是我当初决定自己动手，基于Qt和FFmpeg搭建一个播放器核心的原因。Qt提供了顶级的跨平台GUI框架和一套好用的事件循环、线程管理机制，让你能专注于业务逻辑，而不是陷在Windows消息循环或者Linux的X11事件里。而FFmpeg，则是多媒体处理领域的“瑞士军刀”，几乎所有的播放、转码、流媒体服务背后都有它的身影，它负责最底层的音视频解封装、解码工作。把这两者结合起来，Qt做“面子”（界面和交互），FFmpeg做“里子”（音视频处理），你就能获得一个完全受控、可深度定制、且能运行在Windows、macOS、Linux三大桌面系统上的播放器核心。

这个项目不只是为了播个视频文件。通过剖析源码，你能掌握的是一套处理多媒体数据的通用架构思想。你会明白一帧视频数据从文件到屏幕的完整旅程，理解音画同步这个经典难题的解决方案，学会如何处理各种诡异的媒体格式和网络流。这些知识，在你日后面对音频可视化、视频编辑、实时通信等更复杂的场景时，会成为你工具箱里最趁手的家伙。下面，我就把这个项目的设计思路、关键实现、踩过的坑，毫无保留地拆解给你看。

2. 整体架构设计与核心模块拆解

一个播放器，远不止一个play()函数那么简单。它的核心是一个精密的、多线程协作的数据流水线。我们的架构主要分为三层：控制层、数据层和渲染层。

2.1 核心模块职责划分

1. 主线程（UI线程/控制层）：

   • 职责：运行Qt的事件循环，管理用户界面（播放/暂停按钮、进度条、音量控制等），响应用户交互事件。
   • 关键戒律：绝对禁止在UI线程中进行任何耗时的FFmpeg操作，如读取文件、解码等，否则界面会立即卡死。它的任务只是发送控制命令（如Play、Seek）和更新UI状态。

2. 解复用线程（Demuxer Thread）：

   • 职责：负责“拆快递”。使用FFmpeg的avformat模块打开媒体文件或网络流，读取容器格式（如MP4、MKV、FLV），将交织在一起的音频流和视频流分离（解复用）出来，分别放入音频包队列和视频包队列。
   • 关键数据结构：AVFormatContext（格式上下文）、AVPacket（编码数据包）。

3. 视频解码线程：

   • 职责：负责“翻译视频密码”。从视频包队列中取出AVPacket，利用FFmpeg的avcodec模块，通过视频解码器（如H.264、HEVC）将其解码成原始的图像数据（AVFrame），即YUV或RGB像素数据，然后放入视频帧队列。
   • 关键数据结构：AVCodecContext（编解码上下文）、AVFrame（原始帧）。

4. 音频解码线程：

   • 职责：与视频解码线程类似，从音频包队列取包，解码成PCM音频采样数据（AVFrame），放入音频帧队列。
   • 关键点：音频解码通常比视频快，但音频播放有严格的实时性要求，所以同步策略至关重要。

5. 视频渲染模块：

   • 职责：负责“画画”。从视频帧队列中取出AVFrame，将其转换为Qt的QImage或QOpenGLTexture，最终通过QWidget的paintEvent或OpenGL在屏幕上绘制出来。
   • 性能关键：缩放、色彩空间转换（YUV到RGB）可能很耗CPU，考虑使用GPU（OpenGL Shader）加速。

6. 音频播放模块：

   • 职责：负责“发声”。从音频帧队列中取出PCM数据，通过Qt的QAudioOutput或更底层的平台音频API（如ALSA、Core Audio）播放出去。
   • 同步核心：音频播放的时钟是主时钟，视频需要向其同步。

7. 队列管理器：

   • 职责：整个架构的“缓冲区和协调器”。管理着音频包队列、视频包队列、音频帧队列、视频帧队列。它需要是线程安全的，并且要有容量限制和超时机制，防止内存爆掉或因某个环节阻塞导致整个程序卡死。

整个数据流就像一条工厂流水线：文件→解复用→（音频包/视频包）→解码→（音频帧/视频帧）→（播放/渲染）。多线程让读数据、解码、渲染可以并行，极大提升了效率。

2.2 线程间通信与同步机制

这是项目的难点和精华所在。我们主要使用两种方式：

1. 生产者-消费者队列：这是线程间传递数据（AVPacket，AVFrame）的主要方式。我们通常会实现一个模板化的ThreadSafeQueue。它内部用std::queue或QQueue存储数据，用std::mutex（或QMutex）保护，用std::condition_variable（或QWaitCondition）进行线程等待和唤醒。

   • 生产者（如解复用线程）在队列未满时push数据，并notify_one唤醒可能正在等待的消费者。
   • 消费者（如解码线程）在队列不为空时pop数据，如果为空则等待（wait）被生产者唤醒。
   • 容量控制：必须设置队列最大容量。例如，视频帧队列存最多3秒的数据就够了，防止用户跳转进度（Seek）后，堆积大量过时的帧，导致内存占用过高和同步混乱。

2. 信号与槽（Qt）结合原子标志：这是传递控制命令和状态的最佳方式。例如，用户点击暂停按钮。

   • UI线程发射一个pauseRequested()信号。
   • 解复用、解码线程的槽函数连接到这个信号，收到后，通过原子布尔变量（如std::atomic<bool>）或将标志位存入队列，通知数据流暂停。
   • 这样做解耦了UI和后台线程，符合Qt的设计哲学，也安全。

注意：直接在线程间传递FFmpeg的结构体指针（如AVPacket*）是危险的，因为FFmpeg有很多内部引用计数。我们必须深拷贝或使用FFmpeg提供的av_packet_ref/av_frame_ref来增加引用计数，确保在一个线程释放资源时，不会影响另一个线程正在使用的数据。更简单的做法是，使用AVPacket和AVFrame的智能指针封装类，利用RAII机制自动管理生命周期。

3. FFmpeg核心API使用详解与封装

很多人卡在FFmpeg的第一步：安装和链接。这里跳过安装教程，重点讲在C++项目中如何正确使用。

3.1 初始化解封装与解码器

// 1. 初始化FFmpeg库（网络、编解码器等） avformat_network_init(); // 通常在主程序启动时调用一次即可 // 2. 打开媒体文件，获取格式上下文 AVFormatContext* formatCtx = nullptr; const char* url = "your_video.mp4"; // 也可以是rtmp://, http:// 等 int ret = avformat_open_input(&formatCtx, url, nullptr, nullptr); if (ret < 0) { // 处理错误，av_err2str(ret)可获取错误信息 return; } // 3. 探测流信息 ret = avformat_find_stream_info(formatCtx, nullptr); if (ret < 0) { // 处理错误 avformat_close_input(&formatCtx); return; } // 4. 查找最佳的音频流和视频流索引 int videoStreamIndex = -1; int audioStreamIndex = -1; for (int i = 0; i < formatCtx->nb_streams; ++i) { AVStream* stream = formatCtx->streams[i]; if (stream->codecpar->codec_type == AVMEDIA_TYPE_VIDEO && videoStreamIndex == -1) { videoStreamIndex = i; } else if (stream->codecpar->codec_type == AVMEDIA_TYPE_AUDIO && audioStreamIndex == -1) { audioStreamIndex = i; } } if (videoStreamIndex == -1 && audioStreamIndex == -1) { // 没有可用的音视频流 avformat_close_input(&formatCtx); return; } // 5. 为视频流和音频流分别创建解码器上下文并打开解码器 AVCodecContext* createCodecContext(AVFormatContext* fmtCtx, int streamIndex) { if (streamIndex < 0) return nullptr; AVStream* stream = fmtCtx->streams[streamIndex]; const AVCodec* codec = avcodec_find_decoder(stream->codecpar->codec_id); if (!codec) return nullptr; AVCodecContext* codecCtx = avcodec_alloc_context3(codec); if (!codecCtx) return nullptr; // 将流中的编解码参数拷贝到解码器上下文 ret = avcodec_parameters_to_context(codecCtx, stream->codecpar); if (ret < 0) { avcodec_free_context(&codecCtx); return nullptr; } // 打开解码器 ret = avcodec_open2(codecCtx, codec, nullptr); if (ret < 0) { avcodec_free_context(&codecCtx); return nullptr; } return codecCtx; } AVCodecContext* videoCodecCtx = createCodecContext(formatCtx, videoStreamIndex); AVCodecContext* audioCodecCtx = createCodecContext(formatCtx, audioStreamIndex);

3.2 封装一个安全的AVFrame管理类

直接操作AVFrame容易内存泄漏，封装一下让生活更美好。

class AVFrameWrapper { public: AVFrameWrapper() : frame(av_frame_alloc()) { if (!frame) throw std::runtime_error("Failed to allocate AVFrame"); } // 禁止拷贝，允许移动 AVFrameWrapper(const AVFrameWrapper&) = delete; AVFrameWrapper& operator=(const AVFrameWrapper&) = delete; AVFrameWrapper(AVFrameWrapper&& other) noexcept : frame(other.frame) { other.frame = nullptr; } AVFrameWrapper& operator=(AVFrameWrapper&& other) noexcept { if (this != &other) { if (frame) av_frame_free(&frame); frame = other.frame; other.frame = nullptr; } return *this; } ~AVFrameWrapper() { if (frame) av_frame_free(&frame); } AVFrame* get() const { return frame; } AVFrame* operator->() const { return frame; } // 创建一个深拷贝（用于跨线程传递） AVFrameWrapper clone() const { if (!frame) return AVFrameWrapper(); AVFrameWrapper newFrame; if (av_frame_ref(newFrame.frame, frame) < 0) { throw std::runtime_error("Failed to ref AVFrame"); } return newFrame; } private: AVFrame* frame = nullptr; }; // 使用时，可以用 std::queue<AVFrameWrapper> 作为线程安全队列的元素类型。

3.3 解码循环示例（视频解码线程）

void VideoDecodeThread::run() { AVPacketWrapper pkt; // 类似AVFrameWrapper的封装 AVFrameWrapper frame; while (!m_stopFlag) { // 1. 从视频包队列取一个包 if (!m_videoPacketQueue.pop(pkt, 100)) { // 超时100ms，用于检查停止标志 continue; } // 2. 发送包到解码器 int ret = avcodec_send_packet(m_videoCodecCtx, pkt.get()); if (ret < 0 && ret != AVERROR(EAGAIN) && ret != AVERROR_EOF) { // 发送失败，丢弃这个包，记录错误 continue; } // 3. 循环接收解码后的帧 while (ret >= 0) { ret = avcodec_receive_frame(m_videoCodecCtx, frame.get()); if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) { break; // 需要新的输入包，或解码结束 } else if (ret < 0) { // 解码错误 break; } // 4. 成功解码出一帧！ // 计算这一帧的显示时间戳（PTS），这是同步的关键 double pts = frame->pts * av_q2d(m_videoStream->time_base); if (pts == AV_NOPTS_VALUE) { // 有些流没有有效PTS，需要用帧序号估算 static double frameNum = 0; pts = frameNum * av_q2d(m_videoStream->avg_frame_rate); frameNum++; } // 将pts存入frame的opaque字段或自定义结构，随帧一起放入队列 // ... // 5. 将解码后的帧放入视频帧队列 AVFrameWrapper frameToQueue = frame.clone(); // 深拷贝，因为frame会被复用 if (!m_videoFrameQueue.push(std::move(frameToQueue))) { // 队列已满，可以丢弃最老的一帧（丢帧策略） m_videoFrameQueue.pop(); // 丢弃队首 m_videoFrameQueue.push(std::move(frameToQueue)); } av_frame_unref(frame.get()); // 准备接收下一帧 } av_packet_unref(pkt.get()); // 释放包资源 } }

4. Qt界面集成与音视频渲染实战

有了后台的数据流水线，前端的任务就是优雅地展示和播放。

4.1 自定义视频渲染Widget

我们不直接用QMediaPlayer，而是用QWidget自己画，这样才能获得完全的控制权，比如添加自定义滤镜、OSD（屏幕显示信息）等。

class VideoWidget : public QWidget { Q_OBJECT public: explicit VideoWidget(QWidget *parent = nullptr) : QWidget(parent) { setAttribute(Qt::WA_OpaquePaintEvent); // 告诉Qt我们处理所有绘制，避免背景擦除 setAttribute(Qt::WA_NoSystemBackground); m_image = QImage(640, 480, QImage::Format_RGB888); // 初始图像 m_image.fill(Qt::black); } void presentFrame(const AVFrameWrapper& frame, double pts) { // 这个函数在渲染线程（非UI线程）中被调用 // 1. 将AVFrame转换为QImage QImage img = convertAVFrameToQImage(frame); // 2. 通过锁保护，更新成员变量 { std::lock_guard<std::mutex> lock(m_frameMutex); m_image = std::move(img); m_currentPts = pts; } // 3. 通知UI线程需要重绘 // 使用信号槽，因为QWidget的repaint必须在主线程 QMetaObject::invokeMethod(this, [this]() { update(); }, Qt::QueuedConnection); } protected: void paintEvent(QPaintEvent *event) override { QPainter painter(this); painter.setRenderHint(QPainter::SmoothPixmapTransform); std::lock_guard<std::mutex> lock(m_frameMutex); // 计算缩放，保持宽高比 QRect targetRect = m_image.rect(); targetRect.setSize(m_image.size().scaled(size(), Qt::KeepAspectRatio)); targetRect.moveCenter(rect().center()); painter.drawImage(targetRect, m_image); // 可以在这里绘制OSD信息，如当前时间码 painter.setPen(Qt::white); painter.drawText(10, 20, QString::number(m_currentPts, 'f', 2)); } private: QImage convertAVFrameToQImage(const AVFrameWrapper& frame) { // 简化版：假设frame已经是RGB24格式 // 实际中，YUV420P到RGB的转换是性能瓶颈，建议用SwScale或OpenGL Shader if (frame->format == AV_PIX_FMT_RGB24) { return QImage(frame->data[0], frame->width, frame->height, frame->linesize[0], QImage::Format_RGB888).copy(); } // 否则，需要调用sws_scale进行转换... return QImage(); } QImage m_image; double m_currentPts = 0.0; std::mutex m_frameMutex; };

4.2 音频播放与时钟同步

音频播放是同步的主时钟，因为人耳对声音的断续异常敏感。

class AudioOutput : public QIODevice { Q_OBJECT public: AudioOutput(const QAudioFormat &format, QObject *parent = nullptr) : QIODevice(parent), m_audioOutput(new QAudioOutput(format, this)) { setOpenMode(QIODevice::ReadOnly); m_audioOutput->start(this); // 将本设备作为音频源 } void writeData(const uint8_t* data, int len) { // 这个函数在音频解码线程中被调用 std::lock_guard<std::mutex> lock(m_bufferMutex); int oldSize = m_buffer.size(); m_buffer.resize(oldSize + len); memcpy(m_buffer.data() + oldSize, data, len); m_bytesBuffered += len; // 计算当前音频播放器的时钟 // QAudioOutput已播放的字节数 / 每秒字节数 = 已播放时间 qint64 bytesPlayed = m_audioOutput->processedUSecs() / 1000000.0 * m_format.sampleRate() * m_format.bytesPerFrame(); m_audioClock = bytesPlayed / (double)(m_format.sampleRate() * m_format.bytesPerFrame()); } qint64 readData(char *data, qint64 maxlen) override { // QAudioOutput会主动调用这个函数来拉取数据 std::lock_guard<std::mutex> lock(m_bufferMutex); qint64 bytesToRead = qMin(maxlen, (qint64)m_buffer.size()); if (bytesToRead <= 0) { return 0; // 无数据，播放静音或暂停 } memcpy(data, m_buffer.constData(), bytesToRead); m_buffer.remove(0, bytesToRead); return bytesToRead; } qint64 writeData(const char *, qint64) override { return -1; } // 不支持写 double getAudioClock() const { std::lock_guard<std::mutex> lock(m_bufferMutex); return m_audioClock + m_buffer.size() / (double)(m_format.sampleRate() * m_format.bytesPerFrame()); // 当前时钟 + 缓冲区中剩余数据的时长 } private: QAudioOutput* m_audioOutput; QAudioFormat m_format; QByteArray m_buffer; mutable std::mutex m_bufferMutex; double m_audioClock = 0.0; qint64 m_bytesBuffered = 0; };

音视频同步策略： 在视频渲染前，获取当前的音频时钟audio_clock和当前视频帧的显示时间戳video_pts。

• 计算差值diff = video_pts - audio_clock。
• 如果diff > 0.1（视频快了100ms以上），则延迟渲染这一帧，等待音频追上来。可以通过QThread::usleep(diff * 1000000)实现，但更优雅的是调整下一帧的渲染时机。
• 如果diff < -0.1（视频慢了100ms以上），则丢弃当前帧，立即渲染下一帧，追上音频。
• 这个阈值（0.1秒）可以调整，太小会导致频繁调整观感不佳，太大会导致明显音画不同步。

5. 关键问题排查与性能优化实录

实际开发中，你会遇到无数个坑。这里记录几个最典型的。

5.1 内存泄漏与资源管理

FFmpeg的很多结构体需要手动管理内存。一个黄金法则是：每一个av_xxx_alloc都必须对应一个av_xxx_free。

• AVFormatContext：avformat_open_input分配，avformat_close_input释放。
• AVCodecContext：avcodec_alloc_context3分配，avcodec_free_context释放。
• AVPacket：av_packet_alloc分配，av_packet_free释放。在循环中，每次解码完一个包，必须调用av_packet_unref。
• AVFrame：av_frame_alloc分配，av_frame_free释放。同样，每次处理完一帧，调用av_frame_unref。

使用Valgrind或AddressSanitizer定期检查内存泄漏。我强烈建议像前面那样，用RAII风格的C++类（如AVFrameWrapper）将它们包装起来，利用析构函数自动释放，能避免90%的内存泄漏问题。

5.2 队列阻塞与死锁

多线程队列是死锁的高发区。我的经验是：

1. 设置超时：在队列的pop操作中设置超时（比如100ms）。这样即使生产者暂时没数据，消费者线程也能定期醒来检查退出标志，而不是永久阻塞。
2. Seek操作清空队列：当用户拖动进度条时，必须立即清空所有音视频包和帧队列。因为队列里缓存的是旧位置的数据，如果不清理，播放器会继续播完旧数据才跳到新位置，体验极差。清空队列前，要通知解码线程刷新解码器（avcodec_flush_buffers）。
3. 优雅退出：停止播放时，先通知各线程退出标志，然后等待（join）它们结束。线程的run函数循环中，每次从队列pop前都应检查退出标志。

5.3 性能瓶颈定位

播放高清视频卡顿？CPU占用率100%？按以下顺序排查：

1. 解码性能：用工具（如perf、Intel VTune）分析，看是视频解码（avcodec_receive_frame）还是音频解码耗时。H.264 1080P解码对现代CPU压力不大，但HEVC 4K软解码可能就很吃力。考虑启用硬件解码（如CUDA、DXVA2、VideoToolbox）。
2. 色彩转换与缩放：这是容易被忽视的CPU大户。如果AVFrame是YUV420P，而你的QImage需要RGB32，用sws_scale进行转换，特别是缩放到大窗口时，计算量巨大。优化方案：使用OpenGL渲染，在GPU上用Shader做YUV到RGB的转换和缩放，性能提升是数量级的。
3. 队列竞争：过多的锁竞争会导致线程空转。检查你的线程安全队列，锁的粒度是否过大？可以考虑使用无锁队列（如moodycamel::ConcurrentQueue）替代，但实现复杂度较高。
4. 音频回调：QAudioOutput的回调（readData）必须在极短时间内返回数据，否则会听到爆音。确保向音频缓冲区写入数据的操作是快速的，如果从队列中取数据太慢，考虑预缓冲更多音频数据。

5.4 兼容性难题：奇怪的媒体文件

不是所有MP4文件都能播。你会遇到：

• 时间基（time_base）问题：有些视频流的pts不是以秒为单位，而是以一个分数（AVRational）为单位的刻度。必须用av_q2d(stream->time_base) * pts转换成秒。我遇到过time_base为1/90000和1/1000的，处理不当会导致同步彻底混乱。
• 没有B帧的流：Seek操作会变得简单。有B帧的流，因为帧间依赖关系，Seek到非关键帧时，需要解码器向前寻找关键帧，逻辑更复杂。FFmpeg的av_seek_frame函数有AVSEEK_FLAG_BACKWARD等标志来处理这个问题。
• 损坏的文件或网络中断：av_read_frame可能返回错误码。需要健壮的错误处理，比如网络流中断后尝试重连，或者文件损坏时跳到下一个关键帧继续播放，而不是直接崩溃。

6. 功能扩展与高级特性实现思路

基础播放器完成后，你可以在此基础上添加更多专业功能，这会让你的项目从“玩具”升级为“工具”。

6.1 精准Seek（跳转）

这是播放器的核心用户体验。不能简单调用av_seek_frame就完事。

1. 用户拖动进度条到target_seconds。
2. 清空所有音视频队列。
3. 调用av_seek_frame(format_ctx, -1, target_seconds * AV_TIME_BASE, AVSEEK_FLAG_BACKWARD)。AVSEEK_FLAG_BACKWARD表示向后寻找到最近的关键帧，这是最安全的方式。
4. 刷新解码器上下文：avcodec_flush_buffers(video_codec_ctx)和avcodec_flush_buffers(audio_codec_ctx)。
5. 解复用线程重新开始读包。因为Seek到的是关键帧（通常是I帧），视频解码线程从这一帧开始解码，但音频可能需要丢弃一些数据，直到其时间戳略大于target_seconds，再开始播放，以避免音画不同步。

6.2 倍速播放

单纯的快进（丢帧）或慢放（重复帧）体验不好。真正的倍速播放需要：

• 音频：这是难点。不能简单改变采样率播放，那会变调。需要使用音频重采样库（如libswresample）进行“变速不变调”处理，或者更现代地，使用libsoxr（高质量重采样库）。原理是通过重采样算法，在时间轴上拉伸或压缩音频信号。
• 视频：相对简单。根据倍速调整帧的显示间隔。2倍速播放，则每帧显示时间减半。注意，如果视频帧率本身不高，高速播放可能会显得卡顿，可以结合智能丢帧策略。

6.3 音轨切换与字幕加载

1. 音轨切换：媒体文件中可能包含多条音频流（如多语言）。在AVFormatContext中遍历所有流，找到codec_type为AVMEDIA_TYPE_AUDIO的流。切换时：
   • 关闭当前音频解码器。
   • 用新的流索引创建新的音频解码器上下文。
   • 清空音频相关队列。
   • 通知解复用线程开始向新的音频包队列发送数据。
2. 字幕加载：字幕流（AVMEDIA_TYPE_SUBTITLE）可以是内嵌的（如MKV中的ASS/SSA）或外挂的（SRT、ASS文件）。
   • 内嵌字幕：通过av_read_frame读取到AVPacket，解码后得到文本或图形字幕数据，需要在渲染视频时叠加到画面上。
   • 外挂字幕：需要自己解析SRT/ASS文件格式，根据当前播放时间戳，找到该显示的字幕行，同样叠加渲染。
   • 渲染：可以用Qt的QPainter在VideoWidget的paintEvent中绘制文字。对于高级的ASS字幕（有样式、动画），需要实现一个简单的ASS渲染器，或者集成libass库。

6.4 视频滤镜与硬件解码

• 软件滤镜：FFmpeg自带强大的libavfilter库，可以链式处理视频帧。比如，添加一个“反转颜色”滤镜。你需要创建一个FilterGraph，将解码后的AVFrame送入，处理后再取出渲染。这会给CPU带来额外负担。
• 硬件解码：为了降低CPU占用，播放4K、8K视频必须用上。FFmpeg支持多种硬件API。
  • Windows：DXVA2（DirectX Video Acceleration）或D3D11VA。
  • Linux：VA-API或VDPAU。
  • macOS：VideoToolbox。
  • 通用：CUDA（NVIDIA显卡）。
  • 使用方法：在打开解码器时，通过AVDictionary设置硬件设备类型参数（如hwaccel为cuda）。硬件解码输出的是GPU显存中的帧（可能是特定格式如NV12），你需要将其映射到系统内存或直接用OpenGL纹理渲染，这涉及到另一个复杂的话题——GPU内存到CPU内存或OpenGL纹理的拷贝。

7. 项目构建与部署心得

最后，说说怎么把这一大摊子代码编译成一个可用的程序。

1. 依赖管理：

   • Qt：用Qt Creator或CMake管理很方便。确保你的.pro文件或CMakeLists.txt正确链接了Qt5Core，Qt5Gui，Qt5Widgets，Qt5Multimedia（如果用了QAudioOutput）。
   • FFmpeg：这是最麻烦的。不建议自己编译，直接使用官方预编译的共享库（如来自BtbN的Windows build）。你需要链接avcodec，avformat，avutil，swscale，swresample等库。在CMake中，使用find_package(PkgConfig)和pkg_check_modules来查找FFmpeg的路径和库文件。

2. 跨平台编译：

   • Windows：使用MSVC或MinGW。注意FFmpeg库的版本（MSVC vs MinGW）要匹配你的编译器。运行时需要将FFmpeg的*.dll文件放在可执行文件旁边。
   • Linux：在Ubuntu/Debian上，可以直接apt install libavcodec-dev libavformat-dev ...。注意版本可能较旧。追求新特性最好自己编译或使用第三方PPA。
   • macOS：用Homebrew安装非常方便：brew install ffmpeg qt。链接时注意框架路径。

3. 打包发布：

   • Windows：将Qt的运行时DLL（在Qt安装目录/bin下）、FFmpeg的DLL、以及可能需要的VC++运行时合并到一起。可以使用windeployqt工具自动抓取Qt依赖。
   • Linux：理论上静态链接最好，但FFmpeg的LGPL许可证对静态链接有要求。通常做法是动态链接，在打包说明中告知用户安装ffmpeg和qt5相关运行时包（如libavcodec58，libqt5widgets5）。
   • macOS：使用macdeployqt工具创建.appbundle，它会自动将Qt库复制进去。FFmpeg库也需要复制到app/Contents/Frameworks/目录下，并使用install_name_tool修改其加载路径。

踩过最大的一个坑是：在Linux上，系统自带的FFmpeg库可能太旧，缺少某些编解码器（比如HEVC）。而你自己编译的新版FFmpeg，其soname（如libavcodec.so.59）与系统的（如libavcodec.so.58）不兼容。最终我选择了在项目内附带一个特定版本的FFmpeg动态库，并通过设置LD_LIBRARY_PATH或rpath来优先加载它们，虽然不够优雅，但保证了运行环境的一致性。

这个项目从零到能流畅播放本地视频，我花了大约两周；到能稳定处理网络流和实现精准Seek，又花了一周；再到性能优化和兼容各种奇怪格式，断断续续调试了更久。但整个过程下来，你对多媒体流水线、多线程编程、C++资源管理、跨平台开发的理解会深刻得多。下次再遇到音视频相关需求，你心里就有了一张清晰的蓝图，知道问题可能出在哪个环节，该怎么去解决。这大概就是“造轮子”最大的意义——不是为了重复发明，而是为了彻底理解。