jpeg_validator 0.1.1

Strict, warning-free, full-decode JPEG validation for Dart and Flutter.

jpeg_validator

Strict, warning-free, full-decode JPEG validation for Dart and Flutter.

jpeg_validator considers a JPEG valid only when libjpeg-turbo can read its header, decode every output scanline, finish decompression, and report zero warnings. This rejects truncated images that tolerant image libraries may silently complete or repair.

Usage

import 'dart:io';

import 'package:jpeg_validator/jpeg_validator.dart';

Future<void> main() async {
  final JpegValidationResult result = await validateFile(
    File('photo.jpg'),
  );

  if (result.isValid) {
    print('The complete JPEG decoded without warnings.');
  } else {
    print('${result.status.name}: ${result.message}');
  }
}

Bytes are supported too:

final result = await validateBytes(bytes);

The asynchronous functions perform file I/O and decoding in a worker isolate. The synchronous functions run on the caller's isolate and can block a Flutter UI; use them only when that is intentional.

Limits

The defaults are designed to prevent unexpectedly expensive inputs:

• encoded input: 64 MiB;
• decoded dimensions: 100,000,000 pixels;
• whole operation: 30 seconds.

Override or disable them explicitly:

final options = JpegValidationOptions(
  maxInputBytes: 8 * 1024 * 1024,
  maxPixels: 24 * 1000 * 1000,
  timeout: const Duration(seconds: 10),
);

final noLimits = JpegValidationOptions(
  maxInputBytes: null,
  maxPixels: null,
  timeout: null,
);

Non-null byte and pixel limits must be positive. A timeout may be zero but not negative. Invalid option construction is the only API misuse that throws ArgumentError; validation failures are returned as structured results.

Always branch on JpegValidationResult.status or isValid. message is diagnostic text and can change with decoder versions.

What is accepted

Every JPEG family supported warning-free by the bundled libjpeg-turbo 3.2.0 decompressor is accepted. Qualification covers baseline, progressive, arithmetic, lossless, grayscale, RGB, CMYK/YCCK, restart markers, ICC/EXIF metadata, 8/12/16-bit precision, tiny images, and data after a clean EOI.

Data after EOI is accepted because it is outside the completed JPEG datastream. Missing EOI, incomplete scanlines, malformed markers/tables/dimensions, progressive truncation, bad restart sequences, fatal decoder errors, and any decoder warning are rejected.

Decoder messages are suppressed on stderr and returned through message.

Comparison with evaluated packages

This comparison records the package versions evaluated on July 22, 2026. It describes those versions, not necessarily later releases. The alternatives are useful for their intended jobs.

Package evaluated	Intended use	Difference from jpeg_validator
image_validator 0.2.0	Lightweight validation of several image formats	In the evaluated source, its JPEG corruption check tests boundary signatures and a 1 KB minimum. It does not parse the complete JPEG or decode its pixels, and the size rule can reject valid tiny JPEGs.
libjpeg_turbo_dart 1.0.0	Pure-Dart libjpeg-compatible decoding	It is a capable pure-Dart implementation: it exposes the information needed for strict validation and passed all 31 classification cases. Its drawback in our macOS x64 release/AOT testing was performance: its benchmark bundle took 110.1 ms versus 16.4 ms for jpeg_validator, approximately 6.7x slower. It remains attractive when avoiding a native C build is more important than decode speed.

Choose jpeg_validator when “valid” must mean that the entire JPEG decodes without warnings, and when bounded resource use and actionable result statuses matter. Choose the alternatives when the primary requirement is encoding, image manipulation, broad format support, recoverable/tolerant decoding, or asset-layout linting.

The tradeoff is that jpeg_validator is JPEG-only, has no web implementation, and requires a native C toolchain during application builds.

Platforms and native build

Platform	Status
macOS	Supported and tested
Windows	Experimental preview; not officially supported or verified
Linux	Not supported
Web	Not supported

The package uses Dart code assets to compile a private, OS-neutral C ABI from vendored libjpeg-turbo source. Callers use the same Dart API on every desktop platform. A native C toolchain is required during application builds (Xcode Command Line Tools on macOS or Visual Studio C++ Build Tools on Windows).