ProPainter 参数详解

基础命令格式

python inference_propainter.py [必需参数] [可选参数]

---

必需参数

--video

指定输入视频或视频帧文件夹

支持格式：

• 视频文件：.mp4、.avi、.mov 等
• 帧文件夹：包含按顺序命名的图片（如 0001.jpg、0002.jpg）

示例：

--video inputs/test.mp4
--video inputs/frames_folder

--mask

指定遮罩文件或遮罩文件夹

支持格式：

• 单张遮罩：.png 图片（用于固定位置修复）
• 遮罩文件夹：包含与视频帧对应的遮罩序列

遮罩规则：

• 白色（255）：需要修复的区域
• 黑色（0）：保留的区域

示例：

--mask inputs/mask.png
--mask inputs/mask_folder

---

分辨率控制参数

--width

指定处理宽度（像素）

作用：

• 将视频缩放到指定宽度再处理
• 降低分辨率可减少显存占用和处理时间

默认值：使用原视频宽度

示例：

--width 640

--height

指定处理高度（像素）

作用：

• 将视频缩放到指定高度再处理
• 通常与 --width 配合使用

默认值：使用原视频高度

示例：

--height 360

分辨率建议（5090 显卡）：

• 1080p 视频：可直接处理，无需降低分辨率
• 2K/4K 视频：建议缩放到 1080p 或 720p
• 测试阶段：可用 480p 快速验证效果

---

时序参数

--neighbor_length

邻域帧数量

作用：

• 指定用于参考的前后帧数量
• 更多邻域帧可提高修复质量，但增加计算量

默认值：10

取值范围：5-20

示例：

--neighbor_length 15

调优建议：

• 静态场景（字幕去除）：10-12 即可
• 动态场景（物体移除）：15-20 效果更好
• 快速测试：5-8 可加快速度

--ref_stride

参考帧步长

作用：

• 控制参考帧的采样间隔
• 较大步长可覆盖更长时间范围，但可能跳过关键帧

默认值：10

取值范围：5-30

示例：

--ref_stride 15

调优建议：

• 慢动作视频：5-10（帧间变化小）
• 正常速度：10-15
• 快速运动：15-30（需要更大时间跨度）

---

输出参数

--save_frames

保存处理后的视频帧

作用：

• 除了输出视频文件，还保存每一帧的图片
• 用于后期精修或质量检查

默认值：False（不保存）

示例：

--save_frames

输出位置：

results/
└── {视频名称}_frames/
    ├── 0001.png
    ├── 0002.png
    └── ...

--fps

输出视频帧率

作用：

• 指定输出视频的帧率
• 不影响处理过程，仅影响最终视频播放速度

默认值：使用原视频帧率

示例：

--fps 30

---

模型参数

--ckpt

指定模型权重文件路径

作用：

• 使用自定义训练的模型
• 或指定不同版本的预训练模型

默认值：weights/ProPainter.pth（自动下载）

示例：

--ckpt weights/custom_model.pth

--use_half

使用半精度（FP16）推理

作用：

• 减少显存占用约 50%
• 提升推理速度约 30-50%
• 对效果影响极小

默认值：False

示例：

--use_half

5090 建议：

• 1080p 以下：不需要开启
• 2K/4K 视频：建议开启以节省显存
• 批量处理：建议开启以提高吞吐量

---

高级参数

--mask_dilation

遮罩膨胀系数

作用：

• 自动扩大遮罩的白色区域
• 确保完全覆盖目标物体边缘

默认值：4

取值范围：0-20

示例：

--mask_dilation 8

调优建议：

• 遮罩精确：4-6
• 遮罩偏小：8-12
• 边缘模糊：0-2

--subvideo_length

子视频长度（帧数）

作用：

• 将长视频分段处理，避免显存溢出
• 每段独立处理后拼接

默认值：80

取值范围：40-200

示例：

--subvideo_length 120

5090 建议：

• 1080p：120-150
• 2K：80-100
• 4K：40-60

---

实战示例

场景1：去除视频字幕（5090 最优配置）

python inference_propainter.py \
  --video inputs/video.mp4 \
  --mask inputs/subtitle_mask.png \
  --neighbor_length 12 \
  --ref_stride 10 \
  --mask_dilation 6

场景2：移除移动物体（高质量）

python inference_propainter.py \
  --video inputs/frames \
  --mask inputs/masks \
  --neighbor_length 20 \
  --ref_stride 15 \
  --subvideo_length 100

场景3：4K 视频处理（显存优化）

python inference_propainter.py \
  --video inputs/4k_video.mp4 \
  --mask inputs/mask.png \
  --width 1920 \
  --height 1080 \
  --use_half \
  --subvideo_length 60

场景4：快速测试（低分辨率）

python inference_propainter.py \
  --video inputs/test.mp4 \
  --mask inputs/mask.png \
  --width 640 \
  --height 360 \
  --neighbor_length 8 \
  --ref_stride 8

---

参数调优流程

1. 基础测试：使用默认参数处理短片段（5-10秒）
2. 质量优化：增加 neighbor_length 和 ref_stride
3. 遮罩调整：根据边缘效果调整 mask_dilation
4. 性能优化：根据显存使用情况调整分辨率和 subvideo_length
5. 最终处理：使用优化后的参数处理完整视频

---

常见问题

显存不足（OOM）：

• 降低分辨率（--width --height）
• 开启半精度（--use_half）
• 减小子视频长度（--subvideo_length）

边缘有残留：

• 增加遮罩膨胀（--mask_dilation）
• 检查遮罩是否完全覆盖目标

时序不连贯（闪烁）：

• 增加邻域帧数（--neighbor_length）
• 调整参考帧步长（--ref_stride）

处理速度慢：

• 开启半精度（--use_half）
• 降低分辨率
• 减少邻域帧数