footage-redaction

footage-redaction

scripts/redact.py cuts one clip and bakes its redaction in a single ffmpeg pass. It needs only Python 3 (standard library) and ffmpeg/ffprobe — no venv.

Spec

{
  "trim":  {"from": 47.0, "to": 59.0},
  "speed": 1.0,
  "fps":   30,
  "crop":  {"top": 125, "bottom": 90, "left": 0, "right": 0},
  "delogo": [{"x": 750, "y": 410, "w": 640, "h": 110, "from": 0, "to": 46.9}],
  "blur_when": [{"x": 836, "y": 338, "w": 180, "h": 56, "pad_s": 0.25,
                 "detect": {"x": 820, "y": 300, "w": 220, "h": 30,
                            "rgb": [20, 40, 90], "tol": 30, "min_ratio": 0.6}}]
}

• Coordinate rule — every box (delogo, blur_when target and detect) is in SOURCE-frame pixels, before crop and scale, and every time is on the UNTRIMMED source timeline. Measure boxes on a full-resolution source frame; never on a cropped clip.
• Filter order: trim → delogo → blur → crop → speed → fps → encode.
• blur_when: the detect box is sampled every 0.25 s; it is active when at least min_ratio of its pixels are within tol of rgb (e.g. a popup's navy header). Active samples merge into windows padded by pad_s; the blur runs only inside them. Keep the detect box small (a thin strip of the popup header or status bar): detection is pure Python and its cost grows with box area × clip length.
• Validation rejects a bad spec before writing anything, naming the field (blur_when[0].detect.min_ratio, delogo[0] …).

Run

python3 scripts/redact.py src.mov clips/c05.mp4 --spec c05.redact.json --dry-run   # windows + filter graph
python3 scripts/redact.py src.mov clips/c05.mp4 --spec c05.redact.json [--crf 16] [--strict]

--dry-run prints the resolved windows and graph and writes nothing — iterate on the spec with it. A detector that never fires prints a warning; --strict makes it an error. Output is written to <out>.partial and renamed only on success.

Per-clip caller loop

Keep the project's own shot table (clip id, source, in/out, speed, redaction spec) in the project, and call redact.py once per clip: