Function open_video

scenedetect/__init__.py:84–141

Open a video at the given path. If `backend` is specified but not available on the current system, OpenCV (`VideoStreamCv2`) will be used as a fallback. Arguments: path: Path to video file to open. frame_rate: Overrides detected frame rate if set. Takes precedence over `fram

(
    path: StrPath,
    frame_rate: FrameRate | None = None,
    backend: str = "opencv",
    framerate: float | None = None,
    **kwargs,
)

def open_video(
    path: StrPath,
    frame_rate: FrameRate | None = None,
    backend: str = "opencv",
    framerate: float | None = None,
    **kwargs,
) -> VideoStream:
    """Open a video at the given path. If `backend` is specified but not available on the current
    system, OpenCV (`VideoStreamCv2`) will be used as a fallback.

    Arguments:
        path: Path to video file to open.
        frame_rate: Overrides detected frame rate if set. Takes precedence over `framerate`.
        backend: Name of specific backend to use, if possible. See
            :data:`scenedetect.backends.AVAILABLE_BACKENDS` for backends available on the current
            system. If the backend fails to open the video, OpenCV will be used as a fallback.
        framerate: [DEPRECATED] Use `frame_rate` instead. Retained as a deprecated alias for
            backwards compatibility; ignored when `frame_rate` is provided.
        kwargs: Optional named arguments to pass to the specified `backend` constructor for
            overriding backend-specific options.

    Returns:
        Backend object created with the specified video path.

    Raises:
        :class:`VideoOpenFailure`: Constructing the VideoStream fails. If multiple backends have
            been attempted, the error from the first backend will be returned.
    """
    # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
    # used, once internal callers and downstream users have had a release to migrate.
    if frame_rate is None:
        frame_rate = framerate
    last_error: Exception | None = None
    # If `backend` is available, try to open the video at `path` using it.
    if backend in AVAILABLE_BACKENDS:
        backend_type = AVAILABLE_BACKENDS[backend]
        try:
            logger.debug("Opening video with %s...", backend_type.BACKEND_NAME)
            return backend_type(path, frame_rate, **kwargs)
        except VideoOpenFailure as ex:
            logger.warning("Failed to open video with %s: %s", backend_type.BACKEND_NAME, str(ex))
            if backend == VideoStreamCv2.BACKEND_NAME:
                raise
            last_error = ex
    else:
        logger.warning("Backend %s not available.", backend)
    # Fallback to OpenCV if `backend` is unavailable, or specified backend failed to open `path`.
    backend_type = VideoStreamCv2
    logger.warning("Trying another backend: %s", backend_type.BACKEND_NAME)
    try:
        return backend_type(path, frame_rate)
    except VideoOpenFailure as ex:
        logger.debug("Failed to open video: %s", str(ex))
        if last_error is None:
            last_error = ex
    # Propagate any exceptions raised from specified backend, instead of errors from the fallback.
    assert last_error is not None
    raise last_error