flutter_compress #

One plugin to compress both video and images — on Android, iOS and Web — with no FFmpeg.

Every platform uses its own hardware-accelerated encoder, so output is fast, small, and native-quality — with no 20 MB FFmpeg binary, no GPL, and nothing extra to ship. And the API speaks intent — "make it ~10 MB", "half the bitrate", "under 200 KB" — instead of making you guess at opaque quality knobs.

中文文档见 README.zh-CN.md。

🌐 Try the live web demo in your browser →

Why flutter_compress? #

• 🪶 No FFmpeg, no GPL, no bloat — nothing to bundle beyond the OS encoders your users already have. Your app stays small and license-clean.
• 🌍 One API, three platforms — the same Dart code runs on Android, iOS and the browser (via WebCodecs). Most alternatives skip Web entirely.
• 🎯 Hit a target size, precisely — ask for a size and the plugin derives the bitrate with identical math on every platform.
• 🎬🖼️ Video and images — two dedicated, non-overlapping APIs (compress vs compressImage), each tuned for its medium.
• 📡 Production-ready — live progress, cancellation, sequential batching, and a keep-original-if-larger guard.
• 🧼 Declares no permissions — most compression plugins push a foreground-service notification (and its permissions) into every app that depends on them. Here background compression is opt-in and the notification is yours: your icon, your copy, your channel.
• 🚀 Presets for the common cases — forSocialMedia(), maxCompression(), forAvatar(); skip the tuning entirely.

Under the hood #

Features #

🎬 Video — compress #

• 🎯 Target size, or explicit bitrate, quality %, or preset tiers.
• 🧬 HEVC (H.265) with automatic H.264 fallback on all platforms.
• 📉 Resolution cap, frame-rate cap, audio removal, trim, ÷16 alignment.
• 🖼️ Thumbnails, media info, and a pre-flight size estimate (no encoding).
• 📡 Live progress, cancellation, and sequential batch.

🖼️ Image — compressImage #

• 🎯 Target size (precise — the engine iterates on quality, then downscales) or quality.
• 🎞️ Formats: JPEG · PNG · WebP · HEIC (auto-fallback where unsupported).
• 📐 Resolution cap and optional EXIF keep (orientation, GPS…).
• ⚡ Millisecond-fast, single-image or batch.
• 🧠 Compress bytes in memory (compressImageBytes) — no temp file for an image_picker result, a camera frame, or a download.

Platform support #

🎬 Video #

¹ Web uses HEVC only where the browser supports WebCodecs HEVC encoding (e.g. Safari, Chrome with HW HEVC); otherwise it falls back to H.264.

² Only iOS can decimate frames. Media3 has no frame-dropping effect, and the web pipeline re-encodes every decoded frame — on both, frameRate only influences the bitrate/keyframe maths. Read result.frameRate for what was actually written.

³ Media3 1.4.x exposes no audio-encoder settings, so Android encodes AAC at its own default. The value still shapes the targetSizeMB budget.

⁴ Android needs a foreground service, and its notification must be yours — pass androidNotification and declare FOREGROUND_SERVICE. Without either, the encode runs foreground-only; nothing throws. See Background compression on Android. iOS needs nothing (beginBackgroundTask: no UI, no permission).

Anything marked ❌ is ignored, not approximated — the result object reports what actually happened (result.frameRate, result.hasAudio, result.durationMs).

🖼️ Image #

¹ Android only writes HEIC when a device HEIC encoder is present; otherwise the engine falls back to JPEG (the actual format is reported on the result).

² Android copies 48 EXIF tags (camera, exposure, lens, GPS, timestamps) into JPEG output. iOS passes the source's metadata through wholesale. Web's canvas re-encode strips metadata entirely — there is no way around it.

Install #

dependencies:
  flutter_compress: ^2.0.0

Integrate with an AI assistant #

Point Claude Code, Cursor, Copilot or any LLM at llm-guide.md — the guide walks the assistant through the complete integration.

Read https://rawgit.flutter-io.cn/chenkaiHere/flutter_compress/master/llm-guide.md and add video compression to this screen.

Quick start #

import 'package:flutter_compress/flutter_compress.dart';

final result = await FlutterCompress.instance.compress(
  inputPath,
  const VideoCompressConfig(
    targetSizeMB: 10,          // highest-priority size control
    codec: VideoCodec.h265,    // auto-falls-back to H.264
    maxWidth: 1280,            // downscale-only
    maxHeight: 1280,
  ),
  onProgress: (p) => debugPrint('${(p.progress * 100).toStringAsFixed(0)}%'),
);

print('saved ${result.savedPercent.toStringAsFixed(1)}% → ${result.outputPath}');

Configuration #

VideoCompressConfig — set one size/quality control; priority is:

targetSizeMB → videoBitrateKbps → qualityPercent → quality

API #

final api = FlutterCompress.instance;

// Probe & estimate (no encoding)
final VideoInfo info = await api.getVideoInfo(path);
final CompressionEstimate est = await api.estimate(path, config);

// Compress (single)
final token = CancellationToken();
final result = await api.compress(
  path, config,
  onProgress: (p) => print(p.progress),   // 0.0–1.0
  cancellationToken: token,
  outputDirectory: dir,                    // optional
  outputName: 'my_clip',                   // optional; no extension → auto-added
);
await token.cancel();                      // aborts the job above

// Batch (sequential), thumbnails, housekeeping
await api.compressAll(paths, config);
final String thumb = await api.getThumbnail(path, positionMs: 1000, maxWidth: 320);
final String saved = await api.saveToDownloads(result.outputPath);
await api.releaseOutput(result.outputPath);  // frees one result (see below)
await api.clearCache();

// Global progress feed (e.g. for a batch UI)
api.progressStream.listen((p) => print('${p.id} ${p.progress}'));

Images #

The image API is fully separate from the video one.

final api = FlutterCompress.instance;

// Probe (no encoding)
final ImageMeta meta = await api.getImageInfo(path);

// Compress to a target size (precise — images encode fast, so the engine
// binary-searches quality, then downscales if needed to land under it).
// With no `format`, the output keeps the source's format.
final ImageCompressResult r = await api.compressImage(
  path,
  const ImageCompressConfig(
    targetSizeKB: 200,          // highest-priority size control
    maxWidth: 2560,             // downscale-only
    maxHeight: 2560,
  ),
  outputDirectory: dir,         // optional; null → plugin cache
  outputName: 'my_photo',       // optional; no extension → auto-added
);
print('${r.format} ${r.width}x${r.height} • saved ${r.savedPercent.toStringAsFixed(1)}%');

// Convert format, control quality, go lossless, or batch:
await api.compressImage(path, const ImageCompressConfig(format: ImageFormat.webp, quality: 80));
await api.compressImageLossless(path);   // keep source format, pixel-for-pixel

// Presets — no tuning needed.
await api.compressImage(path, const ImageCompressConfig.forAvatar());
await api.compressImage(path, const ImageCompressConfig.forSocialMedia());

// Already have the bytes? Skip the temp file entirely.
final ImageBytesResult b = await api.compressImageBytes(
  bytes,                                 // e.g. await xFile.readAsBytes()
  const ImageCompressConfig(targetSizeKB: 200),
);
uploadBytes(b.bytes);                    // nothing written to disk, nothing to release

// Batch with progress, cancellation, and per-file error tolerance:
final token = CancellationToken();
final results = await api.compressImages(
  paths,
  const ImageCompressConfig(targetSizeKB: 300),
  onItemDone: (i, total) => print('${i + 1}/$total'),
  cancellationToken: token,
  continueOnError: true,                  // a bad file won't discard the rest
  onItemError: (i, path, e) => print('skipped $path: $e'),
);

Errors #

Everything throws a typed exception — a raw PlatformException never escapes.

try {
  await api.compressImage(path, config);
} on CompressCancelled {
  // cancelled (video or image)
} on ImageCompressException catch (e) {
  if (e.code == CompressErrorCode.imageCompressFailed) { /* … */ }
} on CompressException catch (e) {
  // any other failure from either API
}

Match on CompressErrorCode rather than raw strings — the constants are mirrored on all three platforms, and the values are part of the public contract.

CompressException is the base; VideoCompressException / ImageCompressException narrow it, and CompressCancelled is a marker both cancel types implement.

ImageCompressConfig — priority is lossless → targetSizeKB → quality:

Platform setup #

• Android — min SDK 24, compileSdk 36. Declares no permissions. See Android permissions and Background compression.
• iOS — min 13.0. Uses beginBackgroundTask for a short background grace period. To make saveToDownloads files visible in the Files app, add UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace to Info.plist.
• Web — needs WebCodecs (Chrome/Edge 94+, Safari 16.4+). Inputs/outputs are blob: URLs; the vendored demux/mux JS (216 KB, see THIRD_PARTY_NOTICES) loads lazily on first video compression — image compression never fetches it. Pick a file via file_picker and pass xFile.path (a blob: URL on web). Call releaseOutput(result.outputPath) once you've downloaded or uploaded a result — the browser otherwise holds the whole encoded file in memory for the life of the page (clearCache() releases every output at once). Try the live demo to see it in action.

Android permissions #

This plugin declares no permissions. Compression is codec work on a file you already handed over; it needs none, and manifest merging would push anything declared here into every app that depends on the plugin.

The one thing it does declare is a <service> — a declaration, not a permission, so it has no bearing on store review. It has to be in the manifest for the class to be startable, and it is inert unless you both declare FOREGROUND_SERVICE and pass androidNotification. See Background compression.

The one exception worth knowing about: saveToDownloads() on Android 9 and below writes to the public Downloads folder directly and therefore needs the legacy permission. API 29+ goes through MediaStore and needs nothing.

<!-- Only if you call saveToDownloads() and support Android 9 or below. -->
<uses-permission
    android:name="android.permission.WRITE_EXTERNAL_STORAGE"
    android:maxSdkVersion="28" />

Without it, saveToDownloads() throws CompressErrorCode.permissionDenied with a message saying exactly this. The plugin never requests runtime permissions for you — when to ask the user is a product decision.

The example app declares zero permissions, which is the point: it compresses video and images with nothing granted.

Background compression on Android #

Android suspends work when your app leaves the foreground, so a long encode needs a foreground service — and a foreground service must show a notification. The plugin ships the service but supplies no notification of its own: the icon, wording and channel name are prominent UI that belongs to your app, not to a library.

So it is opt-in in two steps. Declare the permissions:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<!-- Optional, Android 13+ runtime permission. Without it the service still runs,
     the notification is just not shown. Request it with a permissions package. -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

…and pass the notification:

await FlutterCompress.instance.compress(
  path,
  const VideoCompressConfig(
    targetSizeMB: 10,
    androidNotification: AndroidNotification(
      smallIcon: 'drawable/ic_compress',   // your resource
      title: 'Compressing video',          // your copy, your localisation
      text: 'Tap to return to the app',
      channelName: 'Media processing',     // shown in system settings
    ),
  ),
);

smallIcon is "type/name" resolved against your resources ("mipmap/ic_launcher" works too; a bare "ic_compress" means "drawable/ic_compress").

No service starts unless all three hold, and a miss is never an error — the plugin logs and the encode continues foreground-only:

iOS needs none of this: the plugin requests a short background window with beginBackgroundTask, which shows no UI and needs no permission. androidNotification is ignored there and on web.

The service is visible in your APK

The <service> merges into your manifest, is compiled into the APK's binary AndroidManifest.xml, and is readable through PackageManager — so APK inspectors such as LibChecker list com.compress.all.flutter_compress.CompressionService, and can fingerprint this plugin from it. Nothing runs, but the name is there.

To trace any merged element back to whichever dependency added it:

<your-app>/build/app/outputs/logs/manifest-merger-<variant>-report.txt

Each entry names its origin, e.g. service#…CompressionService ADDED from [:flutter_compress].

If your app never wants background compression, drop the declaration — that removes it from the component listing too:

<service android:name="com.compress.all.flutter_compress.CompressionService"
    tools:node="remove" />

Native dependencies #

iOS and web add no third-party native dependencies: iOS uses AVFoundation and ImageIO from the SDK, web uses the browser's WebCodecs plus two vendored JS bundles (see THIRD_PARTY_NOTICES for sizes and licences).

Versions are pinned to the ones actually tested rather than floated. Gradle resolves conflicts upward, so an app declaring a newer Media3 still wins — but the plugin won't silently adopt one. (Media3 changed the meaning of a DefaultMuxer.Factory parameter inside its 1.x line once, which truncated every output to 30 seconds while compiling perfectly cleanly.)

Known limitations #

• Web (v1): audio is dropped and trim is not yet applied.

License #

MIT — see LICENSE.