综合项目实战（上）：设计一个完整的视频播放器

说实话，学到现在，咱们已经啃下了不少硬骨头。解码、渲染、同步、控制……每个模块单独拎出来都能写一篇论文。但真正让我觉得「嗯，我算入门了」的那一刻，是把这些东西拼成一个能跑起来的播放器。

我记得第一次把UI、解码、渲染、同步、控制全部串起来时，播放器居然真的能播了。虽然界面丑得像上个世纪的产物，但那种成就感，比调通任何一个算法都强。

这一章，咱们就来做这件事。设计一个完整的视频播放器，把之前学过的所有模块整合到一起。我会带着你从架构设计开始，一步步把代码写出来。

播放器整体架构

先别急着写代码。我习惯在动手前，先画一张架构图。你想想看，一个播放器要处理的事情太多了：用户点了个播放按钮，你得去读文件、解封装、解码、渲染画面、播放声音，还得保证画面和声音是同步的。如果这些事都挤在一个线程里干，那画面卡顿、声音撕裂都是轻的。

所以，架构设计的第一原则就是：各干各的，互不干扰。

下面这张图，是我个人比较喜欢的一种播放器架构。它不算最复杂，但足够清晰，适合咱们这个实战项目。

这个架构里，我分了四层：

• 用户交互层：就是咱们看到的界面，按钮、进度条、播放窗口。它只管一件事——把用户的操作告诉控制层。
• 控制层：播放器的「大脑」。收到用户指令后，协调各个模块工作。比如用户点了暂停，控制层要通知引擎停止解码，同时通知渲染层停止刷新。
• 核心引擎层：干苦活累活的地方。解封装、音视频解码、管理帧队列，都在这里完成。
• 渲染层：分视频和音频两条线。视频渲染用 OpenGL/SDL 把画面画到窗口上，音频渲染用 SDL/ALSA 把声音送到扬声器。

模块职责划分

架构搭好了，咱们得把每个模块的职责说清楚。不然写着写着就容易串了。

模块	职责	关键技术
UI 模块	显示播放窗口、控制按钮、进度条；响应用户操作	Qt / SDL / Win32 API
控制模块	管理播放状态（播放/暂停/停止/seek）；协调各模块生命周期	状态机 + 消息队列
解封装模块	读取媒体文件，分离音视频流，提取数据包	FFmpeg (avformat)
视频解码模块	将压缩的视频数据解码为原始帧（YUV/RGB）	FFmpeg (avcodec) + 硬件加速
音频解码模块	将压缩的音频数据解码为 PCM 数据	FFmpeg (avcodec)
视频渲染模块	将视频帧显示到窗口上，支持缩放、格式转换	SDL / OpenGL / Vulkan
音频渲染模块	将 PCM 数据送入音频设备播放	SDL / ALSA / WASAPI
同步模块	以音频时钟为基准，控制视频帧的显示时机	音视频时间戳 + 差值补偿

你看，每个模块的边界都很清晰。这样做的好处是：出了问题，你能立刻定位到是哪个模块的锅。我曾经遇到一个播放卡顿的问题，排查了半天，最后发现是音频渲染模块的缓冲区设置太小了。

核心数据结构设计

模块之间怎么通信？靠数据结构。我设计了三类核心数据结构，贯穿整个播放器。

1. 媒体帧结构

解码后的数据，不管是视频还是音频，统一用这个结构装起来。

struct MediaFrame {
    enum Type { VIDEO, AUDIO };
    Type type;                  // 帧类型
    
    // 视频专用
    AVFrame* avFrame;           // FFmpeg 解码帧
    int width;
    int height;
    
    // 音频专用
    uint8_t* pcmData;           // PCM 数据指针
    int pcmSize;                // 数据大小（字节）
    int sampleRate;
    int channels;
    
    // 通用
    int64_t pts;                // 显示时间戳（微秒）
    int64_t duration;           // 帧持续时间（微秒）
    bool isKeyFrame;            // 是否为关键帧
};

2. 帧队列

解码线程和渲染线程之间，靠队列传递数据。队列要支持多线程安全。

template<typename T>
class SafeQueue {
public:
    void push(const T& item) {
        std::lock_guard<std::mutex> lock(m_mutex);
        m_queue.push(item);
        m_cond.notify_one();
    }
    
    bool pop(T& item, int timeoutMs = 1000) {
        std::unique_lock<std::mutex> lock(m_mutex);
        if (!m_cond.wait_for(lock, 
            std::chrono::milliseconds(timeoutMs),
            [this]{ return !m_queue.empty(); })) {
            return false;  // 超时
        }
        item = m_queue.front();
        m_queue.pop();
        return true;
    }
    
    size_t size() {
        std::lock_guard<std::mutex> lock(m_mutex);
        return m_queue.size();
    }
    
private:
    std::queue<T> m_queue;
    std::mutex m_mutex;
    std::condition_variable m_cond;
};

这里我用了条件变量。为什么？因为解码线程往队列里放数据时，渲染线程可能正在等数据。用条件变量，渲染线程可以「睡」着等，不占 CPU。比轮询优雅多了。

3. 播放状态结构

控制模块需要知道播放器当前处于什么状态。

enum class PlayState {
    IDLE,       // 空闲
    LOADING,    // 加载中
    PLAYING,    // 播放中
    PAUSED,     // 暂停
    SEEKING,    // 正在跳转
    STOPPED,    // 停止
    ERROR       // 出错
};

struct PlaybackInfo {
    PlayState state;
    std::string filePath;
    double duration;           // 总时长（秒）
    double currentPosition;    // 当前播放位置（秒）
    int videoWidth;
    int videoHeight;
    double fps;
    int audioSampleRate;
    int audioChannels;
};

模块间通信机制

模块之间怎么通信？我用了两种方式：

• 数据流：通过帧队列传递。解码线程往队列里 push，渲染线程从队列里 pop。这是单向的。
• 控制流：通过事件回调。控制模块发出指令，其他模块响应。比如用户点击暂停，控制模块发出 PAUSE 事件，解码线程暂停解码，渲染线程暂停刷新。

事件回调的实现，我习惯用函数指针 + 注册机制。

// 事件类型
enum class PlayerEvent {
    PLAY, PAUSE, STOP, SEEK,
    FRAME_READY,              // 解码完成一帧
    PLAYBACK_FINISHED,        // 播放结束
    ERROR_OCCURRED
};

// 事件监听器
using EventCallback = std::function<void(PlayerEvent, void* data)>;

class EventDispatcher {
public:
    void registerCallback(EventCallback cb) {
        m_callbacks.push_back(cb);
    }
    
    void dispatch(PlayerEvent event, void* data = nullptr) {
        for (auto& cb : m_callbacks) {
            cb(event, data);
        }
    }
    
private:
    std::vector<EventCallback> m_callbacks;
};

线程模型设计

咱们这个播放器，至少需要四个线程：

1. 主线程（UI 线程）：负责界面刷新和用户交互。
2. 解封装线程：读取文件，分离音视频包，分别送入音视频解码器。
3. 视频解码线程：解码视频包，把解码后的帧放入视频帧队列。
4. 音频解码线程：解码音频包，把解码后的 PCM 数据放入音频帧队列。

渲染呢？视频渲染通常放在主线程（因为要操作窗口），或者单独开一个渲染线程。音频渲染一般由 SDL 或 ALSA 的回调驱动，在回调里取数据播放。

线程多了，就要注意同步问题。我总结了几条铁律：

• 不要跨线程直接访问对方的数据。用队列传递。
• 解码线程和渲染线程之间，用双缓冲队列。一个队列正在被消费，另一个队列正在被生产，避免锁竞争。
• 控制指令用原子变量或事件标志。比如暂停，用一个 std::atomic<bool> m_paused，解码线程每次循环检查一下。

// 暂停控制示例
std::atomic<bool> m_paused{false};

// 解码线程主循环
void decodeThreadFunc() {
    while (!m_stopped) {
        if (m_paused) {
            std::this_thread::sleep_for(std::chrono::milliseconds(10));
            continue;
        }
        // 正常解码...
    }
}

// 控制模块调用
void pause() {
    m_paused = true;
    // 通知渲染线程也暂停
}

void resume() {
    m_paused = false;
}

嗯，这里要注意：暂停时解码线程不能完全停掉，否则 seek 后恢复播放时，解码器需要重新初始化，会有延迟。我一般让解码线程继续跑，但把解码后的帧丢弃，或者缓存起来。

小结

这一章，咱们把播放器的骨架搭好了。架构、模块划分、数据结构、通信机制、线程模型，都有了清晰的方案。说白了，就是「分层解耦，各司其职」这八个字。

下一章，咱们会真正动手写代码，把每个模块实现出来。到时候你会发现，有了今天的设计，写代码就像搭积木一样简单。