Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / mobile-capture-and-backup

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.

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

TriggerConsequenceGuard
Remote sync does not completeThe app skips the backup start because the candidate view may be staleRun remote sync before foreground backup and report the sync error
Gallery permission is denied or limitedThe app discovers no media or only part of the device libraryRequest the platform-specific permission and show the resulting access state
Android battery optimization blocks the workerAutomatic backup may not run when the user expectsSurface the battery setting and explain that the OS can stop background work
An iCloud original cannot be loadedThe asset remains unuploaded and the upload reports a device or cloud-file errorCheck local availability, show download progress, and remove temporary files after the attempt
Cellular use is disabled for the asset typeThe upload waits for an unmetered networkApply the photo and video network settings to both upload modes
A Live Photo part failsThe server may receive only one part of the pairUpload the motion part first and link the still image to its returned asset
An Android media read is cancelled after native data is createdA preview can be lost or native memory can remain allocatedDeliver or free the owned buffer according to the shared cancellation contract
The iOS widget has no shared server credentialsThe widget shows a login state instead of library mediaKeep the app group settings in sync with the signed-in server session
A widget request returns no assets or a stale albumThe widget shows an empty or outdated resultRefresh the album source and distinguish empty results from network errors

Key files

FileWhy to read it
mobile/lib/pages/backup/backup.page.dartMain user flow for album scope, remote preparation, foreground start and stop, counts, and permission notices
mobile/lib/pages/backup/backup_album_selection.page.dartUser flow for selecting and excluding device albums and starting linked album work
mobile/lib/widgets/settings/backup_settings/backup_settings.dartUser-facing network, charging, delay, and album-sync controls
mobile/lib/domain/services/local_sync.service.dartDevice media discovery and the local album and asset view used by backup
mobile/lib/domain/services/hash.service.dartHash preparation that enables duplicate matching and upload readiness
mobile/lib/infrastructure/repositories/backup.repository.dartThe high-level rules for counts and the backup candidate set
mobile/lib/services/foreground_upload.service.dartOpen-app upload behavior, device-file access, iCloud handling, and Live Photo upload order
mobile/lib/services/background_upload.service.dartOS transfer queue behavior for suspended-app uploads and task recovery
mobile/lib/domain/services/background_worker.service.dartAndroid and iOS background run boundaries and preparation order
mobile/lib/domain/services/device_permission.service.dartPlatform-specific gallery permission policy
mobile/…/LocalImagesImpl.ktAndroid access to local image and video data, previews, cancellation, and placeholder input
mobile/…/NativeImage.ktAndroid image conversion and orientation support for shared media buffers
mobile/…/ThumbHash.ktAndroid bridge for decoding lightweight image placeholders
mobile/…/ImmichAPI.swiftServer access and album or asset queries used by the iOS widget
mobile/…/ImageEntry.swiftWidget image entries, cache behavior, deep links, and user-visible error states
mobile/…/RandomWidget.swiftWidget album selection and timeline behavior