Skip to main content
AI tutorials

Batch Clean AI Provenance Markers and Metadata from Images with xxd-strip-ai-meta

This tutorial explains how to install and use xxd-strip-ai-meta to batch-clean C2PA, Content Credentials, OpenAI, gpt-image, and common metadata from images while preserving ICC color profiles and modification times.

About 19 min read
Batch-clean image AI provenance and metadata with xxd-strip-ai-meta

Project Overview

xxd-strip-ai-meta is an image metadata cleaning tool based on ExifTool. It can be used as a standalone command-line program or installed as an AI Agent Skill. It batch-processes local images and cleans supported C2PA, Content Credentials, OpenAI, and gpt-image provenance information, along with EXIF, XMP, IPTC, comments, and other metadata.

The tool modifies original files in place by default, but it does not decode or re-encode image pixels. It preserves ICC color profiles and file modification times, making it suitable for privacy protection, internal asset processing, and metadata organization.

Usage boundaries: This is a metadata cleaning tool. It cannot remove visibly rendered watermarks from an image, nor can it guarantee the removal of pixel-level invisible watermarks, platform fingerprints, or server-side records. Do not use it to mislead others about an image’s origin.

Key Features

  • Recursively finds PNG, JPEG, WebP, TIFF, HEIC, HEIF, and AVIF images.
  • Cleans supported AI provenance information and metadata such as EXIF, XMP, IPTC, and comments.
  • Preserves ICC color profiles by default to reduce the risk of color changes.
  • Preserves file modification times without decoding or re-encoding image pixels.
  • Accepts multiple files and directories at once and automatically removes duplicates caused by overlapping inputs.
  • Skips hidden subdirectories and common cache directories.
  • Skips recognized files whose extensions do not match their file headers by default.
  • Supports previewing, original-file backups, concurrent batch processing, logging, background execution, and post-cleaning verification.

Metadata writing capabilities for specific formats depend on ExifTool and the corresponding file format. The tool accepts only local files or directories; it does not process remote URLs or archives directly.

Prerequisites

Running the project requires Python 3.10 or later and ExifTool available on the system PATH. The project itself has no third-party Python dependencies.

1. Install ExifTool

macOS users can install it with Homebrew:

brew install exiftool

Debian or Ubuntu users can install it with the system package manager:

sudo apt install libimage-exiftool-perl

Windows users can download and install it from the ExifTool website, then ensure that the directory containing its executable is included in PATH.

2. Check the Environment

python3 --version
exiftool -ver

The Python version should be 3.10 or later. On Windows, the Python command may be python; replace python3 in the following examples accordingly.

3. Clone the Project

git clone https://github.com/nevertoday/xxd-strip-ai-meta.git
cd xxd-strip-ai-meta

All commands below assume that the current directory is the repository root.

Basic Workflow

Step 1: Preview Files First

Because the default behavior modifies original files in place, use --dry-run for the first operation. This option only lists files and does not perform cleaning.

python3 scripts/clean_image_provenance.py /path/to/images --dry-run

Review the output and confirm that the scan scope contains no images that should not be processed. If the log reports skipped files or nonexistent paths, resolve those issues first.

Step 2: Clean Files with Backups

After confirming that the file list is correct, add --backup for the first actual run:

python3 scripts/clean_image_provenance.py /path/to/images --backup

ExifTool keeps backups of the original files with the name pattern *_original. After confirming that the results meet expectations, decide how to manage these backups.

Step 3: Process Files and Directories Together

The script accepts multiple local files and directories in one command:

python3 scripts/clean_image_provenance.py \
  /path/to/a.png \
  /path/to/folder-a \
  /path/to/folder-b

Directories are scanned recursively. If input paths overlap, the tool automatically removes duplicates so that the same file is not processed repeatedly because of overlapping paths.

Common Options

  • --dry-run: Preview files without making changes.
  • --backup: Keep the original-file backups generated by ExifTool.
  • --jobs 5: Set the number of concurrent batches; the default is 5. Set it to 1 to reduce system load.
  • --chunk-size 100: Set the number of files per batch; the default is 100.
  • --log-file PATH: Write logs to the specified path.
  • --background: Start the task in the background and print commands for stopping the task and viewing logs; suitable for POSIX shells.
  • --drop-color-profile: Also remove ICC color profiles, which may affect how images are displayed.
  • --no-verify: Skip the post-cleaning metadata provenance check.

Large Batch Jobs

Run in the Background

On systems that support POSIX shells, use background mode for time-consuming tasks:

python3 scripts/clean_image_provenance.py /path/to/images --background

After starting, the command prints commands for stopping the task and viewing logs. Save these instructions for later monitoring or termination.

Control Concurrency and Batch Size

The default is 5 concurrent batches with up to 100 files per batch. If device resources are limited, reduce the concurrency to 1:

python3 scripts/clean_image_provenance.py /path/to/images \
  --jobs 1 \
  --chunk-size 100 \
  --log-file /path/to/clean-image-meta.log

Logs are useful not only for reviewing cleaning failures, but also for checking skipped files and nonexistent input paths. An exit code of 0 does not necessarily mean that images were processed; it may also mean that no files were found.

Verification and Exit Codes

By default, the script checks the ExifTool output after cleaning to see whether related provenance keywords remain. This verification checks metadata markers only. It is not a general watermark detector and cannot determine whether pixel-level invisible markers are present.

  • Exit code 0: No cleaning failures or remnants were reported; it may also mean that no files were found.
  • Exit code 1: A cleaning failure occurred.
  • Exit code 2: Residual markers were found.

If post-cleaning verification is not needed for a specific reason, use:

python3 scripts/clean_image_provenance.py /path/to/images --no-verify

After verification is skipped, the tool will not perform the provenance keyword check described above. Use the logs and other checks to confirm the result.

Advanced Recommendations

Establish a Safer Processing Order

  1. Run --dry-run on the target path first and review the scan scope.
  2. Use --backup for the first actual run to keep recoverable originals.
  3. Specify --log-file for large jobs to make it easier to review failed, skipped, and missing files.
  4. When resources are limited, reduce --jobs to 1, then adjust --chunk-size based on the environment.
  5. Use the exit code to identify failures or remnants, but do not ignore the log contents.
  6. Check the processed images with an image viewer for color and usability before managing the backup files.

Remove ICC Color Profiles with Care

ICC profiles are preserved by default to maintain image color display. If you need to remove color profiles as well, add:

python3 scripts/clean_image_provenance.py /path/to/images \
  --backup \
  --drop-color-profile

--drop-color-profile may change color presentation across different software or devices, so test it on a small number of copies first.

Understand Format Limitations

The script looks for files with supported extensions, but whether a format can be written successfully still depends on the installed ExifTool version and the format itself. When a failure occurs, review the logs and ExifTool output instead of judging compatibility solely by the file extension.

Install as an AI Agent Skill

The project can also be placed in an AI Agent skills directory. For example, with Claude Code:

git clone https://github.com/nevertoday/xxd-strip-ai-meta.git \
  ~/.claude/skills/xxd-strip-ai-meta

If the target location already contains a directory with the same name, back up that directory first or use a different installation location. The Skill entry file is SKILL.md. The Agent should run the script from the installation directory or resolve and use the script’s absolute path first.

Conclusion

xxd-strip-ai-meta provides a batch metadata organization workflow without third-party Python packages. In practice, follow the order “preview first, back up, clean, then review logs,” and clearly distinguish metadata cleaning from visible watermark removal and pixel-level marker detection. The project is licensed under the MIT License. ExifTool is a separately installed dependency and is covered by its own license.