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.

8
likes
160
points
72
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)

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