Add a minimum fade-out duration to ThresholdDetector

[aprylewu]

Add an optional min_out_length to ThresholdDetector, exposed as detect-threshold --min-out-length and the matching configuration setting. This implements the duration filter discussed in #278 using the name suggested there.

Fixes #278.

For example, with a four-frame minimum, a two-frame dark interval is ignored while a later six-frame interval produces its normal fade-biased cut. Ignoring the first interval still updates the detector's fade state, so the later cut uses its own fade-out position. The same filter applies to a final fade-out, counting the last processed frame; a trailing four-frame interval meets a four-frame minimum.

The default is zero and preserves existing behavior. The new constructor argument follows the existing arguments to preserve positional calls. It accepts the same duration representations as min_scene_len and leaves that setting's existing cut-spacing behavior unchanged.

Validation:

• New regression tests cover threshold boundaries, successive short/long fades, both threshold methods, fade bias, minimum scene length, final fades, CLI/config parsing, and real synthetic videos decoded with OpenCV and PyAV.
• The complete standard test suite passed: 426 passed, 2 skipped, 83 release tests deselected. The new test module contributes 37 passing cases.
• ruff check . and ruff format --check . passed for all 104 Python files.
• An independent comparison against the base detector found identical default results and state across 1,920 configurations.

The CLI reference was regenerated with docs/generate_cli_docs.py. This change uses the existing nominal-frame endpoint convention for the last frame; it does not change general VFR endpoint handling.

Developed with OpenAI Codex assistance and independently reviewed by another coding agent. All reported checks were run locally.

[Breakthrough]

Thanks for the PR. Should we set a reasonable default value for this as well in the CLI? How often does this occur?

[Breakthrough]

File headers must all use standardized format:

#
#            PySceneDetect: Python-Based Video Scene Detector
#   -------------------------------------------------------------------
#     [  Site:    https://scenedetect.com                           ]
#     [  Docs:    https://scenedetect.com/docs/                     ]
#     [  Github:  https://github.com/Breakthrough/PySceneDetect/    ]
#
# Copyright (C) 2026 Brandon Castellano <http://www.bcastell.com>.
# PySceneDetect is licensed under the BSD 3-Clause License; see the
# included LICENSE file, or visit one of the above pages for details.
#

[aprylewu]

Updated to the exact header format you provided in 8c1d7df. Also replaced the OpenCV fourcc alias in the test with cv2.VideoWriter.fourcc, which fixes the Pyright failure without changing the generated video.

[aprylewu]

Thanks for reviewing. I don't have representative real-video measurements of how often this occurs. The motivation is the brief within-scene fades described in #278; my validation uses synthetic clips, so it establishes the filter behavior rather than its prevalence.

A nonzero CLI default is possible, but the duration measured here is time below the brightness threshold, not the whole fade. Even a deliberate fade-through-black can have a very short below-threshold interval. That's why I initially kept the default at zero.

If we want suppression enabled by default in the CLI, 0.1s seems like a conservative starting point to evaluate, with the API default still at zero for compatibility. That would be a proposed heuristic, not a value established by the tests, and it would still need representative clips to assess missed transitions. My preference is to keep zero for now unless there is an existing sample set we can use to choose the default.

The header and CI type-check issue are fixed in 8c1d7df. Local Pyright now reports zero errors; Ruff checks pass. The standard test suite also passed again: 426 passed, 2 skipped, 83 release tests deselected.