DocShrink

DocShrink is a high-performance, offline, and cross-platform document and image compression engine. It runs entirely locally on your machine—no cloud services, no APIs, and no internet required. It is built for integration into automated pipelines and handles batch processing effortlessly.

Key Features

• Format Agnostic: Compresses PDF, JPEG, PNG, WebP, TIFF, and BMP seamlessly.
• Novel Algorithms: Uses custom-designed APQM (Advanced Perceptual Quality Model), CCT (Cascade Compression Tournament), POSD (Perceptual Object Stream Deduplication), and EADS (Entropy-Aware Deflate Strategy) algorithms.
• MPTSS (Multi-Phase Target Size Solver): Need an output file to be exactly < 5MB for an email attachment? Just specify --target-size 5MB and DocShrink will find the optimal balance of quality and scale to hit the target.
• Privacy First: 100% local processing. No data is ever uploaded.

Installation

pip install -e .

Usage (CLI)

DocShrink provides a simple yet powerful CLI for individual files and batch processing.

# Compress a single file
docshrink input.pdf output.pdf

# Compress a file using a built-in preset
docshrink input.jpg output.jpg --preset web

# Compress an entire directory of images and PDFs
docshrink ./my_documents ./compressed_documents

# Compress a directory to a specific target size (per file)
docshrink ./large_scans ./compressed_scans --target-size 2MB

# Strip all metadata during compression
docshrink document.pdf output.pdf --remove-metadata

# Convert to grayscale and downsample large images
docshrink large_photo.tiff output.jpg --grayscale --max-resolution 1920

CLI Options

• --lossless: Enforce lossless compression (no visual degradation).
• --lossy: Allow aggressive lossy recompression for maximum size reduction.
• --preset: Use a tuned profile: screen, ebook, print, or archive.
• --target-size: Attempt to compress the file to match the specified size (e.g. 2MB, 500KB).
• --max-resolution: Downsample images so the longest side doesn't exceed this pixel value.
• --grayscale: Convert images and documents to grayscale.
• --remove-metadata: Strip EXIF, XMP, and PDF metadata for maximum privacy and size reduction.
• --dry-run: Evaluate what savings would be achieved without actually writing the files.
• --json-log: Output a detailed JSON report of the batch process.

Architecture

Please see the docs/ folder for deep dives into the underlying systems:

• docs/architecture.md: Overall system design and module boundaries.
• docs/algorithms.md: Explanation of APQM, CCT, POSD, and MPTSS.
• docs/pdf_internals.md: How the PDF engine dissects and compresses streams.