Safer video loading from SLP

sleap_io/io/main.py

@@ -7,16 +7,19 @@
 from pathlib import Path
 
 
-def load_slp(filename: str) -> Labels:
+def load_slp(filename: str, open_videos: bool = True) -> Labels:
     """Load a SLEAP dataset.
 
     Args:
         filename: Path to a SLEAP labels file (`.slp`).
+        open_videos: If `True` (the default), attempt to open the video backend for
+            I/O. If `False`, the backend will not be opened (useful for reading metadata
+            when the video files are not available).
 
     Returns:
         The dataset as a `Labels` object.
     """
-    return slp.read_labels(filename)
+    return slp.read_labels(filename, open_videos=open_videos)
 
 
 def save_slp(

sleap_io/io/slp.py

@@ -43,8 +43,28 @@ class InstanceType(IntEnum):
     PREDICTED = 1
 
 
+def sanitize_filename(
+    filename: str | Path | list[str] | list[Path],
+) -> str | list[str]:
+    """Sanitize a filename to a canonical posix-compatible format.
+
+    Args:
+        filename: A string or `Path` object or list of either to sanitize.
+
+    Returns:
+        A sanitized filename as a string (or list of strings if a list was provided)
+        with forward slashes and posix-formatted.
+    """
+    if isinstance(filename, list):
+        return [sanitize_filename(f) for f in filename]
+    return Path(filename).as_posix().replace("\\", "/")
+
+
 def make_video(
-    labels_path: str, video_json: dict, video_ind: int | None = None
+    labels_path: str,
+    video_json: dict,
+    video_ind: int | None = None,
+    open_backend: bool = True,
 ) -> Video:
     """Create a `Video` object from a JSON dictionary.
 
@@ -53,6 +73,9 @@ def make_video(
         video_json: A dictionary containing the video metadata.
         video_ind: The index of the video in the labels file. This is used to try to
             recover the source video for embedded videos. This is skipped if `None`.
+        open_backend: If `True` (the default), attempt to open the video backend for
+            I/O. If `False`, the backend will not be opened (useful for reading metadata
+            when the video files are not available).
     """
     backend_metadata = video_json["backend"]
     video_path = backend_metadata["filename"]
@@ -65,23 +88,7 @@ def make_video(
         is_embedded = True
 
     # Basic path resolution.
-    video_path = Path(Path(video_path).as_posix().replace("\\", "/"))
-
-    try:
-        if not video_path.exists():
-            # Check for the same filename in the same directory as the labels file.
-            video_path_ = Path(labels_path).parent / video_path.name
-            if video_path_.exists():
-                video_path = video_path_
-            else:
-                # TODO (TP): Expand capabilities of path resolution to support more
-                # complex path finding strategies.
-                pass
-    except OSError:
-        pass
-
-    # Convert video path to string.
-    video_path = video_path.as_posix()
+    video_path = Path(sanitize_filename(video_path))
 
     if is_embedded:
         # Try to recover the source video.
@@ -91,37 +98,63 @@ def make_video(
                     f[f"video{video_ind}/source_video"].attrs["json"]
                 )
                 source_video = make_video(
-                    labels_path, source_video_json, video_ind=None
+                    labels_path,
+                    source_video_json,
+                    video_ind=None,
+                    open_backend=open_backend,
                 )
 
-    if "filenames" in backend_metadata:
-        # This is an ImageVideo.
-        # TODO: Path resolution.
-        video_path = backend_metadata["filenames"]
-
-    try:
-        backend = VideoBackend.from_filename(
-            video_path,
-            dataset=backend_metadata.get("dataset", None),
-            grayscale=backend_metadata.get("grayscale", None),
-            input_format=backend_metadata.get("input_format", None),
-        )
-    except ValueError:
-        backend = None
+    backend = None
+    if open_backend:
+        try:
+            if not video_path.exists():
+                # Check for the same filename in the same directory as the labels file.
+                video_path_ = Path(labels_path).parent / video_path.name
+                if video_path_.exists() and video_path.stat():
+                    video_path = video_path_
+                else:
+                    # TODO (TP): Expand capabilities of path resolution to support more
+                    # complex path finding strategies.
+                    pass
+        except (OSError, PermissionError, FileNotFoundError):
+            pass
+
+        # Convert video path to string.
+        video_path = video_path.as_posix()
+
+        if "filenames" in backend_metadata:
+            # This is an ImageVideo.
+            # TODO: Path resolution.
+            video_path = backend_metadata["filenames"]
+            video_path = [Path(sanitize_filename(p)) for p in video_path]
+
+        try:
+            backend = VideoBackend.from_filename(
+                video_path,
+                dataset=backend_metadata.get("dataset", None),
+                grayscale=backend_metadata.get("grayscale", None),
+                input_format=backend_metadata.get("input_format", None),
+            )
+        except Exception:
+            backend = None
 
     return Video(
         filename=video_path,
         backend=backend,
         backend_metadata=backend_metadata,
         source_video=source_video,
+        open_backend=open_backend,
     )
 
 
-def read_videos(labels_path: str) -> list[Video]:
+def read_videos(labels_path: str, open_backend: bool = True) -> list[Video]:
     """Read `Video` dataset in a SLEAP labels file.
 
     Args:
         labels_path: A string path to the SLEAP labels file.
+        open_backend: If `True` (the default), attempt to open the video backend for
+            I/O. If `False`, the backend will not be opened (useful for reading metadata
+            when the video files are not available).
 
     Returns:
         A list of `Video` objects.
@@ -131,7 +164,9 @@ def read_videos(labels_path: str) -> list[Video]:
         read_hdf5_dataset(labels_path, "videos_json")
     ):
         video_json = json.loads(video_data)
-        video = make_video(labels_path, video_json, video_ind=video_ind)
+        video = make_video(
+            labels_path, video_json, video_ind=video_ind, open_backend=open_backend
+        )
         videos.append(video)
     return videos
 
@@ -145,16 +180,17 @@ def video_to_dict(video: Video) -> dict:
     Returns:
         A dictionary containing the video metadata.
     """
+    video_filename = sanitize_filename(video.filename)
     if video.backend is None:
-        return {"filename": video.filename, "backend": video.backend_metadata}
+        return {"filename": video_filename, "backend": video.backend_metadata}
 
     if type(video.backend) == MediaVideo:
         return {
-            "filename": video.filename,
+            "filename": video_filename,
             "backend": {
                 "type": "MediaVideo",
                 "shape": video.shape,
-                "filename": video.filename,
+                "filename": video_filename,
                 "grayscale": video.grayscale,
                 "bgr": True,
                 "dataset": "",
@@ -164,12 +200,12 @@ def video_to_dict(video: Video) -> dict:
 
     elif type(video.backend) == HDF5Video:
         return {
-            "filename": video.filename,
+            "filename": video_filename,
             "backend": {
                 "type": "HDF5Video",
                 "shape": video.shape,
                 "filename": (
-                    "." if video.backend.has_embedded_images else video.filename
+                    "." if video.backend.has_embedded_images else video_filename
                 ),
                 "dataset": video.backend.dataset,
                 "input_format": video.backend.input_format,
@@ -180,12 +216,12 @@ def video_to_dict(video: Video) -> dict:
 
     elif type(video.backend) == ImageVideo:
         return {
-            "filename": video.filename,
+            "filename": video_filename,
             "backend": {
                 "type": "ImageVideo",
                 "shape": video.shape,
-                "filename": video.backend.filename[0],
-                "filenames": video.backend.filename,
+                "filename": sanitize_filename(video.backend.filename[0]),
+                "filenames": sanitize_filename(video.backend.filename),
                 "dataset": video.backend_metadata.get("dataset", None),
                 "grayscale": video.grayscale,
                 "input_format": video.backend_metadata.get("input_format", None),
@@ -1003,17 +1039,20 @@ def write_lfs(labels_path: str, labels: Labels):
         )
 
 
-def read_labels(labels_path: str) -> Labels:
+def read_labels(labels_path: str, open_videos: bool = True) -> Labels:
     """Read a SLEAP labels file.
 
     Args:
         labels_path: A string path to the SLEAP labels file.
+        open_videos: If `True` (the default), attempt to open the video backend for
+            I/O. If `False`, the backend will not be opened (useful for reading metadata
+            when the video files are not available).
 
     Returns:
         The processed `Labels` object.
     """
     tracks = read_tracks(labels_path)
-    videos = read_videos(labels_path)
+    videos = read_videos(labels_path, open_backend=open_videos)
     skeletons = read_skeletons(labels_path)
     points = read_points(labels_path)
     pred_points = read_pred_points(labels_path)

sleap_io/model/video.py

@@ -34,6 +34,11 @@ class Video:
             information) without having access to the video file itself.
         source_video: The source video object if this is a proxy video. This is present
             when the video contains an embedded subset of frames from another video.
+        open_backend: Whether to open the backend when the video is available. If `True`
+            (the default), the backend will be automatically opened if the video exists.
+            Set this to `False` when you want to manually open the backend, or when the
+            you know the video file does not exist and you want to avoid trying to open
+            the file.
 
     Notes:
         Instances of this class are hashed by identity, not by value. This means that
@@ -47,12 +52,13 @@ class Video:
     backend: Optional[VideoBackend] = None
     backend_metadata: dict[str, any] = attrs.field(factory=dict)
     source_video: Optional[Video] = None
+    open_backend: bool = True
 
     EXTS = MediaVideo.EXTS + HDF5Video.EXTS + ImageVideo.EXTS
 
     def __attrs_post_init__(self):
         """Post init syntactic sugar."""
-        if self.backend is None and self.exists():
+        if self.open_backend and self.backend is None and self.exists():
             self.open()
 
     @classmethod
@@ -181,7 +187,13 @@ def __getitem__(self, inds: int | list[int] | slice) -> np.ndarray:
         See also: VideoBackend.get_frame, VideoBackend.get_frames
         """
         if not self.is_open:
-            self.open()
+            if self.open_backend:
+                self.open()
+            else:
+                raise ValueError(
+                    "Video backend is not open. Call video.open() or set "
+                    "video.open_backend to True to do automatically on frame read."
+                )
         return self.backend[inds]
 
     def exists(self, check_all: bool = False) -> bool:
@@ -208,13 +220,16 @@ def is_open(self) -> bool:
 
     def open(
         self,
+        filename: Optional[str] = None,
         dataset: Optional[str] = None,
         grayscale: Optional[str] = None,
         keep_open: bool = True,
     ):
         """Open the video backend for reading.
 
         Args:
+            filename: Filename to open. If not specified, will use the filename set on
+                the video object.
             dataset: Name of dataset in HDF5 file.
             grayscale: Whether to force grayscale. If None, autodetect on first frame
                 load.
@@ -231,6 +246,9 @@ def open(
             Values for the HDF5 dataset and grayscale will be remembered if not
             specified.
         """
+        if filename is not None:
+            self.replace_filename(filename, open=False)
+
         if not self.exists():
             raise FileNotFoundError(f"Video file not found: {self.filename}")
 

tests/io/test_slp.py

@@ -354,3 +354,12 @@ def test_embed_two_rounds(tmpdir, slp_real_data):
         == "tests/data/videos/centered_pair_low_quality.mp4"
     )
     assert type(labels3.video.backend) == MediaVideo
+
+
+def test_lazy_video_read(slp_real_data):
+    labels = read_labels(slp_real_data)
+    assert type(labels.video.backend) == MediaVideo
+    assert labels.video.exists()
+
+    labels = read_labels(slp_real_data, open_videos=False)
+    assert labels.video.backend is None