OpenScrub 1.0.0__py3-none-any.whl

openscrub-1.0.0.dist-info/METADATA

@@ -0,0 +1,607 @@
+Metadata-Version: 2.4
+Name: OpenScrub
+Version: 1.0.0
+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: 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
+
+# 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. Ships with a HIPAA preset out of the box,
+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 it would otherwise be missed on.
+- **Redact text by pattern** — bring your own regex for account numbers,
+  license plates, 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 regex + OCR).
+- **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.**
+
+## Windows install — easy way
+
+Download everything into one folder and double-click **install.bat**.
+It bootstraps Python if needed (via winget), then runs `installer.py`,
+which probes every dependency and installs what's missing with your
+consent: core pip packages, spaCy NER, Tesseract, ffmpeg (full build with
+NVENC), and PaddleOCR — automatically offering the GPU build when an
+NVIDIA GPU is detected, and offering an ffmpeg upgrade when NVENC is
+present but broken (old build vs. new driver). Re-run any time with
+`python installer.py --check` to audit, or `--yes` for unattended install.
+
+## Windows install — manual way
+
+1. **Python 3.10+** from python.org (check "Add to PATH" during install)
+2. **Tesseract OCR**: installer from https://github.com/UB-Mannheim/tesseract/wiki
+   (default location is auto-detected; no PATH edit needed)
+3. **ffmpeg**: `winget install ffmpeg` in PowerShell (needed for audio + h264 output)
+4. Python packages:
+   ```
+   pip install opencv-python rapidfuzz pytesseract spacy
+   python -m spacy download en_core_web_sm
+   ```
+   spaCy is strongly recommended — it's the primary name detector. The tool
+   still runs without it using heuristics, but NER is more accurate.
+
+   Optional, better OCR on small UI fonts (large install):
+   `pip install paddleocr paddlepaddle`
+
+## Web interface (LAN)
+
+Run `python openscrub_web.py` on an always-on machine and open the printed
+URL (includes a required access token) 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: LAN-grade token auth only — never expose the port to the
+internet. The jobs folder on the server contains PHI (uploads + reports);
+protect it accordingly.
+
+## ⚠️ 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**. Protect them with the same controls as
+  any other PHI: restricted access, encryption at rest where required,
+  and deletion when no longer needed.
+- The web interface provides **LAN-grade token access control only**.
+  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.
+
+## Install
+
+One installer covers Windows and Linux (macOS best-effort). It installs the
+Python dependencies, sets up GPU-accelerated OCR when an NVIDIA card is
+present, installs Tesseract and ffmpeg via your system package manager,
+verifies NVENC hardware encoding, and creates a launchable "OpenScrub"
+shortcut with the program icon.
+
+    Windows:      double-click install.bat        (or: python install.py)
+    Linux/macOS:  ./install.sh                    (or: python3 install.py)
+
+`--check` reports what's present without changing anything; `--yes` runs
+unattended; `--cpu-only` skips GPU OCR. Start the app from the created
+shortcut, or `python openscrub_web.py` — the web interface at the printed
+HTTPS URL is the primary interface. (`openscrub_gui.py`, the desktop Tk
+interface, still works but is legacy: new features land in the web app.)
+
+## Validation
+
+The corpus generator (`make_corpus.py`) plants fake PHI at known
+locations across the hard cases — static charts, schedule grids,
+scrolling notes, OCR-disrupting highlights, embedded face photos — and
+`validate.py` scores the pipeline 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). Run it yourself:
+`python make_corpus.py --out corpus && python validate.py --corpus corpus`.
+CI runs the regression suite (`pytest test_openscrub.py`) and re-validates
+recall on every commit — a detection regression fails the build.
+
+## What's new in v4.1
+
+- **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).
+- **Packaging**: `pip install .` gives `openscrub`, `openscrub-web`,
+  `openscrub-gui` commands.
+
+## What's new in v4
+
+- **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** — new `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 ema.yaml` loads per-environment settings
+  (engine, MRN regex, categories, ignore regions…). CLI flags override the
+  file. See the included `ema.yaml`.
+- **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 now records tool version, timestamp,
+  full settings, and SHA256 of input and output, making the audit trail
+  independently verifiable.
+
+## GUI (Windows)
+
+`python openscrub_gui.py` (or double-click `openscrub_gui.bat`) opens a
+desktop app covering everything the CLI does:
+
+- 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 (v3)
+
+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 Resolve 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 Resolve, 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 |

openscrub-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+openscrub.py,sha256=DCEriczNyyMx1BmbeTAcb7-BVlLDmVXYt7iHsgZhz0I,110537
+openscrub_web.py,sha256=jfuIX3DwFCA_SgGugLXa_ZlnABhctQ2_mzN73n_YlPQ,123986
+zones_ui.py,sha256=fwm3KtUKtz_SjpcQfrridZV0uju7vf1Fo-4uxLNNNN0,17239
+openscrub-1.0.0.dist-info/METADATA,sha256=uKNxkPhLQjTiOfV2ov-e6BfC1mwnirRdAcMWYol1j08,33896
+openscrub-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+openscrub-1.0.0.dist-info/entry_points.txt,sha256=tpiWZTyHbkA0UhBMnjuHJ0tHZM80RnwLgC_OlXE9oJY,80
+openscrub-1.0.0.dist-info/licenses/LICENSE,sha256=_5jiujjv-oJocorIG7G2ZmNMixvzlczbJ8rs49SrLzo,10791
+openscrub-1.0.0.dist-info/RECORD,,

openscrub-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

openscrub-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+openscrub = openscrub:main
+openscrub-web = openscrub_web:main