add docs part 1
This commit is contained in:
214
docs/download.md
Normal file
214
docs/download.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user