[bugfix]: address review — drop false BC docstring claim, dead code; add contract test

- paths.py: remove the claim that the pool auto-squeezes legacy
  (1,T,C,H,W) input — no such code exists anywhere in fastvideo/eval/ —
  and dedupe the shape sentence.
- basic_ltx2_audio_eval.py: drop the unreachable .corpus branch and
  always-true hasattr/isinstance guards (kwargs-form evaluate() returns
  a plain dict and rejects set metrics), restoring the direct
  results[name] lookup; fixes the double-printed skip reason.
- both examples: stdlib import ordering; drop the dead .mp4 suffix
  check on a hardcoded .mp4 path.
- new fastvideo/tests/eval/test_build_eval_kwargs.py locks the
  (T,C,H,W) no-batch-dim contract (CPU-only, PNG frame dir — no video
  decoder needed).

Author: SolitaryThinker

examples/inference/eval/basic_ltx2_audio_eval.py

@@ -18,11 +18,12 @@
 Install: ``uv pip install -e .[eval-audio]`` covers both metrics here
 (and the rest of the audio suite).
 """
+from pathlib import Path
+
 import torch
 
 from fastvideo import VideoGenerator
 from fastvideo.eval import create_evaluator
-from pathlib import Path
 
 PROMPT = (
     "A warm sunny backyard. The camera starts in a tight cinematic close-up "
@@ -70,33 +71,14 @@ def main() -> None:
 
     print("\n=== Audio scores ===")
     for name in METRICS:
-        r = None
-
-        # per-sample metric
-        if hasattr(results, "__contains__") and name in results:
-            r = results[name]
-
-        # corpus-level metric (e.g. audio.frechet_distance)
-        elif hasattr(results, "corpus") and name in results.corpus:
-            r = results.corpus[name]
-
-        if r is None:
-            print(f"  {name}: MISSING")
-            continue
-
+        r = results[name]
         if r.score is None:
-            skipped = (
-                r.details.get("skipped", "no score")
-                if isinstance(r.details, dict)
-                else "no score"
-            )
-            print(f"  {name}: SKIPPED ({skipped})")
+            print(f"  {name}: SKIPPED ({r.details.get('skipped', 'no score')})")
         else:
             print(f"  {name}: {r.score:.4f}")
-
-        if r.details:
-            for k, v in r.details.items():
-                print(f"      {k}: {v}")
+            if r.details:
+                for k, v in r.details.items():
+                    print(f"      {k}: {v}")
 
 
 if __name__ == "__main__":

examples/inference/eval/basic_ltx2_eval.py

@@ -25,12 +25,13 @@
 required scale-down. Drop ``motion_smoothness`` from ``METRICS`` if
 sharing, or run on a smaller-resolution generation.
 """
+from pathlib import Path
+
 import torch
 
 from fastvideo import VideoGenerator
 from fastvideo.eval import Evaluator
 from fastvideo.eval.io import build_eval_kwargs
-from pathlib import Path
 
 PROMPT = (
     "A warm sunny backyard. The camera starts in a tight cinematic close-up "
@@ -68,7 +69,7 @@ def main() -> None:
     output_file = Path(output_path)
 
     # ----- generation (matches examples/inference/basic/basic_ltx2.py) -----
-    if output_file.exists() and output_file.suffix.lower() == ".mp4":
+    if output_file.exists():
         print(f"[eval] found existing video: {output_file}")
         print("[eval] skipping generation")
     else:

fastvideo/eval/io/paths.py

@@ -44,14 +44,11 @@ def _idx(p: Path) -> int:
 def build_eval_kwargs(row: dict, video_path: Path, *, fps: float = 24.0) -> dict[str, Any]:
     """Build evaluator kwargs from a sample row + a video on disk.
 
-    Loads the video as ``(T, C, H, W)`` in ``[0, 1]``.
+    Loads the video as ``(T, C, H, W)`` float in ``[0, 1]`` — the shape
+    every metric consumes (see :meth:`BaseMetric.compute`).
     Forwards ``prompt`` as scalar ``text_prompt`` and ``auxiliary_info``
     as scalar dict when present on the row, matching the one-sample-per-call
     contract used by ``Evaluator.evaluate(**sample)``.
-
-    The returned ``video`` tensor has shape ``(T, C, H, W)`` in ``[0, 1]``.
-    The eval pool still auto-squeezes legacy ``(1, T, C, H, W)`` callers
-    for backward compatibility.
     """
     from fastvideo.eval.io.video import load_video
 

fastvideo/tests/eval/test_build_eval_kwargs.py

@@ -0,0 +1,50 @@
+"""Contract test for :func:`fastvideo.eval.io.build_eval_kwargs`.
+
+Locks the sample shape handed to ``Evaluator.evaluate(**sample)``:
+``video`` must be ``(T, C, H, W)`` float in ``[0, 1]`` — the shape every
+metric consumes (see :meth:`BaseMetric.compute`) — with no leading batch
+dim. Regression guard for the ``unsqueeze(0)`` bug fixed in #1412.
+
+CPU-only; uses a directory of PNG frames so no video decoder is needed.
+"""
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+from fastvideo.eval.io import build_eval_kwargs
+
+T, H, W = 3, 8, 10
+
+
+def _write_frames(dir_path) -> None:
+    dir_path.mkdir()
+    for i in range(T):
+        arr = np.full((H, W, 3), i * 40, dtype=np.uint8)
+        Image.fromarray(arr).save(dir_path / f"frame_{i:03d}.png")
+
+
+def test_build_eval_kwargs_video_is_4d_tchw(tmp_path):
+    frames = tmp_path / "frames"
+    _write_frames(frames)
+
+    row = {"prompt": "a test prompt", "auxiliary_info": {"key": "val"}}
+    sample = build_eval_kwargs(row, frames, fps=24.0)
+
+    video = sample["video"]
+    assert video.shape == (T, 3, H, W), "video must be (T, C, H, W) with no batch dim"
+    assert video.dtype.is_floating_point
+    assert 0.0 <= video.min() and video.max() <= 1.0
+    assert sample["fps"] == 24.0
+    assert sample["text_prompt"] == "a test prompt"
+    assert sample["auxiliary_info"] == {"key": "val"}
+
+
+def test_build_eval_kwargs_omits_absent_row_keys(tmp_path):
+    frames = tmp_path / "frames"
+    _write_frames(frames)
+
+    sample = build_eval_kwargs({}, frames)
+
+    assert set(sample) == {"video", "fps"}
+    assert sample["fps"] == 24.0