Metadata-Version: 2.4
Name: OpenScrub
Version: 1.0.12
Summary: Local, GPU-accelerated redaction for video and screen recordings — blur, black-box, or mosaic faces, names, and any regex-matchable PII, with human review.
Project-URL: Homepage, https://github.com/austinmabry/OpenScrub
Project-URL: Repository, https://github.com/austinmabry/OpenScrub
Project-URL: Issues, https://github.com/austinmabry/OpenScrub/issues
Author: Austin Mabry
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
           1. Definitions.
        
              "License" shall mean the terms and conditions for use, reproduction,
              and distribution as defined by Sections 1 through 9 of this document.
        
              "Licensor" shall mean the copyright owner or entity authorized by
              the copyright owner that is granting the License.
        
              "Legal Entity" shall mean the union of the acting entity and all
              other entities that control, are controlled by, or are under common
              control with that entity. For the purposes of this definition,
              "control" means (i) the power, direct or indirect, to cause the
              direction or management of such entity, whether by contract or
              otherwise, or (ii) ownership of fifty percent (50%) or more of the
              outstanding shares, or (iii) beneficial ownership of such entity.
        
              "You" (or "Your") shall mean an individual or Legal Entity
              exercising permissions granted by this License.
        
              "Source" form shall mean the preferred form for making modifications,
              including but not limited to software source code, documentation
              source, and configuration files.
        
              "Object" form shall mean any form resulting from mechanical
              transformation or translation of a Source form, including but
              not limited to compiled object code, generated documentation,
              and conversions to other media types.
        
              "Work" shall mean the work of authorship, whether in Source or
              Object form, made available under the License, as indicated by a
              copyright notice that is included in or attached to the work
              (an example is provided in the Appendix below).
        
              "Derivative Works" shall mean any work, whether in Source or Object
              form, that is based on (or derived from) the Work and for which the
              editorial revisions, annotations, elaborations, or other modifications
              represent, as a whole, an original work of authorship. For the purposes
              of this License, Derivative Works shall not include works that remain
              separable from, or merely link (or bind by name) to the interfaces of,
              the Work and Derivative Works thereof.
        
              "Contribution" shall mean any work of authorship, including
              the original version of the Work and any modifications or additions
              to that Work or Derivative Works thereof, that is intentionally
              submitted to Licensor for inclusion in the Work by the copyright owner
              or by an individual or Legal Entity authorized to submit on behalf of
              the copyright owner. For the purposes of this definition, "submitted"
              means any form of electronic, verbal, or written communication sent
              to the Licensor or its representatives, including but not limited to
              communication on electronic mailing lists, source code control systems,
              and issue tracking systems that are managed by, or on behalf of, the
              Licensor for the purpose of discussing and improving the Work, but
              excluding communication that is conspicuously marked or otherwise
              designated in writing by the copyright owner as "Not a Contribution."
        
              "Contributor" shall mean Licensor and any individual or Legal Entity
              on behalf of whom a Contribution has been received by Licensor and
              subsequently incorporated within the Work.
        
           2. Grant of Copyright License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              copyright license to reproduce, prepare Derivative Works of,
              publicly display, publicly perform, sublicense, and distribute the
              Work and such Derivative Works in Source or Object form.
        
           3. Grant of Patent License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              (except as stated in this section) patent license to make, have made,
              use, offer to sell, sell, import, and otherwise transfer the Work,
              where such license applies only to those patent claims licensable
              by such Contributor that are necessarily infringed by their
              Contribution(s) alone or by combination of their Contribution(s)
              with the Work to which such Contribution(s) was submitted. If You
              institute patent litigation against any entity (including a
              cross-claim or counterclaim in a lawsuit) alleging that the Work
              or a Contribution incorporated within the Work constitutes direct
              or contributory patent infringement, then any patent licenses
              granted to You under this License for that Work shall terminate
              as of the date such litigation is filed.
        
           4. Redistribution. You may reproduce and distribute copies of the
              Work or Derivative Works thereof in any medium, with or without
              modifications, and in Source or Object form, provided that You
              meet the following conditions:
        
              (a) You must give any other recipients of the Work or
                  Derivative Works a copy of this License; and
        
              (b) You must cause any modified files to carry prominent notices
                  stating that You changed the files; and
        
              (c) You must retain, in the Source form of any Derivative Works
                  that You distribute, all copyright, patent, trademark, and
                  attribution notices from the Source form of the Work,
                  excluding those notices that do not pertain to any part of
                  the Derivative Works; and
        
              (d) If the Work includes a "NOTICE" text file as part of its
                  distribution, then any Derivative Works that You distribute must
                  include a readable copy of the attribution notices contained
                  within such NOTICE file, excluding those notices that do not
                  pertain to any part of the Derivative Works, in at least one
                  of the following places: within a NOTICE text file distributed
                  as part of the Derivative Works; within the Source form or
                  documentation, if provided along with the Derivative Works; or,
                  within a display generated by the Derivative Works, if and
                  wherever such third-party notices normally appear. The contents
                  of the NOTICE file are for informational purposes only and
                  do not modify the License. You may add Your own attribution
                  notices within Derivative Works that You distribute, alongside
                  or as an addendum to the NOTICE text from the Work, provided
                  that such additional attribution notices cannot be construed
                  as modifying the License.
        
              You may add Your own copyright statement to Your modifications and
              may provide additional or different license terms and conditions
              for use, reproduction, or distribution of Your modifications, or
              for any such Derivative Works as a whole, provided Your use,
              reproduction, and distribution of the Work otherwise complies with
              the conditions stated in this License.
        
           5. Submission of Contributions. Unless You explicitly state otherwise,
              any Contribution intentionally submitted for inclusion in the Work
              by You to the Licensor shall be under the terms and conditions of
              this License, without any additional terms or conditions.
              Notwithstanding the above, nothing herein shall supersede or modify
              the terms of any separate license agreement you may have executed
              with Licensor regarding such Contributions.
        
           6. Trademarks. This License does not grant permission to use the trade
              names, trademarks, service marks, or product names of the Licensor,
              except as required for reasonable and customary use in describing the
              origin of the Work and reproducing the content of the NOTICE file.
        
           7. Disclaimer of Warranty. Unless required by applicable law or
              agreed to in writing, Licensor provides the Work (and each
              Contributor provides its Contributions) on an "AS IS" BASIS,
              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
              implied, including, without limitation, any warranties or conditions
              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
              PARTICULAR PURPOSE. You are solely responsible for determining the
              appropriateness of using or redistributing the Work and assume any
              risks associated with Your exercise of permissions under this License.
        
           8. Limitation of Liability. In no event and under no legal theory,
              whether in tort (including negligence), contract, or otherwise,
              unless required by applicable law (such as deliberate and grossly
              negligent acts) or agreed to in writing, shall any Contributor be
              liable to You for damages, including any direct, indirect, special,
              incidental, or consequential damages of any character arising as a
              result of this License or out of the use or inability to use the
              Work (including but not limited to damages for loss of goodwill,
              work stoppage, computer failure or malfunction, or any and all
              other commercial damages or losses), even if such Contributor
              has been advised of the possibility of such damages.
        
           9. Accepting Warranty or Additional Liability. While redistributing
              the Work or Derivative Works thereof, You may choose to offer,
              and charge a fee for, acceptance of support, warranty, indemnity,
              or other liability obligations and/or rights consistent with this
              License. However, in accepting such obligations, You may act only
              on Your own behalf and on Your sole responsibility, not on behalf
              of any other Contributor, and only if You agree to indemnify,
              defend, and hold each Contributor harmless for any liability
              incurred by, or claims asserted against, such Contributor by reason
              of your accepting any such warranty or additional liability.
        
           END OF TERMS AND CONDITIONS
        
           Copyright 2026 [YOUR NAME OR ORGANIZATION — edit this line]
        
           Licensed under the Apache License, Version 2.0 (the "License");
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at
        
               http://www.apache.org/licenses/LICENSE-2.0
        
           Unless required by applicable law or agreed to in writing, software
           distributed under the License is distributed on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
           See the License for the specific language governing permissions and
           limitations under the License.
License-File: LICENSE
Keywords: anonymization,face-blur,ffmpeg,gdpr,hipaa,ocr,opencv,phi,pii,privacy,redaction,screen-recording,video-redaction
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: cheroot>=10.0
Requires-Dist: cryptography
Requires-Dist: flask
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: pillow
Requires-Dist: pytesseract
Requires-Dist: pyyaml
Requires-Dist: rapidfuzz
Provides-Extra: all
Requires-Dist: spacy>=3.7; extra == 'all'
Provides-Extra: ner
Requires-Dist: spacy>=3.7; extra == 'ner'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/austinmabry/OpenScrub/main/assets/social_preview.png"
       alt="OpenScrub — the bucket-hat figure behind a fence, face pixelated, next to the OpenScrub wordmark"
       width="830">
</p>

<p align="center">
  <a href="https://pypi.org/project/OpenScrub/"><img src="https://img.shields.io/pypi/v/OpenScrub?color=1f2a44&label=PyPI" alt="PyPI version"></a>
  <a href="https://pypi.org/project/OpenScrub/"><img src="https://img.shields.io/pypi/pyversions/OpenScrub?color=1f2a44" alt="Python versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-e0432f" alt="License: Apache-2.0"></a>
</p>

# OpenScrub — local video & screen-recording redaction

**A local, GPU-accelerated tool that blurs faces and any on-screen text —
names, phone numbers, SSNs, emails, dates, ID numbers, or anything you can
express as a regex — in videos and screen recordings, with a human review
step before anything is published.**

Runs entirely on your own machine (no cloud, no upload of sensitive
footage). OCR-driven, so it catches text anywhere on screen; face-tracked,
so a face detected once stays covered even when the detector blinks;
scroll- and motion-aware, so blur boxes follow content as it moves; and
onset-aware, so redaction starts on the exact frame a detail first appears
rather than a half-second late. Defaults are tuned for the hardest case —
dense, scrolling medical-records screens — but the engine is
general-purpose.

> Keywords: video redaction · blur faces in video · redact screen recording ·
> PII redaction · anonymize video · blur license plates · GDPR / CCPA /
> FERPA / PCI / HIPAA · OCR text redaction · face blur · privacy tool

## What it does

- **Blur faces** — detected with a DNN model and visually tracked, so a
  single detection covers a face across frames where it would otherwise
  be missed.
- **Blur license plates** — via an optional ONNX detector model
  (see [PLATES.md](PLATES.md)); plates re-detect every frame, so a plate
  crossing the frame stays covered.
- **Redact text by pattern** — bring your own regex for account numbers,
  case numbers, employee IDs, order numbers; built-in
  patterns for SSNs, phone numbers, emails, dates, addresses (including
  multi-line street/city/state/ZIP blocks), credit/debit card numbers (Luhn-validated), API keys/tokens, IP addresses,
  and medical record numbers.
- **Redact names** — via named-entity recognition plus heuristics, with no
  list required (though you can supply an allowlist to *keep* specific names
  visible and a blocklist to *always* remove others).
- **Detection zones** — restrict redaction to a region, or invert it: keep a
  central subject sharp and blur everyone/everything around them, or vice versa.
- **Redaction styles** — blur, solid black box (irreversible), or mosaic
  pixelation, choosable per category (black-box the SSNs, blur the faces).
- **Human review** — every detection is shown as a thumbnail you can keep or
  blur, with an interactive box editor to resize, move, add, or time-bound
  any blur before rendering.
- **Audit trail** — each run produces a report with SHA-256 hashes of input
  and output for provenance.

## Use cases

PHI redaction for medical practices is the flagship use — it's the hardest
version of the problem (dense, scrolling, fast-changing screens) and the
tool is built to handle it. But the same engine fits many privacy workflows:

- **Content creators & tutorials** — strip inboxes, browser tabs, API keys,
  file paths, and notification pop-ups out of screen-recorded walkthroughs
  before publishing. Onset detection catches a notification that flashes for
  a fraction of a second.
- **Legal e-discovery & court exhibits** — redact names, SSNs, account
  numbers, and minors' identities from video exhibits, deposition
  recordings, and bodycam footage; keep the named party visible, blur the rest.
- **Journalism & documentary** — protect sources by blurring informants'
  faces and on-screen identifying text (badges, plates, addresses,
  shared documents); face tracking survives a source turning their head.
- **Law-enforcement & FOIA release** — redact bystander faces, minors, and
  visible PII from body-cam footage for public-records compliance, with a
  hashed audit report for chain-of-custody.
- **GDPR / CCPA compliance** — anonymize identifiable people and personal
  data in any recorded video before it's shared or published.
- **Fintech & financial support videos** — blur account numbers, balances,
  routing and card numbers in screen recordings of banking or accounting
  software (PCI-DSS-relevant), via built-in and custom regex.
- **Education & research (FERPA)** — protect student names, IDs, and grades
  in recorded lectures, gradebook screen-shares, and classroom video;
  "blur every face except the presenter" with an inverted zone.
- **Corporate training & internal demos going public** — remove real
  customer names, employee directories, internal URLs, and chat
  notifications when repurposing production-system recordings for marketing.
- **Real-estate & property walkthroughs** — blur faces, family photos,
  mail with addresses, and documents on desks captured incidentally.
- **Streaming & gaming VODs** — redact Discord DMs, donation alerts with
  real names, second-monitor leaks, and non-consenting on-cam guests.
- **Dashcam footage** — blur license plates and pedestrian faces before
  posting insurance or public clips (plates via the dedicated detector
  model — see [PLATES.md](PLATES.md)).
- **UX & usability research** — anonymize participants' faces, names, and
  on-screen account data before sharing session recordings internally.
- **Government document-on-screen redaction** — remove names, locations,
  and marked strings from recordings that walk through sensitive documents,
  with zones, regex, and an audit trail.

Several of these depend on you supplying the right regex, and on OCR
reading the target text reliably at your recording's resolution — see
[Caveats](#caveats--read-these). Face tracking works best on footage where
faces are stationary or scroll with the page rather than moving rapidly
across the frame. In all cases this is a **best-effort assistive tool:
review the output before publishing.**

## Install from PyPI (quickest)

```
pip install OpenScrub
```

This installs the Python package with all of its Python dependencies and
gives you two commands: `openscrub` (the CLI engine) and `openscrub-web`
(the web interface). The YuNet face model (~230 KB) downloads
automatically on first run.

### Fresh Windows 11 PC — complete setup (copy-paste)

```
winget install -e --id Python.Python.3.12
```
Close and reopen the terminal (so PATH updates), then:
```
pip install OpenScrub
openscrub-setup
```

`openscrub-setup` detects what's missing and installs Tesseract and FFmpeg
for you via winget (asking first; `--yes` to skip prompts, `--check` to
only report). Prefer manual control? The equivalent commands:

```
winget install -e --id UB-Mannheim.TesseractOCR
winget install -e --id Gyan.FFmpeg
```

### Fresh Linux (Debian/Ubuntu)

```
sudo apt install python3-pip
pip install OpenScrub
openscrub-setup        # offers: sudo apt install tesseract-ocr ffmpeg
```

Then run `openscrub-web` and open the URL it prints.

Two system tools are **not** pip-installable and must be present for full
functionality:

1. **Tesseract OCR** — required for every text category (names, SSNs,
   emails, …). Face and plate detection work without it; text detection
   does not.
   - Windows: `winget install -e --id UB-Mannheim.TesseractOCR`
     (or the installer from https://github.com/UB-Mannheim/tesseract/wiki)
   - Linux: `sudo apt install tesseract-ocr`
2. **ffmpeg** (ffprobe ships with it) — strongly recommended: audio
   passthrough, H.264 output, and VFR screen-recording normalization all
   depend on it.
   - Windows: `winget install -e --id Gyan.FFmpeg`
   - Linux: `sudo apt install ffmpeg`

Optional extras:

```
pip install "OpenScrub[ner]"             # spaCy name detection (recommended)
python -m spacy download en_core_web_sm
pip install paddleocr paddlepaddle       # better OCR on small UI fonts (large install)
```

spaCy is strongly recommended — it's the primary name detector. The tool
still runs without it using heuristics, but NER is more accurate.

### A proper Windows install (Program Files + Start Menu)

Prefer a normal Windows program over pip? Every release has
`OpenScrub-Setup-<version>.exe` attached on the
[Releases page](https://github.com/austinmabry/OpenScrub/releases)
(built automatically by CI). It installs branded `openscrub.exe` and
`openscrub-web.exe` into `C:\Program Files\OpenScrub` with Start Menu
shortcuts, an uninstaller, and optional one-click winget installs of
Tesseract and FFmpeg. To build it yourself instead, run
`windows\build_installer.bat` from a checkout (requires Python 3.10+
and Inno Setup 6). App data — jobs, certificates,
zones, downloaded models — lives in `%LOCALAPPDATA%\OpenScrub`, never in
Program Files. Note: the frozen build detects names with the built-in
heuristics (spaCy NER is a pip-only extra).

If you stay with pip instead, `openscrub-setup` on Windows now offers to
create Start Menu + Desktop shortcuts for OpenScrub Web, so you never
have to hunt for pip's `Scripts` folder.

## Guided installer (Windows / Linux / macOS best-effort)

Prefer a setup that installs the system tools too? Clone or download the
repository and run:

    python install.py

It probes every dependency and installs what's missing with your consent:
core pip packages, spaCy NER, Tesseract and ffmpeg (via winget / apt /
dnf / pacman / brew), and PaddleOCR — automatically offering the GPU
build when an NVIDIA card is detected — then verifies NVENC hardware
encoding and creates a launchable "OpenScrub" shortcut with the program
icon (Desktop + Start Menu on Windows, a .desktop entry on Linux, a
.command on macOS).

`--check` reports what's present without changing anything; `--yes` runs
unattended; `--cpu-only` skips GPU OCR; `--with-plates` fetches a
license-plate model (see [PLATES.md](PLATES.md)). Start the app from the
created shortcut, or `python openscrub_web.py` — the web interface is the
primary interface. (`openscrub_gui.py`, the desktop Tk interface, still
works but is legacy: new features land in the web app.)

## Updating

```
openscrub-update            # interactive: shows versions, asks, updates
openscrub-update --check    # just report whether an update exists
```

It detects how OpenScrub was installed: pip installs upgrade via
`pip install --upgrade OpenScrub`; folder deploys download the latest
release from PyPI, **verify its SHA-256** against the hash PyPI
publishes, and replace only the released files — your jobs, certificates,
zones, models, allowlist, and locally pinned plate-model hashes are
never touched, and every replaced file is backed up to
`backups/pre-update-<version>/` first. Git checkouts are left to
`git pull`.

The web interface checks for updates too: when a newer release exists,
the footer shows an update link — one click runs the same updater (only
while no job is running), then asks you to restart the server. Restart
after any update to run the new version.

## Web interface (LAN)

Run `python openscrub_web.py` on an always-on machine and open the printed
URL from any device on your network —
laptop or phone. Workflow: upload a recording (or point at a server-side
path) → scan runs on the server with a live preview and log → **review
page**: every detection shown as a thumbnail grouped by category, uncheck
false positives, per-category all-on/all-off, draw missed regions directly
on any frame (works with touch) → render → download the redacted video and
the audit report. Jobs queue one at a time so they don't fight over the GPU.

Security: HTTPS by default (self-signed certificate — your browser warns
once; or install your own cert from the main page). Access is open to
everyone on your network unless you start with `--token <secret>`, which
then gates every request (recommended). Either way this is LAN-grade
protection — never expose the port to the internet. The jobs folder on
the server contains PHI (uploads + reports); protect it accordingly.
`--retain-days` auto-deletes finished job folders (default 7 days).

## ⚠️ Disclaimer — read this before using openscrub on real PHI

**openscrub is a best-effort assistive tool, not a HIPAA compliance
guarantee, a de-identification certification, or a substitute for human
review.** It uses OCR, named-entity recognition, pattern matching, and
face detection — all of which can and do miss things: low-contrast text,
unusual names, stylized fonts, partially occluded faces, content visible
for only a fraction of a second, handwriting, text inside images, and
categories of identifiers it was never designed to detect.

**You remain fully responsible for reviewing every output before it is
shared, published, or distributed.** The built-in review workflow and the
final QC scrub are not optional extras — they are the compensating
control this tool is designed around. If a redacted video leaks protected
health information, that is your exposure, not this software's.

Specifically:

- The validation numbers in this README are measurements against a
  **synthetic corpus**. They demonstrate the pipeline works as designed;
  they are **not** a guarantee of performance on your recordings, your
  EMR, your fonts, or your screen resolution.
- Audit reports, job folders, and normalized/intermediate video files
  **contain PHI in plaintext** unless you enable the web UI's
  **Encryption at rest** panel: set a password and job files are
  encrypted (scrypt-derived key, AES-256-GCM) whenever the vault is
  locked or the server shuts down, and decrypted while you work.
  **There is no password reset — a lost password makes encrypted files
  permanently unrecoverable.** While unlocked (and during processing)
  files are plaintext on disk, so pair the vault with OS disk
  encryption (BitLocker etc.), restricted access, and deletion when no
  longer needed.
- The web interface provides **LAN-grade access control at most**
  (HTTPS with an optional access token — set one with `--token`).
  Never expose it to the internet, and run it only on networks and
  machines already authorized to handle PHI.
- This tool addresses **on-screen visual content only**. Audio narration,
  metadata, file names, and embedded subtitles are untouched and can all
  carry PHI.
- Nothing in this project constitutes legal, compliance, or regulatory
  advice. Consult your privacy officer or counsel for questions about
  HIPAA, state privacy law, or your organization's obligations.

This software is provided "AS IS" without warranty of any kind — see the
[LICENSE](LICENSE) (Apache-2.0, §7–8) for the governing terms.

## Validation

During development the pipeline is scored against a **synthetic corpus**:
a generator plants fake PHI at known locations across the hard cases —
static charts, schedule grids, scrolling notes, OCR-disrupting
highlights, embedded face photos — and a scorer checks the rendered
output against the ground truth:

    PHI recall:           100.0%   (102/102 planted samples blurred)
    Benign preservation:  100.0%   (39/39 benign samples left readable)

(measured with the Tesseract fallback engine; PaddleOCR + spaCy NER, the
recommended stack, is stronger). The shipped regression suite
(`pytest test_openscrub.py`) exercises the same end-to-end pipeline on
synthetic videos — for this tool a regression is not a bug, it's a leak,
so the suite must stay green on every change.

## Feature notes

- **VFR normalization** — OBS/Game Bar variable-frame-rate recordings are
  detected (ffprobe) and normalized to CFR before processing, preventing
  blur-timing drift and audio desync; recorded in provenance.
- **OCR quality**: low-confidence words that are structurally PHI-shaped
  (emails, phones, digit runs) are rescued instead of dropped; small text
  triggers an automatic 2x re-OCR; a reverse pass re-searches the whole
  timeline for near-misses of remembered PHI. `--paranoid` preset maxes
  recall at the cost of false positives (clean up in review).
- **False-positive economics**: names must be caught by a primary detector
  on two separate scans before memory starts recalling them; a top-recalls
  summary prints after every scan; the web review suggests allowlisting
  strings you disabled everywhere, building a permanent allow-list.
- **Web**: before/after compare scrubber on finished jobs, ETA on the
  progress bar, `--retain-days` auto-deletes PHI-bearing job folders
  (default 7 days).
- **Batch resume** — re-running `--batch` skips files already done
  (`--overwrite` to redo).
- **Review workflow** — scan and render are separate phases; between them
  you can audit every detection and correct both false positives and
  misses. CLI equivalent: run with `--report audit.json`, edit the JSON
  (set `"enabled": false`, or append boxes), then
  `openscrub.py video.mp4 --from-report audit.json` re-renders in seconds
  without re-scanning.
- **Face detection** — the `face` category (on by default) blurs faces in
  clinical photos and webcam bubbles, which OCR is blind to. Uses the
  YuNet DNN detector (auto-downloaded, ~230 KB) with a Haar-cascade
  fallback. Faces re-detect on every scan; boxes are expanded 15%.
- **Config profiles** — `--config profile.yaml` loads per-environment
  settings (engine, MRN regex, categories, ignore regions…). CLI flags
  override the file.
- **Ignore regions** — `--ignore-region X1,Y1,X2,Y2` (repeatable, or in
  config) excludes screen areas like the taskbar clock from all blurring.
- **Batch mode** — `--batch folder` processes every video, writing
  per-file outputs + audit reports and a `batch_summary.json`.
- **Provenance** — every audit report records tool version, timestamp,
  full settings, and SHA256 of input and output, making the audit trail
  independently verifiable.

## Desktop GUI (Windows, legacy)

`python openscrub_gui.py` opens a desktop app covering everything the
CLI does (legacy: it still works, but new features land in the web app):

- Source / output / audit-report file pickers
- OCR engine selection with live status (Tesseract / PaddleOCR / spaCy NER
  / NVENC detected or missing) and one-click **Install** buttons for
  PaddleOCR (CPU or GPU CUDA 12.6) and spaCy NER
- GPU/CPU toggle for OCR, NVENC/x264 toggle for encoding
- Category checkboxes, blur vs box, preview mode, memory on/off
- Allow-names and always-blur name lists (type directly or load a file)
- Sample interval / scan trigger / padding / bridge gap / MRN regex fields
- Live preview showing each frame as it's analyzed with detection boxes
- Progress bar, log pane, and a Cancel button that cleans up partial output

Extra requirement for the preview pane: `pip install pillow`

## Usage

```
:: standard run
python openscrub.py recording.mp4

:: keep provider/staff names visible (one name per line in the file)
python openscrub.py recording.mp4 --allow-names providers.txt

:: tuning pass — draws boxes instead of blurring
:: (red = detected PHI, orange = unscanned scroll safety band)
python openscrub.py recording.mp4 --preview

:: everything
python openscrub.py recording.mp4 --allow-names providers.txt ^
    --extra-names always_blur.txt --sample-interval 0.5 --scan-trigger 60 ^
    --pad 8 --mode blur --report audit.json -o recording_redacted.mp4
```

## How names are detected (no patient list)

Three stacked signals, any of which triggers a blur:
1. **spaCy NER** — PERSON entities in reconstructed text lines
2. **Label heuristic** — text following "Patient:", "Name:", "Pt:",
   "Member:", "Insured:", "Guarantor:", etc., stopping at the next label
3. **Capitalized-pair heuristic** — adjacent capitalized non-UI words
   ("Maria Gonzalez", "Henderson, Robert", "Mrs. Whitfield"); auto-enabled
   as fallback when spaCy is missing, or force with --heuristic-names on

`--allow-names providers.txt` whitelists names to KEEP visible (your
physicians/PAs, e.g. Smith, Patel, Nguyen, Garcia).
`--extra-names` force-blurs specific names the detectors might miss.

## How scrolling is handled

Three mechanisms working together:
1. **Per-frame motion tracking** — global scroll offset is measured every
   frame via phase correlation against a keyframe (drift-bounded, verified
   to a few px over a 500px scroll). Every blur box is anchored in content
   coordinates and translated with the scroll, so blur rides along with
   the text on every single frame — not just at sample times.
2. **Motion-triggered scans** — in addition to the time-based interval,
   an OCR scan fires after every --scan-trigger pixels of scroll (default
   60), so newly revealed content is scanned almost immediately.
3. **Safety bands** — any strip of screen that scrolled into view since
   the last OCR scan is blurred wholesale until it has been scanned.
   Unverified content is never shown, even between scans.

Net effect: text detected once stays covered while it moves, and text
scrolling into view is covered by the safety band before it's even been
read. Verified in testing with 26/26 PHI regions covered across static,
mid-scroll, and post-scroll frames.

## PHI memory and gap bridging

Two reasoning layers prevent "flash of PHI" from intermittent OCR misses:

1. **PHI text memory** — every string confirmed as PHI is remembered for
   the rest of the video. Each scan checks all OCR'd words against memory
   (fuzzy for names, near-exact for numbers), so "Henderson" identified
   once gets blurred on every later appearance anywhere on screen, even
   where NER/heuristics would fail (e.g. a bare surname mid-sentence).
   Disable with --no-memory. Memory is per-run only; nothing persists.
2. **Evidence-based gap bridging** — if the same PHI is detected, missed
   for a few scans, then re-detected in the same region, the blur is held
   straight through the gap (up to --bridge-gap seconds, default 4.0) —
   UNLESS an intermediate scan positively read different text there,
   meaning the content genuinely changed. Unreadable or empty gaps fail
   closed: they stay blurred.

## Caveats — read these

- **Best-effort, not a guarantee.** OCR can miss low-contrast or tiny
  text; NER can miss unusual names (heuristics + label detection back it
  up, but nothing is 100%). Do a final QC scrub in your editor at 2x
  before anything goes public. Treat this as removing ~95% of the manual
  work.
- **All dates are blurred**, since the tool can't distinguish DOBs from
  visit dates. Usually right on a medical UI; drop `dob` from
  --categories if too aggressive for a given recording.
- **Partial-screen scrolling** (one panel scrolls while the rest is
  static) is tracked as whichever motion dominates. If a recording is
  mostly panel-scrolling, use --preview to check coverage and consider
  --sample-interval 0.25.
- **MRN default** is standalone 7+ digit runs, or 6+ digits near an
  MRN/chart/acct label. Tighten with --mrn-regex if benign numbers get
  caught (e.g. `\b\d{7}\b` for an exact-width MRN).
- **The --report JSON contains PHI in plaintext.** Handle it like any
  PHI file.

## Recommended workflow

1. Record as usual
2. `--preview` pass, spot-check red boxes and orange bands
3. Real pass (optionally with --report)
4. Import `_redacted.mp4` into your editor, edit normally
5. Final QC scrub before publishing

## Tuning cheat sheet

| Symptom | Fix |
|---|---|
| Provider names blurred | add them to --allow-names |
| A name slips through | add to --extra-names; install spaCy if not present |
| Random capitalized words blurred | install spaCy so the pair heuristic turns off, or --heuristic-names off |
| Text slips through during very fast scrolling | --scan-trigger 40 and/or --sample-interval 0.25 |
| Benign numbers blurred as MRN | tighten --mrn-regex |
| Blur box clips edges of text | --pad 12 |
| Small text missed entirely | install paddleocr; record at native resolution |
