Alternate Assets

A CLI utility to slightly alter image assets to change their checksums while keeping visual changes imperceptible.

Installation

Option 1: Use with npx (no installation required)

npx imgshift <path> [flags]

Option 2: Install from npm globally

npm install -g imgshift

Option 3: Install from source (Go)

go install github.com/sincerely-manny/imgshift@latest

Option 4: Clone and build locally

git clone https://github.com/your-username/imgshift.git
cd imgshift
go build

Usage

# If installed via Go or built locally
imgshift <path> [flags]

# With npx (no installation)
npx imgshift <path> [flags]

Arguments

• <path>: Path to the image file or directory to process

Flags

• -r, --recursive int: Process directories recursively up to specified depth (default: 0)
• -v, --verbose: Display detailed information about the operations
• -h, --help: Help for imgshift

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)

Examples

Process a single image:

imgshift path/to/image.jpg
# or with npx (no installation required)
npx imgshift path/to/image.jpg

Process all images in a directory (non-recursively):

imgshift path/to/directory
# or with npx (no installation required)
npx imgshift path/to/directory

Process images recursively with a maximum depth of 3:

imgshift path/to/directory -r 3
# or with npx (no installation required)
npx imgshift path/to/directory -r 3

Show detailed information:

imgshift path/to/image.png -v
# or with npx (no installation required)
npx imgshift path/to/image.png -v

How It Works

The tool creates imperceptible changes to images by:

1. Applying a very subtle brightness adjustment (0.1%) to the image
2. For JPEGs: Estimating the original quality and applying a minimal change (±1 quality level)
3. For PNGs: Detecting file characteristics and selecting an appropriate compression level
4. For other formats: Using the imaging library's default encoding

These changes are enough to alter the file's checksum while maintaining the original quality and avoiding visible artifacts or quality degradation.

Building and Publishing

Building for Distribution

This project includes scripts for building cross-platform binaries:

# Build for all platforms (macOS, Linux, Windows)
npm run build:go

# Build and package for npm
npm run build:all

The build script creates binaries for multiple platforms and architectures:

• macOS (amd64, arm64)
• Linux (amd64, arm64)
• Windows (amd64)

npm Package Structure

The npm package includes:

• A JavaScript wrapper that detects the user's platform and architecture
• Pre-compiled binaries for all supported platforms
• No post-install scripts or runtime dependencies

This approach ensures a smooth user experience with no compilation steps required during installation.

Publishing to npm

After building all binaries:

npm run publish:npm

This will publish the npm package with pre-compiled binaries for all supported platforms.

License

MIT