### Install Ironpress Flutter Package

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Add the ironpress package to your Flutter project's dependencies in the pubspec.yaml file.

```yaml
dependencies:
  ironpress: ^0.1.0
```

--------------------------------

### Build Native Binaries from Source

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Commands to build the native Rust libraries for Android and Windows targets using the Rust toolchain.

```bash
# Prerequisites
cargo install cargo-ndk
rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android

# Build Android
cd rust
cargo ndk --target aarch64-linux-android --platform 21 build --release
cargo ndk --target armv7-linux-androideabi --platform 21 build --release
cargo ndk --target x86_64-linux-android --platform 21 build --release

# Build Windows
cargo build --release
```

--------------------------------

### Benchmarking Image Quality with Ironpress

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Explains how to run a quality sweep on images to find the optimal balance between file size and visual quality using benchmarkFile and benchmarkBytes.

```dart
import 'package:ironpress/ironpress.dart';

final bench = await Ironpress.benchmarkFile('/path/to/photo.jpg');
print('Recommended quality: ${bench.recommendedQuality}');

for (final entry in bench.entries) {
  print('q${entry.quality}: ${entry.sizeFormatted} (${entry.reductionPercent}, ${entry.encodeMs}ms)');
}

final result = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  quality: bench.recommendedQuality,
);
```

--------------------------------

### CompressException and Error Handling

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Demonstrates how to catch and handle various exceptions that can occur during image compression, including specific error codes and hints for troubleshooting. It also shows how to handle batch compression results, where individual failures do not halt the entire process.

```APIDOC
## CompressException and Error Handling

Exception thrown when native compression fails, with error codes and actionable hints for troubleshooting.

### Method
```dart
import 'package:ironpress/ironpress.dart';

try {
  final result = await Ironpress.compressFile('/nonexistent/path.jpg');
} on CompressException catch (e) {
  print('Error code: ${e.code}');
  print('Message: ${e.message}');
  print('Hint: ${e.hint}');

  // Error codes:
  // -1: Null pointer or missing input
  // -2: Invalid UTF-8 path or empty buffer
  // -3: Failed to read input file
  // -4: Failed to write output file
  // -5: Input exceeds 256 MB limit
  // -10: Compression engine error (unsupported format, corrupt data)
  // -99: Internal panic on batch item (other items unaffected)
  // -100: Batch isolate crashed unexpectedly
} on ArgumentError catch (e) {
  // Thrown for empty paths or invalid quality values (outside 0-100)
  print('Invalid argument: $e');
}

// Batch error handling - failures don't crash the batch
final batchResult = await Ironpress.compressBatch(inputs);

for (final r in batchResult.results) {
  if (!r.isSuccess) {
    print('Failed: ${r.errorMessage} (code: ${r.errorCode})');
  } else {
    print('Success: ${r.reductionPercent} reduction');
  }
}

print('${batchResult.successfulCount} succeeded, ${batchResult.failedCount} failed');
```
```

--------------------------------

### Using CompressPreset for Image Compression

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Illustrates the use of CompressPreset for applying predefined quality and dimension settings to image compression. Presets simplify common compression tasks, with the option to override specific parameters.

```dart
import 'package:ironpress/ironpress.dart';

// Low preset: social media, messaging (q65, max 1280px)
final lowResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  preset: CompressPreset.low,
);

// Medium preset: general uploads, in-app photos (q80, max 1920px)
final mediumResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  preset: CompressPreset.medium,
);

// High preset: archives, professional use (q92, no resize)
final highResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  preset: CompressPreset.high,
);

// Override specific preset values
final customResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  preset: CompressPreset.medium,
  maxWidth: 1280, // Override just this, keep q80 from preset
);

// Presets in batch compression
final batchResult = await Ironpress.compressBatch(
  inputs,
  preset: CompressPreset.low, // Apply to all images
);
```

--------------------------------

### Advanced JPEG and PNG Compression Options

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Demonstrates how to use JpegOptions and PngOptions for advanced control over image compression. JpegOptions allows tuning parameters like progressive encoding, trellis quantization, and chroma subsampling. PngOptions focuses on optimization levels for PNG compression.

```dart
import 'package:ironpress/ironpress.dart';

// Advanced JPEG options
final result = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  quality: 85,
  jpeg: const JpegOptions(
    progressive: true, // Progressive JPEG (smaller, loads progressively)
    trellis: true, // Trellis quantization - mozjpeg's key feature for smaller files
    chromaSubsampling: ChromaSubsampling.yuv420, // Best compression
  ),
);

// Disable trellis for faster encoding (larger output)
final fastResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  quality: 80,
  jpeg: const JpegOptions(
    trellis: false, // Faster but larger output
  ),
);

// High-quality JPEG with no chroma loss
final hqResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  quality: 95,
  jpeg: const JpegOptions(
    chromaSubsampling: ChromaSubsampling.yuv444, // No chroma loss, larger files
  ),
);

// PNG optimization options
final pngResult = await Ironpress.compressFile(
  '/path/to/image.png',
  format: CompressFormat.png,
  png: const PngOptions(
    optimizationLevel: 2, // 0-6, higher = slower but smaller
  ),
);

// Maximum PNG compression (slow)
final maxPngResult = await Ironpress.compressFile(
  '/path/to/image.png',
  format: CompressFormat.png,
  png: const PngOptions(optimizationLevel: 6),
);
```

--------------------------------

### Selecting Output Format with CompressFormat

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Shows how to specify the output image format using CompressFormat. Supports JPEG, PNG, WebP lossy, and WebP lossless. The 'auto' option preserves the original input format.

```dart
import 'package:ironpress/ironpress.dart';

// Keep original format (default)
final autoResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  format: CompressFormat.auto,
);

// Convert to JPEG
final jpegResult = await Ironpress.compressFile(
  '/path/to/image.png',
  format: CompressFormat.jpeg,
  quality: 85,
);

// Convert to lossless PNG
final pngResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  format: CompressFormat.png,
);

// Convert to WebP lossy (often smaller than JPEG at same quality)
final webpLossyResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  format: CompressFormat.webpLossy,
  quality: 80,
);

// Convert to WebP lossless (typically 25-35% smaller than PNG)
final webpLosslessResult = await Ironpress.compressFile(
  '/path/to/screenshot.png',
  format: CompressFormat.webpLossless,
);
```

--------------------------------

### Batch Image Compression with Ironpress

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Demonstrates how to perform parallel image compression using Ironpress.compressBatch. It covers progress tracking, cancellation tokens, and handling mixed input sources like file paths and raw bytes.

```dart
import 'package:ironpress/ironpress.dart';

final token = CancellationToken();

final result = await Ironpress.compressBatch(
  photos.map((path) => CompressInput(path: path)).toList(),
  preset: CompressPreset.medium,
  maxFileSize: 300 * 1024,
  threadCount: 4,
  chunkSize: 8,
  onProgress: (completed, total) {
    setState(() => _progress = completed / total);
    print('Progress: $completed / $total');
  },
  cancellationToken: token,
);

if (result.hasFailures) {
  print('${result.failedCount} images failed');
}

final mixedInputs = [
  CompressInput(path: '/photos/image1.jpg', outputPath: '/output/image1.jpg'),
  CompressInput(data: imageBytes, outputPath: '/output/image2.jpg'),
  CompressInput(path: '/photos/image3.png'),
];

final mixedResult = await Ironpress.compressBatch(
  mixedInputs,
  quality: 80,
);
```

--------------------------------

### Handle Compression Exceptions and Batch Results in Dart

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Demonstrates how to catch specific CompressException errors during file compression and how to iterate through batch processing results to identify individual successes and failures.

```dart
import 'package:ironpress/ironpress.dart';

try {
  final result = await Ironpress.compressFile('/nonexistent/path.jpg');
} on CompressException catch (e) {
  print('Error code: ${e.code}');
  print('Message: ${e.message}');
  print('Hint: ${e.hint}');
} on ArgumentError catch (e) {
  print('Invalid argument: $e');
}

final batchResult = await Ironpress.compressBatch(inputs);
for (final r in batchResult.results) {
  if (!r.isSuccess) {
    print('Failed: ${r.errorMessage} (code: ${r.errorCode})');
  } else {
    print('Success: ${r.reductionPercent} reduction');
  }
}
```

--------------------------------

### Probe Metadata and Benchmark Quality

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Shows how to read image metadata without decoding pixels and how to run a quality benchmark to find the optimal compression settings for a specific image.

```dart
// Read image metadata without decoding pixels
final probe = await Ironpress.probeFile('photo.jpg');
print(probe); // ImageProbe(3264x2448, JPEG, 4.2 MB, 7.99 MP)

// Find the optimal quality setting for your image
final bench = await Ironpress.benchmarkFile('photo.jpg');
print(bench.recommendedQuality); // e.g., 82
for (final entry in bench.entries) {
  print(entry); // q95: 520 KB (12.4%, 45ms)
}
```

--------------------------------

### Compress JPEG with Advanced Options

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Demonstrates how to compress an image file with specific quality settings and JPEG-specific optimizations like progressive encoding and trellis quantization.

```dart
final result = await Ironpress.compressFile(
  'photo.jpg',
  quality: 85,
  jpeg: const JpegOptions(
    progressive: true,
    trellis: true,
    chromaSubsampling: ChromaSubsampling.yuv420,
  ),
);
```

--------------------------------

### Ironpress.benchmarkFile

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Run a quality sweep on a file to determine the best size/quality trade-off.

```APIDOC
## POST /Ironpress.benchmarkFile

### Description
Encodes an image at multiple quality levels to generate a benchmark report.

### Method
POST

### Endpoint
Ironpress.benchmarkFile

### Parameters
#### Request Body
- **path** (String) - Required - Path to the image.
- **maxWidth** (int) - Optional - Constraint for benchmarking.

### Response
#### Success Response (200)
- **BenchmarkResult** (Object) - Contains entries for each quality level and a recommendedQuality value.
```

--------------------------------

### Migrate from flutter_image_compress

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

A comparison showing the syntax differences when migrating from the flutter_image_compress package to Ironpress.

```dart
// Before
final result = await FlutterImageCompress.compressWithFile(
  file.path,
  minWidth: 1920,
  minHeight: 1080,
  quality: 80,
);

// After
final result = await Ironpress.compressFile(
  file.path,
  maxWidth: 1920,
  maxHeight: 1080,
  quality: 80,
);
final bytes = result.data; // Same Uint8List
```

--------------------------------

### Define Input for Batch Compression (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Describes the input format for batch image compression. It requires either a file path or raw byte data, but not both. An optional output path can be specified; otherwise, the result is returned as bytes.

```dart
const CompressInput({
  String? path,        // File path (mutually exclusive with data)
  Uint8List? data,     // Raw bytes (mutually exclusive with path)
  String? outputPath,  // Output path. If null, result returned as bytes.
})
```

--------------------------------

### Apply Quality Presets for Compression in Dart

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Utilize predefined quality presets for common compression needs. These presets offer a balance between quality and file size for typical use cases.

```dart
final result = await Ironpress.compressFile(
  'photo.jpg',
  preset: CompressPreset.medium, // q80, max 1920px
);
```

--------------------------------

### Configure PNG Optimization Levels (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Specifies advanced PNG optimization settings. The primary option is the optimization level, which ranges from 0 (fastest, no optimization) to 6 (slowest, maximum compression). A balance is struck at level 2.

```dart
const PngOptions({int optimizationLevel = 2})
```

--------------------------------

### POST /compressBatch

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Processes multiple images in a batch with support for cancellation tokens and progress tracking.

```APIDOC
## POST /compressBatch

### Description
Processes a list of images in a batch operation. Supports cancellation via CancellationToken and progress callbacks.

### Method
POST

### Endpoint
/compressBatch

### Parameters
#### Request Body
- **inputs** (List) - Required - List of file paths to process.
- **preset** (CompressPreset) - Optional - Preset to apply to all images.
- **cancellationToken** (CancellationToken) - Optional - Token to abort the batch process.

### Request Example
{
  "inputs": ["/img1.jpg", "/img2.jpg"],
  "preset": "low"
}

### Response
#### Success Response (200)
- **results** (List) - List of processed image results.

#### Response Example
{
  "results": ["/out1.jpg", "/out2.jpg"]
}
```

--------------------------------

### Probing Image Metadata with Ironpress

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Shows how to extract image dimensions, format, and EXIF metadata without full decoding using probeFile and probeBytes. This is ideal for pre-upload validation.

```dart
import 'package:ironpress/ironpress.dart';

final info = await Ironpress.probeFile('/path/to/photo.jpg');
print('Dimensions: ${info.width}x${info.height}');

if (info.megapixels > 12) {
  await Ironpress.compressFile('/path/to/photo.jpg', preset: CompressPreset.medium);
}

final bytes = await File('photo.png').readAsBytes();
final bytesInfo = await Ironpress.probeBytes(bytes);
print('Image is ${bytesInfo.format.name} format');
```

--------------------------------

### Apply Built-in Compression Presets (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Utilizes predefined compression presets for common use cases like social media, general uploads, and archival. Each preset defines quality, minimum quality, and maximum dimension settings. Explicit parameters can override preset values.

```dart
// Use preset as-is
final result = await Ironpress.compressFile(
  'photo.jpg',
  preset: CompressPreset.medium,
);

// Override one field
final result = await Ironpress.compressFile(
  'photo.jpg',
  preset: CompressPreset.medium,
  maxWidth: 1280, // override just this
);
```

--------------------------------

### Retrieve Native Library Version

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Shows how to access the version string of the loaded native Rust library for debugging and verification purposes.

```dart
import 'package:ironpress/ironpress.dart';

print('Native library version: ${Ironpress.nativeVersion}');
```

--------------------------------

### POST /Ironpress/compressFile

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Compresses an image file from a given path and returns the compressed data as bytes along with processing statistics.

```APIDOC
## POST Ironpress.compressFile

### Description
Compress an image file and return the result as bytes. Supports various formats including JPEG, PNG, WebP, GIF, BMP, and TIFF.

### Method
POST

### Endpoint
Ironpress.compressFile

### Parameters
#### Request Body
- **path** (String) - Required - Absolute path to the input image.
- **preset** (CompressPreset?) - Optional - Quality preset.
- **quality** (int?) - Optional - JPEG/WebP quality 0–100.
- **maxWidth** (int?) - Optional - Maximum output width.
- **maxHeight** (int?) - Optional - Maximum output height.
- **maxFileSize** (int?) - Optional - Target maximum output size in bytes.
- **minQuality** (int?) - Optional - Quality floor for binary search.
- **allowResize** (bool) - Optional - Allow automatic downscaling.
- **format** (CompressFormat) - Optional - Output format.
- **keepMetadata** (bool) - Optional - Preserve JPEG EXIF metadata.

### Request Example
{
  "path": "/path/to/photo.jpg",
  "quality": 80
}

### Response
#### Success Response (200)
- **CompressResult** (Object) - Contains compressed bytes and processing stats.

#### Response Example
{
  "compressedSize": 389120,
  "width": 1920,
  "height": 1440
}
```

--------------------------------

### Retrieve Native Version

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Returns the version string of the underlying native library.

```dart
print(Ironpress.nativeVersion); // "0.1.0"
```

--------------------------------

### POST /Ironpress/compressFileToFile

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Compresses an image file and writes the output directly to the specified destination path on disk.

```APIDOC
## POST Ironpress.compressFileToFile

### Description
Compress an image file and write the result directly to disk. This method is memory-efficient as it does not return the image bytes.

### Method
POST

### Endpoint
Ironpress.compressFileToFile

### Parameters
#### Request Body
- **inputPath** (String) - Required - Absolute path to the source image.
- **outputPath** (String) - Required - Absolute path to the destination file.
- **preset** (CompressPreset?) - Optional - Quality preset.

### Request Example
{
  "inputPath": "/input/photo.jpg",
  "outputPath": "/output/photo_compressed.jpg",
  "preset": "medium"
}

### Response
#### Success Response (200)
- **CompressResult** (Object) - Contains processing stats; data field is null.

#### Response Example
{
  "compressedSize": 389120,
  "isFileOutput": true
}
```

--------------------------------

### Cancelling Batch Compression with CancellationToken

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Demonstrates how to use CancellationToken to cancel ongoing batch compression operations. When cancelled, the operation returns results for completed chunks, and the token can be checked for its cancellation state.

```dart
import 'package:ironpress/ironpress.dart';

final token = CancellationToken();

// Start batch compression
final future = Ironpress.compressBatch(
  inputs,
  preset: CompressPreset.medium,
  cancellationToken: token,
  onProgress: (done, total) => print('$done / $total'),
);

// Cancel after 5 seconds
Future.delayed(Duration(seconds: 5), () {
  print('Cancelling...');
  token.cancel();
});

// Result contains partial results for completed chunks
final result = await future;
print('Completed ${result.results.length} of ${inputs.length} before cancellation');

// Check cancellation state
if (token.isCancelled) {
  print('Operation was cancelled');
}

// Reset token for reuse
token.reset();
```

--------------------------------

### Configure JPEG Compression Options (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Defines advanced JPEG encoding options such as progressive encoding, chroma subsampling, and trellis quantization. These options allow fine-tuning of compression for file size and quality. Defaults are provided for common use cases.

```dart
const JpegOptions({
  bool progressive = true,
  ChromaSubsampling chromaSubsampling = ChromaSubsampling.yuv420,
  bool trellis = true,
})
```

--------------------------------

### Benchmark Image Quality and Performance

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Performs a quality sweep on an image to determine the optimal size-to-quality trade-off. Returns a BenchmarkResult containing metrics for various quality levels.

```dart
final bench = await Ironpress.benchmarkFile('/path/to/photo.jpg');
print(bench.recommendedQuality); // e.g., 78

for (final entry in bench.entries) {
  print(entry); // q95: 1.2 MB (70.5%, 210ms)
}
```

--------------------------------

### POST /compressFile

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Compresses a single image file with support for custom JPEG/PNG encoding options, presets, and format conversion.

```APIDOC
## POST /compressFile

### Description
Compresses an image file based on provided quality settings, format, and encoding options.

### Method
POST

### Endpoint
/compressFile

### Parameters
#### Request Body
- **path** (String) - Required - The file system path to the image.
- **quality** (int) - Optional - Compression quality (0-100).
- **preset** (CompressPreset) - Optional - Built-in quality configuration.
- **format** (CompressFormat) - Optional - Target output format (JPEG, PNG, WebP).
- **jpeg** (JpegOptions) - Optional - Advanced mozjpeg settings.
- **png** (PngOptions) - Optional - PNG optimization level.

### Request Example
{
  "path": "/path/to/photo.jpg",
  "quality": 85,
  "jpeg": {
    "progressive": true,
    "trellis": true
  }
}

### Response
#### Success Response (200)
- **result** (Object) - The compressed image data or file path.

#### Response Example
{
  "status": "success",
  "path": "/path/to/output.jpg"
}
```

--------------------------------

### Compress Image File to Disk

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Compresses an image file and writes the output directly to a destination path on disk. This approach is memory-efficient as it avoids loading the compressed output into RAM.

```dart
import 'package:ironpress/ironpress.dart';

final result = await Ironpress.compressFileToFile(
  '/input/photo.jpg',
  '/output/photo_compressed.jpg',
  preset: CompressPreset.medium,
);

final targetResult = await Ironpress.compressFileToFile(
  '/input/large_photo.jpg',
  '/output/optimized.jpg',
  maxFileSize: 500 * 1024,
  quality: 85,
);
```

--------------------------------

### Batch Compress Images with Thread Management

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Processes multiple images in parallel using Rust's rayon thread pool. Includes support for progress tracking, cancellation tokens, and memory-safe chunking.

```dart
final token = CancellationToken();

final result = await Ironpress.compressBatch(
  photos.map((p) => CompressInput(path: p)).toList(),
  preset: CompressPreset.medium,
  maxFileSize: 300 * 1024,
  threadCount: 4,
  onProgress: (done, total) {
    setState(() => _progress = done / total);
  },
  cancellationToken: token,
);

print(result);
```

--------------------------------

### Ironpress.compressBatch

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Batch compress multiple images using Rust's rayon thread pool for high-performance parallel processing.

```APIDOC
## POST /Ironpress.compressBatch

### Description
Processes multiple images in parallel using a thread pool. Designed to keep the UI responsive while handling large batches.

### Method
POST

### Endpoint
Ironpress.compressBatch

### Parameters
#### Request Body
- **inputs** (List<CompressInput>) - Required - List of image paths or data.
- **threadCount** (int) - Optional - Number of threads (default 0 = auto).
- **chunkSize** (int) - Optional - Images processed per chunk (default 8).
- **onProgress** (Function) - Optional - Callback for (completed, total) progress.

### Request Example
{
  "inputs": [{"path": "img1.jpg"}, {"path": "img2.jpg"}],
  "threadCount": 4
}

### Response
#### Success Response (200)
- **result** (BatchCompressResult) - Summary of the batch operation including reduction statistics.
```

--------------------------------

### Compress Image File to Memory

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Compresses an image file from a given path and returns the result as bytes in memory. This method supports quality presets, dimension constraints, and automatic binary search for target file sizes.

```dart
import 'package:ironpress/ironpress.dart';

final result = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  quality: 80,
);

final targetResult = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  maxFileSize: 200 * 1024,
  maxWidth: 1920,
  minQuality: 30,
  allowResize: true,
);
```

--------------------------------

### Implement CancellationToken for Batch Compression

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Demonstrates how to use the CancellationToken to interrupt long-running batch compression tasks in Ironpress. The token allows for asynchronous cancellation via the cancel() method.

```dart
final token = CancellationToken();

final future = Ironpress.compressBatch(
  inputs,
  cancellationToken: token,
);

// Cancel after 5 seconds
Future.delayed(Duration(seconds: 5), () => token.cancel());

final result = await future; // Contains partial results
```

--------------------------------

### Handle Native CompressException

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Defines the structure for exceptions thrown by the underlying Rust engine, including error codes and descriptive messages.

```dart
class CompressException implements Exception {
  final int code;      // Native error code
  final String message; // Human-readable message
}
```

--------------------------------

### Basic File Compression in Dart

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Compress a single image file using Ironpress. This function takes the file path and an optional quality setting, returning compression details.

```dart
import 'package:ironpress/ironpress.dart';

final result = await Ironpress.compressFile(
  'photo.jpg',
  quality: 80,
);
print(result);
// CompressResult(4.2 MB -> 380.0 KB [91.0%], 4000x3000, q80, 1iter)
```

--------------------------------

### Interpret Compression Results (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Provides detailed statistics for a single image compression operation. Includes original and compressed sizes, dimensions, quality used, and resizing information. Computed properties offer easy access to compression ratio and success status.

```dart
// Compressed bytes. `null` when output was written to file via `compressFileToFile`.
Uint8List? data,
// Original input size in bytes.
int originalSize,
// Compressed output size in bytes.
int compressedSize,
// Final image width in pixels.
int width,
// Final image height in pixels.
int height,
// Actual quality used. May differ from requested if `maxFileSize` was set.
int qualityUsed,
// Number of compression iterations (1 if no `maxFileSize`).
int iterations,
// Whether the image was auto-resized to meet the file size target.
bool resizedToFit,
// Error code for failed batch items. `null` for success.
int? errorCode,
// Error message for failed batch items. `null` for success.
String? errorMessage
```

--------------------------------

### Compress Image File to File - Dart

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Compresses an image file and writes the output directly to a specified file path. This method is efficient for large files as it avoids loading the entire compressed image into memory. It accepts the same compression parameters as `compressFile`. Input is source and destination file paths, output is a CompressResult object with statistics, and the compressed data is saved to disk.

```dart
import 'package:ironpress/ironpress.dart';

final result = await Ironpress.compressFileToFile(
  '/input/photo.jpg',
  '/output/photo_compressed.jpg',
  preset: CompressPreset.medium,
);
assert(result.isFileOutput); // true — no bytes in memory
print('Saved ${result.compressedSize} bytes to disk');
```

--------------------------------

### Ironpress.nativeVersion

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Retrieves the version string of the loaded native Rust library. This is useful for debugging and verifying that the correct version of the native library is being used.

```APIDOC
## Ironpress.nativeVersion

Returns the version string of the loaded native Rust library, useful for debugging and verifying correct library loading.

### Method
```dart
import 'package:ironpress/ironpress.dart';

// Get native library version
print('Native library version: ${Ironpress.nativeVersion}');
// Output: 0.1.0
```
```

--------------------------------

### Ironpress.probeFile

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Read image metadata such as dimensions, format, and EXIF presence from a file without decoding the pixel data.

```APIDOC
## GET /Ironpress.probeFile

### Description
Efficiently retrieves image metadata from a file path without full decoding.

### Method
GET

### Endpoint
Ironpress.probeFile

### Parameters
#### Query Parameters
- **path** (String) - Required - File system path to the image.

### Response
#### Success Response (200)
- **ImageProbe** (Object) - Contains width, height, format, file size, and EXIF status.
```

--------------------------------

### Compress Image to Target File Size in Dart

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Compress an image to a specific maximum file size. Ironpress performs a binary search within Rust to achieve the target size efficiently.

```dart
final result = await Ironpress.compressFile(
  'photo.jpg',
  maxFileSize: 200 * 1024, // 200 KB
);
print('Quality: ${result.qualityUsed}, Iterations: ${result.iterations}');
```

--------------------------------

### Compress Image File to Bytes - Dart

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Compresses an image file from a given path and returns the compressed data as bytes. It supports various image formats and allows for detailed control over compression quality, dimensions, and target file size. Dependencies include the 'ironpress' Flutter plugin. Input is a file path, output is a CompressResult object containing compressed bytes and statistics.

```dart
import 'package:ironpress/ironpress.dart';

// Simple compression
final result = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  quality: 80,
);
print(result);
// CompressResult(4.2 MB → 380 KB [91%], 1920x1440, q80, 1iter)

// Target file size — binary search runs entirely in Rust
final result = await Ironpress.compressFile(
  '/path/to/photo.jpg',
  maxFileSize: 200 * 1024, // 200 KB
  maxWidth: 1920,
);
```

--------------------------------

### Aggregate Batch Compression Results (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Summarizes the outcome of a batch compression operation. It contains a list of individual results and the total time elapsed. Computed properties provide insights into overall success rates, throughput, and total data processed.

```dart
// Individual results, one per input.
List<CompressResult> results,
// Total wall-clock time (measured in Rust, excludes FFI overhead).
int elapsedMs
```

--------------------------------

### Compress Image Bytes with Ironpress

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Compresses raw image bytes in memory, supporting multiple formats like JPEG, PNG, and WebP. It throws an ArgumentError if data is empty or a CompressException if the native engine fails.

```dart
final bytes = await File('photo.jpg').readAsBytes();

final result = await Ironpress.compressBytes(
  bytes,
  quality: 80,
);

// Convert to WebP
final webpResult = await Ironpress.compressBytes(
  bytes,
  format: CompressFormat.webpLossy,
  quality: 80,
);
```

--------------------------------

### Parallel Batch Image Compression in Dart

Source: https://github.com/rickyirfandi/ironpress/blob/master/README.md

Compress multiple images concurrently using Ironpress's batch compression feature. It supports progress callbacks, cancellation tokens, and parallel processing across cores.

```dart
import 'package:ironpress/ironpress.dart';

final token = CancellationToken();

final batch = await Ironpress.compressBatch(
  photos.map((p) => CompressInput(path: p)).toList(),
  maxFileSize: 300 * 1024,
  maxWidth: 1920,
  threadCount: 4,
  onProgress: (done, total) => setState(() => progress = done / total),
  cancellationToken: token,
);

print(batch);
// BatchCompressResult(198/200 ok, 2 failed, 6823ms, 29.3 img/s, 4.1 MB/s)
```

--------------------------------

### Define JPEG Chroma Subsampling Modes (Dart)

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Enumerates the available modes for JPEG chroma subsampling. This affects the balance between compression ratio and color fidelity. Options include 4:2:0 (best compression), 4:2:2 (balanced), and 4:4:4 (no color loss).

```dart
enum ChromaSubsampling {
  yuv420, // 4:2:0 — best compression, slight color loss (default)
  yuv422, // 4:2:2 — balanced
  yuv444, // 4:4:4 — no chroma loss, larger files
}
```

--------------------------------

### Probe Image Metadata

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Extracts image dimensions, format, and EXIF data from a file or byte array without decoding the pixel data, which is highly efficient for large images.

```dart
final info = await Ironpress.probeFile('/path/to/photo.jpg');
print(info); // ImageProbe(4000x3000, JPEG, 4.2 MB, 12.0MP, EXIF)

if (info.megapixels > 12) {
  await Ironpress.compressFile(path, preset: CompressPreset.medium);
}
```

--------------------------------

### Compress Raw Image Bytes

Source: https://context7.com/rickyirfandi/ironpress/llms.txt

Compresses raw image data already loaded in memory. This is ideal for processing images retrieved from network requests or existing byte buffers, supporting various output formats including WebP and PNG.

```dart
import 'dart:io';
import 'package:ironpress/ironpress.dart';

final bytes = await File('photo.jpg').readAsBytes();

final result = await Ironpress.compressBytes(
  bytes,
  quality: 80,
);

final webpResult = await Ironpress.compressBytes(
  bytes,
  format: CompressFormat.webpLossy,
  quality: 80,
);
```

--------------------------------

### Ironpress.compressBytes

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

Compress raw image bytes in memory. Supports JPEG, PNG, WebP, GIF, BMP, or TIFF input.

```APIDOC
## POST /Ironpress.compressBytes

### Description
Compresses raw image bytes directly in memory. Useful for handling image data already loaded into memory.

### Method
POST

### Endpoint
Ironpress.compressBytes

### Parameters
#### Request Body
- **data** (Uint8List) - Required - The raw image bytes to compress.
- **quality** (int) - Optional - Compression quality (0-100).
- **format** (CompressFormat) - Optional - Target output format.

### Request Example
{
  "data": "[Uint8List]",
  "quality": 80,
  "format": "webpLossy"
}

### Response
#### Success Response (200)
- **result** (CompressResult) - The compressed image data and metadata.

#### Response Example
{
  "size": 102400,
  "format": "webp"
}
```

--------------------------------

### Define CancellationToken Interface

Source: https://github.com/rickyirfandi/ironpress/blob/master/API.md

The structure of the CancellationToken class used to manage task lifecycle and cancellation state.

```dart
class CancellationToken {
  bool get isCancelled;  // Whether cancellation was requested
  void cancel();         // Request cancellation
  void reset();          // Reset for reuse
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.