flutter_chunked_upload 1.0.2 copy "flutter_chunked_upload: ^1.0.2" to clipboard
flutter_chunked_upload: ^1.0.2 copied to clipboard

A Flutter package for chunked file uploads with resume, progress tracking, and queue management. Supports pause, resume, cancel, and persistent storage for large files.

flutter_chunked_upload #

A Flutter package for handling chunked file uploads with resume capability, progress tracking, and queue management.

🚀 Demo #

Android Demo iOS Demo
Android Demo iOS Demo

🌟 Features #

  • Chunked File Uploads: Split large files into manageable chunks for reliable uploads
  • Resume Capability: Automatically resume uploads from where they left off
  • Queue Management: Manage multiple uploads with priority support
  • Progress Tracking: Real-time progress updates with callbacks
  • Pause/Resume/Cancel: Full control over upload operations
  • Automatic Connectivity Handling: Pause uploads when internet is lost, resume when restored
  • Persistent Storage: Upload progress saved using Hive for app restarts
  • Cross-Platform: Works on iOS, Android, Web, and Desktop
  • Backend Agnostic: Works with any server that supports chunked uploads
  • Notifications: Built-in success, retry, and failure notifications
  • Error Handling: Comprehensive error handling with automatic retries

Getting started #

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_chunked_upload: ^1.0.0

Dependencies #

This package requires the following dependencies:

dependencies:
  hive: ^2.2.3
  hive_flutter: ^1.1.0
  http: ^1.4.0
  path_provider: ^2.1.5
  flutter_local_notifications: ^19.2.1
  rxdart: ^0.28.0
  collection: ^1.19.0

Usage #

Basic Setup #

import 'package:flutter_chunked_upload/flutter_chunked_upload.dart';

// Initialize the upload queue manager
final queueManager = UploadQueueManager();
await queueManager.initAsync();

Creating Upload Jobs #

// Create an upload job
final job = UploadJob(
  id: 'unique_job_id',
  filePath: '/path/to/your/file.mp4',
  url: 'https://api.example.com/upload',
  chunkSize: 1024 * 1024, // 1MB chunks
  priority: 5, // Higher number = higher priority
  onProgress: (id, progress) {
    print('Upload $id progress: ${(progress * 100).toStringAsFixed(1)}%');
  },
  onComplete: (id) {
    print('Upload $id completed successfully!');
  },
  onFailed: (id, error) {
    print('Upload $id failed: $error');
  },
  headerBuilder: (chunkIndex, totalChunks) {
    // Custom headers for each chunk
    return {
      'Content-Type': 'application/octet-stream',
      'X-Chunk-Index': chunkIndex.toString(),
      'X-Total-Chunks': totalChunks.toString(),
    };
  },
);

// Add to queue
await queueManager.addToQueue(job);

🔄 Automatic Connectivity Handling #

The package automatically handles internet connectivity changes:

  • Internet Lost: All active uploads are automatically paused
  • Internet Restored: All paused uploads are automatically resumed
  • No Manual Intervention: Works seamlessly in the background
  • Progress Preserved: No data loss during connectivity changes
// The connectivity handling is automatic - no additional code needed!
// Uploads will pause when internet is lost and resume when restored

Managing Uploads #

// Pause an upload
queueManager.pauseJob('job_id');

// Resume an upload
queueManager.resumeJob('job_id');

// Cancel an upload
queueManager.cancelJob('job_id');

// Get all pending jobs
final pendingJobs = await queueManager.getPendingJobs();

// Get paused jobs
final pausedJobs = await queueManager.getPausedJobs();

// Clear all jobs
queueManager.clearAllJobs();

Using the Debug Panel #

import 'package:flutter/material.dart';
import 'package:flutter_chunked_upload/flutter_chunked_upload.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Upload Manager')),
        body: UploadJobsDebugPanel(), // Shows all upload jobs with controls
      ),
    );
  }
}

Custom Storage Adapters #

You can implement custom storage adapters for different persistence needs:

class CustomJobStorageAdapter implements UploadJobStorageAdapter {
  // Implement the required methods
  @override
  Future<void> saveJob(UploadJob job) async {
    // Your custom implementation
  }
  
  // ... implement other methods
}

// Use custom adapters
await queueManager.initAsync(
  jobStorage: CustomJobStorageAdapter(),
  chunkStorage: CustomChunkStorageAdapter(),
);

API Reference #

UploadJob #

The main class representing an upload job.

class UploadJob {
  String id;                    // Unique identifier
  String filePath;              // Path to file
  String url;                   // Upload endpoint
  int chunkSize;                // Size of each chunk
  UploadJobStatus status;       // Current status
  int retryCount;               // Number of retries
  int maxRetries;               // Maximum retries
  bool isPaused;                // Pause state
  int priority;                 // Queue priority
  double progress;              // Upload progress (0.0-1.0)
  
  // Callbacks
  ProgressCallback? onProgress;
  UploadCompleteCallback? onComplete;
  UploadFailedCallback? onFailed;
  HeaderBuilder? headerBuilder;
}

UploadJobStatus #

enum UploadJobStatus {
  pending,    // Waiting in queue
  uploading,  // Currently uploading
  success,    // Upload completed
  failed,     // Upload failed
}

UploadQueueManager #

Singleton class for managing upload queue.

class UploadQueueManager {
  // Initialize the manager
  Future<void> initAsync({...});
  
  // Queue management
  Future<void> addToQueue(UploadJob job);
  void pauseJob(String jobId);
  void resumeJob(String jobId);
  void cancelJob(String jobId);
  
  // Query methods
  Future<List<UploadJob>> getPendingJobs();
  Future<List<UploadJob>> getPausedJobs();
  
  // Cleanup
  void clearAllJobs();
  void dispose();
}

Configuration #

Chunk Size #

Choose appropriate chunk sizes based on your needs:

  • Small files (< 10MB): 512KB chunks
  • Medium files (10MB - 100MB): 1MB chunks
  • Large files (> 100MB): 2-5MB chunks

Retry Configuration #

final job = UploadJob(
  // ... other properties
  maxRetries: 5, // Increase for unreliable networks
  retryCount: 0, // Start with 0
);

Priority Levels #

  • 0-2: Low priority
  • 3-7: Medium priority
  • 8-10: High priority

Error Handling #

The package handles various error scenarios:

  • File not found: Throws FileSystemException
  • Network errors: Automatic retry with exponential backoff
  • Server errors: Retry based on HTTP status codes
  • Storage errors: Graceful degradation

Platform Support #

  • ✅ Android
  • ✅ iOS
  • ✅ Web (with limitations)
  • ❌ Desktop (not tested)

Contributing #

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License #

This project is licensed under the MIT License - see the LICENSE file for details.

9
likes
160
points
58
downloads

Publisher

verified publisherakshya.site

Weekly Downloads

A Flutter package for chunked file uploads with resume, progress tracking, and queue management. Supports pause, resume, cancel, and persistent storage for large files.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (license)

Dependencies

collection, connectivity_plus, flutter, flutter_local_notifications, hive, hive_flutter, http, path, path_provider, rxdart

More

Packages that depend on flutter_chunked_upload