framesig 0.1.0__py3-none-any.whl

framesig/scanner.py

@@ -0,0 +1,211 @@
+"""The scanner: decode a video, sample frames, score every signature.
+
+This is the compute-heavy core. It walks the video once, sub-samples frames to
+the configured rate, crops each signature's region and asks its detector for a
+score. The resulting score timelines are what gets cached and later turned into
+events.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+import cv2
+
+from . import cache as cache_mod
+from .config import Config
+from .errors import VideoError
+from .events import Event, detect_events
+
+ProgressFn = Callable[[int, int], None]
+
+
+@dataclass
+class ScanResult:
+    """The scored timelines for one video under one config.
+
+    Attributes:
+        video: Path to the scanned video.
+        meta: Decode metadata (native fps, dimensions, duration, sample step...).
+        timestamps: The shared list of sample timestamps in seconds.
+        scores: ``signature name -> list of scores`` aligned with ``timestamps``.
+        from_cache: ``True`` if these scores were loaded from disk rather than
+            recomputed.
+    """
+
+    video: str
+    meta: dict[str, Any]
+    timestamps: list[float]
+    scores: dict[str, list[float]]
+    from_cache: bool = False
+
+    def to_payload(self) -> dict[str, Any]:
+        """Serialise into the dict stored by :class:`~framesig.cache.ScoreCache`."""
+        return {
+            "video": self.video,
+            "meta": self.meta,
+            "timestamps": self.timestamps,
+            "scores": self.scores,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "ScanResult":
+        return cls(
+            video=payload["video"],
+            meta=payload["meta"],
+            timestamps=list(payload["timestamps"]),
+            scores={k: list(v) for k, v in payload["scores"].items()},
+            from_cache=True,
+        )
+
+
+def _iter_frames(cap: "cv2.VideoCapture", step: int) -> Iterator[tuple[int, Any]]:
+    """Yield ``(frame_index, frame)`` for every ``step``-th decoded frame."""
+    index = 0
+    while True:
+        ok, frame = cap.read()
+        if not ok:
+            break
+        if index % step == 0:
+            yield index, frame
+        index += 1
+
+
+def _default_cache_dir(video: Path, config: Config, override: str | None) -> Path:
+    if override is not None:
+        return Path(override)
+    if config.cache_dir is not None:
+        return Path(config.cache_dir)
+    return video.parent / ".framesig_cache"
+
+
+def scan_video(
+    video_path: str | Path,
+    config: Config,
+    *,
+    use_cache: bool = True,
+    cache_dir: str | None = None,
+    progress: ProgressFn | None = None,
+) -> ScanResult:
+    """Scan a video and return per-signature score timelines.
+
+    Args:
+        video_path: Path to the video file.
+        config: A validated :class:`~framesig.config.Config`.
+        use_cache: When ``True`` (default), reuse a matching cached result and
+            write fresh results back to the cache.
+        cache_dir: Override the cache directory. Falls back to
+            ``config.cache_dir`` and then to ``<video>/../.framesig_cache``.
+        progress: Optional callback ``(processed_samples, approx_total)`` invoked
+            as scanning proceeds. ``approx_total`` may be ``0`` if the decoder
+            cannot report a frame count.
+
+    Returns:
+        A :class:`ScanResult`.
+
+    Raises:
+        VideoError: If the file cannot be opened or has an unusable frame rate.
+    """
+    video = Path(video_path)
+    if not video.exists():
+        raise VideoError(f"video not found: {str(video)!r}")
+
+    cache_directory = _default_cache_dir(video, config, cache_dir)
+    key = cache_mod.cache_key(
+        cache_mod.video_fingerprint(video), config.score_fingerprint()
+    )
+    store = cache_mod.ScoreCache(cache_directory)
+
+    if use_cache:
+        cached = store.load(key)
+        if cached is not None:
+            result = ScanResult.from_payload(cached)
+            # Guard against a stale cache missing a newly added signature.
+            if set(result.scores) == {s.name for s in config.signatures}:
+                return result
+
+    result = _scan_uncached(video, config, progress)
+    if use_cache:
+        store.store(key, result.to_payload())
+    return result
+
+
+def _scan_uncached(video: Path, config: Config, progress: ProgressFn | None) -> ScanResult:
+    cap = cv2.VideoCapture(str(video))
+    if not cap.isOpened():
+        raise VideoError(f"could not open video: {str(video)!r}")
+
+    try:
+        native_fps = float(cap.get(cv2.CAP_PROP_FPS))
+        if not math.isfinite(native_fps) or native_fps <= 0:
+            raise VideoError(
+                f"video reports an invalid frame rate ({native_fps}); "
+                f"cannot map frames to timestamps"
+            )
+        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
+
+        step = max(1, int(round(native_fps / config.sample_fps)))
+        approx_total = frame_count // step if frame_count > 0 else 0
+
+        for sig in config.signatures:
+            sig.detector.reset()
+
+        timestamps: list[float] = []
+        scores: dict[str, list[float]] = {s.name: [] for s in config.signatures}
+
+        processed = 0
+        for index, frame in _iter_frames(cap, step):
+            timestamps.append(index / native_fps)
+            for sig in config.signatures:
+                roi = sig.region.crop(frame)
+                scores[sig.name].append(sig.detector.score(roi))
+            processed += 1
+            if progress is not None:
+                progress(processed, approx_total)
+    finally:
+        cap.release()
+
+    if not timestamps:
+        raise VideoError(f"decoded zero frames from {str(video)!r}")
+
+    duration = (timestamps[-1] + step / native_fps) if timestamps else 0.0
+    meta = {
+        "native_fps": native_fps,
+        "frame_count": frame_count,
+        "width": width,
+        "height": height,
+        "sample_fps": config.sample_fps,
+        "step": step,
+        "sample_period": step / native_fps,
+        "samples": len(timestamps),
+        "duration": duration,
+    }
+    return ScanResult(video=str(video), meta=meta, timestamps=timestamps, scores=scores)
+
+
+def detect_all(config: Config, result: ScanResult) -> dict[str, list[Event]]:
+    """Apply each signature's thresholds to its cached scores.
+
+    This step is cheap, so it is kept separate from :func:`scan_video`: you can
+    re-run it with edited thresholds against the same (cached) scores instantly.
+
+    Returns:
+        ``signature name -> list of events``, preserving config order.
+    """
+    out: dict[str, list[Event]] = {}
+    for sig in config.signatures:
+        out[sig.name] = detect_events(
+            sig.name,
+            result.timestamps,
+            result.scores.get(sig.name, []),
+            threshold=sig.threshold,
+            min_duration=sig.min_duration,
+            merge_gap=sig.merge_gap,
+            period=result.meta.get("sample_period"),
+        )
+    return out

framesig/videogen.py

@@ -0,0 +1,173 @@
+"""Generate a self-contained synthetic test clip with ffmpeg.
+
+The clip is a fake game HUD painted with solid colour boxes at *known*
+timestamps, so tests (and the README demo) have deterministic ground truth to
+check the detector against — no external video, model or network required.
+
+Layout (640x360, 15 s, 30 fps, dark-blue base):
+
+  * a red flash across the top HUD area       -> ``death_screen`` (channel_dominance)
+  * a red bar in the lower kill-feed band      -> ``kill_feed``     (color_fraction)
+  * a white flash on a central screen panel    -> ``white_flash``   (brightness)
+  * a hard cut to teal across the whole frame  -> ``scene_cut``     (scene_change)
+
+The four effects occupy disjoint parts of the frame, so each detector sees only
+its own event and the ground truth stays clean.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import DependencyError
+
+WIDTH = 640
+HEIGHT = 360
+FPS = 30
+DURATION = 15.0
+BASE_COLOR = "0x101828"  # dark blue
+
+
+@dataclass(frozen=True)
+class GroundTruth:
+    """The events baked into the synthetic clip, per signature.
+
+    ``intervals`` maps a signature name to the ``(start, end)`` windows during
+    which its effect is on screen. ``cuts`` lists the timestamps of hard scene
+    cuts (single-frame events).
+    """
+
+    intervals: dict[str, list[tuple[float, float]]] = field(default_factory=dict)
+    cuts: list[float] = field(default_factory=list)
+
+    def expected_counts(self) -> dict[str, int]:
+        """Number of distinct events expected for each signature."""
+        counts = {name: len(windows) for name, windows in self.intervals.items()}
+        counts["scene_cut"] = len(self.cuts)
+        return counts
+
+
+@dataclass(frozen=True)
+class SampleVideo:
+    """Result of :func:`generate_sample_video`."""
+
+    path: Path
+    width: int
+    height: int
+    fps: int
+    duration: float
+    ground_truth: GroundTruth
+
+
+# Ground-truth timings, shared by the ffmpeg filter builder and the tests.
+_DEATH = [(2.0, 2.4), (7.5, 7.9)]
+_FEED = [(4.0, 4.3), (4.8, 5.0), (9.4, 9.8)]
+_WHITE = [(11.0, 11.3)]
+_CUT_T = 13.0
+
+
+def ground_truth() -> GroundTruth:
+    """Return the ground-truth events for the synthetic clip."""
+    return GroundTruth(
+        intervals={
+            "death_screen": list(_DEATH),
+            "kill_feed": list(_FEED),
+            "white_flash": list(_WHITE),
+        },
+        cuts=[_CUT_T],
+    )
+
+
+def _enable(windows: list[tuple[float, float]]) -> str:
+    # between(t,a,b) is inclusive; summing non-overlapping windows acts as OR.
+    return "+".join(f"between(t,{a},{b})" for a, b in windows)
+
+
+def _filtergraph() -> str:
+    # Disjoint boxes; single-quoted enable values keep their commas literal.
+    death = (
+        f"drawbox=x=0:y=0:w={WIDTH}:h={int(HEIGHT * 0.55)}:color=red:t=fill:"
+        f"enable='{_enable(_DEATH)}'"
+    )
+    feed = (
+        f"drawbox=x={int(WIDTH * 0.08)}:y={int(HEIGHT * 0.74)}:"
+        f"w={int(WIDTH * 0.84)}:h={int(HEIGHT * 0.18)}:color=red:t=fill:"
+        f"enable='{_enable(_FEED)}'"
+    )
+    white = (
+        f"drawbox=x={int(WIDTH * 0.30)}:y={int(HEIGHT * 0.58)}:"
+        f"w={int(WIDTH * 0.40)}:h={int(HEIGHT * 0.12)}:color=white:t=fill:"
+        f"enable='{_enable(_WHITE)}'"
+    )
+    cut = (
+        f"drawbox=x=0:y=0:w={WIDTH}:h={HEIGHT}:color=0x18A060:t=fill:"
+        f"enable='gte(t,{_CUT_T})'"
+    )
+    return ",".join([death, feed, white, cut])
+
+
+def generate_sample_video(
+    out_path: str | Path, *, ffmpeg: str = "ffmpeg", overwrite: bool = True
+) -> SampleVideo:
+    """Render the synthetic HUD clip to ``out_path`` using ffmpeg.
+
+    Args:
+        out_path: Destination ``.mp4`` file.
+        ffmpeg: Name or path of the ffmpeg binary.
+        overwrite: Overwrite an existing file (passes ``-y``).
+
+    Returns:
+        A :class:`SampleVideo` describing the file and its ground truth.
+
+    Raises:
+        DependencyError: If the ffmpeg binary is not on ``PATH`` or ffmpeg fails.
+    """
+    binary = shutil.which(ffmpeg)
+    if binary is None:
+        raise DependencyError(
+            f"ffmpeg binary {ffmpeg!r} not found on PATH; install ffmpeg to "
+            f"generate the sample clip"
+        )
+
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        binary,
+        "-y" if overwrite else "-n",
+        "-v",
+        "error",
+        "-f",
+        "lavfi",
+        "-i",
+        f"color=c={BASE_COLOR}:s={WIDTH}x{HEIGHT}:r={FPS}:d={DURATION}",
+        "-vf",
+        _filtergraph(),
+        "-pix_fmt",
+        "yuv420p",
+        "-c:v",
+        "libx264",
+        "-crf",
+        "18",
+        "-preset",
+        "veryfast",
+        str(out),
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0 or not out.exists():
+        raise DependencyError(
+            f"ffmpeg failed to render the sample clip (exit {proc.returncode}):\n"
+            f"{proc.stderr.strip()}"
+        )
+
+    return SampleVideo(
+        path=out,
+        width=WIDTH,
+        height=HEIGHT,
+        fps=FPS,
+        duration=DURATION,
+        ground_truth=ground_truth(),
+    )

framesig/viz.py

@@ -0,0 +1,108 @@
+"""Render a score-timeline chart, using only OpenCV (no plotting dependency).
+
+Given a :class:`~framesig.scanner.ScanResult` and the detected events, this draws
+one stacked lane per signature: the score curve, its threshold line, and shaded
+bands where events fired. It is handy for tuning thresholds by eye and for the
+project's README image.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from .config import Config
+from .events import Event
+from .scanner import ScanResult
+
+# Colours are BGR (OpenCV order).
+_BG = (24, 20, 16)
+_PANEL = (34, 30, 26)
+_GRID = (60, 54, 48)
+_TEXT = (210, 210, 210)
+_MUTED = (140, 140, 140)
+_CURVE = (235, 180, 90)
+_THRESH = (110, 110, 235)
+_EVENT = (90, 205, 120)
+
+
+def render_timeline(
+    config: Config,
+    result: ScanResult,
+    events: dict[str, list[Event]],
+    out_path: str | Path,
+    *,
+    width: int = 1040,
+    lane_height: int = 118,
+) -> Path:
+    """Render the score timelines to a PNG and return its path."""
+    signatures = config.signatures
+    pad_l, pad_r, pad_t, pad_b = 150, 24, 54, 40
+    plot_w = width - pad_l - pad_r
+    height = pad_t + pad_b + lane_height * len(signatures)
+
+    img = np.full((height, width, 3), _BG, dtype=np.uint8)
+    duration = max(result.meta.get("duration", 0.0), 1e-6)
+    ts = result.timestamps
+
+    def x_of(t: float) -> int:
+        return int(pad_l + (t / duration) * plot_w)
+
+    _text(img, "framesig  score timelines", (pad_l, 34), 0.72, _TEXT, 2)
+
+    for lane, sig in enumerate(signatures):
+        top = pad_t + lane * lane_height
+        bottom = top + lane_height - 26
+        cv2.rectangle(img, (pad_l, top), (pad_l + plot_w, bottom), _PANEL, -1)
+
+        # Horizontal grid at score 0, 0.5, 1.0.
+        for frac in (0.0, 0.5, 1.0):
+            y = int(bottom - frac * (bottom - top))
+            cv2.line(img, (pad_l, y), (pad_l + plot_w, y), _GRID, 1)
+
+        # Shade detected event spans.
+        for ev in events.get(sig.name, []):
+            x0, x1 = x_of(ev.start), max(x_of(ev.end), x_of(ev.start) + 2)
+            overlay = img.copy()
+            cv2.rectangle(overlay, (x0, top), (x1, bottom), _EVENT, -1)
+            cv2.addWeighted(overlay, 0.22, img, 0.78, 0, img)
+            cv2.line(img, (x_of(ev.peak_t), top), (x_of(ev.peak_t), bottom), _EVENT, 1)
+
+        # Threshold line.
+        yt = int(bottom - sig.threshold * (bottom - top))
+        for xd in range(pad_l, pad_l + plot_w, 10):
+            cv2.line(img, (xd, yt), (xd + 5, yt), _THRESH, 1)
+
+        # Score curve.
+        scores = result.scores.get(sig.name, [])
+        pts = [
+            (x_of(t), int(bottom - min(max(s, 0.0), 1.0) * (bottom - top)))
+            for t, s in zip(ts, scores)
+        ]
+        if len(pts) >= 2:
+            cv2.polylines(img, [np.array(pts, dtype=np.int32)], False, _CURVE, 2, cv2.LINE_AA)
+
+        n = len(events.get(sig.name, []))
+        _text(img, sig.name, (16, top + 26), 0.56, _TEXT, 1)
+        _text(img, f"{sig.detector.type_name}", (16, top + 48), 0.44, _MUTED, 1)
+        _text(img, f"thr {sig.threshold:g}", (16, top + 68), 0.44, _THRESH, 1)
+        _text(img, f"{n} event{'s' if n != 1 else ''}", (16, top + 88), 0.44, _EVENT, 1)
+
+    # Time axis ticks.
+    axis_y = height - pad_b + 16
+    for k in range(0, int(duration) + 1, 2):
+        x = x_of(k)
+        cv2.line(img, (x, pad_t - 6), (x, height - pad_b), _GRID, 1)
+        _text(img, f"{k}s", (x - 8, axis_y), 0.42, _MUTED, 1)
+
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if not cv2.imwrite(str(out), img):
+        raise OSError(f"failed to write chart image to {str(out)!r}")
+    return out
+
+
+def _text(img: np.ndarray, s: str, org: tuple[int, int], scale: float, color, thick: int) -> None:
+    cv2.putText(img, s, org, cv2.FONT_HERSHEY_SIMPLEX, scale, color, thick, cv2.LINE_AA)