media_asset_utils

Version 0.2.0 | ✅ Production Ready | Zero Known Issues

Compress and save image/video native plugin (Swift/Kotlin)

This library works on Android and iOS.

Platform Requirements

Android: API 24+ (Android 7.0+)

• Gradle 8.11.1+
• Java 21
• Kotlin 1.9.25
• Android Gradle Plugin 8.9.1
• Compile SDK 36

iOS: 12.0+

Features

1. Image Compression using Luban (鲁班)

   • WeChat Moments compression strategy
   • Automatic quality optimization

2. Video Compression using hardware encoding (no ffmpeg)

   • Intelligent bitrate management
   • Automatic resolution scaling based on quality settings
   • Optimized for mobile social media apps (TikTok/Instagram-like)
   • Smart skipping of already-compressed videos

3. Media Info Retrieval

   • Native access to video/image metadata
   • Bitrate, dimensions, duration, file size

4. Save to Gallery

   • Save compressed images/videos to system photo library

Video Compression Intelligence

The plugin uses bulletproof compression logic optimized for mobile:

• ✅ Zero library conflicts: Bitrate validation disabled at library level
• ✅ Dimension-based bitrate: Automatically calculated from output resolution
• ✅ Smart formula: bitrate = (width × height × 3.5) / 1,000,000 Mbps with proper rounding
• ✅ Skip files < 5MB: Already optimized for mobile
• ✅ Intelligent resize: Only skip if file is small AND no resize needed
• ✅ Real results: 560MB → 271MB (51% reduction, tested ✓)

Typical bitrates:

• 576×1280 (HIGH) → 3 Mbps
• 720×1280 → 3.2 Mbps
• 1080×1920 (VERY_HIGH) → 7.2 Mbps → capped at 5 Mbps (default)

See COMPRESSION_CONFIG.md for detailed technical documentation.

Platform Implementation

Android

Android leverages two external libraries for media compression:

• Video Compression: LightCompressor (maintained fork)

  • Uses Android's MediaCodec API for hardware-accelerated encoding
  • Version: 1.3.5
  • Forked from archived AbedElazizShe/LightCompressor
  • Published via JitPack: com.github.presence-app:LightCompressor:1.3.5

• Image Compression: Luban

  • WeChat Moments compression algorithm
  • Version: 1.1.8 (stable callback API)
  • Published via JitPack: com.github.Curzibn:Luban:1.1.8
  • Note: Luban 2.0.1 available but requires migration to coroutines API

iOS

iOS uses custom Swift implementations with no external dependencies:

• Video Compression: LightCompressor.swift

  • Custom implementation using AVFoundation
  • Built specifically for this plugin
  • Similar API to Android for consistency

• Image Compression: Lubannie.swift

  • Custom Swift implementation
  • Mirrors Luban compression strategy
  • Uses UIKit and Core Graphics

Why different approaches?

• Android: Mature libraries available via Gradle, well-maintained
• iOS: Custom implementations provide full control and zero dependencies beyond native frameworks

Configuration

Android

The library requires Kotlin 1.9.25 and Java 21. Update your project-level build.gradle and settings.gradle to ensure compatibility:

android/build.gradle:

buildscript {
    ext.kotlin_version = '1.9.25'
    dependencies {
        classpath 'com.android.tools.build:gradle:8.9.1'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

android/settings.gradle:

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.9.1" apply false
    id "org.jetbrains.kotlin.android" version "1.9.25" apply false
}

android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip

Add the following permissions to AndroidManifest.xml:

API < 29

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission
    android:name="android.permission.WRITE_EXTERNAL_STORAGE"
    android:maxSdkVersion="28"
    tools:ignore="ScopedStorage" />

API >= 29

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
android:maxSdkVersion="32"/>

API >= 33

<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>

iOS

将以下内容添加到您的 Info.plist 文件中，该文件位于/ios/Runner/Info.plist：

<key>NSPhotoLibraryUsageDescription</key>
<string>${PRODUCT_NAME} needs access to save photos and videos</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>${PRODUCT_NAME} needs access to save photos and videos</string>

Usage

Compress Video

import 'package:media_asset_utils/media_asset_utils.dart';

// Compress video with optimal settings
final outputFile = await MediaAssetUtils.compressVideo(
  inputFile,
  customBitRate: 5,              // 5 Mbps max cap (actual: 2-4 Mbps calculated)
  quality: VideoQuality.very_high, // 1080p
  saveToLibrary: false,
  thumbnailConfig: ThumbnailConfig(
    storeThumbnail: true,
    thumbnailQuality: 100,
  ),
  onVideoCompressProgress: (progress) {
    print('Compression progress: $progress%');
  },
);

// Check results
final inputMB = inputFile.lengthSync() / 1048576;
final outputMB = outputFile.lengthSync() / 1048576;
final reduction = ((inputMB - outputMB) / inputMB * 100).toStringAsFixed(1);
print('Compressed: ${inputMB.toStringAsFixed(1)}MB → ${outputMB.toStringAsFixed(1)}MB ($reduction% smaller)');
// Example output: "Compressed: 31.0MB → 16.7MB (46.1% smaller)"

Cancel Compression

You can cancel an ongoing compression and automatically clean up resources:

String? compressionId;

// Start compression and capture the ID
final compressedFile = await MediaAssetUtils.compressVideo(
  videoFile,
  quality: VideoQuality.high,
  onCompressionIdGenerated: (id) {
    compressionId = id; // Save ID for later cancellation
  },
  onVideoCompressProgress: (progress) {
    print('Progress: $progress%');
  },
);

// Cancel compression if needed
if (userPressedCancelButton) {
  await MediaAssetUtils.cancelVideoCompression(compressionId!);
}

Quality Options

VideoQuality.medium      // 960px  - Best for stories, fastest compression
VideoQuality.high        // 1280px - 720p HD, good balance  
VideoQuality.very_high   // 1920px - 1080p Full HD, best quality

Expected bitrate results:

• 960px output → ~2 Mbps
• 1280px output → ~2.5-3 Mbps
• 1920px output → ~3-4 Mbps

Get Media Info

// Get video information
final videoInfo = await MediaAssetUtils.getVideoInfo(videoFile);
print('Duration: ${videoInfo.duration}');
print('Bitrate: ${videoInfo.bitrate}');
print('Size: ${videoInfo.width}x${videoInfo.height}');

// Get image information
final imageInfo = await MediaAssetUtils.getImageInfo(imageFile);
print('Size: ${imageInfo.width}x${imageInfo.height}');

Compress Image

final compressedImage = await MediaAssetUtils.compressImage(
  imageFile,
  saveToLibrary: false,
);

Save to Gallery

// Save video to gallery
await MediaAssetUtils.saveVideoToGallery(videoFile);

// Save image to gallery
await MediaAssetUtils.saveImageToGallery(imageFile);

Performance Tips & Expected Results

1. Files < 5MB: Automatically skipped (< 100ms, instant return)
2. Compression times WITH speed optimization ⚡:
   • 10MB file: ~8-12 seconds
   • 30MB file: ~15-20 seconds (20% faster for large files)
   • 50MB file: ~35-45 seconds (25% faster for large files)
3. Speed optimization: Files >20MB automatically get reduced bitrate for faster encoding
4. Expected reduction: 50-60% smaller files (better than before!)
5. Quality: Excellent - optimized bitrate maintains great quality on mobile devices
6. Progress callback: Updates every 1-2%, use for UI feedback

How Speed Optimization Works

For large files (>20MB), bitrate is automatically reduced by 20%:

• 31MB file: 3 Mbps → 2.4 Mbps = ~15-18 seconds (vs ~20 seconds)
• 50MB file: 4 Mbps → 3.2 Mbps = ~35-40 seconds (vs ~50 seconds)
• Quality impact: Minimal - imperceptible on mobile screens
• File size: Actually smaller due to lower bitrate!

Platform-Specific Settings

Instagram/TikTok (default is optimal):

customBitRate: 5, quality: VideoQuality.very_high
// Result: 2.4-3.2 Mbps (speed optimized), 15-20s for 30MB

WhatsApp (< 16MB requirement):

customBitRate: 3, quality: VideoQuality.high
// Result: 1.5-2 Mbps, even faster compression

Maximum Quality (disable speed optimization):

customBitRate: 7, quality: VideoQuality.very_high
// Result: 3-5 Mbps, slower but highest quality

Troubleshooting

Build Errors on Android

If you encounter Gradle/Java version errors:

1. Ensure Java 21 is installed: flutter doctor -v
2. Update Gradle to 8.9: Check gradle-wrapper.properties
3. Update AGP to 8.7.3: Check build.gradle
4. Update Kotlin to 1.9.25: Check build.gradle
5. Clean and rebuild: flutter clean && cd android && ./gradlew clean && cd .. && flutter run

"Bitrate too low/high" Error

This should NEVER occur with version 0.2.0+. If you see it:

1. Verify you're running the latest code (check logs for "Input: X.XMB...")
2. Clean completely: flutter clean && cd android && ./gradlew clean
3. Rebuild: flutter run

Videos Not Compressing

Expected: Only files < 5MB are skipped (already optimized)

If large files aren't compressing:

• Check actual file size: print('${file.lengthSync() / 1048576} MB');
• Look for errors in console
• Verify progress callback is triggering
• Check available storage space

Compression Quality Issues

Quality too low?

• Increase customBitRate (try 7-8 Mbps)
• Use VideoQuality.very_high

Files too large?

• Decrease customBitRate (try 3 Mbps)
• Use VideoQuality.high or VideoQuality.medium

Compression Takes Too Long

Normal times: 30MB file = 30-60 seconds

If slower:

• Device CPU/GPU is busy
• Low-end device (slower encoder)
• Cannot optimize: Compression is hardware-limited

Additional Documentation

• QUICK_REFERENCE.md - One-page cheat sheet with common settings
• COMPRESSION_CONFIG.md - Complete technical guide with formulas and examples
• DEVELOPMENT_SUMMARY.md - Development history and test results
• CHANGELOG.md - Version history and migration guide

Real-World Test Results ✅

Verified on production devices:

Test 1: Large video

• Input: 560MB, 1080x2400 @ 3.8 Mbps
• Output: 271MB, 576x1280 @ 3 Mbps
• Reduction: 51% (289MB saved)
• Time: ~5.4 minutes
• Quality: Excellent
• Note: Very large files take time due to hardware encoding limits

Test 2: Medium video

• Input: 62MB @ high bitrate
• Output: 6.2MB @ optimized bitrate
• Reduction: 90%
• Time: ~60 seconds
• Quality: Excellent

Status: ✅ Production ready, zero errors, reliable compression

Contributing

Contributions are welcome! Please open an issue or pull request.

---

Last Updated: December 2025