@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

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 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

API Reference

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

Compares two images (PNG or JPEG) 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
`failOnLayoutDiff`	`boolean`	`false`	Fail immediately if images have different dimensions

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
 
# Mixed formats (PNG input, JPEG output)
npx blazediff expected.png actual.png diff.jpg
 
# 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 or JPEG)
  <IMAGE2>  Second image path (PNG or JPEG)
  [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)
      --fail-on-layout         Fail on layout (size) difference
  -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

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

Exit Codes

0 - Images are identical
1 - Images differ (or layout mismatch with --fail-on-layout)
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.