ffmpeg-gui/设计文档.md

# FFmpeg-GUI 设计文档

---

## 技术栈

C++ + Dear ImGui + FFmpeg Library

---

## 1. 产品定位

FFmpeg-GUI 是一个面向高级用户的视频处理工具。

UI 设计目标：

- 简洁
- 高效
- 专业
- 低干扰
- 强信息表达

整体风格：

> 现代化扁平设计（Modern Flat Design）

参考方向：

- VS Code
- JetBrains IDE
- Blender
- OBS Studio
- Figma

---

## 2. 架构设计

### 2.1 底层模块划分

```text
UI层（Dear ImGui）
 |
业务层
 |
FFmpeg封装层
 |
硬件/系统层
```

### 2.2 FFmpeg 核心封装层

不应该让业务直接调用底层 FFmpeg API：

```cpp
avcodec_xxx()
avformat_xxx()
```

应该封装为统一接口：

```
FFmpeg Core

├── Decoder
├── Encoder
├── Muxer
├── Filter
└── MediaInfo
```

提供高层 API：

```
Encode()
Remux()
BurnSubtitle()
Analyze()
```

上层不关心 FFmpeg 内部细节。

---

## 3. 功能模块设计

### 3.1 媒体信息分析（Media Analyzer）

**功能说明：** 解析输入媒体文件信息，为其他模块提供媒体数据。

**支持信息：**

| 类别 | 字段 |
|------|------|
| 视频 | 编码格式、分辨率、帧率、比特率、色彩空间、HDR信息、视频流数量 |
| 音频 | 编码格式、声道、采样率、比特率、音轨数量 |
| 字幕 | 字幕格式、字幕语言、字幕数量 |

**输出提供给：** 重新封装、重新编码、字幕烧录

---

### 3.2 重新封装（Remux）

**功能说明：** 仅修改媒体容器，不改变媒体编码。

```text
示例：MKV → MP4 | MOV → MP4 | TS → MKV
```

**操作流程：**

1. 选择输入文件
2. 选择输出格式（MP4、MKV、MOV、TS）
3. 选择媒体流处理

| 流类型 | 操作 |
|--------|------|
| 视频 | Copy / 删除 |
| 音频 | Copy / 删除 |
| 字幕 | Copy / 删除 |

4. 开始任务

> ⚠ 重新封装不涉及编码，因此不需要 GPU 选择、编码参数。

---

### 3.3 重新编码（Encoder）

**功能说明：** 重新压缩视频流。

**支持：**

| 编码格式 | 编码方式 |
|----------|----------|
| H264、H265、AV1 | NVIDIA NVENC、Intel QSV、AMD AMF、CPU Software |

**操作流程：**

1. 选择输入文件
2. 选择输出格式（MP4、MKV）
3. 选择编码器（如：RTX 4090 → HEVC NVENC）
4. 设置编码参数

| 类别 | 参数 |
|------|------|
| 基础 | 编码格式、质量模式、Preset、Profile、Level |
| 视频 | 分辨率、帧率、比特率 |
| 音频 | Copy / 重新编码 |

5. 开始任务

---

### 3.4 字幕烧录（Subtitle Burn）

**功能说明：** 通过 FFmpeg Filter 将字幕渲染到视频，字幕成为视频画面的一部分。

**操作流程：**

1. 选择视频文件
2. 选择字幕文件（ASS、SSA、SRT）
3. 设置字幕参数（字体、字号、位置、编码）
4. 选择输出格式
5. 选择编码器
6. 开始任务

---

### 3.5 硬件管理（Hardware Manager）

**GPU 检测：** 支持 NVIDIA、Intel、AMD

```text
GPU → 支持编码 → 可用参数
```

**示例：**

```
RTX 4090
支持: H264 NVENC | HEVC NVENC | AV1 NVENC
```

**硬件优先级：**

```
1. NVIDIA GPU
2. Intel QSV
3. CPU
```

**程序内部：**

```
Hardware Manager
        |
        ↓
Encoder List

hevc_nvenc
av1_nvenc
h264_qsv
libx265
```

---

### 3.6 任务管理（Task Manager）

**功能说明：** 管理 FFmpeg 工作任务。

| 功能 | 说明 |
|------|------|
| 任务创建 | 添加任务、设置任务参数 |
| 任务控制 | 开始、暂停、停止、删除 |
| 状态 | 等待、执行中、已完成、失败、已取消 |
| 显示信息 | 当前文件、操作类型、编码器、当前帧、FPS、进度、剩余时间 |

---

### 3.7 软件设置

| 分类 | 设置项 |
|------|--------|
| 硬件设置 | GPU检测、GPU优先级、默认编码器 |
| 输出设置 | 默认输出目录、文件命名规则 |
| UI设置 | 主题、深色/浅色 |

---

## 4. 整体布局设计

### 4.1 主窗口结构

```
┌──────────────────────────────┐
│ FFmpeg-GUI                   │
├──────────────┬───────────────┤
│              │               │
│ 功能导航     │ 参数配置区域  │
│              │               │
│              │               │
├──────────────┴───────────────┤
│ 任务状态区域                 │
└──────────────────────────────┘
```

---

### 4.2 页面区域设计

#### 顶部标题栏

- **功能：** 软件名称、当前模块名称、全局状态
- **高度：** 40px - 50px
- **风格：** 简洁、无复杂按钮、弱视觉存在

```
FFmpeg-GUI        Encode
```

#### 左侧功能栏

- **用途：** 切换主要功能（重新封装、重新编码、字幕烧录）
- **宽度：** 160px - 220px

| 状态 | 样式 |
|------|------|
| 默认 | 灰色文字 + 低亮度背景 |
| 选中 | 强调色背景 + 白色文字 |

```
┌──────────┐
│          │
│ ▶ 编码   │
│          │
│   封装   │
│          │
│   字幕   │
│          │
└──────────┘
```

#### 参数配置区域

核心操作区域，采用分组 + 卡片 + 折叠区域的布局方式：

```
输入文件

┌────────────────┐
│ video.mkv      │
└────────────────┘

编码设置

┌────────────────┐
│ HEVC NVENC ▼   │
└────────────────┘
```

#### 任务区域

固定底部，不影响参数修改，支持多任务显示：

```
任务

video01.mkv

HEVC NVENC

██████████──── 70%

FPS:120
剩余时间:03:20
```

---

## 5. 设计原则

### 5.1 扁平化

| 避免 | 采用 |
|------|------|
| 复杂渐变 | 单色背景 |
| 高光效果 | 简洁边界 |
| 拟物化按钮 | 清晰层级 |
| 大量阴影 | 少量强调色 |

### 5.2 工具化设计

软件不是娱乐应用，而是生产力工具。

**重点突出：**
- 当前任务状态
- 当前配置
- 操作反馈

**减少：**
- 装饰元素
- 无意义动画
- 复杂导航

### 5.3 信息密度适中

FFmpeg 需要显示大量参数，设计目标：

> 更多信息 + 清晰层级 + 快速定位

**避免：** 大面积留白、过大的控件、过多卡片嵌套

---

## 6. 色彩设计

**默认主题：暗色主题**

原因：视频工具常用暗色环境，减少视觉疲劳，符合专业软件习惯。

### 6.1 基础颜色

| 用途 | 色值 |
|------|------|
| 背景 | `#181818` |
| 面板 | `#202020` |
| 输入框 | `#2A2A2A` |
| 边框 | `#383838` |
| 主要文字 | `#FFFFFF` |
| 次级文字 | `#AAAAAA` |

### 6.2 强调色

| 用途 | 色值 | 场景 |
|------|------|------|
| 蓝色 | `#3B82F6` | 当前选择、操作按钮、状态提示 |
| 绿色 | `#22C55E` | 成功 |
| 红色 | `#EF4444` | 错误 |
| 黄色 | `#EAB308` | 警告 |

---

## 7. 控件设计

### 7.1 按钮

- **风格：** 扁平、圆角、无立体效果
- **高度：** 32px - 40px

| 状态 | 样式 |
|------|------|
| 默认 | 深色背景 |
| Hover | 增加亮度 |
| Active | 强调色 |

### 7.2 输入框

- 深色背景、弱边框、清晰焦点状态

```
┌────────────────┐
│ input.mp4      │
└────────────────┘
```

### 7.3 下拉框

用于编码器选择、输出格式、Preset 等，设计为简洁文本选择器。

### 7.4 进度条

- **用途：** 任务状态显示
- **要求：** 清晰、不抢占视觉

```
████████────── 60%
```

---

## 8. 图标设计

- **风格：** 线性图标、简洁、单色
- **避免：** 彩色复杂图标、过度装饰
- **使用场景：** 文件选择、删除任务、设置、开始任务

---

## 9. 字体设计

**原则：** 清晰优先。

| 平台 | 推荐字体 |
|------|----------|
| Windows | Segoe UI |
| 跨平台 | Noto Sans |

**字体层级：**

| 用途 | 字号        |
|------|-------------|
| 标题 | 20px - 24px |
| 正文 | 16px        |
| 辅助信息 | 16px        |

---

## 10. 动效设计

轻量动画。

| 允许 | 避免 |
|------|------|
| 页面切换、状态变化、进度变化 | 大量动画、弹跳效果、装饰动画 |

---

## 11. 状态反馈

任务状态与颜色对照：

| 状态 | 颜色 |
|------|------|
| 等待 | 灰色 |
| 运行 | 蓝色 |
| 完成 | 绿色 |
| 失败 | 红色 |
| 取消 | 黄色 |

```
● Encoding
● Completed
● Failed
```

---

## 12. 整体视觉关键词

```
现代 · 扁平 · 专业 · 克制 · 高信息密度 · 工具化 · 暗色 · 低干扰
```

> 打开软件后，用户可以快速选择操作、配置参数、执行任务，并清晰看到 FFmpeg 当前状态。

---

## 13. 实现范围

### 核心必须

```
媒体信息分析
FFmpeg Core 封装
重新封装
重新编码
字幕烧录
硬件管理
任务管理
```