pureframe 0.1.0b1__tar.gz

pureframe-0.1.0b1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug Report
+description: Create a report to help us improve
+title: "[BUG] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command executed
+      description: What exact CLI command did you run?
+      render: bash
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Error Traceback / Logs
+      description: Paste any error messages, logs, or tracebacks here.
+      render: log
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: e.g. Windows 11, Ubuntu 22.04, macOS Sonoma
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Run `python --version`
+    validations:
+      required: true
+  - type: input
+    id: gpu
+    attributes:
+      label: GPU / Hardware
+      description: e.g. RTX 3060, M2 Max, CPU only
+    validations:
+      required: true

pureframe-0.1.0b1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "npm"
+    directory: "/gui"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "cargo"
+    directory: "/gui/src-tauri"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+

pureframe-0.1.0b1/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    name: test (ubuntu, py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Install CPU-only PyTorch first
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check pureframe tests
+
+      - name: Ruff format
+        run: ruff format --check pureframe tests
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: python -m twine check dist/*
+
+      - name: Run fast tests
+        run: pytest -q -m "not slow" --maxfail=3
+        timeout-minutes: 10

pureframe-0.1.0b1/.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  schedule:
+    - cron: '0 0 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python', 'javascript', 'typescript', 'rust' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3

pureframe-0.1.0b1/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+# .github/workflows/publish.yml
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: python -m twine check dist/*
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pureframe/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

pureframe-0.1.0b1/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  tauri-build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+    - name: Setup Rust
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        targets: ${{ matrix.target }}
+    - name: Install dependencies (Ubuntu)
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
+    - name: Install Frontend Dependencies
+      working-directory: gui
+      run: npm install
+    - name: Build Tauri App
+      uses: tauri-apps/tauri-action@v0
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        projectPath: gui
+        tagName: ${{ github.ref_name }}
+        releaseName: 'PureFrame ${{ github.ref_name }}'
+        releaseBody: 'Release ${{ github.ref_name }}'
+        releaseDraft: true
+        prerelease: false
+        args: ${{ matrix.os == 'macos-latest' && format('--target {0}', matrix.target) || '' }}

pureframe-0.1.0b1/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Debug scripts (dev-only)
+debug_test*.py
+update_cli.py
+
+# Lock files (generated)
+uv.lock
+
+# Tauri build artifacts
+gui/src-tauri/target/
+gui/node_modules/
+gui/dist/
+
+# Demo intermediates (keep demo.gif and logo.svg)
+assets/demo_input.mp4
+assets/demo_output.mp4
+assets/demo_plan.json

pureframe-0.1.0b1/BENCHMARKS.md

@@ -0,0 +1,76 @@
+# Performance Benchmarks
+
+> Measurements below are **real, on the machine indicated**. Other tiers are estimated from community contributions. To add your hardware, run `scripts/run_benchmarks.sh` and open a PR.
+
+> **Note on these numbers:** The benchmark clip is a 30s synthetic 1080p video (solid colours, test patterns) with **zero detections**. Real movie content with actual detections will take longer — blurring adds per-frame overhead, and complex scenes trigger more model inference. Use these numbers as a floor, not a ceiling.
+
+## Measured: Author's Machine
+
+| | |
+|---|---|
+| **OS** | Linux (Pop!_OS 24.04, kernel 6.18.7) |
+| **CPU** | Intel Core i5-10400F @ 2.90GHz (6 cores) |
+| **GPU** | NVIDIA GeForce RTX 3060 (12 GB VRAM) |
+| **Python** | 3.13.12 |
+| **PyTorch** | 2.11.0+cu130 |
+| **CUDA** | 13.0 |
+
+| Profile | 30s 1080p clip | Extrapolated 90-min movie | Detection FPS |
+|---|---|---|---|
+| HIGH (12 GB VRAM) | **25.96s** | ~78 min | ~28 fps |
+| MEDIUM (6–11 GB VRAM) | **41.23s** | ~124 min | ~18 fps |
+| LOW (3–5 GB VRAM) | **27.83s** | ~83 min | ~26 fps |
+| CPU (no GPU) | **21.37s** | ~64 min* | ~34 fps* |
+
+*CPU appears faster on synthetic content because CUDA initialization overhead is amortised differently and no inference is triggered on zero-detection clips. Expect CPU to be **3–10× slower** on real movie content.*
+
+## Estimated: Other Hardware
+
+Community contributions welcome. Run `scripts/run_benchmarks.sh` and open a PR to add your hardware below.
+
+| Hardware | Profile | Estimated 90-min movie |
+|---|---|---|
+| RTX 4090 (24 GB) | HIGH | ~30 min (estimated, not measured) |
+| RTX 4070 (12 GB) | HIGH | ~50 min (estimated, not measured) |
+| GTX 1650 (4 GB) | LOW | ~120 min (estimated, not measured) |
+| Apple M2 Pro | MEDIUM | ~90 min (estimated, not measured) |
+| Apple M4 Max | HIGH | ~35 min (estimated, not measured) |
+
+## Profile Knobs
+
+### HIGH (12+ GB VRAM)
+- Detection resolution: 1080px
+- Batch size: 32 frames
+- FP16 inference: enabled
+- Models kept in VRAM between stages
+- Samples 5 keyframes per shot + densifies every frame
+
+### MEDIUM (6–11 GB VRAM)
+- Detection resolution: 720px
+- Batch size: 16 frames
+- FP16 inference: enabled
+- Models kept in VRAM between stages
+- Samples 3 keyframes per shot, densifies every 2nd frame
+
+### LOW (3–5 GB VRAM)
+- Detection resolution: 540px
+- Batch size: 4 frames
+- FP16 inference: enabled
+- Models unloaded between stages (reduces VRAM pressure)
+- Samples 3 keyframes per shot, densifies every 3rd frame
+
+### CPU (no GPU)
+- Detection resolution: 480px
+- Batch size: 1 frame
+- FP16 disabled (CPU doesn't benefit)
+- Models unloaded between stages
+- Samples 2 keyframes per shot, densifies every 5th frame
+
+## How to Contribute Benchmarks
+
+1. Clone the repo and install: `pip install -e .`
+2. Generate the benchmark clip:
+   ```bash
+   bash scripts/run_benchmarks.sh
+   ```
+3. Open a PR adding your row to the "Estimated" table above. Mark it "measured" and include your hardware spec.

pureframe-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0b1] - 2026-05-07
+
+### Added
+- Initial beta release.
+- CLI plan/apply/process workflow.
+- Local explicit-content detection.
+- JSON censor plan review workflow.
+- FFmpeg-based blur rendering.

pureframe-0.1.0b1/LAUNCH.md

@@ -0,0 +1,33 @@
+# Launch Sequence: PureFrame
+
+Follow this battle-tested sequence to maximize visibility and adoption for PureFrame.
+
+### 1. Soft Launch on r/selfhosted
+- **Timing:** Tuesday morning (EST).
+- **Format:** A short text post explaining the *why* (privacy, local AI, Family Movie Act) and a clear link to the GitHub repository.
+- **Visuals:** Use the side-by-side GIF as the primary hook.
+
+### 2. r/Parenting
+- **Timing:** Wednesday evening.
+- **Format:** A relatable, non-technical post. Focus entirely on the benefit: "I built a tool that lets me watch my favorite movies with my kids without skipping scenes."
+- **Tone:** Helpful, empathetic, community-focused.
+
+### 3. r/PleX
+- **Timing:** Thursday.
+- **Format:** Technical showcase. Mention the CLI and batch processing. 
+- **Hook:** "I'm working on a Plex plugin for this next, but the standalone CLI/GUI is ready now."
+
+### 4. Hacker News (Show HN)
+- **Title:** `Show HN: PureFrame — Censor explicit visuals in any video locally, without cutting a frame`
+- **First Comment:** Write a detailed comment explaining the technical challenges (YOLOv8, Audio Zero-shot classification, temporal smoothing algorithm) to engage the HN crowd.
+
+### 5. Product Hunt
+- **Timing:** 12:01 AM PST on a Tuesday or Wednesday.
+- **Assets:** The demo GIF, a nice banner image (using the logo), and clear UI screenshots of the Tauri app's Plan Editor.
+
+### 6. X/Twitter
+- **Format:** A short thread.
+- **Tags:** Tag prominent `#selfhosted`, `#AI`, and open-source tech accounts. Use the demo GIF on the first tweet.
+
+### 7. Blogger Outreach
+- Reach out to family-friendly streaming bloggers and tech journalists. Offer them a pre-compiled Windows `.exe` or Mac `.dmg` so they don't have to compile from source.

pureframe-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PureFrame
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.