readme.md

# DCU Codec Pipeline Benchmark

DCU编解码性能测试工具 - 用于测试和评估不同编解码器后端的视频处理性能。

## 项目简介

该项目是DCU性能压测工具codecbenchmark的python实现，可作为DCU上MacCodecSDK以及ffmpeg的python api参考

## 主要功能

### 核心特性
- ✅ **多后端支持**：支持 CUDA、CUVID、V4L2、VAAPI 等多种编解码后端
- ✅ **编解码测试**：支持 H264、HEVC、VP9、AVS2、MJPEG 等格式的编解码性能测试
- ✅ **多实例并发**：支持多线程并发测试，评估系统并发处理能力
- ✅ **多分辨率支持**：支持从 720p 到 8K 的多种分辨率测试
- ✅ **位深测试**：支持 8-bit 和 10-bit 位深测试
- ✅ **详细报告**：生成 CSV 格式的性能测试报告

### 支持的编解码器

**解码器：**
- H264 (h264_cuvid/h264_v4l2m2m)
- HEVC (hevc_cuvid/hevc_v4l2m2m)
- VP9 (vp9_cuvid/vp9_v4l2m2m)
- AVS2 (avs2_cuvid/avs2_v4l2m2m)
- MJPEG (mjpeg_cuvid/mjpeg_v4l2m2m)

**编码器：**
- H264_NVENC / H264_VAAPI
- HEVC_NVENC / HEVC_VAAPI
- VP9_NVENC / VP9_VAAPI
- MJPEG_NVENC / MJPEG_VAAPI

## 环境要求

与MacCodec环境要求一致

### 依赖安装

```bash
pip install -r requirements.txt
```

主要依赖：
- ffmpeg-python
- MacCodecSDK

## 项目结构

其中测试视频文件为方便clone测试仅包含一个文件，若想参考codecBenchmark全面测试可将所有文件放入同目录下，并取消代码中的注释
```
dcu-codec-pipeline-py/
├── codecbenchmark-py/
│   ├── video_benchmark/          # 测试视频文件目录
│   │   └── sample_1920x1080_30fps_8bit.h264
│   ├── benchmark_multi_inst.py   # 多实例测试模块
│   ├── video_benchmark.py        # 主测试脚本
│   ├── readme.md                 # 项目说明
│   └── requirements.txt          # 依赖列表
├── video_cuda_decode_benchmark.csv  # 解码测试结果
└── video_cuda_encode_benchmark.csv  # 编码测试结果
```

## 使用方法

### 基本用法

运行解码和编码性能测试：

```bash
# 使用 CUDA 后端，默认 6 线程
python video_benchmark.py

# 指定后端和线程数
python video_benchmark.py -c cuda -n 8
python video_benchmark.py -c vaapi -n 4
python video_benchmark.py -c v4l2 -n 6
```

### 命令行参数

```bash
usage: video_benchmark.py [-h] [-c {cuda,cuvid,v4l2,vaapi}] [-n THREADS]

可选参数:
  -h, --help            显示帮助信息
  -c, --codec           编解码后端类型
                        可选值: cuda, cuvid, v4l2, vaapi
                        默认值: cuda
  -n, --threads         并发进程数量
                        默认值: 6
```

## 测试配置

### 解码测试文件

项目预配置了以下测试文件：
- `sample_1920x1080_30fps_8bit.h264` - 1080p 30fps H264 8bit

### 编码测试配置

支持多种分辨率和格式的编码测试：

| 分辨率 | 格式 | 位深 | 帧数 |
|--------|------|------|------|
| 1280x720 | H264/HEVC | 8-bit | 677 |
| 1920x1080 | H264/HEVC/JPEG | 8-bit | 812-2174 |
| 3840x2160 | H264/HEVC/JPEG | 8-bit | 812 |
| 7680x4320 | H264/HEVC | 8-bit | 77 |
| 1280x720 | HEVC | 10-bit | 677 |
| 1920x1080 | HEVC | 10-bit | 812 |
| 3840x2160 | HEVC | 10-bit | 812 |
| 4096x2160 | JPEG | 8-bit | 1 |
| 8192x4320 | JPEG | 8-bit | 1 |

## 输出结果

### CSV 报告文件

测试完成后会生成两个 CSV 文件：

1. **解码测试报告** (`video_{codec}_decode_benchmark.csv`)
   ```csv
   Decode,Bit Depth,Resolution,Fps/(BMZ 1 Core),Fps/(BMZ 6 Processes)
   H264,8,1920x1080,245.67,1234.56
   ```

2. **编码测试报告** (`video_{codec}_encode_benchmark.csv`)
   ```csv
   Encode,Bit Depth,Resolution,Fps/(BMZ 1 Core)
   H264,8,1920x1080,189.34
   HEVC,10,3840x2160,95.67
   ```

### 性能指标说明

- **Fps/(BMZ 1 Core)**: 单核心/单进程处理的帧率（FPS）
- **Fps/(BMZ N Processes)**: N 个并发进程总处理的帧率（FPS）

## 测试流程

1. **解压测试文件**：自动从 `video_benchmark.zip` 解压测试视频
2. **解码测试**：
   - 单实例解码性能测试
   - 多实例并发解码测试
3. **编码测试**：
   - 将解码后的 YUV 数据重新编码
   - 测试不同格式和分辨率的编码性能
4. **结果聚合**：
   - 统计平均性能数据
   - 生成 CSV 报告
5. **清理临时文件**：自动清理测试过程中生成的临时文件

## 示例输出

```
Processing: sample_1920x1080_30fps_8bit.h264 (Idx: 1)
  -> Single instance decode: 245.67 FPS
  -> Multi instance (6 processes): 1234.56 FPS
Encoding: sample_1920x1080_30fps_8bit.h264 -> H264
  -> Encode performance: 189.34 FPS

Aggregating results...
Benchmark finished.
```

## 注意事项

1. **文件准备**：确保测试视频文件位于 `video_benchmark/` 目录或提供 `video_benchmark.zip`
2. **权限要求**：使用 VAAPI/V4L2 后端时可能需要访问 `/dev/dri/renderD128` 设备文件
3. **性能影响**：多实例测试会占用较多系统资源，建议根据硬件配置调整线程数
4. **日志文件**：测试过程会生成临时日志文件，测试完成后自动清理

## 故障排除

### 常见问题

**问题 1**: `FFmpeg command construction failed`
- 检查 FFmpeg 是否正确安装
- 确认选择的编解码后端是否受支持

**问题 2**: `Unknown encoder for XXX`
- 确认 FFmpeg 编译时启用了相应的编码器
- 检查硬件驱动是否正确安装

**问题 3**: 多实例测试性能异常
- 检查系统资源（GPU、内存）是否充足
- 减少并发线程数 `-n` 参数

### 日志调试

测试过程中的详细日志会保存在：
- 解码日志：`video_benchmark/{filename}.log`
- 多实例日志：`video_benchmark/{filename}_multi.log`
- 编码日志：`video_benchmark/{filename}_encode.log`

## 许可证

本项目仅供性能测试和评估使用。

## 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。

---

**版本**: 1.0  
**最后更新**: 2026-02-26