@blazediff/bin

The fastest single-threaded image diff in the world. Native Rust implementation with SIMD optimization, 3-4x faster and 3x smaller than odiff .

View Detailed Benchmarks

Installation


npm install @blazediff/bin


pnpm add @blazediff/bin


yarn add @blazediff/bin


bun add @blazediff/bin

Also available as a Rust crate: cargo install blazediff

Pre-built binaries are included for all major platforms - no compilation required:

macOS ARM64 (Apple Silicon) & x64 (Intel)
Linux ARM64 & x64
Windows ARM64 & x64

Features

PNG, JPEG & QOI support - auto-detected by file extension
3-4x faster than odiff on large images
3x smaller binaries (~700KB-900KB vs ~2-3MB)
SIMD-accelerated - NEON on ARM, SSE4.1 on x86
Block-based optimization - skips unchanged regions
Zero compilation - pre-built binaries for all platforms
TypeScript support out of the box

Vendored Libraries

libspng - Fast PNG decoding/encoding with SIMD
libjpeg-turbo - High-performance JPEG codec with SIMD
qoi - QOI (Quite OK Image) format for fast lossless compression

API Reference

`compare(basePath, comparePath, diffOutput, options?)`

Compares two images (PNG, JPEG, or QOI) and generates a diff image. Format is auto-detected from file extension.

Parameters

Parameter	Type	Description
`basePath`	`string`	Path to the base/expected image
`comparePath`	`string`	Path to the comparison/actual image
`diffOutput`	`string`	Path where the diff image will be saved
`options`	`BlazeDiffOptions`	Comparison options (optional)

Options

Option	Type	Default	Description
`threshold`	`number`	`0.1`	Color difference threshold (0.0-1.0). Lower = more strict
`antialiasing`	`boolean`	`false`	Enable anti-aliasing detection
`diffMask`	`boolean`	`false`	Output only differences with transparent background

Return Types


type BlazeDiffResult =
  | { match: true }
  | { match: false; reason: "layout-diff" }
  | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number }
  | { match: false; reason: "file-not-exists"; file: string };

Threshold Guidelines:

0.0 - Exact match only
0.05 - Strict comparison
0.1 - Default balanced comparison
0.2 - Lenient comparison

Usage

Programmatic API


import { compare } from '@blazediff/bin';
 
const result = await compare('expected.png', 'actual.png', 'diff.png', {
  threshold: 0.1,
  antialiasing: true,
});
 
if (result.match) {
  console.log('Images are identical!');
} else if (result.reason === 'pixel-diff') {
  console.log(`${result.diffCount} pixels differ (${result.diffPercentage.toFixed(2)}%)`);
} else if (result.reason === 'layout-diff') {
  console.log('Images have different dimensions');
}

CLI Usage


# Compare two PNG images
npx blazediff expected.png actual.png diff.png
 
# Compare two JPEG images
npx blazediff expected.jpg actual.jpg diff.jpg
 
# Compare two QOI images
npx blazediff expected.qoi actual.qoi diff.qoi
 
# Mixed formats (PNG input, QOI output - recommended for smallest diff files)
npx blazediff expected.png actual.png diff.qoi
 
# With options
npx blazediff expected.png actual.png diff.png --threshold 0.05 --antialiasing
 
# With higher PNG compression (smaller output file, slower)
npx blazediff expected.png actual.png diff.png -c 6
 
# With JPEG quality setting
npx blazediff expected.jpg actual.jpg diff.jpg -q 85
 
# Output as text format
npx blazediff expected.png actual.png diff.png --output-format text

CLI Options


blazediff [OPTIONS] <IMAGE1> <IMAGE2> [OUTPUT]
 
Arguments:
  <IMAGE1>  First image path (PNG, JPEG, or QOI)
  <IMAGE2>  Second image path (PNG, JPEG, or QOI)
  [OUTPUT]  Output diff image path (optional, format detected from extension)
 
Options:
  -t, --threshold <THRESHOLD>  Color difference threshold (0.0-1.0) [default: 0.1]
  -a, --antialiasing           Enable anti-aliasing detection
      --diff-mask              Output only differences (transparent background)
  -c, --compression <LEVEL>    PNG compression level (0-9, 0=fastest, 9=smallest) [default: 0]
  -q, --quality <QUALITY>      JPEG quality (1-100) [default: 90]
      --output-format <FORMAT> Output format (json or text) [default: json]
  -h, --help                   Print help
  -V, --version                Print version

Supported Formats

Format	Extensions	Notes
PNG	`.png`	Lossless, supports transparency
JPEG	`.jpg`, `.jpeg`	Lossy, smaller file sizes
QOI	`.qoi`	Fast lossless, ideal for diff outputs (12x smaller than uncompressed PNG)

Input images can be mixed formats (e.g., compare PNG to JPEG). Output format is determined by the output file extension.

Use QOI for diff outputs: QOI excels at encoding diff images with large uniform areas, producing files 12x smaller than PNG (level 0) while being faster to encode.

Exit Codes

0 - Images are identical
1 - Images differ (includes layout/size mismatch)
2 - Error (file not found, invalid format, etc.)

Performance

Benchmarked on Apple M1 Max with 5600x3200 4K images:

Tool	Time	Comparison
blazediff	~327ms	-
odiff	~1215ms	3.7x slower

Binary sizes (stripped, LTO optimized):

Platform	blazediff	odiff
macOS ARM64	702 KB	2.2 MB
Linux x64	869 KB	2.9 MB
Windows x64	915 KB	3.0 MB

Why so fast? BlazeDiff uses a two-pass block-based algorithm with SIMD acceleration. The cold pass quickly identifies unchanged 8x8 blocks using 32-bit integer comparison, then the hot pass only processes changed regions with YIQ perceptual color difference.