Search packages, repositories and app categories

flutter_chunked_upload cover
Package detailsv1.0.2

flutter_chunked_upload

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

AndroidiOSmacOSWindowsLinux
30-day downloads
35
Likes
12
Pub points
150

Install package

flutter pub add flutter_chunked_upload

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

A Flutter package designed for uploading large files in chunks, enabling resume capability, real-time progress tracking, and efficient queue management. It supports pause, resume, and cancel operations, with persistent storage to maintain upload state across app restarts. Ideal for handling large file transfers reliably on multiple platforms including Android, iOS, macOS, Windows, and Linux.

Use cases

  • Uploading large video files
  • Resuming interrupted uploads
  • Managing multiple file uploads in a queue
  • Handling unstable network connections
  • Offline-first file transfer workflows

Key features

  • Chunked file upload support
  • Resume interrupted uploads
  • Real-time progress tracking
  • Pause and resume functionality
  • Persistent upload state storage
  • Cross-platform compatibility

Suitable for

  • Apps requiring large file uploads
  • Network-intensive applications
  • Offline-capable data sync features
  • File-sharing or backup services
  • Applications with unreliable connectivity

Considerations

  • Requires careful handling of storage permissions
  • May consume significant memory for large files
  • Needs proper error handling for network failures
  • Not ideal for small file transfers
  • Depends on stable background execution on some platforms

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

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.

Categories

Dependencies

Dependency list 9 items

Source repository

Projects using this package

No data available yet.