Metadata-Version: 2.4
Name: pureframe
Version: 0.1.0b2
Summary: Local AI tool that applies smooth, localized blur over explicit visuals in movies and TV files. No scene cutting, no audio changes.
Project-URL: Homepage, https://github.com/MayonaiseLover/PureFrame
Project-URL: Documentation, https://github.com/MayonaiseLover/PureFrame/tree/master/docs
Project-URL: Issues, https://github.com/MayonaiseLover/PureFrame/issues
Project-URL: Source, https://github.com/MayonaiseLover/PureFrame
Author: PureFrame Contributors
License: MIT
License-File: LICENSE
Keywords: ai,censoring,computer-vision,family-friendly,filter,offline,privacy,smart-blur,video
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.11
Requires-Dist: ffmpeg-python>=0.2.0
Requires-Dist: librosa>=0.10.0
Requires-Dist: nudenet>=3.4.2
Requires-Dist: numpy>=1.24.0
Requires-Dist: onnxruntime>=1.15.0
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: panns-inference>=0.1.1
Requires-Dist: platformdirs>=4.9.6
Requires-Dist: pydantic-settings
Requires-Dist: pydantic>=2.0
Requires-Dist: rich
Requires-Dist: scenedetect>=0.6.4
Requires-Dist: torch>=2.4.0
Requires-Dist: tqdm
Requires-Dist: transformers>=4.30.0
Requires-Dist: typer
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/logo.svg" alt="PureFrame" width="180" />
  <h1>PureFrame</h1>
  <p><strong>Watch any movie with your family. Without cutting a single second.</strong></p>
  <p>PureFrame applies smart, localized blurs over explicit visuals — no cuts, no audio edits, no streaming, no subscription.</p>

  <a href="#install"><img src="https://img.shields.io/pypi/v/pureframe?color=%2334D058&label=PyPI" alt="PyPI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="https://github.com/MayonaiseLover/PureFrame/actions"><img src="https://img.shields.io/github/actions/workflow/status/MayonaiseLover/PureFrame/ci.yml?label=CI" alt="CI" /></a>
  <img src="https://img.shields.io/badge/status-v0.1.0b1-orange" alt="Status: v0.1.0b1" />


  <br /><br />
  <img src="assets/demo.gif" alt="PureFrame in action" width="640" />
</div>

---

PureFrame is a local AI tool that finds explicit visuals in common local video files — nudity, sexual activity, intense kissing — and applies a localized, smoothly-tracked blur over the flagged regions. No scene skipping. No audio cuts. No streaming, no cloud, no subscription. The full movie plays normally; you just don't see the parts you'd rather not.

## Install

```bash
# From PyPI
pip install pureframe

# From source (development)
git clone https://github.com/MayonaiseLover/PureFrame.git
cd PureFrame
pip install -e ".[dev]"
```

> **Requirements:** Python 3.11+, FFmpeg installed and on PATH. GPU recommended but not required.

## Quick Start

```bash
# One-shot: detect and blur in a single pass
pureframe process movie.mp4 --output movie_clean.mp4

# Or split it: generate a plan, review it, then apply
pureframe plan movie.mp4                                           # → movie.censorplan.json
pureframe apply movie.mp4 movie.censorplan.json --output movie_clean.mp4

# Whitelist a false positive by shot index before applying
pureframe plan-whitelist movie.censorplan.json 3 7
```

The plan file is plain JSON — open it, review every flagged shot, whitelist anything you disagree with, then apply. Nothing renders until you say so.

## Why PureFrame?

**No scene skipping.** Most "family-friendly" tools just fast-forward through flagged scenes. You lose dialog, plot, pacing. PureFrame applies a localized Gaussian blur tracked to bounding boxes — the scene plays normally, you just can't see what's behind the blur.

**No cloud, no subscription.** Everything runs on your machine. Your videos never leave your disk. Once the AI models download on first run (~400–500MB), PureFrame works fully offline.

**Works on common local video files.** VidAngel and ClearPlay only support a curated list of popular titles. PureFrame uses computer vision — it works on any MP4, MKV, AVI, or WebM you throw at it. Foreign films, indie movies, decades-old DVDs, whatever.

**Audio-aware detection.** An audio classifier runs alongside the visual pipeline to disambiguate scenes that look ambiguous on camera but are clear from context — keeping false positives low without sacrificing coverage.

**Review before rendering.** The `plan` command generates a JSON file with every detection, bounding box, confidence score, and reasoning. You can inspect it, whitelist false positives, or adjust thresholds before committing to the render.

## How It Works

```mermaid
graph LR
    A[Input Video] --> B[Scene Detection]
    A --> C[Audio Extraction]
    B --> D[YOLOv8 Frame Analysis]
    C --> E[Audio Context Classifier]
    D --> F[Confidence Fusion]
    E --> F
    F --> G[Filter Plan JSON]
    G --> H[Optional: Review & Edit]
    H --> I[Frame Renderer + FFmpeg]
    I --> J[Clean Output Video]
```

1. **Scene detection** splits the video into shots using adaptive threshold detection.
2. **YOLOv8** analyzes sampled frames for nudity, sexual content, and face proximity (kissing detection).
3. **Audio classification** provides ambient context to reduce false positives.
4. A **confidence fusion engine** combines visual + audio signals with configurable thresholds.
5. Results are written to a **filter plan** (`.censorplan.json`) — fully editable before rendering.
6. The **renderer** reads the plan, applies tracked bounding-box blurs frame-by-frame, and re-encodes with FFmpeg.

## Comparison

| Feature | PureFrame | VidAngel / ClearPlay | Manual Editing |
|---|---|---|---|
| Cuts video length? | No — localized blur | Yes — skips scenes | Optional |
| Cost | Free & open source | $9.99/mo subscription | Expensive software |
| Requires internet? | No | Yes | No |
| Works on local files? | Yes | No — curated list only | Yes |
| Reviewable before apply? | Yes — JSON plan | No | N/A |

## Performance

Measured on author's machine: RTX 3060 12GB, i5-10400F, Pop!_OS.

| Profile | 30s synthetic 1080p clip | Extrapolated 90-min movie |
|---|---:|---:|
| HIGH | 25.96s | ~78 min |
| MEDIUM | 41.23s | ~124 min |
| LOW | 27.83s | ~83 min |
| CPU | 21.37s* | ~64 min* |

These are synthetic zero-detection numbers. Real movies with detections can be slower.

Set your profile with `--profile`:
```bash
pureframe process movie.mp4 --output out.mp4 --profile MEDIUM
```

See [BENCHMARKS.md](BENCHMARKS.md) for full metrics and how to run benchmarks.

## Desktop App (Experimental)

PureFrame includes an experimental Tauri desktop GUI. Current status: **work-in-progress**. The GUI shell is functional but features like timeline scrubbing and visual whitelisting are still being built.

```bash
cd gui && npm install && npm run tauri dev
```

## Known Limitations

PureFrame is open-source AI software in early stages. Real-world performance depends on the content:

- **First run downloads ~400–500MB of AI model weights.** Subsequent runs are fully offline.
- **False positives are real.** Especially on swimwear, intimate-but-non-sexual content, and stylized animation. Always run `pureframe plan` first and review the JSON before committing to a render. Use `pureframe plan-whitelist` to remove false positives.
- **Animation needs different thresholds** than live action. A `--content-type` flag is planned for v0.2.
- **Detection is not perfect.** Some explicit content will slip through. PureFrame is a tool to make most content family-safe — it is not a replacement for parental judgment.
- **Hardware encoding** (NVENC, QSV, VideoToolbox) is planned but not yet active. All rendering goes through software FFmpeg encoding.
- **DRM-protected and streaming content is not supported** and will not be supported. PureFrame only operates on files you legally own and can read.

## FAQ

### Is this legal?

PureFrame is intended for private, local use on media files you legally possess. It does not bypass DRM, download media, upload media, or distribute altered copies. Laws vary by jurisdiction, and because PureFrame can create an output file, the legal status may depend on your use case. This is not legal advice.

### Does it work offline?

Yes. After the first run downloads the AI models (~400–500MB), PureFrame never makes a network request.

### Will it ruin the movie?

No. PureFrame never cuts audio, skips frames, or alters the timeline. It applies a localized blur that tracks the content smoothly across frames using temporal interpolation. The pacing and narrative remain exactly as intended.

### Can I review what gets filtered before applying?

Yes. Run `pureframe plan` to generate a `.censorplan.json` file. Open it in the desktop GUI or any text editor. Every flagged shot includes the category, confidence, reasoning, and frame-level bounding boxes. Whitelist anything you disagree with, then run `pureframe apply`.

### Does it handle DRM or streaming?

No. PureFrame only processes local, unencrypted video files. It will not attempt to bypass DRM or intercept streaming content.


## Acknowledgments

PureFrame builds on excellent open-source work: [NudeNet](https://github.com/notAI-tech/NudeNet) for nudity detection, [PySceneDetect](https://github.com/Breakthrough/PySceneDetect) for shot boundary detection, [CLIP](https://github.com/openai/CLIP) for scene understanding, [PANNs](https://github.com/qiuqiangkong/audioset_tagging_cnn) for audio classification, [FFmpeg](https://ffmpeg.org/) for video I/O, and [Tauri](https://tauri.app/) for the desktop application. Thank you to those projects' maintainers.

## Contributing

See [CONTRIBUTING.md](docs/CONTRIBUTING.md). PRs welcome.

## License

[MIT](LICENSE)
