pixel_compressor library

Native image and video compression for Flutter — resizing, format conversion, rotation and EXIF handling, target-size compression, thumbnail generation, media metadata, batch processing with progress and cancellation, capability detection, and cache management.

All processing happens on-device via platform codecs (MediaCodec/MediaMuxer on Android, AVFoundation/VideoToolbox/ ImageIO on iOS/macOS) — nothing is ever uploaded anywhere.

Entry point is the PixelCompressor facade:

final result = await PixelCompressor.image.compress(
  MediaSource.file(file),
  options: const ImageCompressOptions(quality: 80, maxWidth: 1920),
);

Classes

BatchItemResult: The outcome of one item inside a PixelCompressor.image or PixelCompressor.video compressBatch call. Exactly one of result or error is non-null — a batch keeps going after a per-item failure rather than aborting the whole job.
BatchResult: The aggregate outcome of a batch compression job.
CacheManager: Management of pixel_compressor's own output cache directory — reachable as PixelCompressor.cache. Only applies to results written without an explicit outputPath.
Capabilities: A snapshot of which codecs this device can encode with, and the largest resolution its hardware encoder supports.
CapabilityChecker: Device codec capability detection — reachable as PixelCompressor.capabilities.
CompressionResult: The outcome of a successful image or video compression.
ImageCompressOptions: Settings for PixelCompressor.image compression.
ImageCompressor: Image compression — reachable as PixelCompressor.image.
ImageMerger: Pure-Dart image merging (vertical/horizontal stitching) — reachable as PixelCompressor.merge. Unlike every other concern on the facade, this does no native platform-channel work: it's dart:ui Canvas drawing entirely on the Dart side, and only ever produces PNG bytes (dart:ui has no built-in JPEG/WebP/HEIC encoder). To get another format or hit a target file size, pipe the PNG through PixelCompressor.image.compress:
MediaInfo: Metadata read from a source file without compressing it — dimensions, duration, codecs, EXIF presence, etc.
MediaSource: Where a compression input comes from.
MergeCaptureController: Captures a PNG snapshot of the MergeView this controller is attached to. Create one, pass it to MergeView.controller, then call capturePng after the widget has rendered at least one frame (e.g. from a button's onPressed, not initState).
MergeOptions: Settings for PixelCompressor.merge — combining 2+ images into one.
MergeResult: The outcome of a successful PixelCompressor.merge call.
MergeView: Live, on-screen preview of a PixelCompressor.merge-style layout, built from a real Column/Row instead of dart:ui canvas drawing. Has no Material dependency, so it embeds in Material or Cupertino apps alike.
MetadataReader: Media metadata reads — reachable as PixelCompressor.metadata.
PixelCompressor: Single entry point for every pixel_compressor feature, grouped by concern:
ProgressEvent: A progress update for one compression/thumbnail task, identified by taskId so a single global stream (see PixelCompressor.progressStream) can be filtered down to the task a caller cares about.
TaskManager: Cancellation and inspection of in-flight tasks — reachable as PixelCompressor.tasks. The taskId comes from the onProgress events a compress/compressBatch call reports.
ThumbnailGenerator: Video thumbnail generation — reachable as PixelCompressor.thumbnails.
ThumbnailOptions: Settings for PixelCompressor.thumbnails generation.
ThumbnailResult: One generated thumbnail frame.
VideoCompressOptions: Settings for PixelCompressor.video compression.
VideoCompressor: Video compression — reachable as PixelCompressor.video.

Enums

CacheKind: The plugin-owned cache subtree kinds, each a subdirectory under the resolved cache root — matches the native CacheKind/Kind naming exactly (Android's CacheManager.kt, iOS/macOS's CacheManager.swift), since those directories are shared: whichever engine (Dart or native) wrote a file, CacheManager.size/CacheManager.clear account for it.
CodecSupportStatus: Whether a codec or format is available on the current device.
CompressionMode: How a VideoCompressOptions request picks its encoder settings.
CompressionStage: Where a compression task currently is, reported on every ProgressEvent.
ExifPolicy: What to do with EXIF metadata during image compression.
ImageFormat: Output image formats. Not every format is supported on every platform — check PixelCompressor.capabilities before relying on WebP or HEIC.
MediaType: What kind of media a source file was detected as.
MergeAlignment: Cross-axis placement of an image within the merged canvas — only visible when MergeOptions.scaleToFit is false and a source is narrower/shorter than the canvas's shared cross-axis size.
MergeDirection: How images are stitched together by PixelCompressor.merge.
QualityPreset: A named quality/bitrate tradeoff for CompressionMode.smart video compression — the native side picks concrete encoder settings for you.
TaskOutcome: How a compression task ended.
VideoCodec: Output video codec.

Exceptions / Errors

CompressionCancelledException: The task was cancelled before it completed.
DecodingException: The native decoder failed to read the source media.
EncodingException: The native encoder failed, or produced an empty/missing output file.
InsufficientStorageException: There wasn't enough free disk space to write the output file.
InvalidMediaException: The source file couldn't be parsed as valid media, or a request parameter is out of range for the given source (e.g. a thumbnail position past the end of a video).
MetadataException: Reading or writing media metadata (EXIF, container info) failed.
PermissionDeniedException: The source path couldn't be opened due to a permissions error.
PixelCompressorException: Base type for every exception this package throws.
PlatformNotSupportedException: The requested operation isn't supported on the current platform (e.g. video compression on Web).
TargetSizeException: A targetSizeBytes request could not be satisfied even after every fallback (resolution stepping, bitrate clamping) was exhausted.
UnknownPixelCompressorException: An error was reported with a code this package doesn't recognize — should not normally happen, but kept as a safety net instead of crashing the mapping layer on an unexpected code.
UnsupportedCodecException: The requested codec (e.g. HEVC, WebP encode) isn't available on this device or platform.
UnsupportedMediaException: The input file is not an image or video format this package can read.

pixel_compressor library

Classes

Enums

Exceptions / Errors

pixel_compressor package

pixel_compressor library