file_saver_ffi 0.3.1

file_saver_ffi: ^0.3.1 copied to clipboard

File Saver FFI #

A high-performance file saver for Flutter using FFI and JNI. Effortlessly save to gallery (images/videos) or device storage with original quality and custom album support.

Features #

• 🖼️ Gallery Saving – Save images and videos to iOS Photos or Android Gallery with custom albums
• ⚡ Native Performance – Powered by FFI (iOS) and JNI (Android) for near-zero latency
• 📁 Universal Storage – Save any file type (PDF, ZIP, DOCX, etc.) to device storage
• 💾 Original Quality – Files saved bit-for-bit without compression or metadata loss
• 📊 Progress & Cancellation – Real-time progress tracking with cancellable operations
• ⚙️ Conflict Resolution – Auto-rename, overwrite, skip, or fail on existing files

If you want to say thank you, star us on GitHub or like us on pub.dev.

🤖 Ask AI About This Library #

Have questions about file_saver_ffi? Get instant AI-powered answers about the library's features, usage, and best practices.

→ Chat with AI Documentation Assistant

Ask anything like:

• "How do I save a video to the gallery with progress tracking?"
• "What's the difference between saveBytes and saveFile?"
• "How to handle permission errors on Android 10+?"
• "Show me examples of custom file types"

Installation #

First, follow the package installation instructions and add file_saver_ffi to your app.

Quick Start #

Platform Setup #

<!-- Only required for Android 9 (API 28) and below -->
<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="28"/>

<!-- For Photos Library Access (images/videos) -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app needs permission to save photos and videos to your library</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs permission to access your photo library</string>

<!-- Prevent automatic "Select More Photos" prompt on iOS 14+ -->
<key>PHPhotoLibraryPreventAutomaticLimitedAccessAlert</key>
<true/>

<!-- Optional: Make files visible in Files app -->
<key>UIFileSharingEnabled</key>
<true/>

<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

Basic Usage #

import 'package:file_saver_ffi/file_saver_ffi.dart';

try {
  // Save image bytes
  final uri = await FileSaver.instance.saveAsync(
    fileBytes: SaveBytesInput(imageBytes),
    fileName: 'my_image',
    fileType: ImageType.jpg,
  );

  print('Saved to: $uri');
} on PermissionDeniedException catch (e) {
  print('Permission denied: ${e.message}');
} on FileSaverException catch (e) {
  print('Save failed: ${e.message}');
}

Core Concepts #

Unified API #

The library provides a single, consistent API for all save operations using SaveInput polymorphism:

• save: Stream-based save to standard location (Downloads, Photos, etc.).
• saveAsync: Future-based save to standard location.
• saveAs: Stream-based save to a user-selected location (System Picker).
• saveAsAsync: Future-based save to a user-selected location.

Input Sources (SaveInput)

Use the appropriate input class for your data source:

Usage Matrix 📊

Standard Location: defined enum (e.g., Downloads, Photos). User-Chosen: via pickDirectory() or auto-prompt.

User-Selected Location (Save As) #

Sometimes you want the user to choose where to save the file.

• pickDirectory(): Opens the system directory picker (Android SAF / iOS Document Picker) and returns a persistent permission URI (Android) or URL (iOS).
• saveAs() / saveAsAsync(): Saves a file to a user-selected location. If no location is provided, it automatically prompts the user to pick one.

Note: On Android, this uses the Storage Access Framework (SAF), which allows your app to write to arbitrary locations (SD cards, USB drives, etc.) without standard storage permissions.

File Types #

The library supports 35+ file formats across 4 categories:

Save Locations #

Control where files are saved using platform-specific enum values:

Android (AndroidSaveLocation)

iOS (IosSaveLocation)

iOS Photos Permission Behavior:

When saving to Photos Library, the permission level requested depends on the subDir parameter:

subDir	Permission Requested	Dialog Options (iOS 14+)	Capabilities
"MyAlbum"	.readWrite	Full Access / Limited Access / Don't Allow	Album creation, conflict resolution
null	.addOnly	Allow / Don't Allow	Basic save only (no album)

If the user denies .readWrite, the save will fail — there is no automatic fallback to .addOnly, as iOS treats a .readWrite denial as a full denial of Photos access.

Conflict Resolution #

Handle existing files with 4 strategies:

* Platform limitations:

• iOS Photos: Can only overwrite files owned by your app
• Android 10+: Can only overwrite files owned by your app (scoped storage)

Common Use Cases #

Download video from Network to Gallery #

final uri = await FileSaver.instance.saveAsync(
  input: SaveNetworkInput(
    url: 'https://example.com/video.mp4',
    headers: {'Authorization': 'Bearer token'}, // Optional headers
    timeout: Duration(minutes: 5), // Custom timeout
  ),
  fileName: 'downloaded_video',
  fileType: VideoType.mp4,
  saveLocation: Platform.isAndroid
    ? AndroidSaveLocation.movies
    : IosSaveLocation.photos,
);

Progress Tracking #

// Using Unified API
await FileSaver.instance.saveAsync(
  input: SaveNetworkInput(url: '...'),
  fileName: 'video',
  fileType: VideoType.mp4,
  onProgress: (progress) {
    print('Download progress: ${(progress * 100).toInt()}%');
  },
);

Cancellation #

// Stream API allows cancellation
final subscription = FileSaver.instance.save(
  input: SaveNetworkInput(url: '...'), // Works for all inputs
  fileName: 'video',
  fileType: VideoType.mp4,
).listen((event) {
    if (event is SaveProgressCancelled) {
      print('Cancelled!');
    }
});

// Cancel anytime
subscription.cancel();

Save to User-Selected Directory #

// 1. Pick directory (Optional, saveAs handles this automatically if null)
final location = await FileSaver.instance.pickDirectory();

if (location != null) {
  // 2. Save file to that directory
  await FileSaver.instance.saveAsAsync(
    input: SaveBytesInput(pdfBytes),
    fileName: 'invoice',
    fileType: CustomFileType(ext: 'pdf', mimeType: 'application/pdf'),
    saveLocation: location,
  );
}

API Reference #

Unified API (Recommended) #

save

Stream-based API for advanced control (cancellation, detailed events).

Stream<SaveProgress> save({
  required SaveInput input,
  required String fileName,
  required FileType fileType,
  // ... same optional params
})

saveAsync

Future-based API for simple usage.

Future<Uri> saveAsync({
  required SaveInput input,
  required String fileName,
  required FileType fileType,
  SaveLocation? saveLocation,
  String? subDir,
  ConflictResolution conflictResolution,
  Function(double)? onProgress,
})

saveAs

Stream-based interactive save.

Stream<SaveProgress> saveAs({
  required SaveInput input,
  required String fileName,
  required FileType fileType,
  UserSelectedLocation? saveLocation,
  ConflictResolution conflictResolution,
})

saveAsAsync

Interactive save (shows picker) or save to specific UserSelectedLocation.

Future<Uri?> saveAsAsync({
  required SaveInput input,
  required String fileName,
  required FileType fileType,
  UserSelectedLocation? saveLocation, // Null = Show Picker
  ConflictResolution conflictResolution,
  Function(double)? onProgress,
})

pickDirectory

Open system picker to let user choose a folder.

Future<UserSelectedLocation?> pickDirectory({bool shouldPersist = true})

Input Models #

SaveBytesInput

• fileBytes: Uint8List (Required)

SaveFileInput

• filePath: String (Required - absolute path)

SaveNetworkInput

• url: String (Required)
• headers: Map<String, String>? (Optional)
• timeout: Duration (Default: 60s)

Direct API #

Specific methods are still available but save/saveAsync is recommended.

• saveBytes / saveBytesAsync
• saveFile / saveFileAsync
• saveNetwork / saveNetworkAsync

SaveProgress Events #

Stream API emits these sealed class events:

Exception Reference #

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

Future Features #

• File Input Methods
• Save from Network URL
• User-Selected Location Android (SAF), iOS (Document Picker)
• Custom Path Support
• Progress Tracking
• Cancellation Support
• Save from File Path
• MacOS Support
• Windows Support
• Web Support

License #

MIT License - see LICENSE file for details.