> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fastpix.com/docs/upload-videos/set-up-resumable-uploads-for-android/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/_mcp/server. # Set up resumable uploads for Android The FastPix [Android Resumable Uploads](https://github.com/FastPix/android-uploads-sdk) SDK helps you efficiently upload large files from the browser by splitting them into chunks and also gives you the ability to pause and resume your uploads. \ #### How resumable uploads work through chunking \ Resumable uploads can be effectively handled through a technique called **chunking**. This method involves breaking down large files into smaller, more manageable pieces, or "chunks." Here's how chunking works: 1. **Divide the file**: Large files are split into smaller, manageable chunks (e.g., 16 MB by default). 2. **Upload individually**: Each chunk is uploaded separately. If a chunk fails, only that specific chunk needs to be re-uploaded. 3. **Resume capability**: If the upload is interrupted, you can resume from the last successfully uploaded chunk instead of starting over. \ This approach is important because: * **It reduces the risk**: Uploading smaller chunks minimizes the risk of failure. If a chunk fails to upload due to network issues, only that specific chunk needs to be re-uploaded, not the entire file. * **Improves performance**: Smaller chunks can be uploaded more quickly and efficiently, especially on slower connections, as they require less time to transfer. * **Easier management**: Chunking allows for better tracking of upload progress, making it easier to implement features like pause and resume. \ \ ## Step 1: Install the Android SDK \ ### Add our repository to your Gradle project ```kotlin maven(url ="https://maven.pkg.github.com/FastPix/android-uploads-sdk") { credentials { username = "your_gihub_username" password = "your_github_personal_token" } } ``` ```groovy maven { url "https://maven.pkg.github.com/FastPix/android-uploads-sdk" credentials { username = "your_gihub_username" password = "your_github_personal_token" } } ``` \ ### Add the dependency to your app Add Fastpix’s library to the dependencies block of your app in module level build.gradle file. ```kotlin dependencies { implementation("io.fastpix:uploads:1.0.1") } ``` ```groovy dependencies { implementation 'io.fastpix:uploads:1.0.1' } ``` \ ## 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 [Authentication Guide](/getting-started/activate-your-account) for details on retrieving these credentials. After obtaining your credentials, the next step is to generate a signed URL by calling the [Upload Media from Device](/video-on-demand-api/upload-and-import-videos/direct-upload-video-media#/) API. Once you have the signed URL, you’re all set to move forward with integrating the SDK into your app. The example below demonstrates how to retrieve a signed URL using the Upload Media from Device API. You can either use this example directly or refer to our guide on [uploading videos directly](/upload-videos/upload-videos-from-device) for more details. \ ```kotlin private fun getSignedUrl() { val client = OkHttpClient() val mediaType = "application/json; charset=utf-8".toMediaType() // Construct JSON body using JSONObject val requestBodyJson = JSONObject().apply { put("corsOrigin", "*") put("pushMediaSettings", JSONObject().apply { put("metadata", JSONObject().apply { put("key1", "value1") }) put("accessPolicy", "public") put("maxResolution", "1080p") put("mediaQuality", "standard") }) } val requestBody = requestBodyJson.toString().toRequestBody(mediaType) // Create Authorization header val credentials = "$tokenId:$secretKey" val auth = "Basic " + Base64.encodeToString(credentials.toByteArray(), Base64.NO_WRAP) // Build the HTTP request val request = Request.Builder() .url("https://api.fastpix.com/v1/on-demand/upload") .addHeader("Authorization", auth) .addHeader("Content-Type", "application/json") .post(requestBody) .build() // Execute request client.newCall(request).enqueue(object : Callback { override fun onFailure(call: Call, e: IOException) { LOGGER.log(Level.SEVERE, e.message) } override fun onResponse(call: Call, response: Response) { if (response.isSuccessful) { response.body?.string()?.let { val jsonObject = JSONObject(it) val jsonData = jsonObject.getJSONObject("data") val signedUrl = jsonData.getString("url") // TODO: use signedUrl and uploadId as needed } } else { LOGGER.log(Level.SEVERE, "Upload URL request failed: ${response.code}") } } }) } ``` ```java private void getSignedUrl() { OkHttpClient client = new OkHttpClient(); // Construct JSON body using JSONObject JSONObject metadata = new JSONObject(); JSONObject pushMediaSettings = new JSONObject(); JSONObject requestBodyJson = new JSONObject(); try { metadata.put("key1", "value1"); pushMediaSettings.put("metadata", metadata); pushMediaSettings.put("accessPolicy", "public"); pushMediaSettings.put("maxResolution", "1080p"); pushMediaSettings.put("mediaQuality", "standard"); requestBodyJson.put("corsOrigin", "*"); requestBodyJson.put("pushMediaSettings", pushMediaSettings); } catch (JSONException e) { e.printStackTrace(); return; } MediaType mediaType = MediaType.parse("application/json; charset=utf-8"); RequestBody requestBody = RequestBody.create(requestBodyJson.toString(), mediaType); // Create Authorization header String credentials = tokenId + ":" + secretKey; String auth = "Basic " + Base64.encodeToString(credentials.getBytes(StandardCharsets.UTF_8), Base64.NO_WRAP); // Build the request Request request = new Request.Builder() .url("https://api.fastpix.com/v1/on-demand/upload") .addHeader("Authorization", auth) .addHeader("Content-Type", "application/json") .post(requestBody) .build(); // Execute the request client.newCall(request).enqueue(new Callback() { @Override public void onFailure(@NonNull Call call, @NonNull IOException e) { Log.e("UPLOAD", "Failed to get signed URL", e); } @Override public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException { if (response.isSuccessful()) { String responseBody = response.body() != null ? response.body().string() : null; if (responseBody != null) { try { JSONObject jsonObject = new JSONObject(responseBody); JSONObject jsonData = jsonObject.getJSONObject("data"); String signedUrl = jsonData.getString("url"); String uploadId = jsonData.getString("uploadId"); // TODO: use signedUrl and uploadId as needed } catch (JSONException e) { Log.e("UPLOAD", "Failed to parse response", e); } } } else { Log.e("UPLOAD", "Upload URL request failed: " + response.code()); } } }); } ``` \ > **PLEASE NOTE** > > When making Basic Auth API calls, securely retrieve the username and password from environment variables (.env) or a protected server endpoint to prevent unauthorized access. \ In the API response, you will get a signed URL upon successful API request. Next step is to take the signed URL and pass it to the SDK. \ ## Step 3: Start your upload To perform the upload from your Android app, you can use the `FastPixUploadSdk` class. At the simplest, you need to build your `FastPixUploadSdk` via its Builder, then add your listeners and `start()` the upload. \ ```kotlin val sdk = FastPixUploadSdk.Builder(this) .setFile(file) .setSignedUrl(signedUrl) .setChunkSize(chunkSize * 1024 * 1024) .build() sdk.startUpload() ``` ```groovy FastPixUploadSdk sdk = new FastPixUploadSdk.Builder(this) .setFile(file) .setSignedUrl(signedUrl) .setChunkSize(chunkSize * 1024 * 1024) .build(); sdk.startUpload(); ``` \ ### Parameters to use: This SDK supports the following parameters | Parameter | Required? | Description | | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | | setSignedUrl | Yes | The URL endpoint where the file will be uploaded. | | setFile | Yes | The file object that you want to upload (e.g., a video file). | | setChunkSize | No | Defines the chunk size in bytes. By default, the SDK splits files into 16 MB chunks. You can customize this (minimum of 5 MB). | | callback | No | Lets you handle the upload lifecycle events such as progress, completion, and errors. | | setMaxRetries | No | Sets the number of retry attempts for failed chunk uploads. Defaults to 5. | | setRetryDelay | No | Sets the wait time (in milliseconds) before retrying a failed chunk upload. Defaults to 2000ms. | \ ## Monitor the upload progress through lifecycle events Using the following lifecycle events lets you to build a robust and user-friendly upload experience. By tracking progress in real-time, handling errors proactively, managing chunk retries, and responding to network changes, you can ensure seamless and efficient uploads. Integrating these event handlers into your application can enhance reliability, optimize performance, and provide users with clear, actionable feedback throughout the upload process. \ ```kotlin class MyUploadCallback : FastPixUploadCallbacks { override fun onProgressUpdate(progress: Double) { // Called periodically to report upload progress (0.0 - 100.0) // Example: update a progress bar } override fun onSuccess(timiMillis: Long) { // Called when the upload completes successfully // timiMillis indicates how long the upload took } override fun onError(error: String, timiMillis: Long) { // Called when an error occurs during upload // error provides the error message // timiMillis indicates how long the upload lasted before failing } override fun onNetworkStateChange(isOnline: Boolean) { // Called when the network connectivity changes // isOnline indicates whether the device is currently online or offline } override fun onUploadInit() { // Called when the upload process is initialized // Use this to show an initial loading state or setup UI } override fun onAbort() { // Called when the upload is manually aborted // Use this to clean up UI or notify the user } override fun onChunkHandled( totalChunks: Int, filSizeInBytes: Long, currentChunk: Int, currentChunkSizeInBytes: Long ) { // Called after a chunk is successfully uploaded // totalChunks: total number of chunks to upload // filSizeInBytes: total file size // currentChunk: index of the currently uploaded chunk // currentChunkSizeInBytes: size of the uploaded chunk } override fun onChunkUploadingFailed( failedChunkRetries: Int, chunkCount: Int, chunkSize: Long ) { // Called when a chunk fails to upload after retry attempts // failedChunkRetries: number of retries attempted for the chunk // chunkCount: index of the failed chunk // chunkSize: size of the failed chunk } override fun onPauseUploading() { // Called when the upload is paused // Use this to reflect paused state in UI } override fun onResumeUploading() { // Called when the upload resumes after being paused // Use this to resume UI indicators or timers } } ``` ```java public class MyUploadCallback implements FastPixUploadCallbacks { @Override public void onProgressUpdate(double progress) { // Called periodically to report upload progress (0.0 - 100.0) // Example: update a progress bar } @Override public void onSuccess(long timiMillis) { // Called when the upload completes successfully // timiMillis indicates how long the upload took } @Override public void onError(String error, long timiMillis) { // Called when an error occurs during upload // error provides the error message // timiMillis indicates how long the upload lasted before failing } @Override public void onNetworkStateChange(boolean isOnline) { // Called when the network connectivity changes // isOnline indicates whether the device is currently online or offline } @Override public void onUploadInit() { // Called when the upload process is initialized // Use this to show an initial loading state or setup UI } @Override public void onAbort() { // Called when the upload is manually aborted // Use this to clean up UI or notify the user } @Override public void onChunkHandled(int totalChunks, long filSizeInBytes, int currentChunk, long currentChunkSizeInBytes) { // Called after a chunk is successfully uploaded // totalChunks: total number of chunks to upload // filSizeInBytes: total file size // currentChunk: index of the currently uploaded chunk // currentChunkSizeInBytes: size of the uploaded chunk } @Override public void onChunkUploadingFailed(int failedChunkRetries, int chunkCount, long chunkSize) { // Called when a chunk fails to upload after retry attempts // failedChunkRetries: number of retries attempted for the chunk // chunkCount: index of the failed chunk // chunkSize: size of the failed chunk } @Override public void onPauseUploading() { // Called when the upload is paused // Use this to reflect paused state in UI } @Override public void onResumeUploading() { // Called when the upload resumes after being paused // Use this to resume UI indicators or timers } } ``` \ ## Manage video uploads You can control the upload lifecycle with the following methods: \ ### Pause an upload: ```kotlin sdk.pauseUploading() ``` \ ### Resume an upload: ```kotlin sdk.resumeUploading() ``` \ ### Abort an upload: ``` sdk.abort() ``` \ ## Usage example of Android uploads SDK The following examples give an overview of integrating the FastPix Android Uploads SDK into your project, enabling you to build a fully customized upload interface. By making use of the SDK's lifecycle events and configurable attributes, you can enhance functionality and optimize the upload experience. \ ```kotlin class UploadActivity : AppCompatActivity(), FastPixUploadCallbacks { private lateinit var sdk: FastPixUploadSdk override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val file = File(filesDir, "your-video.mp4") val signedUrl = "https://your-signed-upload-url" // Replace with actual signed URL val chunkSize = 5 // Chunk size in MB sdk = FastPixUploadSdk.Builder(this) .setFile(file) .setSignedUrl(signedUrl) .setChunkSize(chunkSize * 1024 * 1024) // Convert MB to bytes .setMaxRetries(3) // Optional: Number of retries for failed chunks .setRetryDelay(2000) // Optional: Delay between retries in milliseconds .callback(this) // Set this activity as the callback handler .build() sdk.startUpload() // Start the upload } // === FastPixUploadCallbacks Implementation === override fun onProgressUpdate(progress: Double) { // Called periodically to report upload progress (0.0 - 100.0) Log.d("Upload", "Progress: $progress%") } override fun onSuccess(timiMillis: Long) { // Called when the upload completes successfully Log.d("Upload", "Upload completed in $timiMillis ms") } override fun onError(error: String, timiMillis: Long) { // Called when an error occurs during upload Log.e("Upload", "Error: $error after $timiMillis ms") } override fun onNetworkStateChange(isOnline: Boolean) { // Called when the network connectivity changes Log.d("Upload", if (isOnline) "Back online" else "Offline") } override fun onUploadInit() { // Called when the upload process is initialized Log.d("Upload", "Upload initialized") } override fun onAbort() { // Called when the upload is manually aborted Log.d("Upload", "Upload aborted by user") } override fun onChunkHandled( totalChunks: Int, filSizeInBytes: Long, currentChunk: Int, currentChunkSizeInBytes: Long ) { // Called after a chunk is successfully uploaded Log.d("Upload", "Uploaded chunk $currentChunk/$totalChunks") } override fun onChunkUploadingFailed( failedChunkRetries: Int, chunkCount: Int, chunkSize: Long ) { // Called when a chunk fails after all retry attempts Log.e("Upload", "Chunk $chunkCount failed after $failedChunkRetries retries") } override fun onPauseUploading() { // Called when the upload is paused Log.d("Upload", "Upload paused") } override fun onResumeUploading() { // Called when the upload resumes Log.d("Upload", "Upload resumed") } } ``` ```java class UploadActivity : AppCompatActivity(), FastPixUploadCallbacks { private lateinit var sdk: FastPixUploadSdk override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val file = File(filesDir, "your-video.mp4") val signedUrl = "https://your-signed-upload-url" // Replace with actual signed URL val chunkSize = 5 // Chunk size in MB sdk = FastPixUploadSdk.Builder(this) .setFile(file) .setSignedUrl(signedUrl) .setChunkSize(chunkSize * 1024 * 1024) // Convert MB to bytes .setMaxRetries(3) // Optional: Number of retries for failed chunks .setRetryDelay(2000) // Optional: Delay between retries in milliseconds .callback(this) // Set this activity as the callback handler .build() sdk.startUpload() // Start the upload } // === FastPixUploadCallbacks Implementation === override fun onProgressUpdate(progress: Double) { // Called periodically to report upload progress (0.0 - 100.0) Log.d("Upload", "Progress: $progress%") } override fun onSuccess(timiMillis: Long) { // Called when the upload completes successfully Log.d("Upload", "Upload completed in $timiMillis ms") } override fun onError(error: String, timiMillis: Long) { // Called when an error occurs during upload Log.e("Upload", "Error: $error after $timiMillis ms") } override fun onNetworkStateChange(isOnline: Boolean) { // Called when the network connectivity changes Log.d("Upload", if (isOnline) "Back online" else "Offline") } override fun onUploadInit() { // Called when the upload process is initialized Log.d("Upload", "Upload initialized") } override fun onAbort() { // Called when the upload is manually aborted Log.d("Upload", "Upload aborted by user") } override fun onChunkHandled( totalChunks: Int, filSizeInBytes: Long, currentChunk: Int, currentChunkSizeInBytes: Long ) { // Called after a chunk is successfully uploaded Log.d("Upload", "Uploaded chunk $currentChunk/$totalChunks") } override fun onChunkUploadingFailed( failedChunkRetries: Int, chunkCount: Int, chunkSize: Long ) { // Called when a chunk fails after all retry attempts Log.e("Upload", "Chunk $chunkCount failed after $failedChunkRetries retries") } override fun onPauseUploading() { // Called when the upload is paused Log.d("Upload", "Upload paused") } override fun onResumeUploading() { // Called when the upload resumes Log.d("Upload", "Upload resumed") } } ``` \ --- \ ## Changelog All notable changes to the Upload SDK for android will be documented below. \ ### Current version ### \[2.0.0] A full rewrite of the upload engine for spec-compliant, production-grade GCS resumable uploads. **Breaking:** the public API has changed — see the migration table in the README. #### Added * **New public API** under `io.fastpix.uploads`: * `FastPixUploader` (replaces `FastPixUploadSdk`) with a fluent `Builder` and `start()` / `pause()` / `resume()` / `cancel()` methods. * `UploadListener` (replaces `FastPixUploadCallbacks`) with no-op defaults — override only what you need. New callbacks: `onStateChange(UploadState)`, `onPrepared(...)`, `onChunkUploaded(...)`, `onRetryScheduled(...)`, `onCancelled(...)`. * `UploadState` enum (`IDLE`, `PREPARING`, `UPLOADING`, `PAUSED`, `RETRYING`, `NETWORK_LOST`, `QUERYING_STATUS`, `COMPLETED`, `FAILED`, `CANCELLED`) for explicit lifecycle modelling. * `UploadError` sealed class with typed variants: `InvalidConfiguration`, `FileNotFound`, `FileNotReadable`, `FileEmpty`, `FileReadFailure`, `NetworkFailure`, `SessionExpired` (HTTP 410), `ClientError(code)`, `ServerError(code)`, `RetryLimitExceeded`, `UnexpectedResponse`. * **GCS spec compliance:** * Chunk PUTs with `Content-Range: bytes start-end/total`; non-final chunk size enforced as a multiple of 256 KiB at build time. * Server-authoritative resume: parses the `Range` header from `308 Resume Incomplete` and resumes from `last + 1`. Handles 308 without a `Range` header (resume from byte 0) per spec. * **Always issues a status query** (`PUT` with `Content-Range: bytes */TOTAL`, empty body) before resuming after pause, network loss, or transient failure — never assumes how much the server has. * HTTP 410 → `UploadError.SessionExpired`. Retryable: 408, 429, 5xx. Fatal: other 4xx. * **Smooth, monotonic progress.** Updates fire as each chunk streams (no longer only at chunk boundaries), throttled to one event per integer-percent change. A CAS-guarded high-water mark ensures progress never regresses on retry. * **Explicit upload state machine** with validated transitions. Structurally impossible to send a chunk PUT after pause/retry/network-loss without first going through `QUERYING_STATUS`. * **Single-threaded engine.** All state mutations serialised on one executor; OkHttp callbacks, network events, consumer commands, and retry timers all funnel through it. No race conditions. * **Multi-transport network awareness.** Tracks the active set of networks with INTERNET capability; only signals offline when *all* transports drop. Transient WiFi/cellular handover events no longer trip false `NETWORK_LOST`. * **Configurable retry policy.** Full-jitter exponential backoff (`retryBaseDelay`, `retryMaxDelay`), bounded by `maxRetries`. * **Main-thread callback dispatch by default.** Listener calls land on the main looper; consumers no longer need `runOnUiThread` wrappers. Override via `Builder.callbackExecutor(Executor)`. * **Optional HTTP logging** via `Builder.debugLogging(true)`. Off by default — release builds no longer leak signed session URIs to logcat. * **JUnit unit tests** for `GcsResumableProtocol`, `UploadStateMachine`, `RetryPolicy`, and `CallbackDispatcher` (47 tests total). #### Fixed * **Retries no longer silently disabled after the first successful chunk.** The retry executor is now permanent for the upload's lifetime; previously a `CoroutineScope.cancel()` killed it after chunk 1, causing later failures to hang forever. * **Network failures are now routed through the retry path.** Previously any `IOException` (broken pipe, DNS hiccup, TLS reset, OkHttp cancel) terminated the upload with `onError`. Now classified, backed off, and resumed via status query. * **`onSuccess`, `onFailure`, and `onCancelled` now actually fire.** A "defense in depth" terminated-flag silently dropped the terminal callback itself. Removed. * **`cancel()` no longer double-fires `onError` + `onCancelled`.** OkHttp call cancellation is now correctly distinguished from real failures via a generation counter. * **`pause()` no longer leaks as `onError`.** Intentional cancellations are detected in `onFailure` and suppressed. * **`NetworkCallback` no longer leaks across uploads.** Per-uploader registration with explicit `unregisterNetworkCallback` on terminal. * **Working Wi-Fi no longer falsely reported as `NETWORK_LOST`.** Dropped the `NET_CAPABILITY_VALIDATED` requirement, which is gated on a probe to Google's `connectivitycheck` endpoint and is missing for the first few seconds of a fresh connection (and indefinitely on networks where that endpoint is blocked, e.g. corporate Wi-Fi). * **Transient losses during WiFi/cellular handover no longer trigger `NETWORK_LOST`.** Network state is now derived from the *set* of matching networks; offline is signalled only when all transports drop. * **File reads no longer silently misalign on large files.** `RandomAccessFile.seek()` replaces `InputStream.skip()`, which was allowed to skip fewer bytes than requested. * **OkHttp no longer silently re-PUTs bodies on connection failure.** `retryOnConnectionFailure(false)` lets the upload engine own all retry semantics. * **Public commands after terminal state no longer crash.** `cancel()` called twice, late OkHttp callbacks, and late connectivity events post-teardown now silently no-op instead of throwing `RejectedExecutionException`. #### Changed * **Minimum SDK** bumped from API 21 to API 24. * **Default chunk size** changed from 16 MiB to 8 MiB (the GCS-recommended value). * **Method renames** (see migration table in README): `setSignedUrl` → `sessionUri`, `setFile` → `file`, `setChunkSize` → `chunkSize`, `setMaxRetries` → `maxRetries`, `setRetryDelay` → `retryBaseDelay` + `retryMaxDelay`, `callback` → `listener`, `startUpload` → `start`, `pauseUploading` → `pause`, `resumeUploading` → `resume`, `abort` → `cancel`. * **Errors:** `UploadExceptions` and its subclasses replaced with the `UploadError` sealed hierarchy. #### Removed * `FastPixUploadSdk`, `FastPixUploadCallbacks`, `UploadExceptions`, `StreamingFileRequestBody`, `RetryHelper`, `NetworkHandler`, `UploadEventType`. ### Previous version #### v1.0.1 * Implemented support for Google Cloud Storage resumable uploads and chunked client uploads. * Added retry mechanism with exponential backoff for GCS upload failures based on retryable status codes. * Enabled support for user-provided signed URLs, allowing resumable uploads to work with externally generated session URIs. * Updated the API endpoint from [https://v1.fastpix.io/on-demand/uploads](https://v1.fastpix.io/on-demand/uploads) to [https://api.fastpix.com/v1/on-demand/upload](https://api.fastpix.com/v1/on-demand/upload) for obtaining signed URLs. \ #### v1.0.0 **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 for 5 times 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. \ > The single API stack for video: upload, encode, stream, secure, and analyze video at any scale. Explore guides, API references, and SDKs.