media_gallery_saver #

A Flutter plugin that allows you to save files to the iOS and Android galleries from URL, asset, and file. The plugin supports Stream-based progress tracking for network downloads with concurrent download support and handles permissions automatically.

Supported File Formats #

Type	Formats
Images	jpg, jpeg, png, gif, webp, heic
Videos	mp4, mov

Installation #

Add this to your pubspec.yaml:

dependencies:
  media_gallery_saver: ^1.3.1

Then run:

flutter pub get

Platform Setup #

iOS #

Add the following permission to your ios/Runner/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to photo library to save images and videos</string>

Android #

The required permissions are automatically included in the plugin's AndroidManifest.xml:

WRITE_EXTERNAL_STORAGE (for Android < 10)
READ_EXTERNAL_STORAGE

Usage #

Basic Usage #

import 'package:media_gallery_saver/media_gallery_saver.dart';

// Create an instance
final saver = MediaGallerySaver();

// Save from URL with progress tracking
final result = saver.saveMediaFromUrl(
  url: 'https://example.com/image.jpg',
);

// Listen to progress updates
result.progress.listen((progress) {
  print('Progress: ${(progress.progress * 100).toInt()}%');
});

// Wait for completion
final success = await result.completion;

// Save from local file (no progress tracking needed)
File file = File('path/to/your/file.jpg');
bool success = await saver.saveMediaFromFile(file: file);

// Save from asset (no progress tracking needed)
bool success = await saver.saveMediaFromAsset(
  rootBundle: rootBundle,
  assetName: 'assets/images/sample.png',
);

Stream-based Progress Tracking #

Track download progress for network files with real-time streams:

final result = saver.saveMediaFromUrl(
  url: 'https://example.com/large-video.mp4',
);

// Listen to progress updates
result.progress.listen((progress) {
  print('Task ${result.taskId}: ${(progress.progress * 100).toInt()}%');
  print('Downloaded: ${progress.downloadedBytes}/${progress.totalBytes} bytes');
  
  // Update your UI here
  setState(() {
    _downloadProgress = progress.progress;
  });
});

// Wait for completion
final success = await result.completion;

Complete Example with Progress UI #

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:media_gallery_saver/media_gallery_saver.dart';

class DownloadScreen extends StatefulWidget {
  @override
  _DownloadScreenState createState() => _DownloadScreenState();
}

class _DownloadScreenState extends State<DownloadScreen> {
  double _progress = 0.0;
  bool _isDownloading = false;
  String _statusMessage = '';
  StreamSubscription? _progressSubscription;

  Future<void> _downloadAndSave() async {
    setState(() {
      _progress = 0.0;
      _isDownloading = true;
      _statusMessage = 'Starting download...';
    });

    try {
      final result = MediaGallerySaver().saveMediaFromUrl(
        url: 'https://sample-videos.com/zip/10/mp4/SampleVideo_1280x720_1mb.mp4',
      );
      
      // Listen to progress updates
      _progressSubscription = result.progress.listen((progress) {
        setState(() {
          _progress = progress.progress;
          _statusMessage = 'Downloading... ${(progress.progress * 100).toInt()}%';
        });
      });
      
      // Wait for completion
      final success = await result.completion;
      
      setState(() {
        _isDownloading = false;
        _statusMessage = success ? 'Download completed!' : 'Download failed';
      });
    } catch (e) {
      setState(() {
        _isDownloading = false;
        _statusMessage = 'Error: $e';
      });
    } finally {
      _progressSubscription?.cancel();
      _progressSubscription = null;
    }
  }

  @override
  void dispose() {
    _progressSubscription?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Media Gallery Saver')),
      body: Padding(
        padding: EdgeInsets.all(16.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            if (_isDownloading) ...[
              LinearProgressIndicator(value: _progress),
              SizedBox(height: 16),
            ],
            Text(_statusMessage, style: TextStyle(fontSize: 16)),
            SizedBox(height: 32),
            ElevatedButton(
              onPressed: _isDownloading ? null : _downloadAndSave,
              child: Text('Download and Save'),
            ),
          ],
        ),
      ),
    );
  }
}

Configuration Options #

Customize network behavior with MediaGallerySaverOptions:

final saver = MediaGallerySaver(
  options: MediaGallerySaverOptions(
    connectTimeout: 30000, // Connection timeout: 30 seconds
    readTimeout: 120000,   // Read timeout: 2 minutes
  ),
);

Available Options #

Option	Type	Default	Description
`connectTimeout`	`int`	`15000`	Connection timeout in milliseconds
`readTimeout`	`int`	`0`	Read timeout in milliseconds (0 = unlimited)

API Reference #