Clarify video inference warnings

Refines `video_inference` logging so empty results distinguish unreadable videos from detector misses, and keeps re-encoding guidance for partial reads. Expands tests to cover zero-prediction, partial-prediction, and shelf-writer cases.
C-Achard · Oct 23, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 9, 2026
commit 292d068807d0eb4f85122d8ff75bc52cf34c28f5
diff --git a/deeplabcut/pose_estimation_pytorch/apis/videos.py b/deeplabcut/pose_estimation_pytorch/apis/videos.py
@@ -229,21 +229,29 @@ def video_inference(
     if shelf_writer is not None:
         shelf_writer.close()
 
-    if shelf_writer is None and len(predictions) == 0 and n_frames > 0:
-        logging.warning(
-            "No predictions were produced for this video. This can happen if no "
-            "animals were detected in any frame. If that is unexpected, check "
-            "model performance and verify that the video can be read correctly."
-        )
-    elif shelf_writer is None and len(predictions) != n_frames:
+    if shelf_writer is None:
         tip_url = "https://deeplabcut.github.io/DeepLabCut/docs/recipes/io.html"
         header = "#tips-on-video-re-encoding-and-preprocessing"
-        logging.warning(
-            f"The video metadata indicates that there {n_frames} in the video, but "
-            f"only {len(predictions)} were able to be processed. This can happen if "
-            "the video is corrupted. You can try to fix the issue by re-encoding your "
-            f"video (tips on how to do that: {tip_url}{header})"
+        reencoding_tip = (
+            "This can happen if the video is corrupted. You can try to fix the issue "
+            f"by re-encoding your video (tips on how to do that: {tip_url}{header})"
         )
+        if len(predictions) == 0:
+            causes = (
+                "no animals were detected in any frame, or the video could not be read"
+                if detector_runner is not None
+                else "the video could not be read"
+            )
+            logging.warning(
+                f"No predictions were produced for {video.video_path}: {causes}. "
+                f"Check model performance if that is unexpected. {reencoding_tip}"
+            )
+        elif len(predictions) != n_frames:
+            logging.warning(
+                f"The video metadata indicates that there are {n_frames} frames in "
+                f"the video, but only {len(predictions)} were able to be processed. "
+                f"{reencoding_tip}"
+            )
 
     return predictions
 

diff --git a/tests/pose_estimation_pytorch/apis/test_videos.py b/tests/pose_estimation_pytorch/apis/test_videos.py
@@ -52,27 +52,108 @@ def test_create_df_from_prediction_rejects_empty_predictions(tmp_path):
     assert not (tmp_path / "video.h5").exists()
 
 
-def test_video_inference_warns_distinctly_for_zero_predictions(monkeypatch, caplog):
-    class FakeVideoIterator:
-        def __init__(self, video_path, cropping=None):
-            self.video_path = video_path
-            self.fps = 25
-            self.dimensions = (640, 480)
+@pytest.fixture
+def patch_video_iterator(monkeypatch):
+    """Patches ``VideoIterator`` with a stub reporting ``n_frames`` empty frames."""
 
-        def get_n_frames(self, robust=False):
-            return 3
+    def _patch(n_frames: int):
+        class FakeVideoIterator:
+            def __init__(self, video_path, cropping=None):
+                self.video_path = video_path
+                self.fps = 25
+                self.dimensions = (640, 480)
 
-        def __iter__(self):
-            return iter(())
+            def get_n_frames(self, robust=False):
+                return n_frames
 
-    monkeypatch.setattr(videos, "VideoIterator", FakeVideoIterator)
-    pose_runner = Mock()
-    pose_runner.batch_size = 2
-    pose_runner.inference.return_value = []
+            def set_context(self, context):
+                pass
+
+            def __iter__(self):
+                return iter(())
+
+        monkeypatch.setattr(videos, "VideoIterator", FakeVideoIterator)
+        return FakeVideoIterator
+
+    return _patch
+
+
+def _pose_runner(predictions: list) -> Mock:
+    runner = Mock()
+    runner.batch_size = 2
+    runner.inference.return_value = predictions
+    return runner
+
+
+def test_video_inference_zero_predictions_warns_about_unreadable_video(patch_video_iterator, caplog):
+    """Without a detector, every readable frame yields a prediction, so an empty
+    result means the video could not be read - not that no animals were found."""
+    patch_video_iterator(3)
+
+    with caplog.at_level("WARNING"):
+        predictions = videos.video_inference("video.mp4", _pose_runner([]))
+
+    assert predictions == []
+    assert "No predictions were produced for video.mp4" in caplog.text
+    assert "the video could not be read" in caplog.text
+    assert "no animals were detected" not in caplog.text
+    # the re-encoding tip is the actionable advice in this case
+    assert "re-encoding your video" in caplog.text
+
+
+def test_video_inference_zero_predictions_with_detector_warns_about_detections(patch_video_iterator, caplog):
+    patch_video_iterator(3)
+
+    with caplog.at_level("WARNING"):
+        predictions = videos.video_inference("video.mp4", _pose_runner([]), detector_runner=_pose_runner([]))
+
+    assert predictions == []
+    assert "no animals were detected in any frame" in caplog.text
+    assert "the video could not be read" in caplog.text
+    assert "re-encoding your video" in caplog.text
+
+
+def test_video_inference_zero_predictions_warns_when_frame_count_is_zero(patch_video_iterator, caplog):
+    """A video whose metadata reports 0 frames must still warn."""
+    patch_video_iterator(0)
+
+    with caplog.at_level("WARNING"):
+        predictions = videos.video_inference("video.mp4", _pose_runner([]))
+
+    assert predictions == []
+    assert "No predictions were produced for video.mp4" in caplog.text
+
+
+def test_video_inference_warns_when_some_frames_are_missing(patch_video_iterator, caplog):
+    patch_video_iterator(3)
+
+    with caplog.at_level("WARNING"):
+        predictions = videos.video_inference("video.mp4", _pose_runner([{}, {}]))
+
+    assert len(predictions) == 2
+    assert "there are 3 frames in the video, but only 2" in caplog.text
+    assert "re-encoding your video" in caplog.text
+    assert "No predictions were produced" not in caplog.text
+
+
+def test_video_inference_does_not_warn_when_all_frames_are_predicted(patch_video_iterator, caplog):
+    patch_video_iterator(3)
+
+    with caplog.at_level("WARNING"):
+        predictions = videos.video_inference("video.mp4", _pose_runner([{}, {}, {}]))
+
+    assert len(predictions) == 3
+    assert "No predictions were produced" not in caplog.text
+    assert "were able to be processed" not in caplog.text
+
+
+def test_video_inference_does_not_warn_when_writing_to_a_shelf(patch_video_iterator, caplog):
+    """The returned list is empty by design when a shelf writer is given."""
+    patch_video_iterator(3)
 
     with caplog.at_level("WARNING"):
-        predictions = videos.video_inference("video.mp4", pose_runner)
+        predictions = videos.video_inference("video.mp4", _pose_runner([]), shelf_writer=Mock())
 
     assert predictions == []
-    assert "No predictions were produced for this video." in caplog.text
-    assert "video is corrupted" not in caplog.text
+    assert "No predictions were produced" not in caplog.text
+    assert "were able to be processed" not in caplog.text