Mobile capture and backup
Mobile capture and backup moves media from the device library to the Immich server. The mobile app discovers local albums and media, lets the user define the backup scope, prepares media for upload, and runs uploads while the app is open or in an OS-managed background task. This page complements mobile application architecture, mobile library synchronization, sync and client state, native media core, and asset lifecycle and media processing.
Media discovery
The mobile app treats the device media library as the source of capture data. It keeps a local view of device albums and assets so that later backup work can use stable local records instead of scanning the whole library for every upload.
Device media catalog
The local sync flow reads album and media changes from the platform media library. It supports both a full refresh and a smaller change set, then updates the local album and asset view. On iOS it also refreshes cloud-backed albums because their changes are not always part of the normal change set. See mobile library synchronization for the wider sync model.
References: mobile/…/local_sync.service.dart• L45-126 mobile/…/local_sync.service.dart• L128-171
Local media access
Local media access turns device-library records into media data for app views and later media work. On Android it reads encoded images, creates bounded image and video previews, applies image orientation, and converts decoded pixels into buffers that the shared app can use. Requests can be cancelled when the owning view or task no longer needs the data. The same bridge decodes thumbhash data for lightweight image placeholders.
References: mobile/…/LocalImagesImpl.kt• L115-317 mobile/…/NativeBuffer.kt• L7-29 mobile/…/NativeImage.kt• L5-27 mobile/…/ThumbHash.kt• L3-9
Media availability
An asset can be known to the device while its original file is not stored locally. Before upload, the app checks availability and can request a temporary copy from iCloud on iOS. The copy supports normal media and the motion part of a Live Photo, reports progress to the backup view, and is removed after use.
References: mobile/…/storage.repository.dart• L15-35 mobile/…/storage.repository.dart• L90-155 mobile/…/foreground_upload.service.dart• L244-317
Backup scope
Backup scope is the set of device albums that the user marks for upload. The app also supports exclusions so that one asset is not uploaded when it appears in both an included and an excluded album.
Album selection
The backup screen shows device albums and lets the user select, clear, or exclude them. The selection is stored with the local album record, so it remains available to foreground and background runs. A selected album can also be linked to a server album when album sync is enabled.
References: mobile/…/backup_album_selection.page.dart• L84-147 mobile/…/backup_album.provider.dart• L13-46 mobile/…/local_album.model.dart• L6-25
Candidate set
The candidate set contains assets in selected albums that are not in excluded albums and do not already match a server asset owned by the current user. This gives backup a stable answer to “what remains” and lets uploads from another client or device count as already backed up.
References: mobile/…/backup.repository.dart• L17-35 mobile/…/backup.repository.dart• L37-80 mobile/…/backup.repository.dart• L82-114
Hash preparation
The app hashes media before it uses the candidate set. A content hash acts as the match key for local media and server assets, so the app can skip duplicates without relying only on file names or device IDs. Hashing may use cloud access for media in selected albums.
References: mobile/…/hash.service.dart• L40-80 mobile/…/hash.service.dart• L83-146
Upload flows
Backup uses two upload modes because an active app and a suspended app have different time and network limits. Both modes use the same backup scope and candidate rules, while the platform chooses how long the work can continue.
Foreground upload
When the app is open, the backup screen first refreshes remote state and then starts a foreground upload for the remaining candidates. The app can upload several items at once, pause the run through cancellation, and show per-item progress, speed, errors, and iCloud download progress.
The same foreground path also serves direct user actions such as uploading selected media and uploading files received from the device share flow. These actions are not dependent on automatic backup being enabled.
References: mobile/…/backup.page.dart• L41-104 mobile/…/foreground_upload.service.dart• L52-114 mobile/…/foreground_upload.service.dart• L141-189 mobile/…/upload.action.dart• L21-107
Background upload
The background path runs after local discovery, remote sync, and hashing make enough state available. Android performs a bounded sequential upload in its background worker. iOS hands upload tasks to the platform background transfer service so work can continue after the app is suspended. Failed work can be retried by a later background run.
The diagram shows the shared preparation stages and the platform-specific upload paths.
flowchart TD
A[OS background opportunity or app resume] --> B[Sync device media]
B --> C[Sync remote state]
C --> D[Hash new media]
D --> E{Backup enabled?}
E -- No --> F[End run]
E -- Yes --> G[Build backup candidates]
G --> H{Platform}
H -- Android --> I[Bounded foreground upload]
H -- iOS --> J[Background transfer queue]
I --> K[Record result and retry failures]
J --> K
References: mobile/…/background_worker.service.dart• L146-203 mobile/…/background_worker.service.dart• L205-243 mobile/…/background_worker.service.dart• L297-331 mobile/…/background_upload.service.dart• L147-177
Asset upload shape
Each upload carries the device asset identity and media dates so the server can relate the upload to its source. Live Photos use a two-part flow: the motion video is sent first, then the still image refers to that video. The server can then treat the pair as one captured item.
References: mobile/…/foreground_upload.service.dart• L314-405 mobile/…/background_upload.service.dart• L274-377 mobile/…/background_upload.service.dart• L391-455
Background execution
Background execution is an opportunity supplied by the operating system, not a promise that the app can run at any time. The app configures the worker with user limits and stops work when the platform time budget or cancellation signal ends.
Android execution controls
Android exposes controls for charging-only work and for the delay between capture and a background run. Battery optimization and notification permissions affect how reliably the user can see and trust background backup, so the backup screen surfaces these states and points the user to system settings when needed.
References: mobile/…/backup_settings.dart• L24-38 mobile/…/backup_settings.dart• L212-287 mobile/…/backup.page.dart• L187-311 mobile/…/background_worker.service.dart• L38-63
iOS execution controls
iOS controls when a background refresh or transfer can run. The app must fit local sync, remote sync, hashing, and upload into the time supplied by the OS. Background transfer tasks can resume after suspension, but the app cannot turn that scheduling window into continuous execution.
References: mobile/…/background_worker.service.dart• L158-203 mobile/…/background_upload.service.dart• L84-88 mobile/…/background_upload.service.dart• L137-197 docs/…/mobile-backup.md• L71-85
Permission boundaries
Media capture depends on permission to read the device library. The app maps platform-specific permission rules to one gallery status, while other permissions affect only optional behavior such as media location, notifications, or Android media management.
Gallery access
The permission service requests the platform permission that matches the device. Older Android versions use shared storage access. Newer versions request photo and video access separately, and supported Android versions also request media-location access when gallery access succeeds. A limited result still means that the app can see only part of the library.
References: mobile/…/device_permission.service.dart• L7-47 mobile/…/permission.repository.dart• L13-32 mobile/…/gallery_permission.provider.dart• L8-29
Permission-sensitive media work
Missing gallery access limits discovery and therefore limits backup candidates. Missing Android media-management access prevents the background sync from processing media in the device trash. Permission failure is kept separate from upload failure so the user can correct the system setting instead of treating the media as a bad upload.
References: mobile/…/local_sync.service.dart• L45-55 mobile/…/permission.repository.dart• L50-64 mobile/…/backup.page.dart• L208-230
User controls and status
The backup screen is the user-facing control point for scope, start and stop actions, network rules, background rules, album links, and work status. Its counts distinguish all media in scope, media already backed up, media still remaining, and media still being prepared.
Backup settings
The user can enable cellular transfer for photos or videos. On Android the user can also require charging and set the background delay. Album sync is a separate switch that creates or updates server albums to reflect selected device albums; it is one-way from the device to the server.
References: mobile/…/backup_settings.dart• L19-40 mobile/…/backup_settings.dart• L43-145 mobile/…/backup_settings.dart• L184-287 mobile/…/backup_config.dart• L6-15
Widget library access
The iOS widget is a read-only view of the server library rather than a device-media backup path. A user can choose a server album or favorites, show its name, and open a displayed asset in the app. The widget uses the app group session settings to request random assets and resized previews, then keeps the last image for transient fetch failures.
The widget separates missing login, connection failure, missing albums, and empty results. This gives the user a clear action for setup problems while keeping a cached image available when the server is temporarily unreachable.
References: mobile/…/ImmichAPI.swift• L7-35 mobile/…/ImmichAPI.swift• L106-202 mobile/…/ImmichAPI.swift• L292-339 mobile/…/ImageEntry.swift• L6-16 mobile/…/ImageEntry.swift• L46-113 mobile/…/RandomWidget.swift• L7-53 mobile/…/RandomWidget.swift• L57-140
Progress and recovery
The backup view reports preparation and upload progress rather than treating the whole run as one opaque task. A user can stop a foreground run, inspect failed items, and start again. A remote sync failure blocks the next backup start because the candidate view may not yet represent the server state.
References: mobile/…/backup.page.dart• L85-169 mobile/…/backup.page.dart• L417-535 mobile/…/backup.provider.dart• L33-70 mobile/…/backup.provider.dart• L124-160
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the album selection rules aligned with candidate counting and candidate listing. A mismatch can show a count for media that the uploader will skip.
- Keep content-hash matching aligned with the server asset identity used by remote sync. A change can create duplicate uploads or hide media from the remainder count.
- Keep the foreground and background upload paths aligned for network rules, Live Photo pairing, and media metadata. Users can otherwise see different results for the same backup run.
- Keep Android worker settings aligned with the visible backup controls. A stored setting that is not applied to the worker silently changes background behavior.
- Keep permission status and media discovery behavior aligned. A limited gallery result must not be presented as a complete library.
- Keep temporary cloud-file cleanup paired with every iOS upload path. A change can leave large media copies in the device cache.
- Keep Android local media reads aligned with the shared image buffer contract. A mismatch can corrupt previews or leave native memory allocated after a cancelled request.
- Keep iOS widget credentials, album filters, and cached-entry keys aligned. A mismatch can make a valid widget configuration show the wrong album or a stale error.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Remote sync does not complete | The app skips the backup start because the candidate view may be stale | Run remote sync before foreground backup and report the sync error |
| Gallery permission is denied or limited | The app discovers no media or only part of the device library | Request the platform-specific permission and show the resulting access state |
| Android battery optimization blocks the worker | Automatic backup may not run when the user expects | Surface the battery setting and explain that the OS can stop background work |
| An iCloud original cannot be loaded | The asset remains unuploaded and the upload reports a device or cloud-file error | Check local availability, show download progress, and remove temporary files after the attempt |
| Cellular use is disabled for the asset type | The upload waits for an unmetered network | Apply the photo and video network settings to both upload modes |
| A Live Photo part fails | The server may receive only one part of the pair | Upload the motion part first and link the still image to its returned asset |
| An Android media read is cancelled after native data is created | A preview can be lost or native memory can remain allocated | Deliver or free the owned buffer according to the shared cancellation contract |
| The iOS widget has no shared server credentials | The widget shows a login state instead of library media | Keep the app group settings in sync with the signed-in server session |
| A widget request returns no assets or a stale album | The widget shows an empty or outdated result | Refresh the album source and distinguish empty results from network errors |
Key files
| File | Why to read it |
|---|---|
mobile/lib/pages/backup/backup.page.dart | Main user flow for album scope, remote preparation, foreground start and stop, counts, and permission notices |
mobile/lib/pages/backup/backup_album_selection.page.dart | User flow for selecting and excluding device albums and starting linked album work |
mobile/lib/widgets/settings/backup_settings/backup_settings.dart | User-facing network, charging, delay, and album-sync controls |
mobile/lib/domain/services/local_sync.service.dart | Device media discovery and the local album and asset view used by backup |
mobile/lib/domain/services/hash.service.dart | Hash preparation that enables duplicate matching and upload readiness |
mobile/lib/infrastructure/repositories/backup.repository.dart | The high-level rules for counts and the backup candidate set |
mobile/lib/services/foreground_upload.service.dart | Open-app upload behavior, device-file access, iCloud handling, and Live Photo upload order |
mobile/lib/services/background_upload.service.dart | OS transfer queue behavior for suspended-app uploads and task recovery |
mobile/lib/domain/services/background_worker.service.dart | Android and iOS background run boundaries and preparation order |
mobile/lib/domain/services/device_permission.service.dart | Platform-specific gallery permission policy |
| mobile/…/LocalImagesImpl.kt | Android access to local image and video data, previews, cancellation, and placeholder input |
| mobile/…/NativeImage.kt | Android image conversion and orientation support for shared media buffers |
| mobile/…/ThumbHash.kt | Android bridge for decoding lightweight image placeholders |
| mobile/…/ImmichAPI.swift | Server access and album or asset queries used by the iOS widget |
| mobile/…/ImageEntry.swift | Widget image entries, cache behavior, deep links, and user-visible error states |
| mobile/…/RandomWidget.swift | Widget album selection and timeline behavior |