mirror of
https://github.com/wiltodelta/remove-ai-watermarks.git
synced 2026-08-09 15:36:01 +02:00
Victor KuznetsovandClaude Opus 5
13095fb45c
Every code-referencing claim in the docs, the README and the rules files was checked against src/, and each finding was re-derived independently before it was applied. 35 held, 5 were false positives. Two of them were code, not text. `InvisibleOptions` promises in its docstring to mirror `InvisibleEngine`, and two defaults had silently stopped: `max_resolution=None` reached `_target_size`'s `max_resolution > 0` and raised `TypeError` on every library call that left the options alone, and `cpu_offload=True` made a library run slower than the identical CLI run. Both are fixed, and `TestInvisibleOptionsMirrorTheEngine` compares the two signatures field by field rather than pinning the two values that happen to be known. A companion assertion in `TestTargetSize` reads the engine's own declared default, so a drift on the engine side -- which the mirror check alone would accept, because both sides would still agree -- fails too. The user-facing docs: README called `invisible` GPU-optional where it raises without CUDA, and gave the image `metadata` command `video metadata`'s output rule, promising the source survives a command that overwrites it. Yuanbao was missing from the supported-mark list. `veo` was listed among the video policies that require a run anchor, though its row sets no `anchor_iou`. `known-limitations` called ControlNet the default profile and contradicted itself ninety lines below. An unescaped pipe truncated the `hailuo` table row. The `dev` extra, the CI shape, ffmpeg's role, the sdist boundary and the strength-curve range were corrected, and `remove_all`/`remove_batch`, the pill gate, `erase --keep-metadata` and `all`'s CUDA failure mode were documented. Research notes that described removed modules, extras and flags in the present tense now say so once in the page banner instead of sentence by sentence, which covers the whole page rather than the lines that happened to be noticed, and one fixture is referred to by role rather than by name. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
228 lines
7.0 KiB
Markdown
228 lines
7.0 KiB
Markdown
# Installation
|
|
|
|
Python 3.10.1 or newer is required.
|
|
|
|
## Default metadata mode
|
|
|
|
The default package provides:
|
|
|
|
- provenance inspection;
|
|
- AI metadata inspection and removal.
|
|
|
|
It installs Pillow, piexif, and c2pa-python for reading metadata directly from
|
|
files. It does not install NumPy, OpenCV, pillow-heif, Torch, diffusion models,
|
|
or invisible-watermark decoders.
|
|
|
|
Install it as an isolated command with uv:
|
|
|
|
```bash
|
|
uv tool install remove-ai-watermarks
|
|
```
|
|
|
|
Or with pipx:
|
|
|
|
```bash
|
|
pipx install remove-ai-watermarks
|
|
```
|
|
|
|
You can also install the Homebrew package on macOS or Linux:
|
|
|
|
```bash
|
|
brew install wiltodelta/tap/remove-ai-watermarks
|
|
```
|
|
|
|
## Visible watermark removal
|
|
|
|
Visible mark detection, OpenCV inpainting, and manual region erasing need the
|
|
`visible` extra:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[visible]"
|
|
```
|
|
|
|
Add `heif` only when the pixel path must decode HEIC, HEIF, or AVIF:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[visible,heif]"
|
|
```
|
|
|
|
## Video processing
|
|
|
|
Video metadata inspection works with the default package, and MP4 and MOV
|
|
stripping uses the in-tree ISOBMFF box walker. Stripping the non-ISOBMFF
|
|
containers (MKV, WebM, AVI, FLV, and the audio formats) and writing any cleaned
|
|
video need ffmpeg on PATH, for example `brew install ffmpeg`. Stable
|
|
visible-mark identification and removal, full video cleaning, and visible/all
|
|
batch modes need the `video` extra:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[video]"
|
|
```
|
|
|
|
The extra includes the visible pixel runtime and PyAV for preserving variable
|
|
frame timestamps. Video SynthID regeneration also needs the diffusion stack:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[video,diffusion]"
|
|
```
|
|
|
|
## Invisible watermark removal
|
|
|
|
Install the `qwen-zimage` extra:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[qwen-zimage]"
|
|
```
|
|
|
|
Both remaining profiles run a Z-Image face stage on the DiffSynth runtime, so
|
|
both need this extra. It includes the `diffusion` dependencies; `diffusion` on its
|
|
own covers the torch and diffusers imports but not the face stage, so it is not
|
|
enough to run a removal.
|
|
|
|
**An NVIDIA GPU is required.** `qwen-zimage` and `sdxl-zimage` are CUDA-only, and
|
|
construction refuses any other device rather than falling back to a slow or broken
|
|
one. There is no CPU, MPS or XPU path for invisible-watermark removal. Visible-mark
|
|
removal, metadata stripping and every `identify` command still run anywhere.
|
|
|
|
Video SynthID regeneration is a separate VAE path and does still run on CPU or MPS;
|
|
it needs the `diffusion` extra, not this one.
|
|
|
|
## Feature extras
|
|
|
|
Extras are composable. Install only the capabilities and file formats the
|
|
application actually uses:
|
|
|
|
| Extra | Capability | Automatically includes | Torch or model download |
|
|
| --- | --- | --- | --- |
|
|
| `pixels` | Shared BGR array and image-processing runtime | NumPy, headless OpenCV | No |
|
|
| `heif` | HEIC, HEIF, and AVIF pixel decoding | pillow-heif | No |
|
|
| `visible` | Visible mark detection, OpenCV inpainting, and manual erasing | `pixels` | No |
|
|
| `video` | Visible video identification/removal and timestamp preservation | `visible`, PyAV | No |
|
|
| `detect` | Open DWT-DCT detection for Stable Diffusion, SDXL, and FLUX | `pixels`, PyWavelets | No |
|
|
| `trustmark` | Adobe TrustMark detection | trustmark | Yes |
|
|
| `diffusion` | Torch and Diffusers runtime; video SynthID regeneration | `pixels`, Torch, Diffusers | Yes |
|
|
| `migan` | MI-GAN ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
|
|
| `lama` | big-LaMa ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
|
|
| `qwen-zimage` | Invisible image-watermark removal, both CUDA-only profiles | `diffusion`, DiffSynth | Yes |
|
|
| `all` | Every production feature | All rows above | Yes |
|
|
| `dev` | Tests, linting, typing, and upstream parity checks | `video`, `detect`, upstream invisible-watermark | Yes, for parity tests |
|
|
|
|
Dependency composition:
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
visible --> pixels
|
|
video --> visible
|
|
detect --> pixels
|
|
diffusion --> pixels
|
|
migan --> visible
|
|
lama --> visible
|
|
qwen["qwen-zimage"] --> diffusion
|
|
heif
|
|
trustmark
|
|
```
|
|
|
|
`heif` and `trustmark` are independent branches. Combine them explicitly with
|
|
another feature when required. The `all` bundle contains every production
|
|
branch but never includes `dev`.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
# Metadata plus torch-free DWT-DCT detection
|
|
uv tool install --force "remove-ai-watermarks[detect]"
|
|
|
|
# Visible removal with HEIC/AVIF support and MI-GAN
|
|
uv tool install --force "remove-ai-watermarks[migan,heif]"
|
|
|
|
# Visible video removal with preserved timestamps
|
|
uv tool install --force "remove-ai-watermarks[video]"
|
|
|
|
# DWT-DCT and TrustMark detection without diffusion removal
|
|
uv tool install --force "remove-ai-watermarks[detect,trustmark]"
|
|
|
|
# Every production capability
|
|
uv tool install --force "remove-ai-watermarks[all]"
|
|
|
|
# An arbitrary minimal combination
|
|
uv tool install --force "remove-ai-watermarks[migan,detect]"
|
|
```
|
|
|
|
`heif` stays independent so applications that only process PNG, JPEG, or WebP
|
|
do not install libheif. `detect` uses the in-tree torch-free decoder and does
|
|
not install the upstream `invisible-watermark` package. Optional models download
|
|
their weights on first use.
|
|
|
|
The old `gpu` and `remove` aliases are intentionally not provided. Use
|
|
`diffusion` and `visible` respectively.
|
|
|
|
## Install from the repository
|
|
|
|
```bash
|
|
git clone https://github.com/wiltodelta/remove-ai-watermarks.git
|
|
cd remove-ai-watermarks
|
|
uv sync --frozen
|
|
```
|
|
|
|
Add the feature groups required for your work:
|
|
|
|
```bash
|
|
uv sync --frozen --extra dev
|
|
uv sync --frozen --extra dev --extra diffusion
|
|
```
|
|
|
|
Run commands from the repository root:
|
|
|
|
```bash
|
|
uv run remove-ai-watermarks --help
|
|
```
|
|
|
|
## Development setup
|
|
|
|
Install development dependencies:
|
|
|
|
```bash
|
|
uv sync --frozen --extra dev
|
|
```
|
|
|
|
Run the complete project gate:
|
|
|
|
```bash
|
|
bash maintain.sh
|
|
```
|
|
|
|
The script syncs every optional backend on top of the `dev` environment above,
|
|
then runs dependency checks, linting, formatting, type checking, and the test
|
|
suite. It applies Ruff fixes and formatting in place rather than only reporting
|
|
them.
|
|
|
|
## Hugging Face authentication
|
|
|
|
Pass a Hugging Face token directly when the selected model or account requires
|
|
one:
|
|
|
|
```bash
|
|
remove-ai-watermarks invisible image.png --hf-token "$HF_TOKEN"
|
|
```
|
|
|
|
The CLI also loads `HF_TOKEN` from the environment and from a local `.env`
|
|
file. The same name is documented in `.env.example`.
|
|
|
|
## Troubleshooting
|
|
|
|
### The first model run is slow
|
|
|
|
Diffusion and learned fill backends may download model weights on first use.
|
|
Later runs reuse their caches.
|
|
|
|
### The command skips invisible removal
|
|
|
|
The normal behavior is to skip diffusion when no supported local signal is
|
|
found. A missing signal does not prove that the image is clean. If you know the
|
|
image came from a relevant generator, use `--force`.
|
|
|
|
If the CLI reports that the removal dependencies are unavailable, install the
|
|
`qwen-zimage` extra. `diffusion` alone covers Torch and Diffusers but not the
|
|
DiffSynth face stage that both profiles run. Video SynthID removal is a separate
|
|
path and needs `video` and `diffusion`.
|