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.