framesig 0.1.0__py3-none-any.whl

framesig/__init__.py

@@ -0,0 +1,78 @@
+"""framesig — detect on-screen events in any video by pixel signature.
+
+Define a region of interest plus a colour/brightness signature in YAML, and
+framesig scans the video (sub-sampling frames, caching scores) to report the
+timestamps where the event appears. It is game- and source-agnostic: it only
+ever reasons about pixels, never about what produced them.
+
+Typical use::
+
+    from framesig import load_config, scan_video, detect_all
+
+    config = load_config("signatures.yaml")
+    result = scan_video("clip.mp4", config)
+    events = detect_all(config, result)
+    for name, evs in events.items():
+        for e in evs:
+            print(name, round(e.peak_t, 2))
+"""
+
+from __future__ import annotations
+
+from .cache import ScoreCache
+from .config import Config, Signature, load_config, parse_config
+from .detectors import (
+    Brightness,
+    ChannelDominance,
+    ColorFraction,
+    Detector,
+    SceneChange,
+    available_detectors,
+    build_detector,
+)
+from .errors import (
+    ConfigError,
+    DependencyError,
+    FramesigError,
+    VideoError,
+)
+from .events import Event, detect_events
+from .regions import Region
+from .scanner import ScanResult, detect_all, scan_video
+from .videogen import GroundTruth, SampleVideo, generate_sample_video
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # config
+    "Config",
+    "Signature",
+    "load_config",
+    "parse_config",
+    # regions & detectors
+    "Region",
+    "Detector",
+    "Brightness",
+    "ChannelDominance",
+    "ColorFraction",
+    "SceneChange",
+    "available_detectors",
+    "build_detector",
+    # scanning & events
+    "ScanResult",
+    "scan_video",
+    "detect_all",
+    "Event",
+    "detect_events",
+    "ScoreCache",
+    # sample generation
+    "generate_sample_video",
+    "SampleVideo",
+    "GroundTruth",
+    # errors
+    "FramesigError",
+    "ConfigError",
+    "VideoError",
+    "DependencyError",
+]

framesig/_coerce.py

@@ -0,0 +1,47 @@
+"""Shared coercions for turning parsed YAML scalars into typed values.
+
+YAML hands us whatever the document contained, so ``threshold: high`` arrives as
+a ``str`` and a bare ``gain:`` arrives as ``None``. Every conversion that can
+fail on user input goes through this module, which reports the failure as a
+:class:`~framesig.errors.ConfigError` — the contract stated in
+:mod:`framesig.errors` and in :func:`framesig.config.parse_config`.
+
+It lives in its own module so that both :mod:`framesig.config` and
+:mod:`framesig.regions` can use it without an import cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import ConfigError
+
+
+def as_number(field: str, value: Any) -> float:
+    """Coerce ``value`` to ``float``.
+
+    Args:
+        field: Human-readable name of the field, used in the error message.
+        value: The raw value straight out of the YAML document.
+
+    Raises:
+        ConfigError: If ``float()`` rejects ``value``.
+    """
+    try:
+        return float(value)
+    except (ValueError, TypeError) as exc:
+        raise ConfigError(f"{field} must be a number, got {value!r}") from exc
+
+
+def as_bool(field: str, value: Any) -> bool:
+    """Return ``value`` if it is a real ``bool``.
+
+    Deliberately strict: ``bool("false")`` is ``True``, so quietly coercing a
+    quoted YAML string would invert the user's intent.
+
+    Raises:
+        ConfigError: If ``value`` is not a ``bool``.
+    """
+    if not isinstance(value, bool):
+        raise ConfigError(f"{field} must be true or false, got {value!r}")
+    return value

framesig/cache.py

@@ -0,0 +1,85 @@
+"""On-disk caching of per-frame scores.
+
+Scanning a video is the expensive part; thresholding the resulting scores is
+practically free. framesig therefore caches the raw score timelines keyed by
+
+  * a fingerprint of the *video* (path, size, mtime), and
+  * a fingerprint of the *score-relevant* config (sampling rate, regions, and
+    detector parameters — but **not** thresholds, ``min_duration`` or
+    ``merge_gap``).
+
+That split is the whole point: tweak a threshold, re-run, and framesig reuses
+the cached scores for an instant answer. Change a detector's parameters and the
+fingerprint changes, so a stale cache is transparently ignored.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+CACHE_VERSION = 2
+
+
+def video_fingerprint(path: str | Path) -> dict[str, Any]:
+    """Cheap identity for a video file: absolute path, byte size and mtime."""
+    p = Path(path)
+    stat = p.stat()
+    return {"path": str(p.resolve()), "size": stat.st_size, "mtime_ns": stat.st_mtime_ns}
+
+
+def _digest(payload: dict[str, Any]) -> str:
+    blob = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(blob).hexdigest()[:16]
+
+
+def cache_key(video_fp: dict[str, Any], config_fp: dict[str, Any]) -> str:
+    """Combine video and config fingerprints into a stable filename stem."""
+    return _digest({"video": video_fp, "config": config_fp, "v": CACHE_VERSION})
+
+
+class ScoreCache:
+    """A tiny JSON-backed cache of score timelines.
+
+    Args:
+        directory: Where cache files live. Created on first write.
+    """
+
+    def __init__(self, directory: str | Path) -> None:
+        self.directory = Path(directory)
+
+    def _path_for(self, key: str) -> Path:
+        return self.directory / f"scores_{key}.json"
+
+    def load(self, key: str) -> dict[str, Any] | None:
+        """Return the cached payload for ``key``, or ``None`` on a miss.
+
+        A corrupt or unreadable cache file is treated as a miss rather than an
+        error, so a bad cache can never break a scan.
+        """
+        path = self._path_for(key)
+        if not path.exists():
+            return None
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        if not isinstance(payload, dict) or payload.get("version") != CACHE_VERSION:
+            return None
+        return payload
+
+    def store(self, key: str, payload: dict[str, Any]) -> Path:
+        """Write ``payload`` under ``key`` and return the file path.
+
+        The write is atomic (temp file + replace) so a crash mid-write cannot
+        leave a half-written cache behind.
+        """
+        self.directory.mkdir(parents=True, exist_ok=True)
+        payload = {**payload, "version": CACHE_VERSION}
+        path = self._path_for(key)
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(payload), encoding="utf-8")
+        tmp.replace(path)
+        return path

framesig/cli.py

@@ -0,0 +1,243 @@
+"""Command-line interface for framesig.
+
+Subcommands:
+  * ``scan``       — scan a video against a YAML config and emit JSON events.
+  * ``gen-sample`` — render the self-contained synthetic test clip.
+  * ``demo``       — generate the clip, scan it, and write events + a chart.
+  * ``detectors``  — list the available detector types.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from . import __version__
+from .config import Config, load_config, parse_config
+from .detectors import available_detectors
+from .errors import ConfigError, FramesigError
+from .events import Event
+from .scanner import ScanResult, detect_all, scan_video
+from .videogen import generate_sample_video
+
+# Canonical demo config, mirrored by examples/flash.yaml. Matches the ground
+# truth baked into framesig.videogen.
+DEMO_CONFIG: dict[str, Any] = {
+    "sample_fps": 10,
+    "regions": {
+        "hud_top": {"x": 0.0, "y": 0.0, "w": 1.0, "h": 0.55},
+        "kill_feed": {"x": 0.08, "y": 0.74, "w": 0.84, "h": 0.18},
+        "screen_mid": {"x": 0.30, "y": 0.58, "w": 0.40, "h": 0.12},
+        "corner": {"x": 0.82, "y": 0.94, "w": 0.18, "h": 0.06},
+    },
+    "signatures": [
+        {
+            "name": "death_screen",
+            "region": "hud_top",
+            "detector": "channel_dominance",
+            "params": {"channel": "red", "gain": 2.0},
+            "threshold": 0.30,
+            "min_duration": 0.15,
+            "merge_gap": 0.25,
+        },
+        {
+            "name": "kill_feed",
+            "region": "kill_feed",
+            "detector": "color_fraction",
+            "params": {
+                "hsv_low": [0, 120, 70],
+                "hsv_high": [10, 255, 255],
+                "hsv_low2": [170, 120, 70],
+                "hsv_high2": [179, 255, 255],
+            },
+            "threshold": 0.20,
+            "min_duration": 0.10,
+            "merge_gap": 0.20,
+        },
+        {
+            "name": "white_flash",
+            "region": "screen_mid",
+            "detector": "brightness",
+            "threshold": 0.75,
+            "min_duration": 0.10,
+        },
+        {
+            "name": "scene_cut",
+            "region": "corner",
+            "detector": "scene_change",
+            "threshold": 0.15,
+            "min_duration": 0.0,
+        },
+    ],
+}
+
+
+def _events_payload(events: dict[str, list[Event]]) -> dict[str, list[dict[str, Any]]]:
+    return {name: [e.to_dict() for e in evs] for name, evs in events.items()}
+
+
+def _print_summary(result: ScanResult, events: dict[str, list[Event]], stream) -> None:
+    meta = result.meta
+    src = "cache" if result.from_cache else "scan"
+    total = sum(len(v) for v in events.values())
+    print(
+        f"{Path(result.video).name}  "
+        f"{meta.get('width')}x{meta.get('height')}  "
+        f"{meta.get('duration', 0):.1f}s  "
+        f"{meta.get('samples')} samples @ {meta.get('sample_fps')} fps  ({src})",
+        file=stream,
+    )
+    print(f"{total} event(s) across {len(events)} signature(s)", file=stream)
+    for name, evs in events.items():
+        print(f"  {name}: {len(evs)}", file=stream)
+        for e in evs:
+            print(
+                f"    [{e.start:6.2f}s -> {e.end:6.2f}s]  "
+                f"peak {e.peak_score:.2f} @ {e.peak_t:6.2f}s  "
+                f"({e.samples} samples)",
+                file=stream,
+            )
+
+
+def _write_json(obj: dict[str, Any], out: str | None) -> None:
+    text = json.dumps(obj, indent=2)
+    if out is None or out == "-":
+        print(text)
+    else:
+        Path(out).parent.mkdir(parents=True, exist_ok=True)
+        Path(out).write_text(text + "\n", encoding="utf-8")
+        print(f"wrote {out}", file=sys.stderr)
+
+
+def _run_scan(config: Config, video: str, *, use_cache: bool) -> tuple[ScanResult, dict[str, list[Event]]]:
+    result = scan_video(video, config, use_cache=use_cache)
+    events = detect_all(config, result)
+    return result, events
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    if args.sample_fps is not None:
+        # Mutating the dataclass skips parse_config's validation, so repeat it
+        # here: the flag must obey the same rule as the YAML key.
+        if args.sample_fps <= 0:
+            raise ConfigError("--sample-fps must be positive")
+        config.sample_fps = float(args.sample_fps)
+    result, events = _run_scan(config, args.video, use_cache=not args.no_cache)
+
+    if not args.quiet:
+        _print_summary(result, events, sys.stderr)
+    payload = {
+        "video": result.video,
+        "meta": result.meta,
+        "from_cache": result.from_cache,
+        "events": _events_payload(events),
+    }
+    _write_json(payload, args.output)
+
+    if args.chart:
+        from .viz import render_timeline
+
+        path = render_timeline(config, result, events, args.chart)
+        print(f"wrote chart {path}", file=sys.stderr)
+    return 0
+
+
+def cmd_gen_sample(args: argparse.Namespace) -> int:
+    sample = generate_sample_video(args.output)
+    print(f"wrote {sample.path}  ({sample.width}x{sample.height}, {sample.duration:g}s)", file=sys.stderr)
+    if args.print_truth:
+        _write_json(
+            {
+                "intervals": {k: v for k, v in sample.ground_truth.intervals.items()},
+                "cuts": sample.ground_truth.cuts,
+            },
+            "-",
+        )
+    return 0
+
+
+def cmd_demo(args: argparse.Namespace) -> int:
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    video_path = out_dir / "sample.mp4"
+
+    print("[1/3] rendering synthetic clip with ffmpeg...", file=sys.stderr)
+    generate_sample_video(video_path)
+
+    print("[2/3] scanning for pixel signatures...", file=sys.stderr)
+    config = parse_config(DEMO_CONFIG)
+    result, events = _run_scan(config, str(video_path), use_cache=not args.no_cache)
+    _print_summary(result, events, sys.stderr)
+
+    events_path = out_dir / "events.json"
+    _write_json(
+        {"video": result.video, "meta": result.meta, "events": _events_payload(events)},
+        str(events_path),
+    )
+
+    print("[3/3] rendering score-timeline chart...", file=sys.stderr)
+    from .viz import render_timeline
+
+    chart_path = render_timeline(config, result, events, out_dir / "timeline.png")
+    print(f"done. outputs in {out_dir}/", file=sys.stderr)
+    print(f"  {video_path.name}, {events_path.name}, {chart_path.name}", file=sys.stderr)
+    return 0
+
+
+def cmd_detectors(_args: argparse.Namespace) -> int:
+    for name in available_detectors():
+        print(name)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="framesig",
+        description="Detect on-screen events in a video by pixel signature.",
+    )
+    parser.add_argument("--version", action="version", version=f"framesig {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="scan a video against a YAML config")
+    p_scan.add_argument("video", help="path to the video file")
+    p_scan.add_argument("-c", "--config", required=True, help="YAML config path")
+    p_scan.add_argument("-o", "--output", help="write events JSON here ('-' for stdout)")
+    p_scan.add_argument("--sample-fps", type=float, help="override the sampling rate")
+    p_scan.add_argument("--no-cache", action="store_true", help="ignore and skip the score cache")
+    p_scan.add_argument("--chart", help="also render a score-timeline PNG here")
+    p_scan.add_argument("-q", "--quiet", action="store_true", help="suppress the text summary")
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_gen = sub.add_parser("gen-sample", help="render the synthetic test clip")
+    p_gen.add_argument("output", help="destination .mp4 path")
+    p_gen.add_argument("--print-truth", action="store_true", help="print the ground-truth events")
+    p_gen.set_defaults(func=cmd_gen_sample)
+
+    p_demo = sub.add_parser("demo", help="generate a clip, scan it, and chart the result")
+    p_demo.add_argument("--out-dir", default="framesig_demo", help="output directory")
+    p_demo.add_argument("--no-cache", action="store_true", help="skip the score cache")
+    p_demo.set_defaults(func=cmd_demo)
+
+    p_det = sub.add_parser("detectors", help="list available detector types")
+    p_det.set_defaults(func=cmd_detectors)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point. Returns a process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except FramesigError as exc:
+        print(f"framesig: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

framesig/config.py

@@ -0,0 +1,202 @@
+"""Declarative configuration.
+
+A framesig run is described entirely by a small YAML document: how densely to
+sample the video, which regions of interest exist, and which signatures to
+evaluate over them. This module parses that document into validated dataclasses.
+
+Example:
+    sample_fps: 10
+    regions:
+      hud_top:   {x: 0.0, y: 0.0,  w: 1.0,  h: 0.55}
+      kill_feed: {x: 0.08, y: 0.74, w: 0.84, h: 0.18}
+    signatures:
+      - name: death_screen
+        region: hud_top
+        detector: channel_dominance
+        params: {channel: red, gain: 2.0}
+        threshold: 0.30
+        min_duration: 0.1
+        merge_gap: 0.25
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+from ._coerce import as_number
+from .detectors import Detector, build_detector
+from .errors import ConfigError
+from .regions import Region
+
+_ALLOWED_TOP_KEYS = {"sample_fps", "regions", "signatures", "cache_dir"}
+
+_ALLOWED_SIGNATURE_KEYS = {
+    "name",
+    "region",
+    "detector",
+    "params",
+    "threshold",
+    "min_duration",
+    "merge_gap",
+}
+
+
+@dataclass
+class Signature:
+    """One thing to look for: a detector applied to a region, plus event rules.
+
+    Attributes:
+        name: Unique identifier, used in output and cache keys.
+        region: The :class:`~framesig.regions.Region` to crop before scoring.
+        detector: The instantiated :class:`~framesig.detectors.Detector`.
+        threshold: Minimum score for a sample to count as active.
+        min_duration: Discard events shorter than this many seconds.
+        merge_gap: Merge active runs separated by at most this many seconds.
+    """
+
+    name: str
+    region: Region
+    detector: Detector
+    threshold: float = 0.5
+    min_duration: float = 0.0
+    merge_gap: float = 0.0
+
+    def score_fingerprint(self) -> dict[str, Any]:
+        """Fields that change the *scores* (not the thresholds)."""
+        return {"region": self.region.fingerprint(), "detector": self.detector.fingerprint()}
+
+
+@dataclass
+class Config:
+    """A fully validated framesig configuration.
+
+    Attributes:
+        sample_fps: Target sampling rate in frames per second. The scanner
+            processes roughly this many frames per second of video, regardless
+            of the source frame rate.
+        regions: Declared regions, keyed by name.
+        signatures: The signatures to evaluate.
+        cache_dir: Optional directory for the score cache. ``None`` defers to
+            the scanner's default (a ``.framesig_cache`` folder next to the video).
+    """
+
+    sample_fps: float = 5.0
+    regions: dict[str, Region] = field(default_factory=dict)
+    signatures: list[Signature] = field(default_factory=list)
+    cache_dir: str | None = None
+
+    def score_fingerprint(self) -> dict[str, Any]:
+        """The score-relevant projection of the config, for cache keying."""
+        return {
+            "sample_fps": self.sample_fps,
+            "signatures": {s.name: s.score_fingerprint() for s in self.signatures},
+        }
+
+
+def _parse_signature(raw: Mapping[str, Any], regions: Mapping[str, Region]) -> Signature:
+    if not isinstance(raw, Mapping):
+        raise ConfigError(f"each signature must be a mapping, got {type(raw).__name__}")
+    unknown = set(raw) - _ALLOWED_SIGNATURE_KEYS
+    if unknown:
+        raise ConfigError(
+            f"signature has unknown keys {sorted(unknown)}; "
+            f"allowed: {sorted(_ALLOWED_SIGNATURE_KEYS)}"
+        )
+    try:
+        name = str(raw["name"])
+        region_name = str(raw["region"])
+        detector_type = str(raw["detector"])
+    except KeyError as exc:
+        raise ConfigError(f"signature missing required key {exc.args[0]!r}") from exc
+
+    if region_name not in regions:
+        raise ConfigError(
+            f"signature {name!r} references unknown region {region_name!r}; "
+            f"declared regions: {sorted(regions)}"
+        )
+
+    params = raw.get("params") or {}
+    if not isinstance(params, Mapping):
+        raise ConfigError(
+            f"signature {name!r}: 'params' must be a mapping, "
+            f"got {type(params).__name__}"
+        )
+
+    detector = build_detector(detector_type, params)
+    return Signature(
+        name=name,
+        region=regions[region_name],
+        detector=detector,
+        threshold=as_number(f"signature {name!r}: threshold", raw.get("threshold", 0.5)),
+        min_duration=as_number(
+            f"signature {name!r}: min_duration", raw.get("min_duration", 0.0)
+        ),
+        merge_gap=as_number(f"signature {name!r}: merge_gap", raw.get("merge_gap", 0.0)),
+    )
+
+
+def parse_config(data: Mapping[str, Any]) -> Config:
+    """Build a :class:`Config` from an already-parsed mapping.
+
+    Raises:
+        ConfigError: On any structural or semantic problem.
+    """
+    if not isinstance(data, Mapping):
+        raise ConfigError("top-level config must be a mapping")
+
+    unknown = set(data) - _ALLOWED_TOP_KEYS
+    if unknown:
+        raise ConfigError(
+            f"unknown top-level keys {sorted(unknown)}; "
+            f"allowed: {sorted(_ALLOWED_TOP_KEYS)}"
+        )
+
+    sample_fps = as_number("sample_fps", data.get("sample_fps", 5.0))
+    if sample_fps <= 0:
+        raise ConfigError("sample_fps must be positive")
+
+    raw_regions = data.get("regions") or {}
+    if not isinstance(raw_regions, Mapping):
+        raise ConfigError("'regions' must be a mapping of name -> box")
+    regions = {name: Region.from_mapping(name, box) for name, box in raw_regions.items()}
+
+    raw_signatures = data.get("signatures") or []
+    if not isinstance(raw_signatures, list):
+        raise ConfigError("'signatures' must be a list")
+    signatures = [_parse_signature(s, regions) for s in raw_signatures]
+
+    if not signatures:
+        raise ConfigError("config declares no signatures; nothing to detect")
+
+    names = [s.name for s in signatures]
+    dupes = {n for n in names if names.count(n) > 1}
+    if dupes:
+        raise ConfigError(f"duplicate signature names: {sorted(dupes)}")
+
+    cache_dir = data.get("cache_dir")
+    return Config(
+        sample_fps=sample_fps,
+        regions=regions,
+        signatures=signatures,
+        cache_dir=str(cache_dir) if cache_dir is not None else None,
+    )
+
+
+def load_config(path: str | Path) -> Config:
+    """Load and validate a YAML config from disk."""
+    path = Path(path)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"cannot read config {str(path)!r}: {exc}") from exc
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"invalid YAML in {str(path)!r}: {exc}") from exc
+    if data is None:
+        raise ConfigError(f"config {str(path)!r} is empty")
+    return parse_config(data)