# 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](./backup.md) | [Next: Sharing](./sharing.md)