215 lines
6.8 KiB
Markdown
215 lines
6.8 KiB
Markdown
# 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)
|