Logo

Gal

Dart3 plugin for saving image or video to photos gallery ios photos google photos microsoft photos

pub.dev »

Since pub points CodeFactor Codacy Badge CI pub package

📢 Support Us

Please support our volunteer efforts by giving us a LIKE👍 and STAR⭐️.

🧠 DeepWiki Documentation

DeepWiki

📱 Supported Platforms

Android iOS macOS Windows Linux
Support SDK 21+ 11+ 11+ 10+ See: gal_linux

Support means that all functions have been tested manually or automatically whenever possible.

📸 Demo

iOS Android
Example ios android

✨ Features

  • Open gallery
  • Save video
  • Save image
  • Save to album
  • Save with metadata
  • Handle permission
  • Handle errors
  • Comprehensive documentation and wiki

🚀 Getting Started

Add Dependency

Add the latest stable version of gal to your dependencies:

flutter pub add gal

iOS Setup

Add the following keys to ios/Runner/Info.plist:

  • <key>NSPhotoLibraryAddUsageDescription</key> Required
  • <key>NSPhotoLibraryUsageDescription</key> Required for iOS < 14 or saving to album

You can copy from example's Info.plist.

Android Setup

Add the following keys to android/app/src/main/AndroidManifest.xml:

  • <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" /> Required for API <= 29
  • android:requestLegacyExternalStorage="true" Required for saving to album in API 29

You can copy from example's AndroidManifest.xml.

Warning

Android emulators with API < 29 require SD card setup. Real devices don't.

macOS Setup

Add the following keys to macos/Runner/Info.plist:

  • <key>NSPhotoLibraryAddUsageDescription</key> Required
  • <key>NSPhotoLibraryUsageDescription</key> Required for saving to album

You can copy from example's Info.plist.

Warning

Flutter currently has a fatal problem for loading info.plist, which may cause permission denials or app crashes in some code editors.

Windows Setup

Update Visual Studio to the latest version for using C++ 20.

Tip

If you can't compile, try downloading the latest Windows SDK:

  1. Open Visual Studio Installer
  2. Select Modify
  3. Select Windows SDK

Linux Setup

Linux is not officially supported, but can be added through a non-endorsed federated plugin. See: gal_linux

💻 Usage

Save from Local

// Save Image (Supports two ways)
await Gal.putImage('$filePath');
await Gal.putImageBytes('$uint8List');

// Save Video
await Gal.putVideo('$filePath');

// Save to Album
await Gal.putImage('$filePath', album: '$album')
...

Download from Internet

flutter pub add dio

// Download Image
final imagePath = '${Directory.systemTemp.path}/image.jpg';
await Dio().download('$url',imagePath);
await Gal.putImage(imagePath);

// Download Video
final videoPath = '${Directory.systemTemp.path}/video.mp4';
await Dio().download('$url',videoPath);
await Gal.putVideo(videoPath);

Save from Camera

flutter pub add image_picker

// Capture and Save
final image = await ImagePicker.pickImage(source: ImageSource.camera);
await Gal.putImage(image.path);

flutter pub add camera

// Record and Save
...
final video = await controller.stopVideoRecording();
await Gal.putVideo(video.path);

Handle Permissions

// Check Access Permission
final hasAccess = await Gal.hasAccess();

// Request Access Permission
await Gal.requestAccess();

// ... for saving to album
final hasAccess = await Gal.hasAccess(toAlbum: true);
await Gal.requestAccess(toAlbum: true);

Handle Errors

// Save Image with try-catch
try {
  await Gal.putImage('$filePath');
} on GalException catch (e) {
  log(e.type.message);
}

// Exception Type
enum GalExceptionType {
  accessDenied,
  notEnoughSpace,
  notSupportedFormat,
  unexpected;

  String get message => switch (this) {
        accessDenied => 'Permission to access the gallery is denied.',
        notEnoughSpace => 'Not enough space for storage.',
        notSupportedFormat => 'Unsupported file format.',
        unexpected => 'An unexpected error has occurred.',
      };
}

📚 Documentation

If you write an article about Gal, let us know in the discussion and we'll post the URL in the wiki or readme 🤝

💚 Trusted by Major Projects

Although Gal has only been released for a short time, it's already trusted by major projects.

and more...

Libraries

gal