Open a video file, image sequence, or network stream. Arguments: path: Path to the video. Can be a file, image sequence (`'folder/DSC_%04d.jpg'`), or network stream. frame_rate: If set, overrides the detected frame rate. Takes precedence over
(
self,
path: StrPath | None = None,
frame_rate: FrameRate | None = None,
max_decode_attempts: int = 5,
path_or_device: StrPath | int | None = None,
framerate: float | None = None,
)
| 72 | """OpenCV `cv2.VideoCapture` backend.""" |
| 73 | |
| 74 | def __init__( |
| 75 | self, |
| 76 | path: StrPath | None = None, |
| 77 | frame_rate: FrameRate | None = None, |
| 78 | max_decode_attempts: int = 5, |
| 79 | path_or_device: StrPath | int | None = None, |
| 80 | framerate: float | None = None, |
| 81 | ): |
| 82 | """Open a video file, image sequence, or network stream. |
| 83 | |
| 84 | Arguments: |
| 85 | path: Path to the video. Can be a file, image sequence (`'folder/DSC_%04d.jpg'`), |
| 86 | or network stream. |
| 87 | frame_rate: If set, overrides the detected frame rate. Takes precedence over |
| 88 | `framerate`. |
| 89 | max_decode_attempts: Number of attempts to continue decoding the video |
| 90 | after a frame fails to decode. This allows processing videos that |
| 91 | have a few corrupted frames or metadata (in which case accuracy |
| 92 | of detection algorithms may be lower). Once this limit is passed, |
| 93 | decoding will stop and emit an error. |
| 94 | path_or_device: [DEPRECATED] Specify `path` for files, image sequences, or |
| 95 | network streams/URLs. Use `VideoCaptureAdapter` for devices/pipes. |
| 96 | framerate: [DEPRECATED] Use `frame_rate` instead. Retained as a deprecated |
| 97 | alias for backwards compatibility; ignored when `frame_rate` is provided. |
| 98 | |
| 99 | Raises: |
| 100 | OSError: file could not be found or access was denied |
| 101 | VideoOpenFailure: video could not be opened (may be corrupted) |
| 102 | ValueError: specified frame rate is invalid |
| 103 | """ |
| 104 | super().__init__() |
| 105 | # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is |
| 106 | # used, once internal callers and downstream users have had a release to migrate. |
| 107 | if frame_rate is None: |
| 108 | frame_rate = framerate |
| 109 | if path_or_device is not None: |
| 110 | warnings.warn( |
| 111 | "The `path_or_device` argument is deprecated, use `path` or `VideoCaptureAdapter`" |
| 112 | " instead.", |
| 113 | DeprecationWarning, |
| 114 | stacklevel=2, |
| 115 | ) |
| 116 | resolved: str | int = ( |
| 117 | path_or_device if isinstance(path_or_device, int) else os.fspath(path_or_device) |
| 118 | ) |
| 119 | elif path is None: |
| 120 | raise ValueError("Path must be specified!") |
| 121 | else: |
| 122 | resolved = os.fspath(path) |
| 123 | if frame_rate is not None and frame_rate < MAX_FPS_DELTA: |
| 124 | raise ValueError(f"Specified frame rate ({float(frame_rate):f}) is invalid!") |
| 125 | if max_decode_attempts < 0: |
| 126 | raise ValueError("Maximum decode attempts must be >= 0!") |
| 127 | |
| 128 | self._path_or_device: str | int = resolved |
| 129 | self._is_device = isinstance(self._path_or_device, int) |
| 130 | |
| 131 | # VideoCapture state |