open-redactor 0.2.0__py3-none-any.whl

open_redactor/__init__.py

@@ -0,0 +1,4 @@
+"""Open Redactor."""
+
+__all__ = ["__version__"]
+__version__ = "0.2.0"

open_redactor/analytics.py

@@ -0,0 +1,146 @@
+"""Analytics and severity for redaction runs and shadow audits.
+
+Severity reflects how identifying an element is on its own.
+Critical items can identify a person or account alone. High items
+identify with a little context. Medium items help locate or profile.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List
+
+SEVERITY_WEIGHTS = {"critical": 10, "high": 6, "medium": 3, "low": 1}
+
+SEVERITY_MAP = {
+    "passport": "critical",
+    "credit card": "critical",
+    "credit card number": "critical",
+    "ssn": "critical",
+    "driver license": "critical",
+    "id card": "critical",
+    "face": "high",
+    "person": "high",
+    "email": "high",
+    "phone number": "high",
+    "house number": "high",
+    "code": "high",
+    "license plate": "medium",
+    "screen": "medium",
+    "name badge": "medium",
+    "street sign": "medium",
+    "document": "medium",
+    "mailbox": "medium",
+    "lanyard": "medium",
+}
+
+
+def severity_for(name: str) -> str:
+    low = name.lower()
+    for key, level in SEVERITY_MAP.items():
+        if key in low:
+            return level
+    return "medium"
+
+
+def kind_from_track_key(track_key: str) -> str:
+    """Track keys look like phrase:id, pii:kind:n, or code:code:n."""
+    parts = track_key.split(":")
+    if parts[0] == "pii" and len(parts) >= 2:
+        return parts[1]
+    if parts[0] == "code":
+        return "code"
+    return parts[0]
+
+
+def build_summary(
+    tracks: Dict[str, Dict[int, object]],
+    total_frames: int,
+    audio_mode: str = "keep",
+    shadow: bool = False,
+) -> dict:
+    elements: List[dict] = []
+    frames_with_hits: set[int] = set()
+    counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+    for key in sorted(tracks.keys()):
+        frame_map = tracks[key]
+        if not frame_map:
+            continue
+        kind = kind_from_track_key(key)
+        level = severity_for(kind)
+        counts[level] += 1
+        detected = sorted(frame_map.keys())
+        for f in detected:
+            frames_with_hits.add(f)
+        elements.append(
+            {
+                "track": key,
+                "kind": kind,
+                "severity": level,
+                "severity_weight": SEVERITY_WEIGHTS[level],
+                "frames_detected": len(detected),
+                "first_frame": detected[0],
+                "last_frame": detected[-1],
+                "share_of_clip": round(len(detected) / total_frames, 3) if total_frames else 0.0,
+            }
+        )
+    elements.sort(key=lambda e: (-e["severity_weight"], -e["frames_detected"], e["track"]))
+    risk = sum(e["severity_weight"] * max(0.2, e["share_of_clip"]) for e in elements)
+    if audio_mode == "keep":
+        audio_note = "Audio kept. Original voices remain a separate identifying channel."
+    elif audio_mode == "mute":
+        audio_note = "Audio muted. No voice channel remains."
+    else:
+        audio_note = "Audio pitch shifted. Voices are disguised."
+    return {
+        "mode": "shadow audit, nothing was redacted or rendered" if shadow else "redaction",
+        "total_frames": total_frames,
+        "frames_with_sensitive_elements": len(frames_with_hits),
+        "share_of_frames_affected": round(len(frames_with_hits) / total_frames, 3) if total_frames else 0.0,
+        "elements_found": len(elements),
+        "severity_counts": counts,
+        "exposure_score": round(risk, 1),
+        "audio_mode": audio_mode,
+        "audio_note": audio_note,
+        "elements": elements,
+    }
+
+
+def summary_text(summary: dict) -> str:
+    lines = []
+    lines.append("Open Redactor analytics")
+    lines.append(f"Mode: {summary['mode']}")
+    lines.append(
+        f"Frames affected: {summary['frames_with_sensitive_elements']} of {summary['total_frames']} "
+        f"({summary['share_of_frames_affected']:.0%})"
+    )
+    c = summary["severity_counts"]
+    lines.append(
+        f"Elements: {summary['elements_found']} total, {c['critical']} critical, {c['high']} high, {c['medium']} medium"
+    )
+    lines.append(f"Exposure score before action: {summary['exposure_score']}")
+    lines.append(f"Audio: {summary['audio_note']}")
+    if summary["elements"]:
+        lines.append("")
+        lines.append("Most sensitive first:")
+        for e in summary["elements"]:
+            lines.append(
+                f"- [{e['severity'].upper()}] {e['track']}: {e['frames_detected']} frames, "
+                f"frames {e['first_frame']} to {e['last_frame']}"
+            )
+    else:
+        lines.append("No sensitive elements were detected.")
+    return "\n".join(lines) + "\n"
+
+
+def write_summary_files(summary: dict, base_output: Path, shadow: bool = False) -> Dict[str, Path]:
+    json_path = base_output.with_suffix(".summary.json")
+    json_path.parent.mkdir(parents=True, exist_ok=True)
+    json_path.write_text(json.dumps(summary, indent=2))
+    paths = {"json": json_path}
+    if shadow:
+        audit_path = base_output.with_suffix(".audit.txt")
+        audit_path.write_text(summary_text(summary))
+        paths["audit"] = audit_path
+    return paths

open_redactor/cli.py

@@ -0,0 +1,274 @@
+"""CLI for Open Redactor."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from .pipeline import run_pipeline
+from .presets import PRESETS, apply_preset
+from .sam_client import resolve_targets
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="open-redactor", description="Make video share-safe with SAM 3.1 prompt-driven redaction")
+    p.add_argument("input", nargs="?", default=None, help="Input video file, MP4, MOV, MKV, WebM, AVI, or M4V, or a directory in batch mode")
+    p.add_argument("--output", default=None, help="Output path. Defaults to input name plus a redacted suffix")
+    p.add_argument("--target", action="append", default=None, help="Add one phrase. Can be repeated")
+    p.add_argument("--targets-default", action="store_true", help="Start from the default set of person, face, license plate, and screen")
+    p.add_argument("--add-target", action="append", default=None, help="Add one phrase on top of the defaults. Can be repeated")
+    p.add_argument("--mode", choices=["blur", "pixelate", "replace"], default="blur", help="Redaction mode: blur, pixelate, or replace with generated stand-ins")
+    p.add_argument("--strength", type=int, default=21, help="Blur radius or pixel block size")
+    p.add_argument("--mask-margin", type=int, default=10, help="Pad every mask by this many pixels")
+    p.add_argument("--carry-frames", type=int, default=4, help="Hold a track for this many frames after it vanishes")
+    p.add_argument("--contact-sheet", action="store_true", help="Write a PNG grid of redacted sample frames")
+    p.add_argument("--preview", action="store_true", help="Render only a 3 second sample plus contact sheet and coverage report")
+    p.add_argument("--report", action="store_true", help="Write a coverage report next to the output. On by default")
+    p.add_argument("--no-report", action="store_true", help="Skip the coverage report")
+    p.add_argument("--local", action="store_true", help="Run open weights on device and send nothing to the API")
+    p.add_argument("--api-key-env", default="MODEL_API_KEY", help="Name the environment variable that holds the API key")
+    p.add_argument("--preset", choices=sorted(PRESETS.keys()), default=None, help="Use a preset: family, street, screen-share, or documents")
+    p.add_argument("--no-cache", action="store_true", help="Do not reuse cached SAM results")
+    p.add_argument("--pii-text", action="store_true", help="Also OCR sampled frames for card numbers, SSNs, phones, and emails and blur them")
+    p.add_argument("--codes", action="store_true", help="Also detect and cover QR codes and barcodes in sampled frames")
+    p.add_argument("--sensitive", action="store_true", help="Turn on --pii-text and --codes together")
+    p.add_argument("--shadow", action="store_true", help="Audit only: report what would be removed with severity, render nothing")
+    p.add_argument("--audio", choices=["keep", "mute", "pitch"], default="keep", help="Audio redaction: keep the original track, mute it, or pitch shift voices")
+    p.add_argument("--pitch-factor", type=float, default=0.8, help="Pitch multiplier for --audio pitch. Below 1 deepens, above 1 raises")
+    p.add_argument("--provider", choices=["sam", "grounding-sam"], default=None, help="Model provider: SAM via API or hosted, or Grounding SAM locally")
+    p.add_argument("--backend", choices=["api", "hosted", "local"], default=None, help="Where SAM runs: Meta Model API, your own hosted endpoint, or local open weights")
+    p.add_argument("--endpoint", default=None, help="Responses API endpoint for the hosted backend, or set OPEN_REDACTOR_ENDPOINT")
+    p.add_argument("--ui", action="store_true", help="Launch the drag and drop local web page instead of processing a file")
+    p.add_argument("--batch", action="store_true", help="Treat the input as a directory and process each MP4 inside")
+    return p
+
+
+def default_output_path(input_path: Path) -> Path:
+    return unique_output_path(input_path.with_name(f"{input_path.stem}.redacted.mp4"))
+
+
+def unique_output_path(path: Path) -> Path:
+    """Return a path that does not overwrite an existing file."""
+    if not path.exists():
+        return path
+    for i in range(1, 1000):
+        candidate = path.with_name(f"{path.stem}-{i}{path.suffix}")
+        if not candidate.exists():
+            return candidate
+    return path
+
+
+def process_one(
+    input_path: Path,
+    output_path: Optional[Path],
+    targets: List[str],
+    mode: str,
+    strength: int,
+    mask_margin: int,
+    carry_frames: int,
+    contact_sheet: bool,
+    local: bool,
+    api_key_env: str,
+    preview: bool = False,
+    report: bool = True,
+    use_cache: bool = True,
+    backend: str | None = None,
+    endpoint: str | None = None,
+    provider: str | None = None,
+    pii_text: bool = False,
+    codes: bool = False,
+    audio_mode: str = "keep",
+    pitch_factor: float = 0.8,
+    shadow: bool = False,
+) -> int:
+    out = output_path if output_path else default_output_path(input_path)
+    if output_path is not None:
+        out = unique_output_path(output_path)
+        if out.resolve() == input_path.resolve():
+            out = unique_output_path(input_path.with_name(f'{input_path.stem}.redacted.mp4'))
+        elif out != output_path:
+            print(f'Output exists, writing to {out} instead so nothing is overwritten.')
+    try:
+        run_pipeline(
+            input_path=input_path,
+            output_path=out,
+            targets=targets,
+            mode=mode,
+            strength=strength,
+            mask_margin=mask_margin,
+            carry_frames=carry_frames,
+            contact_sheet=contact_sheet,
+            local=local,
+            api_key_env=api_key_env,
+            preview=preview,
+            report=report,
+            use_cache=use_cache,
+            backend=backend,
+            endpoint=endpoint,
+            provider=provider,
+            pii_text=pii_text,
+            codes=codes,
+            audio_mode=audio_mode,
+            pitch_factor=pitch_factor,
+            shadow=shadow,
+        )
+        return 0
+    except FileNotFoundError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.ui:
+        from .webui import serve_ui
+        print("Open http://127.0.0.1:8765 in your browser. Files stay on this machine.")
+        serve_ui()
+        return 0
+
+    if not args.input:
+        parser.error("input is required unless you pass --ui")
+
+    # Presets fill only values the user did not set explicitly
+    if args.preset:
+        preset = apply_preset(args.preset)
+        if not args.target and not args.add_target and not args.targets_default:
+            args.target = list(preset["targets"])
+        if args.mode == "blur" and preset["mode"] != "blur":
+            args.mode = preset["mode"]
+        # Strength, margin, and carry use CLI defaults, so only apply preset
+        # values when the user left them at the default sentinels
+        if args.strength == 21:
+            args.strength = int(preset["strength"])
+        if args.mask_margin == 10:
+            args.mask_margin = int(preset["mask_margin"])
+        if args.carry_frames == 4:
+            args.carry_frames = int(preset["carry_frames"])
+        print(f"Preset: {args.preset} - {preset['description']}")
+
+    targets = resolve_targets(
+        targets=args.target,
+        add_targets=args.add_target,
+        use_defaults=args.targets_default,
+    )
+
+    input_path = Path(args.input)
+
+    if args.batch:
+        if not input_path.is_dir():
+            print(f"Error: batch mode needs a directory: {input_path}", file=sys.stderr)
+            return 2
+        from .pipeline import SUPPORTED_INPUT_SUFFIXES
+        mp4s = sorted(f for f in input_path.iterdir() if f.is_file() and f.suffix.lower() in SUPPORTED_INPUT_SUFFIXES)
+        if not mp4s:
+            print(f"No supported video files found in {input_path}")
+            return 0
+        exit_code = 0
+        for mp4 in mp4s:
+            out = None
+            if args.output:
+                # In batch mode --output is treated as an output directory
+                out_dir = Path(args.output)
+                out = out_dir / default_output_path(mp4).name
+            code = process_one(
+                input_path=mp4,
+                output_path=out,
+                targets=targets,
+                mode=args.mode,
+                strength=args.strength,
+                mask_margin=args.mask_margin,
+                carry_frames=args.carry_frames,
+                contact_sheet=args.contact_sheet,
+                local=args.local,
+                api_key_env=args.api_key_env,
+                preview=args.preview,
+                report=not args.no_report,
+                use_cache=not args.no_cache,
+                backend=args.backend,
+                endpoint=args.endpoint,
+                provider=args.provider,
+                pii_text=args.pii_text or args.sensitive,
+                codes=args.codes or args.sensitive,
+                audio_mode=args.audio,
+                pitch_factor=args.pitch_factor,
+                shadow=args.shadow,
+            )
+            if code != 0:
+                exit_code = code
+        return exit_code
+
+    # Photo mode: image inputs go to the image pipeline, output keeps its format
+    if input_path.suffix.lower() in {".jpg", ".jpeg", ".png", ".webp", ".bmp"}:
+        from .image_pipeline import run_image_pipeline
+        out = Path(args.output) if args.output else unique_output_path(
+            input_path.with_name(f"{input_path.stem}.redacted{input_path.suffix}")
+        )
+        if args.output:
+            out = unique_output_path(out)
+        try:
+            run_image_pipeline(
+                input_path=input_path,
+                output_path=out,
+                targets=targets,
+                mode=args.mode,
+                strength=args.strength,
+                mask_margin=args.mask_margin,
+                local=args.local,
+                api_key_env=args.api_key_env,
+                backend=args.backend,
+                endpoint=args.endpoint,
+                provider=args.provider,
+                pii_text=args.pii_text or args.sensitive,
+                codes=args.codes or args.sensitive,
+            )
+            return 0
+        except Exception as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+
+    # Single file mode
+    if not input_path.exists():
+        print(f"Error: Input not found: {input_path}", file=sys.stderr)
+        return 2
+    if input_path.is_dir():
+        print("Error: Input is a directory. Use --batch to process a folder.", file=sys.stderr)
+        return 2
+
+    output_path = Path(args.output) if args.output else None
+    return process_one(
+        input_path=input_path,
+        output_path=output_path,
+        targets=targets,
+        mode=args.mode,
+        strength=args.strength,
+        mask_margin=args.mask_margin,
+        carry_frames=args.carry_frames,
+        contact_sheet=args.contact_sheet,
+        local=args.local,
+        api_key_env=args.api_key_env,
+        preview=args.preview,
+        report=not args.no_report,
+        use_cache=not args.no_cache,
+        backend=args.backend,
+        endpoint=args.endpoint,
+        provider=args.provider,
+        pii_text=args.pii_text or args.sensitive,
+        codes=args.codes or args.sensitive,
+        audio_mode=args.audio,
+        pitch_factor=args.pitch_factor,
+        shadow=args.shadow,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

open_redactor/codes.py

@@ -0,0 +1,80 @@
+"""QR code and barcode scanning for sampled frames.
+
+Uses OpenCV detectors that ship with opencv-python. QR codes carry URLs,
+Wi-Fi passwords, payment links, and contact cards, so any readable code
+in frame is treated as sensitive and covered. Boxes are held between
+samples the same way text PII boxes are.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+Box = Tuple[int, int, int, int]
+
+
+def boxes_from_points(points) -> List[Box]:
+    """Turn detector corner points into axis aligned boxes."""
+    boxes: List[Box] = []
+    if points is None:
+        return boxes
+    arr = np.asarray(points, dtype=float)
+    if arr.size == 0:
+        return boxes
+    # Shapes seen in the wild: (n, 4, 2), (n, 1, 4, 2), or (4, 2) for one code
+    arr = arr.reshape(-1, arr.shape[-2], arr.shape[-1]) if arr.ndim >= 3 else arr.reshape(1, -1, 2)
+    for poly in arr:
+        xs, ys = poly[:, 0], poly[:, 1]
+        boxes.append((int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())))
+    return boxes
+
+
+def detect_codes_in_frame(frame) -> List[Box]:
+    """Detect QR codes, and barcodes when the OpenCV build provides them."""
+    import cv2
+
+    boxes: List[Box] = []
+    try:
+        detector = cv2.QRCodeDetector()
+        ok, decoded, points, _ = detector.detectAndDecodeMulti(frame)
+        if points is not None:
+            boxes.extend(boxes_from_points(points))
+        elif ok:
+            single_ok, single_points = detector.detect(frame)
+            if single_ok:
+                boxes.extend(boxes_from_points(single_points))
+    except Exception:
+        pass
+    # Barcode detector lives in opencv-contrib builds only
+    try:
+        barcode_detector = cv2.barcode.BarcodeDetector()  # type: ignore[attr-defined]
+        ok, decoded_info, decoded_type, points = barcode_detector.detectAndDecodeWithType(frame)
+        if points is not None:
+            boxes.extend(boxes_from_points(points))
+    except Exception:
+        pass
+    return boxes
+
+
+class CodeScanner:
+    """Sample frames, detect codes, and hold each box until the next sample."""
+
+    def __init__(self, sample_every: int = 10) -> None:
+        self.sample_every = sample_every
+
+    def scan_frames(self, frames) -> Dict[str, Dict[int, List[Box]]]:
+        result: Dict[str, Dict[int, List[Box]]] = {}
+        total = len(frames)
+        count = 0
+        for idx in range(0, total, max(1, self.sample_every)):
+            boxes = detect_codes_in_frame(frames[idx])
+            for box in boxes:
+                count += 1
+                key = f"code:{count}"
+                hold_until = min(total, idx + max(1, self.sample_every))
+                for f in range(idx, hold_until):
+                    result.setdefault(key, {}).setdefault(f, []).append(box)
+                print(f"Code: QR or barcode covered near frame {idx}")
+        return result

open_redactor/image_pipeline.py

@@ -0,0 +1,117 @@
+"""Photo pipeline. One image in, redacted image out, same layers as video."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List
+
+import cv2
+import numpy as np
+
+from .masks import build_per_frame_masks
+from .pipeline import apply_redaction_to_frame
+from .sam_client import LocalSamStub, SamApiClient, SegmentationResult
+
+SUPPORTED_IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+
+
+def run_image_pipeline(
+    input_path: Path,
+    output_path: Path,
+    targets: List[str],
+    mode: str = "blur",
+    strength: int = 21,
+    mask_margin: int = 10,
+    local: bool = False,
+    api_key_env: str = "MODEL_API_KEY",
+    backend: str | None = None,
+    endpoint: str | None = None,
+    provider: str | None = None,
+    pii_text: bool = False,
+    codes: bool = False,
+) -> Dict[str, object]:
+    frame = cv2.imread(str(input_path))
+    if frame is None:
+        raise ValueError(f"Could not read image: {input_path}")
+    height, width = frame.shape[:2]
+    shape = (height, width)
+    print(f"Input photo: {input_path} {width}x{height}")
+    print(f"Targets: {', '.join(targets)}")
+
+    resolved_backend = backend or ("local" if local else "api")
+    resolved_provider = provider or ("grounding-sam" if resolved_backend == "local" else "sam")
+    client: object
+    if resolved_backend == "local":
+        if resolved_provider == "grounding-sam":
+            from .local_gsam import LocalGroundingSamClient
+
+            client = LocalGroundingSamClient()
+        else:
+            client = LocalSamStub()
+    else:
+        client = SamApiClient.from_env(api_key_env, endpoint=endpoint)
+        if resolved_backend == "hosted":
+            print(f"Hosted backend endpoint: {client.endpoint}")  # type: ignore[attr-defined]
+
+    all_tracks: Dict[str, Dict[int, np.ndarray]] = {}
+    total_objects = 0
+    for phrase in targets:
+        try:
+            result: SegmentationResult = client.segment_image(input_path, phrase, shape=shape)  # type: ignore[attr-defined]
+        except Exception as exc:
+            print(f"Warning: SAM failed for phrase '{phrase}': {exc}")
+            result = SegmentationResult(phrase=phrase)
+        total_objects += len(result.objects)
+        for track_id, frame_map in result.tracks.items():
+            merged: Dict[int, np.ndarray] = {}
+            for _fidx, m in frame_map.items():
+                merged[0] = m
+            if merged:
+                all_tracks[f"{phrase}:{track_id}"] = merged
+
+    frames = [frame]
+    if pii_text:
+        from .pii import PiiScanner
+
+        for key, frame_boxes in PiiScanner(sample_every=1).scan_frames(frames).items():
+            for fidx, boxes in frame_boxes.items():
+                m = np.zeros(shape, dtype=bool)
+                for x1, y1, x2, y2 in boxes:
+                    m[max(0, y1) : min(height, y2), max(0, x1) : min(width, x2)] = True
+                if np.any(m):
+                    all_tracks[f"pii:{key}"] = {0: m}
+                    total_objects += 1
+    if codes:
+        from .codes import CodeScanner
+
+        for key, frame_boxes in CodeScanner(sample_every=1).scan_frames(frames).items():
+            for fidx, boxes in frame_boxes.items():
+                m = np.zeros(shape, dtype=bool)
+                for x1, y1, x2, y2 in boxes:
+                    m[max(0, y1) : min(height, y2), max(0, x1) : min(width, x2)] = True
+                if np.any(m):
+                    all_tracks[f"code:{key}"] = {0: m}
+                    total_objects += 1
+
+    if total_objects == 0:
+        print("Nothing matched. Writing a clean copy.")
+    masks = build_per_frame_masks(
+        tracks=all_tracks, total_frames=1, shape=shape, margin=mask_margin, carry_frames=0, smooth_radius=1
+    )
+    if mode == "replace":
+        from .replace import apply_replacement
+        redacted = frame
+        for track_key, track_map in all_tracks.items():
+            single = build_per_frame_masks(
+                tracks={track_key: track_map}, total_frames=1, shape=shape,
+                margin=mask_margin, carry_frames=0, smooth_radius=1,
+            )
+            if np.any(single[0]):
+                redacted = apply_replacement(redacted, single[0], track_key)
+    else:
+        redacted = apply_redaction_to_frame(frame, masks[0], mode=mode if mode in ("blur", "pixelate") else "blur", strength=strength)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    if not cv2.imwrite(str(output_path), redacted):
+        raise RuntimeError(f"Could not write output image: {output_path}")
+    print(f"Wrote: {output_path}")
+    return {"input": str(input_path), "output": str(output_path), "objects": total_objects, "photo": True}