Summary

Currently there exist different functions for collecting video paths from a list of directories and files, with slightly different behavior. See #3300.

Old behavior

• list_videos_in_folder always filters the input files by extension: either the default SUPPORTED_VIDEOS or custom specified video_type.
• get_video_list only filters directories by SUPPORTED_VIDEOS, but not files.
• get_list_of_videos only filters directories by SUPPORTED_VIDEOS, but not files.

Issues

• Multiple functions with inconsistent behavior
• No way to collect videos without extension
• Ambiguous input parameters video_type and videotype: the meanings of "" and None differ per-case. List of strings is not always accepted.
• Code exists in deep branches where

Changes

• The current PR moves and renames the list_videos_in_folder function, to have a single centralized helper for this purpose
• The contract is changed to treat files and directories as follows
  • File paths are accepted as-is when extensions is None; only filtered when
    extensions is explicitly set.
  • Directory contents are always filtered by extension: by SUPPORTED_VIDEOS when
    extensions is None, or by the given value(s) otherwise.
  • exclude_patterns are always applied to both files and directory contents.

solves #3300

Details

PR Status

• relocate list_videos_in_folder to auxfun_videos: more centralized instead of pytorch-specific
• rename to collect_video_paths, which more accurately reflects function. feedback on naming is welcome!
• conditional filtering:
  • treat specified video files differently from video paths collected from specified directory
  • files are not filtered by extension by default, only when explicitly specifying extensions to filter for.
  • directories are scanned using SUPPORTED_VIDEOS by default or with specified extensions filter if set.
  • All cases are filtered using exclude_patterns which is defaults to ["_labeled.", "_full."] to match prior DLC outputs.
• add basic testing
• deprecate original list_videos_in_folder and map to new collect_video_paths
• deprecate get_list_of_videos and map to new collect_video_paths
• deprecate get_video_list and map to new collect_video_paths
• keep grab_files_in_folder, get_camerawise_videos (different implementation)

New function signature

def collect_video_paths(
    data_path: str | Path | list[str | Path],
    extensions: str | Sequence[str] | None = None,
    shuffle: bool = False,
    exclude_patterns: Sequence[str] = DEFAULT_EXCLUDE_PATTERNS,
) -> list[Path]:
    """
    Collects video paths from a given set of data paths: directories, files, or a mix
    of both. Directories are scanned one level deep (non-recursively).

    Files and directories are treated differently with respect to extension filtering:
    - File paths are accepted as-is when ``extensions`` is ``None``; only filtered when
      ``extensions`` is explicitly set.
    - Directory contents are always filtered by extension: by ``SUPPORTED_VIDEOS`` when
      ``extensions`` is ``None``, or by the given value(s) otherwise.
    - ``exclude_patterns`` are always applied to both files and directory contents.

    Args:
        data_path: Path or list of paths to folders containing videos, or individual
            video files. Can be a mix of directories and files.
        extensions: Controls extension filtering for collected video files.
            - ``None`` (default): file paths are accepted without extension filtering;
              directories are scanned for files with a recognized video extension.
            - ``str`` or ``Sequence[str]`` (e.g. ``"mp4"`` or ``["mp4", "avi"]``):
              both file paths and directory contents are filtered to only include files
              matching the given extension(s).
            - Empty ``str`` ``""`` is treated as ``None`` (deprecated, keep for backwards
              compatibility).
        shuffle: Whether to shuffle the order of videos. If ``False``, videos are
            returned in sorted order for deterministic behavior.
        exclude_patterns: Patterns to exclude from the collection. Defaults to
            ``DEFAULT_EXCLUDE_PATTERNS``. Set to ``[]`` to disable pattern exclusion.

    Returns:
        The paths of videos to analyze. Duplicate paths are removed.

    Raises:
        FileNotFoundError: If any path in ``data_path`` does not exist.
        ValueError: If ``extensions`` is an empty sequence.
    """
 ...
    return unique_videos