# 视频编码硬件加速实现指导文档

本文档供 AI 编码助手参考，用于在现有 C++ 远程控制程序中实现 H.264 硬件编码 + AV1 编码路径。

---

## 1. 项目背景

### 1.1 当前状态

- C++ Windows 远程控制程序
- 已实现 H.264 编码，基于 x264 软编（`CX264Encoder`），preset = `ultrafast + zerolatency`
- 视频管线：桌面捕获（RGB/BGRA）→ 编码 → 网络传输 → 客户端解码显示
- 当前架构：每个主控端连接对应一个独立编码器实例
- **分发模式**：单 exe，FFmpeg 静态链接

### 1.2 目标

分两阶段渐进推进，**始终保留 x264 软编作为兜底**：

**阶段一（H.264 硬编加速）**
- 新增 H.264 硬编（NVENC / QSV / AMF），按 GPU 能力探测优先走硬编
- x264 软编在无 GPU / 虚拟机 / 远程桌面会话等环境下兜底
- 浏览器解码零兼容性风险（H.264 全平台原生支持）

**阶段二（AV1 路径）**
- 新增 AV1 硬编（`av1_nvenc` / `av1_qsv` / `av1_amf`）
- 客户端浏览器握手时声明 AV1 能力
- 双方都能用就走 AV1，否则回落 H.264

**最终产物仍为单 exe**，体积增量可接受 6–10 MB。

### 1.3 关键决策记录

#### 1.3.1 为什么跳过 HEVC

经评估，HEVC 在本项目目标场景下没有独占价值：

| 维度 | 现状 |
|---|---|
| **浏览器解码** | Firefox 完全不支持；Chrome/Edge 需 Win11 + 商店付费的 HEVC Video Extensions |
| **专利授权** | 商用涉及 MPEG-LA / Access Advance / Velos Media 三个专利池 |
| **替代方案** | AV1 压缩效率更高、AOMedia 免专利、浏览器原生支持广 |

HEVC 编码端硬件普及度好（几乎所有 2015+ GPU）这个优势，被解码端短板完全抵消。

#### 1.3.2 为什么 H.264 硬编先于 AV1

- **AV1 硬编硬件门槛高**：仅 NVIDIA RTX 40+ / AMD RX 7000+ / Intel Arc 才有
- **"多机混杂"场景**下大部分编码端 GPU 没有 AV1 硬编
- **H.264 硬编**（NVENC/QSV/AMF）几乎所有现代 GPU 都有，覆盖面广
- **客户端浏览器解 H.264** 是零兼容性问题，跨浏览器/跨平台 100% 通用

H.264 硬编是先把"地板抬起来"，AV1 是"在新硬件上的天花板"。

### 1.4 设计约束

- **平台**：仅 Windows（macOS/Linux 未来另行设计）
- **GPU 不确定**：NVIDIA / AMD / Intel / 无独显 / 虚拟机无 GPU 都需支持
- **延迟要求**：不敏感（不追求极致低延迟）
- **并发模型**：通常 1 对 1，少数 1 对多（每个连接独立编码器）
- **客户端**：浏览器（WebCodecs 优先，`<video>` 次之），未来集成
- **工具链**：Visual Studio 2019
- **属性**：个人项目，暂不商用，专利问题搁置但仍优先选免专利方案

---

## 2. 技术方案总览

### 2.1 编码器优先级链

```
新连接进入（带客户端能力）
       │
       ├─ 客户端声明支持 AV1？─── 否 ────┐
       │       是                       │
       │       ↓                        │
       ├─ av1_nvenc/qsv/amf 能开？──┐   │
       │       │                    │   │
       │       成功 → 用 AV1         │   │
       │                            ↓   ↓
       └─ h264_nvenc/qsv/amf/mf 能开？──┐
              │                         │
              成功 → 用 H.264 硬编        │
                                        ↓
                                  x264 软编（始终可用）
```

### 2.2 编码器后端表

| 类型 | FFmpeg 编码器名 | 硬件要求 | 备注 |
|---|---|---|---|
| AV1 硬编 | `av1_nvenc` | NVIDIA RTX 40+（Ada Lovelace） | 2022 Q4 起 |
| AV1 硬编 | `av1_amf`   | AMD RX 7000+（RDNA 3） | 2022 Q4 起 |
| AV1 硬编 | `av1_qsv`   | Intel Arc / 部分新 Iris Xe | 2022 起 |
| H.264 硬编 | `h264_nvenc` | 几乎所有 NVIDIA GPU（GTX 650+） | 2012 起 |
| H.264 硬编 | `h264_qsv`   | 几乎所有 Intel 核显（HD 4000+） | 2012 起 |
| H.264 硬编 | `h264_amf`   | 几乎所有 AMD GPU | |
| H.264 硬编 | `h264_mf`    | Windows Media Foundation | 兜底，质量/稳定性一般 |
| H.264 软编 | `libx264`（现有 `CX264Encoder`） | 任意 CPU | 始终兜底 |

**不使用 `libx265` / `libaom-av1` / `libsvtav1`**（CPU 软编），原因：
- 远控产品对 CPU 占用敏感，AV1/HEVC 软编实时编码压力大
- `libx265` 会让 FFmpeg 切到 GPL，`libaom-av1` 编码速度也不够

### 2.3 类结构

```
VideoEncoderBase（新增抽象接口）
    ├── CX264Encoder           （改造现有类继承接口，保留软编兜底）
    ├── CFFmpegH264Encoder     （新增，封装 h264_nvenc/qsv/amf/mf）
    └── CFFmpegAV1Encoder      （新增，封装 av1_nvenc/qsv/amf）
```

### 2.4 协商流程

```
握手阶段：
- 客户端（浏览器）在 WebSocket 握手时上报能力：
    { "codecs": ["av1", "h264"] }    // 浏览器实际能解的，按优先级排
- 服务端取「客户端能力 ∩ 自己硬件能力」选 codec

会话阶段：
- 选定 codec 后创建对应编码器，整个连接生命周期不变
- 运行中不切换 codec（保持简单，需要切换就重连）
```

---

## 3. 硬编 vs 现有 x264 软编对比

### 3.1 CPU 占用（最大收益）

| 编码器 | 1080p @ 30fps CPU 占用 |
|---|---|
| x264 `ultrafast`（现状） | 单核 15–30% |
| x264 `medium`（同画质基准） | 单核 60–100% |
| `h264_nvenc p4` | 总 **1–3%** |
| `h264_qsv medium` | 总 2–5% |
| `h264_amf balanced` | 总 2–5% |

被控端是用户的主力工作机，他自己还在干活。CPU 让出来意味着远控对他几乎不可感。

### 3.2 同 CPU 预算下画质更高

x264 的 preset 排序（同码率下画质）：

```
ultrafast < superfast < veryfast < faster < fast < medium < slow ...
   ↑ 现状                                       ↑ 标准基准
```

NVENC `p4` 预设大致对应 x264 `fast` ~ `medium`，**画质明显优于当前 ultrafast，且 CPU 占用低一个数量级**。

### 3.3 其他收益

- **编码延迟稳定**：ASIC 不受 CPU 调度影响，单帧 1–5 ms
- **笔记本电池/温度**：ASIC 几瓦，键盘不烫、风扇不转
- **可拉高分辨率/帧率**：4K@30 / 多屏拼接软编扛不住，硬编轻松

### 3.4 代价（必须接受）

- **二进制 +6–10 MB**（FFmpeg 静态库，可接受）
- **编译复杂度上升**：vcpkg 或自编 FFmpeg
- **不同后端参数语义有差异**：rc 模式、preset 名字、bitrate 表现都不一样
- **必须保留 x264 软编兜底**：无 GPU / 远程桌面 / 虚拟机 / NVENC session 满 等场景

---

## 4. 现有 H.264 编码器现状

`CX264Encoder` 签名（`client/X264Encoder.cpp`）：

```cpp
class CX264Encoder
{
private:
    x264_t*         m_pCodec;
    x264_picture_t* m_pPicIn;
    x264_picture_t* m_pPicOut;
    x264_param_t    m_Param;

public:
    bool open(int width, int height, int fps, int crf);
    bool open(x264_param_t* param);
    void close();
    int encode(uint8_t* rgb, uint8_t bpp, uint32_t stride,
               uint32_t width, uint32_t height,
               uint8_t** lppData, uint32_t* lpSize,
               int direction = 1);
};
```

集成点（`client/ScreenCapture.h`）：

| 位置 | 内容 |
|---|---|
| `L148` | `CX264Encoder* m_encoder;`（持有具体类，需改为接口） |
| `L926-930` | 关键帧路径硬编码 `new CX264Encoder()` |
| `L956-960` | 增量帧路径硬编码 `new CX264Encoder()` |
| `L170-176` | `BitRateToCRF(bitRate)` 码率→CRF 映射 |

参数现状：
- `param.i_threads = 1`
- `preset = "ultrafast", tune = "zerolatency"`
- `i_keyint_max = fps * 15`（15 秒一个 IDR）
- `i_bframe = 0`、`b_open_gop = 0`
- `rc.i_rc_method = X264_RC_CRF`（CRF 模式，未设 VBV）

需要的改造（详见 §6）：
1. `ScreenCapture::m_encoder` 改 `std::unique_ptr<VideoEncoderBase>`
2. 编码器创建走 `CreateEncoder` 工厂
3. 接口的 quality 语义解耦（CRF vs kbps，详见 §6.2）

---

## 5. FFmpeg 静态库准备

### 5.1 推荐方案：vcpkg

VS2019 + vcpkg 是最稳的路径：

```
vcpkg install ffmpeg[core,nvcodec,amf,qsv]:x64-windows-static-md
```

要点：
- **三元组选 `x64-windows-static-md`**：链接静态 FFmpeg 但用动态 CRT（`/MD`），与本项目当前工程一致
- 如果工程是 `/MT` 改用 `x64-windows-static`
- `nvcodec` feature 引入 NVENC 头文件，`amf` 引入 AMF，`qsv` 引入 libmfx
- 阶段一只需要 H.264，可以先不带这些 feature，但建议一次到位

阶段二需要 AV1，FFmpeg 较新版本默认已支持 `av1_nvenc` / `av1_amf` / `av1_qsv`，无需额外 feature 名。

### 5.2 备选方案：自编

MSYS2 + MinGW-w64 + `--toolchain=msvc` 产出 MSVC 兼容 `.lib`：

```bash
./configure \
  --prefix=/path/to/install \
  --arch=x86_64 \
  --target-os=mingw64 \
  --toolchain=msvc \
  --disable-shared --enable-static \
  --disable-everything \
  --disable-autodetect \
  --disable-network \
  --disable-doc \
  --disable-programs \
  --disable-debug \
  --enable-small \
  --enable-encoder=h264_nvenc \
  --enable-encoder=h264_amf \
  --enable-encoder=h264_qsv \
  --enable-encoder=h264_mf \
  --enable-encoder=av1_nvenc \
  --enable-encoder=av1_amf \
  --enable-encoder=av1_qsv \
  --enable-protocol=file
```

**不要** `--enable-gpl` 或 `--enable-libx265 / --enable-libaom`，保持 LGPL 且避免软编 H.265/AV1。

### 5.3 工程链接配置（MSVC）

**附加包含目录**（C/C++ → 常规）：
```
$(VcpkgRoot)\installed\x64-windows-static-md\include
```

**附加库目录**（链接器 → 常规）：
```
$(VcpkgRoot)\installed\x64-windows-static-md\lib
```

**附加依赖项**（链接器 → 输入）：
```
avcodec.lib
avutil.lib
swresample.lib

# FFmpeg 静态链接依赖的 Windows 系统库
mfplat.lib
mfuuid.lib
strmiids.lib
ws2_32.lib
secur32.lib
bcrypt.lib
```

**预处理器定义**：
```
ENABLE_HW_ENCODER
__STDC_CONSTANT_MACROS    # FFmpeg C 头文件在 C++ 中需要
```

---

## 6. 实现任务清单

### 6.1 文件清单

| 文件 | 操作 | 说明 |
|---|---|---|
| `VideoEncoderBase.h` | 新增 | 抽象基类 + EncoderParams |
| `X264Encoder.h/.cpp` | 修改 | 继承 `VideoEncoderBase`，新增 `forceIDR()` / `codec()` / `backendName()` |
| `CFFmpegH264Encoder.h/.cpp` | 新增（阶段一） | 封装 `h264_nvenc/qsv/amf/mf` |
| `CFFmpegAV1Encoder.h/.cpp` | 新增（阶段二） | 封装 `av1_nvenc/qsv/amf` |
| `EncoderFactory.h/.cpp` | 新增 | 工厂 + 多后端探测 |
| `EncoderProbe.h/.cpp` | 新增 | 启动时一次性探测可用后端，缓存结果 |
| `ScreenCapture.h` | 修改 | `m_encoder` 改 `std::unique_ptr<VideoEncoderBase>` |
| 握手协议代码 | 修改（阶段二） | 加 `codecs` 能力字段 |
| 工程配置 | 修改 | FFmpeg 静态库链接（详见 §5.3） |

### 6.2 抽象接口定义

`VideoEncoderBase.h`：

```cpp
#pragma once
#include <cstdint>

enum class VideoCodec { H264, AV1 };
enum class RateControl { CRF, BITRATE };

struct EncoderParams {
    int width;
    int height;
    int fps;
    RateControl rc = RateControl::BITRATE;
    int crf = 23;            // 当 rc == CRF 时使用（x264 路径）
    int bitrate_kbps = 4000; // 当 rc == BITRATE 时使用（硬编路径）
    int gop_seconds = 4;     // 关键帧间隔（秒），编码器内部转 frames
};

class VideoEncoderBase {
public:
    virtual ~VideoEncoderBase() = default;

    virtual bool open(const EncoderParams& params) = 0;
    virtual void close() = 0;

    virtual int encode(
        uint8_t* rgb,
        uint8_t  bpp,
        uint32_t stride,
        uint32_t width,
        uint32_t height,
        uint8_t** lppData,
        uint32_t* lpSize,
        int direction = 1
    ) = 0;

    virtual void forceIDR() = 0;
    virtual void setBitrate(int kbps) {}   // 默认空实现
    virtual VideoCodec codec() const = 0;
    virtual const char* backendName() const = 0;  // "x264" / "h264_nvenc" / "av1_amf" ...
};
```

设计要点：
- **抛弃** `open(w, h, fps, quality)` 的设计 —— `quality` 在 H.264 是 CRF、在硬编是 kbps，语义不清楚是坑
- 改用 `EncoderParams` 结构体 + `RateControl` 枚举，明确指定速率控制模式
- `backendName()` 返回实际后端名（"x264" / "h264_nvenc" / "av1_amf"），调用方可用于日志/监控

### 6.3 CFFmpegH264Encoder 设计

```cpp
#pragma once
#include "VideoEncoderBase.h"
#include <vector>
#include <string>

extern "C" {
#include <libavcodec/avcodec.h>
#include <libavutil/opt.h>
#include <libavutil/imgutils.h>
}

class CFFmpegH264Encoder : public VideoEncoderBase {
public:
    CFFmpegH264Encoder();
    ~CFFmpegH264Encoder() override;

    bool open(const EncoderParams& params) override;
    void close() override;

    int encode(uint8_t* rgb, uint8_t bpp, uint32_t stride,
               uint32_t width, uint32_t height,
               uint8_t** lppData, uint32_t* lpSize,
               int direction = 1) override;

    void forceIDR() override;
    void setBitrate(int kbps) override;
    VideoCodec codec() const override { return VideoCodec::H264; }
    const char* backendName() const override { return m_backend.c_str(); }

private:
    bool tryOpenBackend(const char* name, const EncoderParams& p);
    void cleanupCodec();
    int convertToNV12(uint8_t* rgb, uint8_t bpp, uint32_t stride,
                      uint32_t width, uint32_t height, int direction);

    AVCodecContext* m_ctx     = nullptr;
    AVFrame*        m_frame   = nullptr;
    AVPacket*       m_packet  = nullptr;
    std::vector<uint8_t> m_outputBuffer;
    std::vector<uint8_t> m_i420Scratch;   // RGB24 路径用
    int64_t  m_pts       = 0;
    bool     m_forceIDR  = false;
    std::string m_backend;
};
```

#### 6.3.1 后端探测顺序

```cpp
static const char* kH264Backends[] = {
    "h264_nvenc",   // NVIDIA：质量/速度/稳定性都最好
    "h264_qsv",     // Intel：核显普及度高
    "h264_amf",     // AMD
    "h264_mf",      // Media Foundation 兜底（可选，质量一般）
};

bool CFFmpegH264Encoder::open(const EncoderParams& p) {
    for (auto name : kH264Backends) {
        if (tryOpenBackend(name, p)) {
            m_backend = name;
            return true;
        }
        cleanupCodec();
    }
    return false;
}
```

#### 6.3.2 各后端参数差异

```cpp
bool CFFmpegH264Encoder::tryOpenBackend(const char* name, const EncoderParams& p) {
    const AVCodec* codec = avcodec_find_encoder_by_name(name);
    if (!codec) return false;

    m_ctx = avcodec_alloc_context3(codec);
    if (!m_ctx) return false;

    // 通用参数
    m_ctx->width        = p.width;
    m_ctx->height       = p.height;
    m_ctx->time_base    = {1, p.fps};
    m_ctx->framerate    = {p.fps, 1};
    m_ctx->pix_fmt      = AV_PIX_FMT_NV12;
    m_ctx->gop_size     = p.fps * p.gop_seconds;
    m_ctx->max_b_frames = 0;
    m_ctx->bit_rate     = (int64_t)p.bitrate_kbps * 1000;
    m_ctx->rc_max_rate  = (int64_t)p.bitrate_kbps * 1500;
    m_ctx->rc_buffer_size = (int)(p.bitrate_kbps * 1000);

    if (strcmp(name, "h264_nvenc") == 0) {
        av_opt_set(m_ctx->priv_data, "preset", "p4", 0);
        av_opt_set(m_ctx->priv_data, "tune", "ll", 0);
        av_opt_set(m_ctx->priv_data, "rc", "cbr", 0);
        av_opt_set(m_ctx->priv_data, "zerolatency", "1", 0);
        av_opt_set(m_ctx->priv_data, "delay", "0", 0);
    } else if (strcmp(name, "h264_qsv") == 0) {
        av_opt_set(m_ctx->priv_data, "preset", "medium", 0);
        av_opt_set_int(m_ctx->priv_data, "async_depth", 1, 0);
        av_opt_set_int(m_ctx->priv_data, "low_power", 0, 0);
    } else if (strcmp(name, "h264_amf") == 0) {
        av_opt_set(m_ctx->priv_data, "usage", "lowlatency", 0);
        av_opt_set(m_ctx->priv_data, "quality", "balanced", 0);
        av_opt_set(m_ctx->priv_data, "rc", "cbr", 0);
    } else if (strcmp(name, "h264_mf") == 0) {
        av_opt_set_int(m_ctx->priv_data, "hw_encoding", 1, 0);
        av_opt_set(m_ctx->priv_data, "rate_control", "cbr", 0);
    }

    if (avcodec_open2(m_ctx, codec, nullptr) < 0) return false;

    m_frame = av_frame_alloc();
    m_frame->format = AV_PIX_FMT_NV12;
    m_frame->width  = p.width;
    m_frame->height = p.height;
    if (av_frame_get_buffer(m_frame, 32) < 0) return false;

    m_packet = av_packet_alloc();
    return m_packet != nullptr;
}
```

#### 6.3.3 encode 实现

```cpp
int CFFmpegH264Encoder::encode(
    uint8_t* rgb, uint8_t bpp, uint32_t stride,
    uint32_t width, uint32_t height,
    uint8_t** lppData, uint32_t* lpSize, int direction)
{
    if (av_frame_make_writable(m_frame) < 0) return -1;

    // 像素格式转换（直接用 libyuv，与现有 x264 路径保持一致，不引入 sws_scale）
    int signed_height = direction * (int)height;
    if (bpp == 32) {
        libyuv::ARGBToNV12(
            rgb, stride,
            m_frame->data[0], m_frame->linesize[0],
            m_frame->data[1], m_frame->linesize[1],
            width, signed_height
        );
    } else if (bpp == 24) {
        if (convertToNV12(rgb, bpp, stride, width, height, direction) != 0)
            return -1;
    } else {
        return -2;
    }

    m_frame->pts = m_pts++;

    if (m_forceIDR) {
        m_frame->pict_type = AV_PICTURE_TYPE_I;
        m_frame->key_frame = 1;
        m_forceIDR = false;
    } else {
        m_frame->pict_type = AV_PICTURE_TYPE_NONE;
        m_frame->key_frame = 0;
    }

    if (avcodec_send_frame(m_ctx, m_frame) < 0) return -3;

    int ret = avcodec_receive_packet(m_ctx, m_packet);
    if (ret == AVERROR(EAGAIN)) {
        // 首帧延迟正常情况：返回成功但本次无输出
        *lpSize = 0;
        *lppData = nullptr;
        return 0;
    }
    if (ret < 0) return -4;

    m_outputBuffer.assign(m_packet->data, m_packet->data + m_packet->size);
    *lppData = m_outputBuffer.data();
    *lpSize  = (uint32_t)m_outputBuffer.size();
    av_packet_unref(m_packet);
    return 0;
}
```

#### 6.3.4 RGB24 → NV12（libyuv 无直接 API，两步走）

```cpp
int CFFmpegH264Encoder::convertToNV12(uint8_t* rgb, uint8_t /*bpp*/,
                                      uint32_t stride, uint32_t width, uint32_t height,
                                      int direction)
{
    int signed_height = direction * (int)height;
    int y_size  = width * height;
    int uv_size = (width / 2) * (height / 2);
    m_i420Scratch.resize(y_size + 2 * uv_size);

    uint8_t* y = m_i420Scratch.data();
    uint8_t* u = y + y_size;
    uint8_t* v = u + uv_size;

    libyuv::RGB24ToI420(
        rgb, stride,
        y, width,
        u, width / 2,
        v, width / 2,
        width, signed_height
    );
    libyuv::I420ToNV12(
        y, width,
        u, width / 2,
        v, width / 2,
        m_frame->data[0], m_frame->linesize[0],
        m_frame->data[1], m_frame->linesize[1],
        width, height
    );
    return 0;
}
```

### 6.4 CFFmpegAV1Encoder 设计

结构与 `CFFmpegH264Encoder` **完全对称**，仅 backend 名换：

```cpp
static const char* kAV1Backends[] = {
    "av1_nvenc",   // RTX 40+
    "av1_amf",     // RX 7000+
    "av1_qsv",     // Intel Arc / 部分 11 代+ 核显
};
```

参数差异（av1_nvenc 与 h264_nvenc 略有不同）：

```cpp
if (strcmp(name, "av1_nvenc") == 0) {
    av_opt_set(m_ctx->priv_data, "preset", "p4", 0);
    av_opt_set(m_ctx->priv_data, "tune", "ll", 0);
    av_opt_set(m_ctx->priv_data, "rc", "cbr", 0);
    // AV1 特有：tile-columns/rows 可调，多核解码更友好
    av_opt_set_int(m_ctx->priv_data, "tile-columns", 1, 0);
} else if (strcmp(name, "av1_amf") == 0) {
    av_opt_set(m_ctx->priv_data, "usage", "lowlatency", 0);
    av_opt_set(m_ctx->priv_data, "quality", "balanced", 0);
    av_opt_set(m_ctx->priv_data, "rc", "cbr", 0);
} else if (strcmp(name, "av1_qsv") == 0) {
    av_opt_set(m_ctx->priv_data, "preset", "medium", 0);
    av_opt_set_int(m_ctx->priv_data, "async_depth", 1, 0);
}
```

实现建议：先把 `CFFmpegH264Encoder` 跑通稳定，**再把它复制改名做 AV1 版本**。同步两个类的逻辑可以后续考虑抽公共基类，但不要为了 DRY 提前抽。

### 6.5 EncoderFactory 与探测

`EncoderFactory.h`：

```cpp
#pragma once
#include "VideoEncoderBase.h"
#include <memory>

struct ClientCapability {
    bool supportAV1  = false;
    bool supportH264 = true;   // 假定都支持
};

struct EncoderRequest {
    int width, height, fps;
    int bitrate_kbps;
    ClientCapability client;
};

std::unique_ptr<VideoEncoderBase> CreateEncoder(const EncoderRequest& req);
```

`EncoderFactory.cpp`：

```cpp
#include "EncoderFactory.h"
#include "EncoderProbe.h"
#include "CFFmpegAV1Encoder.h"
#include "CFFmpegH264Encoder.h"
#include "X264Encoder.h"

std::unique_ptr<VideoEncoderBase> CreateEncoder(const EncoderRequest& req) {
    EncoderParams p;
    p.width  = req.width;
    p.height = req.height;
    p.fps    = req.fps;

    // 1. AV1 路径（仅当客户端支持且启动探测确认硬件可用）
    if (req.client.supportAV1 && EncoderProbe::HasAV1Hw()) {
        auto enc = std::make_unique<CFFmpegAV1Encoder>();
        p.rc = RateControl::BITRATE;
        p.bitrate_kbps = req.bitrate_kbps;
        if (enc->open(p)) {
            LOG_INFO("encoder: AV1 backend=%s", enc->backendName());
            return enc;
        }
        LOG_WARN("encoder: AV1 open failed, falling back to H.264");
    }

    // 2. H.264 硬编路径
    if (EncoderProbe::HasH264Hw()) {
        auto enc = std::make_unique<CFFmpegH264Encoder>();
        p.rc = RateControl::BITRATE;
        p.bitrate_kbps = req.bitrate_kbps;
        if (enc->open(p)) {
            LOG_INFO("encoder: H264-HW backend=%s", enc->backendName());
            return enc;
        }
        LOG_WARN("encoder: H264 HW open failed, falling back to x264");
    }

    // 3. H.264 软编兜底（始终可用）
    {
        auto enc = std::make_unique<CX264Encoder>();
        p.rc = RateControl::CRF;
        p.crf = BitRateToCRF(req.bitrate_kbps);
        if (enc->open(p)) {
            LOG_INFO("encoder: H264-SW (libx264)");
            return enc;
        }
    }

    LOG_ERROR("encoder: all backends failed");
    return nullptr;
}
```

要点：
- **不要**引入会话池（`HEVCSessionPool` 那套）—— 个人项目场景下不需要
- NVENC session 限制由 FFmpeg 自己报错，工厂捕获后自动降级
- 失败路径都打日志，方便定位

### 6.6 启动时一次性后端探测

避免每个新连接都重复尝试每个 backend：

```cpp
// EncoderProbe.h
class EncoderProbe {
public:
    static void RunOnce();                 // 程序启动时调用一次
    static bool HasAV1Hw();
    static bool HasH264Hw();
    static const char* PreferredAV1Backend();   // 第一个能用的 AV1 后端名
    static const char* PreferredH264Backend();
};

// EncoderProbe.cpp 实现思路：
// 对每个候选后端尝试 alloc_context → open2 → free
// 用最低分辨率（如 640x480 @30fps）减少探测开销
// 结果缓存在静态变量，加 std::once_flag 保证线程安全
```

启动时探测 1 次，运行时 `CreateEncoder` 直接读结果。

### 6.7 ScreenCapture.h 改造

**当前**（`client/ScreenCapture.h:148, 926-930, 956-960`）：
```cpp
CX264Encoder* m_encoder;
// ...
m_encoder = new CX264Encoder();
int br = (m_nBitRate > 0) ? m_nBitRate : (width * height / 1266);
m_encoder->open(width, height, 20, BitRateToCRF(br));
```

**改造后**：
```cpp
std::unique_ptr<VideoEncoderBase> m_encoder;
ClientCapability m_clientCap;   // 握手阶段填入
// ...
if (!m_encoder) {
    EncoderRequest req{
        (int)width, (int)height, 20,
        m_nBitRate > 0 ? m_nBitRate : (int)(width * height / 1266),
        m_clientCap
    };
    m_encoder = CreateEncoder(req);
    if (!m_encoder) return nullptr;
}
int err = m_encoder->encode(nextData, 32, 4 * width, width, height,
                            &encoded_data, &encoded_size);
```

注意：两处 `new CX264Encoder()` 提取成一个 `ensureEncoder()` 私有方法，避免重复。

### 6.8 协议握手（阶段二）

客户端浏览器 WebSocket 连接时上报：

```json
{
  "type": "client_capability",
  "codecs": ["av1", "h264"]
}
```

浏览器端探测脚本（JS）：

```javascript
async function probeBrowserCodecs() {
    const codecs = [];
    if (typeof VideoDecoder !== 'undefined') {
        // AV1 Main Profile, Level 4.0, 8-bit
        const av1 = await VideoDecoder.isConfigSupported({ codec: 'av01.0.04M.08' });
        if (av1.supported) codecs.push('av1');
    }
    codecs.push('h264');   // 兜底假定支持，<video> 标签也支持
    return codecs;
}
```

**向后兼容**：老版本客户端不发 `codecs` 字段 → 服务端按 H.264 处理。`ClientCapability::supportAV1` 默认 false。

可参考 `docs/hevc_browser_decode_test.html`（改造一份 AV1 版本）做浏览器解码端到端验证。

---

## 7. 像素格式与转换

保持与现有 x264 路径完全一致的做法：

- **硬编内部格式**：`AV_PIX_FMT_NV12`（NVENC/QSV/AMF 通用）
- **转换库**：libyuv（不引入 `sws_scale`）
- **BGRA → NV12**：`libyuv::ARGBToNV12` 直接
- **RGB24 → NV12**：libyuv 无直接 API，分两步 RGB24 → I420 → NV12
- **direction 参数**：沿用现有 `X264Encoder.cpp:136` 的写法（`direction * height` 作为乘子）

---

## 8. 测试要求

### 8.1 单元测试

- `VideoEncoderBase` 各实现的 `open / encode / close` 生命周期
- `CFFmpegH264Encoder` 在缺失各后端时降级到下一个
- `EncoderFactory` 在不同 `ClientCapability` × 硬件能力 矩阵下返回正确后端
- `EncoderProbe::RunOnce()` 在不同 GPU 上的结果一致性

### 8.2 集成测试

| 场景 | 期望 |
|---|---|
| 客户端支持 AV1 + 编码端 RTX 40 | 使用 AV1（`av1_nvenc`） |
| 客户端支持 AV1 + 编码端 GTX 1080 | 降级 H.264 硬编（`h264_nvenc`） |
| 客户端不支持 AV1 + 编码端任意 | H.264（硬编优先） |
| 编码端无 GPU / 虚拟机 | x264 软编 |
| 编码端集显 + 独显 | 优先级中第一个成功的后端 |
| 中途客户端能力变化 | 当前连接不变；下次握手按新能力 |
| H264 硬编创建失败 | 自动回落 x264 软编，连接不断 |

### 8.3 硬件验证矩阵

| 编码端 | 客户端浏览器 | 期望 |
|---|---|---|
| RTX 40 / 50 | Chrome / Firefox / Edge | AV1 |
| GTX 10/16 / RTX 20/30 | Chrome / Firefox / Edge | H.264 NVENC |
| Intel Arc | Chrome / Firefox | AV1（`av1_qsv`） |
| Intel 12 代+ 核显 | Chrome / Firefox | H.264 QSV |
| AMD RX 7000+ | Chrome / Firefox | AV1（`av1_amf`） |
| AMD 老卡 | Chrome / Firefox | H.264 AMF |
| 虚拟机 / 远程桌面会话 | 任意 | x264 软编 |
| iOS Safari < 17 | 任意编码端 | H.264 |
| iOS Safari ≥ 17（A17 Pro+） | 任意编码端 | AV1 优先 |

### 8.4 体积验证

- exe 体积增量 < 12 MB（vcpkg 静态链接，含 AV1+H264 全后端）
- 若超出明显，检查 vcpkg feature 是否引入了不需要的 codec

### 8.5 回归测试（关键）

每一步改造后必须验证：
- 现有 x264 软编通路完全可用（在禁用所有硬编后端的环境下）
- 现有客户端（不发 `codecs` 字段）可正常工作
- 编码码流向后兼容，老客户端能解

---

## 9. 已知风险与注意事项

### 9.1 多 GPU 跨适配器
笔记本集显+独显场景，FFmpeg 默认走主显卡。可能报 "failed to create device"。**Catch 后回落到下一个后端**，不要直接终止。

### 9.2 第一帧延迟
FFmpeg 硬编可能在首次 `send_frame` 后 `receive_packet` 返回 `EAGAIN`。调用方代码必须能处理 `*lpSize == 0` 的情况（返回 0 表示成功但本次无输出）。`ScreenCapture::GetNextScreenData` 当前 `encoded_size == 0` 会怎么处理需要确认。

### 9.3 NVENC session 数限制
NVIDIA **消费级**卡（GeForce）有 NVENC session 上限（驱动 522.25+ 起 3 个，更新版可能放宽到 5）。多连接超限时 `open` 失败 → 工厂自动降级到 QSV/AMF/x264。**不要做"会话池"提前拦截** —— 让 FFmpeg 自己报错，工厂处理。

### 9.4 浏览器解 AV1 的硬件依赖
- 桌面 Chrome/Firefox/Edge：软解兜底（CPU 占用高，但能用）
- 移动端：iPhone 15 Pro+ / M3+ 才有 AV1 硬解，老设备只能软解（可能卡）
- `isConfigSupported` 报 true 不等于跑得流畅。**建议握手时也带上设备类型**，弱设备强制走 H.264

### 9.5 LGPL 静态链接合规
个人项目暂搁置。商用前需法务确认（FFmpeg 源代码提供、重新链接能力等）。

### 9.6 配置项（建议）

建议做成 INI/JSON：
```
encoder.prefer_av1            = true
encoder.h264.bitrate_default  = 4000   (kbps)
encoder.fallback_to_x264      = true
encoder.probe_at_startup      = true
encoder.disable_h264_mf       = true   (h264_mf 质量一般，可禁用)
```

### 9.7 日志要求

关键路径必须有日志：
- 启动探测结果：每个后端是否可用 + 失败原因（`av_err2str`）
- 每个连接选定的 `codec` + `backend`（INFO）
- 后端打开失败 + 回落（WARN）
- 编码过程中的异常（ERROR）

### 9.8 线程安全
- 每个编码器实例不跨线程
- `EncoderProbe` 单例首次初始化加 `std::once_flag`
- FFmpeg 新版本不需要全局初始化（`av_register_all` 已废弃）

### 9.9 与现有 `DISABLE_X264_FOR_TEST` 编译开关协同
项目已有 `DISABLE_X264_FOR_TEST` 宏（见 `X264Encoder.cpp:5`）和最近 `c0a632a` 提交"Compliance: Add building option to disable x264 and ffmpeg"。新代码须遵循同样的可禁用约定：
- `ENABLE_HW_ENCODER` 关闭时整个 `CFFmpegH264Encoder` / `CFFmpegAV1Encoder` 编译为空实现或不参与链接
- 工厂在该宏关闭时直接返回 `CX264Encoder`

---

## 10. 实现顺序建议

**每一步独立可合入**，每一步完成后 x264 通路必须可用、客户端无感知。

### Step 0：抽象层（零功能改动）
1. 新建 `VideoEncoderBase.h`，定义接口 + `EncoderParams` + `RateControl`
2. `CX264Encoder` 改造继承 `VideoEncoderBase`：
   - 新增 `forceIDR()`（设置一个标志，下次 encode 时通过 `x264_picture_t::i_type = X264_TYPE_IDR`）
   - 实现 `codec()` 返回 `H264`
   - 实现 `backendName()` 返回 `"x264"`
   - 旧 `open(w, h, fps, crf)` 签名保留，转调新的 `open(EncoderParams)`
3. `ScreenCapture::m_encoder` 改 `std::unique_ptr<VideoEncoderBase>`，但仍直接 `new CX264Encoder`
4. **不引 FFmpeg、不引工厂**
5. 验证：H.264 通路完全不变，对外行为零变化

### Step 1：FFmpeg 集成 + `h264_nvenc` 单后端
1. vcpkg 安装 `ffmpeg[core,nvcodec]:x64-windows-static-md`
2. 工程添加包含目录 / 库目录 / 系统库
3. 新建 `CFFmpegH264Encoder`，仅实现 `h264_nvenc`
4. 在 `ScreenCapture` 加临时开关：硬编码切到 `CFFmpegH264Encoder` 跑一下
5. 用浏览器解码 demo 验证码流能解
6. 体积验证（应 +4–6 MB）

### Step 2：扩展 H.264 硬编后端
1. `CFFmpegH264Encoder` 加 `h264_qsv` / `h264_amf` 探测
2. 顺序：`nvenc → qsv → amf`（`mf` 可暂不接）
3. 不同后端的参数适配（见 §6.3.2）
4. 测试 Intel 核显 + AMD 卡

### Step 3：工厂 + 软编兜底
1. 新建 `EncoderFactory` / `EncoderProbe`
2. 工厂按 `H264 硬编 → x264 软编` 顺序
3. `ScreenCapture` 改用工厂（消除两处 `new CX264Encoder`）
4. 测试无 GPU 环境降级到 x264

### Step 4：AV1 路径（独立闭环）
1. 重跑 vcpkg：`ffmpeg[core,nvcodec,amf,qsv]:x64-windows-static-md`
2. 新建 `CFFmpegAV1Encoder`，结构与 H.264 对称（直接 copy + 改 backend 名 + 调参）
3. `EncoderProbe` 加 AV1 探测
4. 工厂前置 AV1 路径
5. 硬件验证矩阵执行

### Step 5：握手协商 + 浏览器探测
1. 客户端 JS `isConfigSupported` 探测 AV1 / H.264
2. WebSocket 握手字段 `codecs` 上报
3. 服务端解析后填入 `ClientCapability`
4. 老客户端向后兼容（无 `codecs` 字段 → 默认 H.264）
5. 端到端验证：编码端 RTX 40 + 浏览器 Chrome 走 AV1，回落场景走 H.264

---

## 11. 不在本次范围

- HEVC 编码（决策已排除，见 §1.3.1）
- 软编 AV1（libaom / SVT-AV1，CPU 占用不适合远控）
- 运行中动态切换 codec（需要切换就重连）
- 转发流（1 路编码多路分发）
- 桌面捕获共享
- 客户端浏览器解码具体实现（可参考 `docs/hevc_browser_decode_test.html` 改 AV1 版本验证）
- Linux/macOS 移植
- FFmpeg DLL 形式分发

---

## 12. 参考资料

- FFmpeg 编码器列表：`ffmpeg -encoders | grep -E "h264|av1"`
- NVENC 参数：`ffmpeg -h encoder=h264_nvenc`、`ffmpeg -h encoder=av1_nvenc`
- QSV 参数：`ffmpeg -h encoder=h264_qsv`、`ffmpeg -h encoder=av1_qsv`
- AMF 参数：`ffmpeg -h encoder=h264_amf`、`ffmpeg -h encoder=av1_amf`
- NVIDIA Video Codec Support Matrix：https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new
- WebCodecs API：https://developer.mozilla.org/en-US/docs/Web/API/WebCodecs_API
- libyuv：https://chromium.googlesource.com/libyuv/libyuv/
- vcpkg ffmpeg port：https://github.com/microsoft/vcpkg/tree/master/ports/ffmpeg
- FFmpeg HWAccel Intro：https://trac.ffmpeg.org/wiki/HWAccelIntro
- AOMedia AV1：https://aomedia.org/

---

**文档结束**

实现时如遇到本文档未覆盖的设计抉择，优先选择**简单、与现有 x264 通路对称、不破坏已有功能、不增加运行时外部依赖**的方案，并在代码注释中说明决策依据。