Set up resumable uploads for Flutter

The FastPix Flutter Resumable Uploads SDK helps you efficiently upload large files from Flutter apps by splitting them into chunks and also gives you the ability to pause and resume your uploads.

Step 1: Install the Flutter SDK

Add the dependency to yourpubspec.yaml

Add FastPix’s Flutter library to the dependencies block of your pubspec.yaml file.

1
dependencies:
2
flutter:
3
sdk: flutter
4
fastpix_resumable_uploader: ^1.0.0

Install dependencies
Run the following command to install the dependencies:

$
flutter pub get

Step 2: Create an upload URL

In order to upload a video, you will need a signed upload URL.

To get this signed URL, you’ll need a valid Access Token and Secret Key. See the Basic Authentication Guide for details on retrieving these credentials.

Once you have your credentials, use the Upload media from device API to generate a signed URL for uploading media. After fetching the the signed URL you can continue with integrating the SDK into your application.

The example below gives you an idea about how to get the signed URL using the upload media from device API. You can use the example directly or also refer to our upload videos directly guide.

1
import  'dart:convert';
2
import  'dart:io';
3
import  'package:http/http.dart'  as http;
4
5
Future<String> getSignedUrl() async {
6
    final client = http.Client();
7
    // Construct JSON body
8
    final requestBody = jsonEncode({
9
        "corsOrigin": "*",
10
        "pushMediaSettings": {
11
            "metadata": {
12
            "key1": "value1"
13
            },
14
        "accessPolicy": "public",
15
        "maxResolution": "1080p",
16
        "mediaQuality": "standard"
17
        }
18
    });
19
    // Create Authorization header
20
    final credentials = "$tokenId:$secretKey";
21
    final auth = "Basic ${base64Encode(utf8.encode(credentials))}";
22
    try {
23
        final response = await client.post(
24
            Uri.parse('https://api.fastpix.com/v1/on-demand/uploads'),
25
            headers: {
26
            'Authorization': auth,
27
            'Content-Type': 'application/json',
28
            },
29
            body: requestBody,
30
        );
31
        if (response.statusCode == 200) {
32
            final data = jsonDecode(response.body);
33
            return data['signedUrl']; // Return the signed URL
34
        } else {
35
            throw  Exception('Failed to get signed URL: ${response.statusCode}');
36
        }
37
    } finally {
38
        client.close();
39
    }
40
}

Step 3: Start your upload

The Flutter SDK provides a builder pattern for easy configuration and initialization:

1
import  'dart:io';
2
import  'package:fastpix_resumable_uploader/fastpix_resumable_uploader.dart';
3
4
Future<void> uploadVideo() async {
5
    final file = File('/path/to/your/video.mp4');
6
    final signedUrl = await getSignedUrl(); // Get signed URL from Step 2
7
    final uploadService = FlutterResumableUploads.builder()
8
        .file(file)
9
        .signedUrl(signedUrl)
10
        .chunkSize(16 * 1024 * 1024) // 16MB chunks
11
        .maxRetries(3)
12
        .retryDelay(Duration(milliseconds: 2000))
13
        .onProgress((progress) {
14
            print('Upload progress: ${progress.uploadPercentage}%');
15
            print('Current chunk: ${progress.currentChunkIndex}/${progress.totalChunks}');
16
        })
17
        .onError((error) {
18
            print('Upload error: ${error.message}');
19
        })
20
        .build();
21
    await uploadService.uploadVideo();
22
}

Builder configuration options

Step 4: Monitor upload events

The SDK provides comprehensive callback methods to monitor upload progress and handle various events:

1
FlutterResumableUploads.builder()
2
    .file(file)
3
    .signedUrl(signedUrl)
4
    .onProgress((progress) {
5
    // Called periodically to report upload progress
6
        print('Upload progress: ${progress.uploadPercentage}%');
7
        print('Current chunk: ${progress.currentChunkIndex}/${progress.totalChunks}');
8
        print('Status: ${progress.status}');
9
    })
10
    .onError((error) {
11
        // Called when an error occurs during upload
12
        print('Upload error: ${error.message}');
13
        print('Error code: ${error.code}');
14
    })
15
    .onPause(() {
16
        // Called when the upload is paused
17
        print('Upload paused');
18
    })
19
    .onAbort(() {
20
        // Called when the upload is aborted
21
        print('Upload aborted');
22
    })
23
    .build();

Progress model
The progress callback provides a ProgressModel with the following properties:

• uploadPercentage: Progress percentage (0.0 - 100.0)
• currentChunkIndex: Current chunk being uploaded
• totalChunks: Total number of chunks
• status: Current upload status (e.g., “splitting_chunks”, “uploading_chunks”, “completed”)
• fileSize: Total file size in bytes
• uploadedBytes: Number of bytes uploaded so far

Step 5: Manage video uploads

You can control the upload lifecycle with the following methods:

Pause an upload

1
uploadService.pauseUpload();

Resume an upload

1
uploadService.resumeUpload();

Abort an upload

1
uploadService.abortUpload();

Check upload status

1
final isPaused = uploadService.isPaused;
2
final isCompleted = uploadService.isCompleted;
3
final isAborted = uploadService.isAborted;

Detailed usage example

The following example gives an overview of integrating the FastPix Flutter Uploads SDK into your project, enabling you to build a fully customized upload interface:

1
import  'dart:io';
2
import  'package:flutter/material.dart';
3
import  'package:fastpix_resumable_uploader/fastpix_resumable_uploader.dart';
4
5
class  UploadScreen  extends  StatefulWidget {
6
    @override
7
    _UploadScreenState createState() => _UploadScreenState();
8
}
9
10
class _UploadScreenState extends  State<UploadScreen> {
11
    FlutterResumableUploads? _uploadService;
12
    double _progress = 0.0;
13
    String _status = 'Ready to upload';
14
    bool _isUploading = false;
15
    bool _isPaused = false;
16
17
    @override
18
19
    Widget build(BuildContext context) {
20
        return Scaffold(
21
            appBar: AppBar(
22
                title: Text('Video Upload'),
23
            ),
24
            body: Padding(
25
                padding: EdgeInsets.all(16.0),
26
                child: Column(
27
                    children: [
28
                        // Progress indicator
29
                        LinearProgressIndicator(
30
                            value: _progress / 100.0,
31
                            backgroundColor: Colors.grey[300],
32
                            valueColor: AlwaysStoppedAnimation<Color>(Colors.blue),
33
                        ),
34
                        SizedBox(height: 16),
35
                        // Status text
36
                        Text(
37
                            _status,    
38
                            style: TextStyle(fontSize: 16),
39
                        ),
40
                        SizedBox(height: 24),
41
                        ElevatedButton(
42
                            onPressed: _isUploading ? null : _startUpload,
43
                            child: Text('Start Upload'),
44
                        ),
45
                        SizedBox(height: 16),
46
        // Pause/Resume button
47
                    if (_isUploading)
48
                        ElevatedButton(
49
                            onPressed: _isPaused ? _resumeUpload : _pauseUpload,
50
                            child: Text(_isPaused ? 'Resume' : 'Pause'),
51
                        ),
52
                        SizedBox(height: 16),
53
                        // Abort button
54
                        if (_isUploading)
55
                        ElevatedButton(
56
                            onPressed: _abortUpload,
57
                            style: ElevatedButton.styleFrom(
58
                                backgroundColor: Colors.red,
59
                            ),
60
                            child: Text('Abort Upload'),
61
                        ),
62
                    ],
63
                ),
64
            ),
65
        );
66
    }
67
68
    Future<void> _startUpload() async {
69
        try {
70
            final file = File('/path/to/your/video.mp4');
71
            final signedUrl = await getSignedUrl(); // Implement this method
72
            setState(() {
73
                _isUploading = true;
74
                _status = 'Initializing upload...';
75
            });
76
            _uploadService = FlutterResumableUploads.builder()
77
                .file(file)
78
                .signedUrl(signedUrl)
79
                .chunkSize(16 * 1024 * 1024) // 16MB chunks
80
                .maxRetries(3)
81
                .retryDelay(Duration(milliseconds: 2000))
82
                .onProgress((progress) {
83
                    setState(() {
84
                        _progress = progress.uploadPercentage;
85
                        _status = 'Uploading: ${progress.currentChunkIndex}/${progress.totalChunks} chunks';
86
                    });
87
                })
88
                .onError((error) {
89
                    setState(() {
90
                        _status = 'Error: ${error.message}';
91
                        _isUploading = false;
92
                    });
93
                })
94
                .onPause(() {
95
                    setState(() {
96
                        _isPaused = true;
97
                        _status = 'Upload paused';
98
                    });
99
                })
100
                .build();
101
            await _uploadService!.uploadVideo();
102
            setState(() {
103
                _status = 'Upload completed successfully!';
104
                _isUploading = false;
105
                _progress = 100.0;
106
            });
107
        } catch (e) {
108
            setState(() {
109
                _status = 'Error: $e';
110
                _isUploading = false;
111
            });
112
        }
113
    }
114
115
    void _pauseUpload() {
116
        _uploadService?.pauseUpload();
117
    }
118
119
    void _resumeUpload() {
120
        _uploadService?.resumeUpload();
121
        setState(() {
122
            _isPaused = false;
123
            _status = 'Uploading...';
124
        });
125
    }
126
127
    void _abortUpload() {
128
        _uploadService?.abortUpload();
129
        setState(() {
130
            _isUploading = false;
131
            _isPaused = false;
132
            _status = 'Upload aborted';
133
            _progress = 0.0;
134
        });
135
    }
136
137
    @override
138
    void dispose() {
139
        _uploadService?.abortUpload();
140
        super.dispose();
141
    }
142
}

Features

Core features

• Chunking: Files are automatically split into chunks (default chunk size is 16MB).
• Pause and resume: Allows temporarily pausing the upload and resuming after a while.
• Retry: Uploads might fail due to temporary network failures. Individual chunks are retried with exponential backoff to recover automatically from such failures.
• Lifecycle event listeners: Provides real-time feedback through various upload lifecycle events.
• Error handling: Comprehensive error management to notify users of issues during uploads.
• Customizability: Options to customize chunk size and retry attempts.

Advanced features

• Network health monitoring: Automatically detects network connectivity changes and handles offline scenarios.
• Upload lock management: Prevents multiple concurrent uploads from the same service instance.
• Progress tracking: Detailed progress reporting with chunk-level information.
• File validation: Built-in file size and format validation.
• Memory efficient: Streams file chunks without loading the entire file into memory.

BEST PRACTICES

Chunk Size: Use appropriate chunk sizes based on your target platform and network conditions. 16MB is a good default for most scenarios.

Error Handling: Always implement proper error handling to provide meaningful feedback to users.
Progress Updates: Use progress callbacks to update your UI and keep users informed about upload status.

Network Monitoring: The SDK automatically handles network connectivity changes, but you may want to add additional network monitoring for better UX.

Memory Management: For very large files, consider implementing additional memory management strategies.

Retry Configuration: Adjust retry settings based on your network environment and requirements.

Troubleshooting common issues

DEBUG INFORMATION

Enable debug logging to get detailed information about upload operations.

• The SDK automatically logs debug information when running in debug mode.
• Check the console output for detailed upload information

For more information and support, contact us.

Changelog

All notable changes to this project are documented in this file.

2.0.0

Spec correctness — GCS resumable protocol compliance

• Parse the Range: response header on 308 responses. The client now resyncs its cursor to the byte offset GCS actually committed instead of blindly advancing to the end of the chunk it sent. Fixes silent data corruption on flaky networks where the server partially commits a chunk before returning 308.
• Status-query path (Content-Range: bytes */<total>). After any transient failure / timeout / network loss / signed-URL refresh, the SDK now asks GCS for its true cursor before re-uploading. Available as _resyncCursorFromServer() internally and via refreshSignedUrl(...) publicly.
• Any 2xx is now terminal success. Previously only HTTP 200 finalized the upload; 201 / 204 fell through to the retry path.
• Empty trailing chunk guard. When the local cursor reaches EOF but no terminal 2xx has been observed, the SDK queries the server rather than PUT-ing a zero-byte (and inverted-Range) request.

Retry policy

• Real exponential backoff with jitter. 2s, 4s, 8s, 16s, 30s (cap) with ±25% jitter. Previously linear (2s, 4s, 6s…) with no jitter — no longer prone to thundering-herd on shared-backend incidents.
• HTTP-status-aware retry classification. 4xx (other than 408/429) is no longer retried. 408/429/5xx are retried; everything else surfaces as a permanent failure.
• Stop swallowing timeouts and DioExceptionType.unknown. Connection errors, send/receive timeouts, and unknown transport faults are now classified as transient and routed through the retry path.
• Retry timers are tracked and cancelled on dispose(), abortUpload(), and reset(). Stray retry callbacks no longer fire into stale state.
• DioExceptionType.badCertificate is treated as permanent (cert pinning / MITM situations should not be retried).

Concurrency / state

• Pause and abort no longer surface through the error stream. Previously the SDK emitted UploadError('Upload Paused') and UploadError('Upload Aborted') via onError, which led consumers to treat user-initiated pause as a failure (and disable the Resume button). Pause and abort are now communicated only through the dedicated onPause / onAbort callbacks and the progress event with the appropriate UploadStatus.
• De-singletoned VideoUploadProgress. Was a process-wide static class whose callbacks were overwritten by every new uploader — two concurrent uploads in the same app would cross-wire their callbacks. Now per-instance.
• De-singletoned VideoUploadRetry. Per-instance retry controller owns its own pending timer.
• First-network-event swallow fixed. The _isFirstTime flag no longer drops the first connectivity event, so an upload kicked off while offline can be auto-resumed when the network returns.

API surface (breaking changes — see “Migration” below)

• uploadVideo() now returns a Future<void> that actually resolves when the upload finalizes (or rejects with UploadError on permanent failure / abort). Previously the future resolved immediately after the first chunk was scheduled.
• progressStream and errorStream — broadcast streams on the uploader for callers that want more than one listener or prefer streams over callbacks. The legacy onProgress / onError callbacks still work.
• isUploading() now honors terminal failure state — returns false after a permanent failure instead of staying true forever.
• onUrlRefresh: Future<String> Function() — builder hook called automatically when the SDK detects an expired signed URL (HTTP 401 / 403 / 410). Mint a fresh URL and the upload resumes from the server’s committed cursor against the new URL.
• refreshSignedUrl(String) — manual / proactive URL replacement on the uploader.
• .observeAppLifecycle() — opt-in builder flag. Attaches a WidgetsBindingObserver that auto-pauses on background and resumes on foreground. Does NOT enable true background uploads (that needs platform-level integration), but leaves the resumable session in a clean state for when the user returns.
• Builder default maxRetries reconciled with the uploader default (both now 5). Removed the dead _builderMaxRetries field.

Memory / performance

• Killed the double-copy in VideoUploadChunker.readFileChunk. Uint8List.fromList(raf.read(...)) is replaced with the direct raf.read(...) return — saves a 16 MB copy per chunk.
• Uint8List.sublistView in the progress stream in place of sublist. For a 4 GB upload that’s ~1M fewer heap allocations.

Tests

• 32 unit tests covering chunker math, file-chunk read edge cases, exponential-backoff math (doubling, cap, jitter bounds, never-negative), GCS Range: header parsing, and HTTP-status classification (200 / 201 / 204 / 308 / 308-with-Range / 400 / 403 / 408 / 429 / 500).

Migration from 1.x

1
- final uploader = FlutterResumableUploads.builder()
2
-     .file(file)
3
-     .signedUrl(url)
4
-     .onProgress((p) => ...)
5
-     .build();
6
- // upload was fire-and-forget; this returned immediately
7
- await uploader.uploadVideo();
8
+ final uploader = FlutterResumableUploads.builder()
9
+     .file(file)
10
+     .signedUrl(url)
11
+     .onProgress((p) => ...)
12
+     .onUrlRefresh(() => myBackend.mintSignedUrl())  // optional
13
+     .observeAppLifecycle()                          // optional
14
+     .build();
15
+ try {
16
+   // now actually awaits completion
17
+   await uploader.uploadVideo();
18
+ } on UploadError catch (e) {
19
+   // permanent failure / abort / exhausted retries
20
+ }

• If your code relied on the static VideoUploadProgress.emitProgress(...) / VideoUploadProgress.setupCallbacks(...) access path, switch to per-instance methods on FlutterResumableUploads (or use the new progressStream / errorStream).

1.0.1

Documentation & Homepage URL Update

• Updated homepage in pubspec.yaml from https://www.fastpix.io/ to https://www.fastpix.com/.
• Updated documentation links in README.md (Basic Authentication, Upload media from device) from docs.fastpix.io to docs.fastpix.com.
• Updated documentation link in the GitHub issue template (.github/ISSUE_TEMPLATE/question_support.md) from docs.fastpix.io to docs.fastpix.com.

1.0.0

Initial Release - Flutter Resumable Uploads SDK

A robust Flutter package for uploading large video and audio files with enterprise-grade features.

Core Features

• Chunked Upload System: Automatically splits large files into configurable chunks (default 16MB) for reliable uploads
• Resumable Uploads: Pause and resume functionality with state persistence across app sessions
• Network Resilience: Automatic retry mechanism with configurable retry attempts and delays
• Advanced Chunk-Level Retry Tracking: Individual retry tracking per chunk to prevent app sluggishness
• Real-time Progress Tracking: Detailed progress updates with chunk-level information and percentage completion
• Network Monitoring: Automatic detection of network connectivity changes with smart resume logic
• Comprehensive Error Handling: Detailed error reporting with specific error codes and messages
• Advanced Logging System: Configurable logging with multiple levels (DEBUG, INFO, WARNING, ERROR)

Architecture & Design

• Builder Pattern: Clean, fluent API for easy configuration and setup
• State Management: Robust state tracking for upload progress, network status, and retry attempts
• Modular Design: Well-organized codebase with separate modules for core, network, models, and utilities
• Memory Efficient: Proper resource management with dispose and reset capabilities
• Thread Safe: Upload lock mechanism to prevent concurrent upload conflicts

Technical Capabilities

• File Validation: Comprehensive file size and format validation
• Signed URL Support: Secure uploads using pre-authenticated URLs
• HTTP Status Handling: Proper handling of 308 (Partial Content) and 200 (Complete) responses
• Cancel Token Integration: Dio-based cancellation for clean upload termination
• Upload Statistics: Detailed logging of upload metrics and retry statistics
• Network Health Monitoring: Real-time network connectivity monitoring using connectivity_plus

Developer Experience

• Fluent API: Easy-to-use builder pattern for configuration
• Callback System: Comprehensive callback support for progress, errors, pause, and abort events
• Debug Information: Rich debugging capabilities with detailed state information
• Error Recovery: Intelligent error handling with automatic retry and manual recovery options
• Documentation: Comprehensive documentation with usage examples and best practices

Configuration Options

• Chunk Size: Configurable chunk size (default: 16MB)
• Retry Settings: Customizable retry attempts and delay intervals
• File Size Limits: Optional maximum file size validation
• Logging Control: Enable/disable logging with custom log levels and tags
• Network Timeouts: Configurable network timeout settings

Security & Reliability

• Secure Uploads: Signed URL-based authentication
• Data Integrity: Proper chunk validation and error checking
• Resource Management: Automatic cleanup and memory management
• State Persistence: Upload state tracking for reliable resume functionality

Dependencies

• dio: ^5.8.0+1 - HTTP client for network operations
• connectivity_plus: ^6.1.4 - Network connectivity monitoring
• internet_connection_checker: ^3.0.1 - Internet connection validation

Use Cases

• Large video file uploads in mobile applications
• Audio file uploads with progress tracking
• Media uploads requiring pause/resume functionality
• Applications requiring network resilience
• Enterprise applications needing detailed upload analytics