immish/docs/download.md

Download

This document describes the asset download functionality.

Download Overview

Users can download assets from the server to their device:

• Single asset download
• Bulk download
• Live photo handling
• Video download

Download Flow

┌─────────────────────────────────────────────────────────────┐
│                     Download Flow                            │
├─────────────────────────────────────────────────────────────┤
│  1. User initiates download                                 │
│  2. Create download task                                    │
│  3. Download file to temp directory                         │
│  4. Save to device gallery                                  │
│  5. Clean up temp file                                      │
│  6. Notify completion                                       │
└─────────────────────────────────────────────────────────────┘

Download API

Get Original Asset

GET /assets/{id}/original

Headers:
  Authorization: Bearer {token}

Response: Binary file data

Download Endpoint Pattern

{server_endpoint}/assets/{asset_id}/original

Download Task Configuration

Task Parameters

DownloadTask {
  taskId: String        // Usually asset remote ID
  url: String           // Download URL
  headers: Map          // Auth headers
  filename: String      // Target filename
  group: String         // Task group for tracking
  updates: Boolean      // Send progress updates
  metaData: String?     // Additional metadata (JSON)
}

Task Groups

Group	Purpose
group_image	Image downloads
group_video	Video downloads
group_livephoto	Live photo downloads

Download Types

Image Download

1. Create download task
2. Download to temp directory
3. Save to device gallery (DCIM/Immich)
4. Delete temp file

Video Download

Same as image, but:

• Larger file sizes
• Longer download times
• Progress tracking more important

Live Photo Download (iOS)

1. Download image component
2. Download video component
3. Combine as live photo
4. Save to gallery

Download Task 1: Image (original HEIC/JPG)
  metadata: { part: "image", id: "asset-id" }

Download Task 2: Video (motion MOV)
  metadata: { part: "video", id: "asset-id" }

When both complete → Combine and save

Download Progress

Progress Tracking

┌─────────────────────────────────────────────────────────────┐
│  Downloads                                              X   │
├─────────────────────────────────────────────────────────────┤
│  IMG_1234.jpg                                               │
│  [████████████████░░░░░░░░░░░░░] 65%                       │
│  2.4 MB / 3.7 MB                                           │
├─────────────────────────────────────────────────────────────┤
│  VID_5678.mp4                                               │
│  [████░░░░░░░░░░░░░░░░░░░░░░░░░] 12%                       │
│  15.2 MB / 128.4 MB                                        │
└─────────────────────────────────────────────────────────────┘

Progress Callbacks

onProgress(bytesReceived, totalBytes)
onStatusChange(taskId, status)
onComplete(taskId, filePath)
onError(taskId, error)

Bulk Download

Multiple Asset Download

1. Create download task for each asset
2. Queue all tasks
3. Download in parallel (max 6 concurrent)
4. Track overall progress
5. Report failures individually

Parallel Download Limits

• Max concurrent: 6
• Max per host: 6
• Max per group: 3

Save Locations

Android

DCIM/Immich/
  ├── IMG_1234.jpg
  ├── VID_5678.mp4
  └── ...

iOS

• Saved to Photos app
• In "Immich" album (if created)
• Respects photo permissions

Cancel Download

Cancel Single

Cancel task by taskId

Cancel All

Cancel all tasks in download queue

Error Handling

Common Errors

Error	Description	Action
Network error	Connection lost	Retry
Storage full	No space on device	Alert user
File not found	Asset deleted on server	Skip
Permission denied	Gallery access denied	Request permission

Retry Logic

• Automatic retry on network errors
• Exponential backoff
• Max 3 retries

Download Notification

Progress Notification

┌─────────────────────────────────────────────────────────────┐
│  Immich                                                     │
│  Downloading 3 items...                                     │
│  [Progress bar]                                             │
└─────────────────────────────────────────────────────────────┘

Completion Notification

┌─────────────────────────────────────────────────────────────┐
│  Immich                                                     │
│  Download complete                                          │
│  3 items saved to gallery                                   │
└─────────────────────────────────────────────────────────────┘

Large File Handling

Android Large Files

• Files > 256MB run in foreground service
• Shows persistent notification
• Prevents system kill

Background Download

• Can continue when app backgrounded
• System manages task lifecycle
• Resumes on network recovery

---

Previous: Backup & Upload | Next: Sharing