PySceneDetect 检测器参数扫描报告深度解析:BBC / AutoShot / ClipShots 上的 F1 网格搜索与最佳参数推荐
PySceneDetect 检测器参数扫描报告深度解析:BBC / AutoShot / ClipShots 上的 F1 网格搜索与最佳参数推荐
本文以仓库内 benchmark/SWEEP_REPORT.md 为骨架,结合
benchmark/目录下的扫描、评分、数据集与报告生成源码,完整解读 PySceneDetect 五个内置检测器(detect-content、detect-adaptive、detect-hash、detect-hist、detect-threshold)在三个公开镜头边界数据集上的暴力网格参数扫描结果,并说明如何自行复现扫描、理解 TRECVID-SBD 打分口径,以及如何基于扫描数据推导默认参数决策。
报告概览:这份扫描报告回答了什么
SWEEP_REPORT.md 是 PySceneDetect 基准测试体系(benchmark/)中"参数扫描"环节的最终输出。它由 benchmark/report_sweep.py 自动生成,数据来源是 benchmark/sweep.py 对 benchmark/results/sweep/<detector>-<dataset>.json 网格结果文件的汇总(完整驱动脚本见 scripts/benchmark_sweep.sh)。
报告回答了两个核心问题:
- 对每个数据集而言,哪个参数组合在该检测器上拿到最高的硬切 F1@1?(每个数据集一行的 "Best cell per dataset" 表格)
- 对三个数据集整体而言,哪个参数组合的"跨数据集平均 F1@1"最高,可作为统一的推荐默认值?("Best params averaged across all datasets" 表格,每检测器给出 top-5)
阅读这份报告前需要先明确其口径(原报告首段即声明):
- 所有 F1 / Precision / Recall 均为百分比数值,且只针对**硬切(hard cuts)**统计;
tol(tolerance)是帧容差:F1@1 表示预测切点与真值切点相差 ≤ 1 帧即算命中,F1@0 表示逐帧精确匹配;hash与hist两个检测器在扫描时min_scene_len固定在其默认值(不再作为被扫描维度);- 报告中的
min_scene_len取值(如0.4、0.6)是以秒为单位的浮点数,而非帧数——这样同一组参数在不同帧率的数据集之间才具有可比性(详见 benchmark/sweep.py 的说明)。
从源码看,benchmark/report_sweep.py 的 main() 正是按此逻辑逐检测器读取 JSON:取每个数据集上 results<a href="https://link.gitcode.com/i/79c0d3c056415a4db397befd885d404f" target="_blank">"1"]["aggregate"]["hard_cuts"]["f1"] 最高的格点(best cell),再把"在全部三个数据集上都出现过"的格点按平均 F1@1 排序取前五。若某检测器存在 <detector>-ext-<dataset>.json 的网格扩展文件,其格点会被合并计入([benchmark/report_sweep.py),detect-hist 的注记即来源于此。
评估口径:TRECVID-SBD 打分在仓库中如何实现
报告中的 F1 不是简单"预测切点 == 真值切点"计数,而是实现了 TRECVID-SBD 评测约定,相关代码位于 benchmark/evaluator.py,其核心逻辑可直接在单元测试 tests/test_benchmark_evaluator.py 中验证:
- 硬切匹配:
_score_hard_cuts()(benchmark/evaluator.py)枚举所有"预测切点—真值切点"对,只要绝对帧距 ≤ tolerance 即为候选,随后按距离排序,用贪心 1 对 1 最近邻依次认领。被认领的预测记matched,认领不上的预测记false_positives,真值中未被命中的记missed。等距时按稳定排序顺序打破平局(测试test_hard_equidistant_tie_resolves_deterministically)。 - 渐变转场匹配:
_score_fade_transitions()(benchmark/evaluator.py)对淡入淡出区间采用"点落在区间内"的匹配方式,每个区间只认第一个落入的预测,后续落入同一区间的预测记为误报,且被消费掉的预测不再参与硬切匹配。 - 聚合口径:
BenchmarkResult按 TRECVID 约定跨视频汇总计数(而非对逐视频 F1 取平均),再计算整体 precision / recall / F1;matched 事件还累计绝对帧偏移用于报告定位误差(mean_abs_offset_hard_cuts)。
因此报告表格里的每个 F1 都是"整库所有视频的汇总 F1",这也是它与各视频单独结果可能不一致的原因。评分入口 evaluate() 见 benchmark/evaluator.py。
实验设定:三个数据集与它们的真值类型
扫描与评分运行在三个公开数据集上,定义于 benchmark/dataset.py(注册表 DATASETS 见 benchmark/dataset.py):
| 数据集 | 内容特征 | 真值类型 | 源码类 |
|---|---|---|---|
| BBC(Planet Earth) | 11 段长时广播纪录片 | 仅硬切 | BBCDataset(benchmark/dataset.py) |
| AutoShot | 短视频测试集(原 200 个,36 个已不可公开获取,按磁盘现存样本运行) | 仅硬切 | AutoShotDataset(benchmark/dataset.py) |
| ClipShots | 短视频,默认 test 划分 | 硬切 + 淡入淡出/溶解等渐变转场(仓库内唯一带渐变真值的数据集) | ClipShotsDataset(benchmark/dataset.py) |
值得注意的是 BBC/AutoShot 的标注文件是"制表符分隔"的第二列为 0 基帧号,加载时统一转成 1 基(与 PySceneDetect 的 FrameTimecode 约定一致),而 ClipShots 的 JSON 标注帧号本身已对齐边界帧约定,无需偏移(见 benchmark/dataset.py 与 benchmark/dataset.py 的注释)。
detect-content:ContentDetector 的阈值与最短镜头长度
ContentDetector 在 HSV 色彩空间比较相邻帧的色相/饱和度/亮度(及可选边缘)加权差,超过固定阈值即触发切点,源码见 scenedetect/detectors/content_detector.py,默认 threshold=27.0、min_scene_len=15(帧)。扫描的正是这两个最敏感维度:threshold 与以秒计的 min_scene_len。
每个数据集的最佳格点(按 F1@1):
| Dataset | F1@1 | Prec@1 | Rec@1 | F1@0 | Params |
|---|---|---|---|---|---|
| BBC | 88.34 | 90.00 | 86.75 | 87.35 | min_scene_len=0.8, threshold=25 |
| AutoShot | 73.44 | 79.54 | 68.21 | 70.54 | min_scene_len=0.4, threshold=29 |
| ClipShots | 66.74 | 58.93 | 76.95 | 66.44 | min_scene_len=0.8, threshold=35 |
全部数据集平均后的最佳格点(平均 F1@1):
| Mean F1@1 | BBC | AutoShot | ClipShots | Params |
|---|---|---|---|---|
| 73.39 | 85.95 | 71.51 | 62.73 | min_scene_len=0.6, threshold=31 |
| 73.37 | 84.27 | 70.95 | 64.89 | min_scene_len=0.6, threshold=33 |
| 73.32 | 83.99 | 72.43 | 63.54 | min_scene_len=0.4, threshold=33 |
| 73.15 | 87.28 | 72.05 | 60.13 | min_scene_len=0.6, threshold=29 |
| 73.09 | 85.18 | 72.97 | 61.10 | min_scene_len=0.4, threshold=31 |
解读与源码印证:
- 各数据集最优格点差异明显:BBC 偏爱较小阈值(25)+ 较长最短镜头(0.8s),ClipShots 需要更高阈值(35)以抑制短视频中频繁的强画面变化,AutoShot 居中。这符合
threshold语义——它决定"平均像素强度变化必须超过多少才触发切点"(scenedetect/detectors/content_detector.py)。 - 综合三库后,
min_scene_len=0.6s + threshold=31以平均 F1@1=73.39 成为推荐格点。它比 v0.7 默认threshold=27略高,说明在该语料混合下略收紧阈值能更好平衡三库。 - 需要注意
min_scene_len=15(帧)这一源码默认值换算成秒取决于帧率:在 25fps 的 BBC 上恰为 0.6s,在 30fps 网页视频上约为 0.5s。扫描统一用秒是为了消除帧率差异(benchmark/sweep.py)。
detect-adaptive:AdaptiveDetector 的滚动均值阈值
AdaptiveDetector 继承自 ContentDetector,但阈值不是固定的,而是相邻帧变化分数的滚动平均:目标帧分数与前后 window_width 帧平均分的比值(adaptive_ratio)超过 adaptive_threshold 且原始分数超过 min_content_val 才触发切点,可缓解快速摄像机运动带来的误检(scenedetect/detectors/adaptive_detector.py)。被扫描的维度是 adaptive_threshold、min_scene_len、window_width。
每个数据集的最佳格点(按 F1@1):
| Dataset | F1@1 | Prec@1 | Rec@1 | F1@0 | Params |
|---|---|---|---|---|---|
| BBC | 94.57 | 94.89 | 94.26 | 93.50 | adaptive_threshold=2, min_scene_len=0.6, window_width=2 |
| AutoShot | 77.19 | 80.48 | 74.16 | 75.45 | adaptive_threshold=3.5, min_scene_len=0.4, window_width=3 |
| ClipShots | 65.53 | 60.19 | 71.89 | 65.47 | adaptive_threshold=5.5, min_scene_len=0.6, window_width=3 |
全部数据集平均后的最佳格点(平均 F1@1):
| Mean F1@1 | BBC | AutoShot | ClipShots | Params |
|---|---|---|---|---|
| 76.34 | 90.41 | 76.27 | 62.32 | adaptive_threshold=3.5, min_scene_len=0.6, window_width=3 |
| 76.21 | 87.87 | 76.17 | 64.58 | adaptive_threshold=4, min_scene_len=0.6, window_width=3 |
| 76.18 | 90.43 | 77.19 | 60.93 | adaptive_threshold=3.5, min_scene_len=0.4, window_width=3 |
| 76.16 | 87.91 | 77.07 | 63.51 | adaptive_threshold=4, min_scene_len=0.4, window_width=3 |
| 75.45 | 85.28 | 75.71 | 65.37 | adaptive_threshold=4.5, min_scene_len=0.6, window_width=3 |
解读与源码印证:
AdaptiveDetector是五个检测器中跨数据集平均 F1 最高的(76.34),且 BBC 单项高达 90.41——滚动均值天然适应长时广播内容的亮度/运动节奏变化。- 推荐格点
adaptive_threshold=3.5, min_scene_len=0.6, window_width=3相比源码默认(3.0 / 15 / 2)把阈值略调高、窗口从 2 扩到 3。窗口越大,均值越平滑,对单帧噪声越不敏感(required_frames = 1 + 2 * window_width,见 scenedetect/detectors/adaptive_detector.py)。 - 三库最优格点呈明显梯度(BBC 2.0 → AutoShot 3.5 → ClipShots 5.5),再次说明同一组参数难以同时满足三库,这也是"取平均推荐"存在局限的典型例证。
detect-hash:HashDetector 的感知哈希距离阈值
HashDetector 对每帧做感知哈希(DCT + 低通滤波 + 按中位数二值化),用相邻帧哈希的归一化汉明距离(除以 size × size)与阈值比较,超过即触发切点(scenedetect/detectors/hash_detector.py)。扫描维度为 threshold(0.0~1.0 的归一化距离)与 size,min_scene_len 固定为默认值。
每个数据集的最佳格点(按 F1@1):
| Dataset | F1@1 | Prec@1 | Rec@1 | F1@0 | Params |
|---|---|---|---|---|---|
| BBC | 86.91 | 81.59 | 92.96 | 85.81 | size=16, threshold=0.425 |
| AutoShot | 70.17 | 76.06 | 65.12 | 66.89 | size=8, threshold=0.325 |
| ClipShots | 56.38 | 44.46 | 77.03 | 55.66 | size=8, threshold=0.4 |
全部数据集平均后的最佳格点(平均 F1@1):
| Mean F1@1 | BBC | AutoShot | ClipShots | Params |
|---|---|---|---|---|
| 69.83 | 86.38 | 68.98 | 54.12 | size=8, threshold=0.35 |
| 69.63 | 86.65 | 65.86 | 56.38 | size=8, threshold=0.4 |
| 69.63 | 86.65 | 65.86 | 56.37 | size=8, threshold=0.375 |
| 68.18 | 84.28 | 70.17 | 50.10 | size=8, threshold=0.325 |
| 67.00 | 83.71 | 61.66 | 55.65 | size=8, threshold=0.425 |
解读与源码印证:
- BBC 偏好
size=16(更大哈希,携带更多低频信息)且阈值更高,而两个短视频数据集均偏好size=8;综合推荐落在size=8, threshold=0.35。 - 阈值语义:距离 0 表示画面完全相同,1 表示毫不相关,阈值越小越敏感(scenedetect/detectors/hash_detector.py)。BBC 需要 0.425 的较高阈值来抑制长时内容的连续渐变;AutoShot/ClipShots 用 0.325~0.4。
- 当前源码中
HashDetector构造器默认即为threshold=0.35, size=8(scenedetect/detectors/hash_detector.py),与扫描推荐一致;而 benchmark/README.md 记录的 v0.7 默认(threshold=0.395, size=16)则与推荐相差明显,二者可作为"调参带来的收益"的对照。
detect-hist:HistogramDetector 的亮度直方图相关性阈值
HistogramDetector 将每帧 BGR 转 YUV,取 Y(亮度)通道做直方图,用 cv2.compareHist 的相关性(HISTCMP_CORREL)比较相邻帧;相关性低于阈值即触发切点(scenedetect/detectors/histogram_detector.py)。扫描维度为 threshold 与 bins,min_scene_len 固定默认值。
Note: thresholds >= 0.21 come from a grid-extension run (
detect-hist-ext-<dataset>.json) after the initial grid's best cell landed on its 0.20 upper edge.
(原报告注记:初始网格的最优格点落在 0.20 的上边界上,因此用网格扩展运行补充了 0.21 及以上的阈值。扩展格点由 benchmark/report_sweep.py 自动合并。)
每个数据集的最佳格点(按 F1@1):
| Dataset | F1@1 | Prec@1 | Rec@1 | F1@0 | Params |
|---|---|---|---|---|---|
| BBC | 86.58 | 87.32 | 85.86 | 85.42 | bins=128, threshold=0.11 |
| AutoShot | 68.99 | 75.29 | 63.67 | 65.70 | bins=128, threshold=0.2 |
| ClipShots | 53.25 | 46.26 | 62.74 | 52.90 | bins=128, threshold=0.35 |
全部数据集平均后的最佳格点(平均 F1@1):
| Mean F1@1 | BBC | AutoShot | ClipShots | Params |
|---|---|---|---|---|
| 66.27 | 82.10 | 68.99 | 47.72 | bins=128, threshold=0.2 |
| 66.23 | 81.47 | 68.87 | 48.36 | bins=128, threshold=0.21 |
| 66.20 | 82.74 | 68.81 | 47.06 | bins=128, threshold=0.19 |
| 66.19 | 80.69 | 68.92 | 48.97 | bins=128, threshold=0.22 |
| 66.17 | 79.53 | 68.88 | 50.10 | bins=128, threshold=0.24 |
解读与源码印证:
- 所有 top-5 格点均为
bins=128,说明 256 个 bin 在此三库上并无增益(bin 数影响直方图分辨率的代价收益权衡)。 - 注意源码内部将阈值做了反转:构造时
self._threshold = 1.0 - threshold,实际比较的是相关性(1.0 = 完全相同),相关性 ≤ 内部阈值才触发切点(scenedetect/detectors/histogram_detector.py)。因此报告中的threshold越大代表允许的直方图差异越大、检测越不敏感——这与哈希检测器"阈值越大越不敏感"的方向一致,但内部实现不同。 - 该检测器在 ClipShots 上平均 F1 明显偏低(约 48~50),与 benchmark/README.md 中默认参数下 ClipShots 硬切 F1 仅 19.80 形成强烈对比:一次调参(从默认
threshold=0.05, bins=256到0.2/128)可带来约 30 个点的提升,是所有检测器中默认值与最优值差距最大的。
detect-threshold:只检测淡入淡出的"管线校验"结果
ThresholdDetector 以平均像素亮度越过/低于阈值来检测淡入淡出(fade to/from black),而非硬切(scenedetect/detectors/threshold_detector.py)。原报告为此专门加了一段注记:
Note:
detect-thresholddetects fades (fade to/from black), not hard cuts. These datasets' ground truth is hard cuts, so the hard-cut F1 below is expectedly near zero. It is included to validate the sweep pipeline end-to-end, not as a meaningful hard-cut accuracy result.
(即:该数据集的真值是硬切,因此下面的硬切 F1 接近零是符合预期的;它被纳入扫描的唯一目的是端到端验证扫描管线本身,而不是作为有意义的硬切精度结果。)
每个数据集的最佳格点(按 F1@1):
| Dataset | F1@1 | Prec@1 | Rec@1 | F1@0 | Params |
|---|---|---|---|---|---|
| BBC | 0.79 | 2.89 | 0.45 | 0.32 | min_scene_len=0.2, threshold=19 |
| AutoShot | 3.98 | 51.09 | 2.07 | 3.14 | min_scene_len=0.4, threshold=20 |
| ClipShots | 1.75 | 6.21 | 1.02 | 0.18 | min_scene_len=0, threshold=10 |
全部数据集平均后的最佳格点(平均 F1@1):
| Mean F1@1 | BBC | AutoShot | ClipShots | Params |
|---|---|---|---|---|
| 2.07 | 0.77 | 3.90 | 1.55 | min_scene_len=0, threshold=19 |
| 2.06 | 0.73 | 3.98 | 1.48 | min_scene_len=0, threshold=20 |
| 2.02 | 0.79 | 3.90 | 1.37 | min_scene_len=0.2, threshold=19 |
| 2.00 | 0.71 | 3.98 | 1.30 | min_scene_len=0.2, threshold=20 |
| 1.96 | 0.69 | 3.90 | 1.28 | min_scene_len=0.4, threshold=19 |
正确解读:
- 三库最优格点的 F1@1 均不足 4(BBC 0.79、AutoShot 3.98、ClipShots 1.75),AutoShot 的 Precision 高达 51.09 但 Recall 仅 2.07——这说明该检测器在硬切真值上几乎不产生命中。这不应被解读为"检测器很差",而是任务错配:用它评估硬切数据集本就无意义。
- 从工程角度,这一行表格的价值在于:它证明"扫描 → 评分 → 汇总 → 报告"全链路能对任何检测器正确产出数值(包括"预期接近零"的数值),可当作管线的冒烟测试。若要评测淡入淡出能力,应使用带渐变真值的 ClipShots 数据集,并查看 fades 维度(benchmark/main.py 会在数据集声明含 fade 事件时额外输出淡变指标表)。
平均最优参数汇总:一份"跨库推荐默认值"清单
将上述五张"平均后最佳格点"表归纳如下(即 benchmark/README.md 中 Parameter sweep results 一节的结论,完整明细见 benchmark/SWEEP_REPORT.md):
| Detector | 平均 F1@1(最优) | 推荐参数 | 当前源码构造器默认值 |
|---|---|---|---|
| detect-content | 73.39 | threshold=31, min_scene_len=0.6s | threshold=27.0, min_scene_len=15(帧) |
| detect-adaptive | 76.34 | adaptive_threshold=3.5, window_width=3, min_scene_len=0.6s | adaptive_threshold=3.0, window_width=2 |
| detect-hash | 69.83 | size=8, threshold=0.35 | threshold=0.35, size=8(与推荐一致) |
| detect-hist | 66.27 | bins=128, threshold=0.20 | threshold=0.20, bins=128(与推荐一致) |
| detect-threshold | 不适用 | 检测淡入淡出,仅作管线校验 | threshold=12 |
可以观察到:detect-hash 与 detect-hist 的源码构造器默认值已经落在扫描推荐上,说明这份扫描的结论已部分落实到实现;而 detect-content 与 detect-adaptive 的默认值仍与推荐存在差距,这正是调参的潜在空间。需要强调:这些推荐是基于这三个数据集平均的结果,如果你的目标内容与 BBC(长时广播)、AutoShot/ClipShots(短视频)差异很大,应优先看对应数据集的"Best cell per dataset"表,而不是直接套用平均推荐。
工具链实战:如何自己跑一次参数扫描
1. 单次扫描命令
参数扫描由 benchmark/sweep.py 提供,入口参数定义见 create_parser()(benchmark/sweep.py)。典型用法:
python -m benchmark.sweep \
--detector detect-content --dataset BBC \
--params "threshold=15:35:1;min_scene_len=0.0:1.0:0.1" \
--tolerance 0,1 --workers 16 --out sweep.json
各参数说明:
--detector:五个可扫描检测器之一:detect-content、detect-adaptive、detect-hash、detect-hist、detect-threshold(注册表见 benchmark/_common.py)。--dataset:BBC、AutoShot、ClipShots之一。--params:参数规格语言。分号分隔多个子句;每个子句要么是key=v1,v2,v3(枚举值),要么是key=a:b:s(数值区间,步长恰好落在 b 上时含 b)。未列出的键使用检测器构造器默认值。解析实现见 benchmark/sweep.py 与 benchmark/sweep.py。--tolerance:逗号分隔的帧容差列表,默认0,1。--workers:单次视频解码并行驱动的检测器实例数,默认 8;--workers=16是 scripts/benchmark_sweep.sh 的默认值。--quick N:只对前 N 个样本评分,用于快速迭代;对外发布的数字必须来自全量语料。--out:输出机器可读 JSON(每个格点一条,含各容差下的聚合与逐视频结果,见 benchmark/sweep.py)。
2. 成本摊薄原理:FanOutVideoStream
网格是参数组合的笛卡尔积(cartesian_grid(),benchmark/sweep.py)。如果朴素地对每个格点重新解码整段视频,100 格 × 500 视频的语料需要 50000 次解码。PySceneDetect 的解决方案是 FanOutVideoStream(scenedetect/_fan_out.py):单次解码把帧"扇出"到 N 个消费者流,每个消费者由独立线程驱动一个检测器实例,因此成本从"格点数 × 视频数"降为"视频数 × ⌈格点数 / workers⌉"次解码(benchmark/sweep.py)。
内存上界为 workers × prefetch 帧(每个消费者队列深度可配,prefetch=0 即 1 深缓冲,见 scenedetect/_fan_out.py);源流由最慢的消费者"节流",快线程不会无限超前。消费者流是单向的,不支持 seek/reset,重跑需重建(scenedetect/_fan_out.py)。逐格点耗时记录的是墙钟时间且受最慢线程约束,因此只作为相对成本参考(benchmark/sweep.py)。
3. 一键跑完整轮扫描
scripts/benchmark_sweep.sh 封装了"5 检测器 × 3 数据集"的通宵扫描,网格规模按约 8~10 小时、--workers=16 设计:
scripts/benchmark_sweep.sh
脚本支持环境变量覆盖:DATASET_ROOT(数据集根目录)、OUT_DIR(输出目录,默认 benchmark/results/sweep)、WORKERS、QUICK(冒烟测试)、PY、DETECTORS / DATASETS(子集)。各检测器网格定义在 grid_for()(scripts/benchmark_sweep.sh):
| 检测器 | 网格规格 |
|---|---|
| detect-content | threshold=15:35:2;min_scene_len=0.0,0.2,0.4,0.6,0.8 |
| detect-adaptive | adaptive_threshold=1.5:6.0:0.5;min_scene_len=0.4,0.6;window_width=2,3 |
| detect-hash | threshold=0.25:0.55:0.025;size=8,16(min_scene_len 固定默认) |
| detect-hist | threshold=0.02:0.35:0.01;bins=128,256(min_scene_len 固定默认) |
注意 report_sweep.py 输出中的 detect-hist 扩展格点(≥0.21)来自后续的网格扩展运行 detect-hist-ext-<dataset>.json,属于报告作者在发现最优格点贴到 0.20 上边界后追加的精细扫描。
4. 重新生成报告
扫描 JSON 就位后,重新生成 SWEEP_REPORT.md:
python -m benchmark.report_sweep
输出由 benchmark/report_sweep.py 的 main() 写入 benchmark/SWEEP_REPORT.md,内容即本文剖析的这套表格。若要跑"各检测器默认参数"的对照基准(benchmark/README.md 中的 Accuracy at default settings 表),使用:
scripts/benchmark_defaults.sh # 全部 5 检测器 × 3 数据集,tolerance 0,1
python -m benchmark --detector detect-content --dataset BBC # 单次
从扫描结果到默认参数决策:analyze_sweep.py 的判定流程
SWEEP_REPORT.md 只给出"平均 F1 最高的格点",而是否真的要把默认值改成它,是另一套更保守的决策逻辑——benchmark/analyze_sweep.py 实现了一个固定判定流程(benchmark/analyze_sweep.py):
- 以出厂默认值为基线(
DEFAULTS映射见 benchmark/analyze_sweep.py); - 候选集:平均 F1@1 距最优 ≤ 1.0(
EPSILON)的"高原"格点,而非单纯取峰值; - 邻域稳健性:候选格点沿细粒度数值轴任一方向的单步邻居不得使平均 F1 陡降超过 2.0(分类轴如
size/bins不视为"步"); - 权重敏感性:候选须在等权平均与每个"留一数据集平均"(LODO)方案下都优于默认值,即改善不依赖任一单个数据集;
- 精度底线:各数据集 precision@1 不得比默认值低超过 5.0;
- 实质性:要求平均 F1@1 提升 ≥ 2.0、至少两个数据集提升 ≥ 1.0、且无数据集回退超过 1.0;
- 对扫描过
min_scene_len的检测器,额外输出把min_scene_len固定到默认等效值的切片排名,使阈值建议独立成立。
最终输出形如"Recommendation: CHANGE to ..."或"Recommendation: KEEP current default"。这套流程的价值在于:扫描报告回答"哪个格点最高",analyze 回答"哪个格点值得成为新默认",二者配套使用才能避免把偶然的峰值误当全局最优。
复现前提、局限与正确解读
数据获取:三个数据集均需自行下载放入 benchmark/<NAME>/ 目录(详见 benchmark/README.md 的 Dataset Download 一节;ClipShots 默认 test 划分为 500 个视频,全量约 46 GB)。目录结构必须满足各加载器的约定(BBC 的 videos/ + fixed/,AutoShot 的 videos/ + annotations/,ClipShots 的 annotations/ + video_lists/ + videos/)。
解读边界(务必阅读):
- 报告数字是百分比形式的硬切 F1,且基于"整库汇总计数"而非逐视频平均;
min_scene_len以秒计,而源码默认15是帧——两者仅在特定帧率下等价(25fps 时 15 帧 = 0.6s),跨帧率比较必须用秒;detect-threshold一行是任务错配的管线校验,不代表其淡入淡出检测能力;- 各数据集最优格点差异显著(尤其 threshold 类参数),跨库平均推荐不保证在你自己的内容上最优——在自己的语料上复跑扫描、或优先参考与目标内容同类的数据集行才是正确用法;
- benchmark/evaluator.py 的注释还指出:现有基准数据集几乎都是 CFR(恒定帧率),v0.7 对 VFR 的支持在这些基准上暂无用武之地,评估接口仍以帧号为单位。
延伸阅读
- 报告本体:benchmark/SWEEP_REPORT.md
- 基准测试总览与默认参数对照:benchmark/README.md
- 扫描工具:benchmark/sweep.py、scripts/benchmark_sweep.sh
- 评分实现与测试:benchmark/evaluator.py、tests/test_benchmark_evaluator.py
- 数据集加载:benchmark/dataset.py
- 默认参数决策流程:benchmark/analyze_sweep.py
- 五个检测器源码:scenedetect/detectors/content_detector.py、scenedetect/detectors/adaptive_detector.py、scenedetect/detectors/hash_detector.py、scenedetect/detectors/histogram_detector.py、scenedetect/detectors/threshold_detector.py
- 扇出解码(扫描提速核心):scenedetect/_fan_out.py