视频黑边裁剪
更新时间：2026-06-15
简介
视频黑边裁剪算子，自动检测并裁剪视频画面四周的黑色边框区域，提升画面利用率和视觉一致性。支持多种检测算法，适用于老片修复、内容上传等场景。
功能描述
- 多种检测算法：支持阈值比例、边缘检测、直方图三种黑边检测算法，适应不同视频内容
- 智能核心区域保护：自动保护视频中心区域，避免误裁剪重要内容
- 连续黑边过滤：可配置连续黑边行/列阈值，过滤掉小范围黑色区域
- 音频保留：可选择是否保留原始音频流
- 批量处理：支持对多个视频文件并行处理
- CPU环境即可运行，无需GPU
- 视频上传前的预处理（去除平台黑边）
- 老旧视频修复（去除胶片黑边）
- 内容平台适配（统一画面比例）
- 视频分析预处理（减少无效区域干扰）
- 视频压缩优化（去除冗余黑边区域）
- 帧处理仅做统计与坐标计算，不会修改原始文件
- 视频裁剪通过 FFmpeg 完成，编码格式为 H.264 (libx264)
- 原始音频流会被保留（如启用）或被丢弃
- 复杂场景（深色视频、渐变背景）可能需要调整参数以获得最佳效果
算子参数
输入
| 输入 | 含义 |
|---|---|
| input_path | 输入视频路径（BOS路径、本地路径或HTTP URL） |
| output_path | 输出视频路径（BOS路径或本地路径） |
输出
| 输出 | 含义 |
|---|---|
| result | 处理后的视频路径（BOS路径），失败时返回 None |
参数
| 参数名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| detection_method | str | 'threshold_ratio' | 黑边检测算法。可选值：threshold_ratio: 阈值比例法，适用于大部分视频 edge_detection: 边缘检测法，适用于内容对比明显的视频 histogram: 直方图法，适用于渐变场景 |
| black_threshold | int | 10 | 判定为黑色的像素亮度上限（0-255）。值越小判定越严格 默认值：10 |
| valid_pixel_ratio | float | 0.1 | 行/列中非黑像素的最小有效比例。值越小保留区域越多 默认值：0.1 |
| sample_frames | int | 20 | 用于检测的采样帧数。值越大检测越精确但速度越慢 默认值：20 |
| is_keep_audio | bool | True | 是否保留原始音频流。True: 保留音频；False: 去除音频 默认值：True |
| timeout | int | None | None |
| core_region_ratio | float | 0.5 | 中心保护区域占视频尺寸的比例，范围 (0, 1)。该区域内不会被裁剪 默认值：0.5 |
| continuous_black_rows | int | 3 | 行方向上连续黑边的最小行数阈值，少于该值不视为黑边 默认值：3 |
| continuous_black_cols | int | 3 | 列方向上连续黑边的最小列数阈值，少于该值不视为黑边 默认值：3 |
| dark_region_brightness | int | 50 | 判定为暗场景的亮度均值阈值。低于该值时使用更宽松的检测比例 默认值：50 |
| edge_sensitivity | float | 1.0 | 边缘检测的灵敏度系数（仅在 edge_detection 算法下生效）。值越大检测越敏感 默认值：1.0 |
调用示例
Python
1from __future__ import annotations
2
3import os
4
5import daft
6from daft import col
7
8from daft.aihc.common.udf import aihc_udf
9from daft.aihc.functions.video.video_blackborder_crop import VideoBlackBorderCrop
10
11if __name__ == "__main__":
12 if os.getenv("DAFT_RUNNER", "native") == "ray":
13 import ray
14 ray.init(dashboard_host="0.0.0.0", ignore_reinit_error=True)
15 daft.set_runner_ray()
16 daft.set_execution_config(actor_udf_ready_timeout=6000, min_cpu_per_task=0)
17
18 # TODO: 根据实际场景准备样本数据
19 samples = {
20 "input_path": [
21 "bos://storage-aihc/test/aihc/test_data/test_video_with_black_border.mp4"
22 ],
23 "output_path": [
24 "bos://storage-aihc/test/aihc/test_data/test_video_cropped.mp4"
25 ],
26 }
27 ds = daft.from_pydict(samples)
28 constructor_kwargs = {
29 "detection_method": 'threshold_ratio',
30 "black_threshold": 10,
31 "valid_pixel_ratio": 0.1,
32 "sample_frames": 20,
33 "is_keep_audio": True,
34 "core_region_ratio": 0.5,
35 }
36 ds = ds.with_column(
37 "result",
38 aihc_udf(
39 VideoBlackBorderCrop,
40 construct_args=constructor_kwargs,
41 num_cpus=1,
42 concurrency=4,
43 batch_size=8,
44 )(col("input_path"), col("output_path")),
45 )
46 ds.show()评价此篇文章