Ghost Remover
AI-powered video inpainting engine. Remove watermarks, logos, and objects from video using SAM 2 + ProPainter.
Features
- SAM 2 tracking - Segment anything with text, box, or point prompts via Grounding DINO + SAM 2
- ProPainter inpainting - Temporal-aware video inpainting with optical flow completion
- Two-pass architecture - Pass 1: tracking + mask generation. Pass 2: inpainting + streaming encode
- Chunked processing - Handles arbitrarily long videos with overlap blending
- MPS optimized - Native Apple Silicon support with automatic CPU fallback for unsupported ops
- Checkpoint resume - Interrupt and resume without losing progress
- Batch processing - Process multiple videos in one command
- Quality metrics - Temporal consistency, pixel integrity (PSNR), and style (LPIPS) checks
v0.3 Performance Upgrades
| Optimization | Effect |
|---|---|
| Eliminate redundant ffprobe | frames_to_numpy accepts video_info param, skips re-probing |
| Single decode in Pass 1 | Reuses extracted JPEGs for re-detection fallback instead of second FFmpeg decode |
| Float16 mixed precision | torch.autocast("mps", float16) for ProPainter inference — ~1.5x faster, half memory |
| Chunk prefetch | Background thread decodes next chunk while current chunk is being inpainted |
| Vectorized blending | Overlap blending uses numpy batch ops instead of per-frame Python loop |
| OOM auto-retry | On memory error: split chunk in half → retry → downscale fallback → original frames |
| FFmpeg timeout | All subprocess calls have timeout protection (120-300s) |
| Frame count validation | Warns when decoded frame count doesn't match expected |
Installation
# Create conda environment
conda env create -f environment.yml
conda activate ghost-remover
# Clone ProPainter into third_party/
git clone https://github.com/sczhou/ProPainter.git third_party/ProPainter
bash setup_propainter.sh
# Download SAM 2 checkpoints
mkdir -p checkpoints
# See https://github.com/facebookresearch/segment-anything-2#download-checkpoints
Usage
CLI
# Basic - remove watermark by text prompt
ghost-remover remove --video input.mp4 --target "watermark"
# With bounding box
ghost-remover remove --video input.mp4 --target "logo" --box 100,50,300,150
# Dry-run (preview mask overlay only)
ghost-remover remove --video input.mp4 --target "watermark" --dry-run
# Batch processing
ghost-remover remove --video a.mp4 b.mp4 c.mp4 --target "watermark"
# Hardware-accelerated encoding (VideoToolbox)
ghost-remover remove --video input.mp4 --target "watermark" --hw-accel
# Adjust sensitivity (0.1=tight, 1.0=aggressive)
ghost-remover remove --video input.mp4 --target "watermark" --sensitivity 0.7
Python API
from main import GhostRemoverPipeline
config = {
"video_path": "input.mp4",
"target": "watermark",
"sensitivity": 0.5,
"sam_model_size": "large",
}
pipeline = GhostRemoverPipeline(config)
output = pipeline.run()
pipeline.cleanup()
Architecture
ghost-remover/
core/
ffmpeg_handler.py # Video decode/encode, streaming pipe I/O
tracker_sam3.py # SAM 2 segmentation + video tracking
inpainter_pp.py # ProPainter inpainting engine
utils/
gpu_manager.py # MPS memory monitoring + chunk size estimation
video_chunker.py # Chunk planning + overlap blending
checkpoint.py # Interrupt recovery
quality_metrics.py # Temporal/pixel/style quality checks
api/
skill_interface.py # CLI + JSON API
main.py # Two-pass pipeline orchestrator
Pipeline Flow
Input Video
│
├─ Pass 1: SAM 2 Tracking (5-50%)
│ ├─ First frame segmentation (text/box/point prompt)
│ ├─ Per-chunk mask propagation
│ ├─ Drift detection + re-detection
│ └─ Packed mask storage (.npz)
│
├─ Pass 2: ProPainter Inpainting (50-95%)
│ ├─ RAFT optical flow (fp16)
│ ├─ Bidirectional flow completion
│ ├─ Image propagation
│ ├─ Transformer inpainting (sliding window)
│ ├─ Overlap blending (vectorized)
│ └─ Streaming FFmpeg encode
│
└─ Finalize (95-100%)
├─ Audio merge
└─ Quality check
Tests
# Run all tests (134 tests)
python3 -m pytest tests/ghost-remover/ -v
Requirements
- Python >= 3.11
- PyTorch >= 2.2.0 (MPS support)
- FFmpeg
- SAM 2 (segment-anything-2)
- ProPainter (third_party/)
- Grounding DINO (via HuggingFace transformers, optional for text prompts)
Version
v0.3.0 — 134 tests passing
License
MIT
Metadata
Release files for ghost-remover 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ghost_remover-0.3.1.tar.gz | 24.7 kB | Without provenance | Details for ghost_remover-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ghost_remover-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for ghost_remover-0.3.1-py3-none-any.whl |
Total release size: 50.3 kB
Release files / ghost_remover-0.3.1.tar.gz
| Download URL | ghost_remover-0.3.1.tar.gz |
|---|---|
| Size | 24.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8017a7b07e17c4aaa0b10b07c75a72098b6e750e482151594eb0b4abc18c6f9e
|
|
BLAKE2b-256 checksum How to use checksums |
4d7f3a62aaf8661d3b232545b215418b2a3340c64bf0e9e3dd008e21e879c8bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Release files / ghost_remover-0.3.1-py3-none-any.whl
| Download URL | ghost_remover-0.3.1-py3-none-any.whl |
|---|---|
| Size | 25.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ad18989d51ca15c801a6e370cb14d2ba574e6fc1d8e5f5f1e8f8979a276b2045
|
|
BLAKE2b-256 checksum How to use checksums |
1705ecd2c38bcc7bbed7d4c462a04dc8f3a97b920106f5dc221640a25feb13ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Security for ghost-remover 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.