gal

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

gal 패키지는 이미지와 동영상을 장치의 사진 갤러리에 저장할 수 있도록 해주는 Flutter 플러그인으로 내장된 권한 처리 기능을 제공합니다. 안드로이드, iOS, macOS, Windows를 지원하여 미디어 내보내기 기능이 필요한 앱에 적합합니다. 이 플러그인은 권한을 자동으로 관리함으로써 갤러리에 접근하는 과정을 단순화하고 반복 코드를 줄입니다. 특히 이미지 또는 동영상 캡처, 편집, 공유를 포함하는 멀티미디어 워크플로우에 원활하게 통합됩니다.

사용 사례

갤러리에 캡처한 이미지/비디오 저장
편집 후 미디어 내보내기 자동화
크로스 플랫폼 앱에서 갤러리 접근 통합
미디어 저장소 권한 요청 처리
사용자 친화적인 미디어 공유 활성화

주요 기능

자동 권한 처리
크로스 플랫폼 지원 (Android, iOS, macOS, Windows)
미디어 저장을 위한 간단한 API
내장형 오류 관리
경량이며 통합이 쉬움

적합한 대상

미디어 캡처 기능을 갖춘 플러터 앱
이미지 또는 비디오 편집 도구
갤러리 접근 권한이 필요한 앱
미디어 저장을 위한 최소 설정을 원하는 개발자
크로스 플랫폼 멀티미디어 애플리케이션

고려 사항

플랫폼별 구성 파일에 적절한 권한이 필요합니다
특정 운영 체제 동작을 위해 추가 처리가 필요할 수 있습니다
고급 메타데이터 제어 없이 기본 저장 작업에 제한됨
업데이트를 위해 외부 저장소에 의존합니다
미디어 선택 또는 탐색용으로 설계되지 않음

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

Dart3 plugin for saving image or video to photos gallery

pub.dev »

📢 Support Us

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

🧠 DeepWiki Documentation

📱 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

✨ 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:

Open Visual Studio Installer

Select Modify

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.',
      };
}