Skip to content

World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.

fix(source_media_review): correct frame_sampler and probe contracts (#573)

xp29c646635e46
diff --git a/lib/source_media_review.py b/lib/source_media_review.py
index 43d4a924..8a70a70e 100644
--- a/lib/source_media_review.py
+++ b/lib/source_media_review.py
@@ -52,8 +52,13 @@ def _probe_video(path: Path, tool_registry: Any) -> dict[str, Any]:
except Exception as e:
logger.warning("audio_probe failed for %s: %s", path, e)
- # If audio_probe didn't work, try ffprobe directly
- if not result["technical_probe"]:
+ # audio_probe reports audio detail only, under a nested "audio" object, and
+ # carries no resolution/fps/video-codec. The summary built in
+ # review_source_media() reads flat "resolution"/"audio_codec"/"channels"
+ # keys, so without this ffprobe pass every video is reported as
+ # "unknown resolution, without audio". Merge rather than replace so the
+ # richer audio_probe fields survive.
+ if not result["technical_probe"].get("resolution"):
try:
import subprocess
cmd = [
@@ -67,7 +72,7 @@ def _probe_video(path: Path, tool_registry: Any) -> dict[str, Any]:
streams = probe_data.get("streams", [])
video_stream = next((s for s in streams if s.get("codec_type") == "video"), {})
audio_stream = next((s for s in streams if s.get("codec_type") == "audio"), {})
- result["technical_probe"] = {
+ result["technical_probe"].update({
"duration_seconds": float(fmt.get("duration", 0)),
"resolution": f"{video_stream.get('width', '?')}x{video_stream.get('height', '?')}",
"fps": _parse_fps(video_stream.get("r_frame_rate", "0/1")),
@@ -77,7 +82,7 @@ def _probe_video(path: Path, tool_registry: Any) -> dict[str, Any]:
"channels": int(audio_stream.get("channels", 0)) if audio_stream else 0,
"file_size_bytes": int(fmt.get("size", 0)),
"bitrate_kbps": round(int(fmt.get("bit_rate", 0)) / 1000, 1),
- }
+ })
except Exception as e:
logger.warning("ffprobe failed for %s: %s", path, e)
result["quality_risks"].append(f"Could not probe file: {e}")
@@ -90,11 +95,25 @@ def _probe_video(path: Path, tool_registry: Any) -> dict[str, Any]:
timestamps = _sample_timestamps(duration, count=4)
sample_result = frame_sampler.execute({
"input_path": str(path),
+ "strategy": "timestamps",
"timestamps": timestamps,
- "output_dir": str(path.parent / ".source_review_frames"),
+ # Namespaced per source file: the tool writes a fixed
+ # frame_NNNN.jpg set, so a shared directory lets each video
+ # overwrite the previous one's frames.
+ "output_dir": str(path.parent / f".source_review_frames_{path.stem}"),
})
if sample_result.success:
- result["representative_frames"] = sample_result.data.get("frame_paths", [])
+ # The frame list lives under "frames" (not "frame_paths"), as
+ # objects of {"path", "timestamp_seconds", "index"}. The
+ # artifact schema declares representative_frames as an array
+ # of path strings, so unwrap to paths or the artifact fails
+ # validation.
+ frames = sample_result.data.get("frames", [])
+ result["representative_frames"] = [
+ str(frame["path"])
+ for frame in frames
+ if isinstance(frame, dict) and frame.get("path")
+ ]
except Exception as e:
logger.warning("frame_sampler failed for %s: %s", path, e)
diff --git a/tests/lib/test_source_media_review_real_media.py b/tests/lib/test_source_media_review_real_media.py
new file mode 100644
index 00000000..fe66a9bd
--- /dev/null
+++ b/tests/lib/test_source_media_review_real_media.py
@@ -0,0 +1,127 @@
+"""Regression tests for source_media_review against real media files.
+
+The existing empty-input tests (test_source_media_review_empty.py) never
+reach the real-media path in _probe_video(). That gap hid four contract
+defects in how the review talks to the analysis tools:
+
+1. frame_sampler was called without the required "strategy" input
+2. the frame list was read from "frame_paths", a key that tool never returns
+3. frame objects were passed through where the schema wants path strings
+4. audio_probe's nested, audio-only output left every video summarised as
+ "unknown resolution, without audio"
+5. every video wrote its frames into one shared directory, so each clip
+ overwrote the previous one's frames
+
+(2) and (4) still produced schema-valid output -- an empty array and the
+string "unknown" -- so nothing ever raised. These tests build tiny real
+videos and assert the review is both accurate and schema-valid.
+"""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from lib.source_media_review import review_source_media # noqa: E402
+from schemas.artifacts import validate_artifact # noqa: E402
+
+
+pytestmark = pytest.mark.skipif(
+ shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None,
+ reason="ffmpeg/ffprobe are required to build and probe the fixture video",
+)
+
+
+def sample_video(tmp_path):
+ """A 2s 320x240 clip carrying an AAC audio track."""
+ path = tmp_path / "clip.mp4"
+ subprocess.run(
+ [
+ "ffmpeg", "-v", "error",
+ "-f", "lavfi", "-i", "testsrc=duration=2:size=320x240:rate=15",
+ "-f", "lavfi", "-i", "sine=frequency=440:duration=2",
+ "-shortest", "-c:v", "libx264", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", "-y", str(path),
+ ],
+ check=True,
+ )
+ return path
+
+
+def _single_entry(path):
+ artifact = review_source_media([path], {"pipeline_type": "hybrid"})
+ assert len(artifact["files"]) == 1, artifact["summary"]
+ return artifact["files"][0]
+
+
+def test_video_probe_reports_resolution_and_audio(sample_video):
+ """A video with a real audio track must not be reported as mute."""
+ entry = _single_entry(sample_video)
+ probe = entry["technical_probe"]
+
+ assert probe["resolution"] == "320x240"
+ assert probe["fps"] == pytest.approx(15.0, abs=0.1)
+ assert probe["audio_codec"] == "aac"
+
+ assert "with audio" in entry["content_summary"]
+ assert "unknown" not in entry["content_summary"]
+
+
+def test_video_probe_extracts_representative_frame_paths(sample_video):
+ """Frames must be extracted, and unwrapped to path strings."""
+ entry = _single_entry(sample_video)
+
+ frames = entry["representative_frames"]
+ assert len(frames) == 4
+ assert all(isinstance(frame, str) for frame in frames)
+ assert all(Path(frame).exists() for frame in frames)
+
+
+def test_review_with_real_video_is_schema_valid(sample_video):
+ """The artifact must survive validation once it carries real data."""
+ artifact = review_source_media([sample_video], {"pipeline_type": "hybrid"})
+
+ # Raises jsonschema.ValidationError on mismatch.
+ validate_artifact("source_media_review", artifact)
+
+
+def _make_solid_video(tmp_path, name, color):
+ """A 2s single-colour clip, so two clips are distinguishable files."""
+ path = tmp_path / name
+ subprocess.run(
+ [
+ "ffmpeg", "-v", "error",
+ "-f", "lavfi", "-i", f"color=c={color}:s=320x240:d=2:r=15",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", "-y", str(path),
+ ],
+ check=True,
+ )
+ return path
+
+
+def test_multiple_videos_do_not_share_frame_directory(tmp_path):
+ """Regression: the frame output dir was shared, so with several clips
+ each one overwrote the previous one's frames and every entry ended up
+ pointing at the last clip's frame_NNNN.jpg set.
+ """
+ clip_a = _make_solid_video(tmp_path, "a.mp4", "red")
+ clip_b = _make_solid_video(tmp_path, "b.mp4", "blue")
+
+ artifact = review_source_media([clip_a, clip_b], {"pipeline_type": "hybrid"})
+ entries = {Path(e["path"]).name: e for e in artifact["files"]}
+
+ frames_a = set(entries["a.mp4"]["representative_frames"])
+ frames_b = set(entries["b.mp4"]["representative_frames"])
+
+ assert frames_a, "clip a produced no representative frames"
+ assert frames_b, "clip b produced no representative frames"
+ assert frames_a.isdisjoint(frames_b), (
+ "frames overlap between clips -- the output directory is shared: "
+ f"{sorted(frames_a & frames_b)}"
+ )