Immich Cloud Photos
2.1.2 · GitHub
More about this app
Cloud media provider that surfaces a self-hosted Immich library in Android's system photo picker, configured via Shizuku or ADB.
Immich Cloud Photos
An Android Cloud Media Provider that integrates your self-hosted Immich server with the system photo picker. Browse and select your Immich photos and videos directly from any app that uses Android's built-in photo picker.
Installation
Or download the latest APK from the Releases page.
Requirements
- Android 13 or later (API 33)
- An Immich server instance
Setup
- Install the app and log in with your Immich server URL and credentials (email/password or API key). If you use an API key, give it the six permissions below.
- Enable the cloud media provider via ADB. The app shows the right command for your Android version, ready to copy, and can also run it through Shizuku.
# Android 15 and later
adb shell device_config override mediaprovider allowed_cloud_providers codes.dreaming.cloudmedia
# Android 14
adb shell device_config put mediaprovider allowed_cloud_providers codes.dreaming.cloudmedia
# Android 13
adb shell device_config put storage_native_boot allowed_cloud_providers codes.dreaming.cloudmedia.cloudmedia
adb shell device_config put mediaprovider allowed_cloud_providers codes.dreaming.cloudmedia
For the debug build, replace codes.dreaming.cloudmedia with codes.dreaming.cloudmedia.debug in each command. Android 13 and 14 have no override command. A server flag sync can reset a value set with put, so run it again if Immich disappears from the picker. If the picker does not show Immich right away, reboot the phone.
Android 13 needs two commands because the setting moved. The MediaProvider that ships with Android 13 reads the provider authority from storage_native_boot, and only when it starts, so reboot after you run the commands. A MediaProvider updated through Google Play system updates reads the package name from mediaprovider.
- Open any app's photo picker. Your Immich library appears as a cloud source.
An API key needs six permissions
If you log in with an API key, give the key these permissions in Immich under Account Settings > API Keys. Email/password and SSO logins do not use them. Endpoint paths are relative to your server's /api.
| Permission | Endpoints the app calls | Used for |
|---|---|---|
user.read |
GET /users/me |
Checking the key at login and showing the account name |
album.read |
GET /albums |
Listing albums |
asset.read |
GET /timeline/buckets, POST /search/metadata, POST /search/smart |
Listing the timeline, album contents, and search results, and detecting new and deleted photos |
asset.view |
GET /assets/{id}/thumbnail, GET /assets/{id}/video/playback |
Thumbnails, previews, and video playback |
asset.download |
GET /assets/{id}/original |
Full-resolution files |
person.read |
GET /people, GET /people/{id}/thumbnail |
People and their face thumbnails |
A key with all also works. The key does not need sync.stream. With an API key, the app checks GET /timeline/buckets for changes and never calls the sync endpoints, because Immich 3 rejects API keys there.
Features
- Browse all photos and videos from your Immich server in the system photo picker
- Album support with full asset browsing
- People/face recognition categories (Android 16 and later)
- Smart search across your library (Android 16 and later)
- Video playback with streaming support
- Thumbnail previews and full-resolution downloads on demand
Building from source
# Debug build
./gradlew assembleDebug
# Release build
./gradlew assembleRelease
Requires JDK 17.
License
This project is not affiliated with or endorsed by Immich.
How Shizuku is used
Can register and unregister the app as a system photo picker cloud provider via `device_config` through Shizuku.
This is an AI-assisted analysis of Shizuku-related usages in the app's public source code. It is best effort, so it may not catch every single usage.
How this app uses Shizuku
Shizuku is used to allowlist this app as a cloud media provider so a self hosted Immich library appears in Android's system photo picker.
- Enable cloud provider: tapping enable registers the app with the system photo picker using the
device_config overrideshell command through Shizuku (usingdevice_config puton older Android versions, with an extra key on Android 13 and below). - Disable cloud provider: tapping disable removes the registration using the
device_config clear_overrideshell command through Shizuku (usingdevice_config deleteon older Android versions, clearing both keys on Android 13 and below).
Android APIs or commands used
device_config override mediaprovider allowed_cloud_providersdevice_config clear_override mediaprovider allowed_cloud_providersdevice_config put mediaprovider allowed_cloud_providersdevice_config delete mediaprovider allowed_cloud_providersdevice_config put storage_native_boot allowed_cloud_providersdevice_config delete storage_native_boot allowed_cloud_providers
Notable details
The same enable and disable operations can be done without Shizuku by running the displayed ADB commands from a computer, which the app offers to copy. On Android 13 and below the change needs a reboot to take effect.
Changelog
What's new for version 2.1.2
Fixes
- Cloud media on first open. The picker could open without your Immich photos the first time it connected to the app after a restart. Android hides cloud media until the app returns its library info, and the app waited for a server request before it answered. The app now returns the library info it already has right away, then checks the server in the background. (#29, #30, closes #28 reported by @TrafficDemotion)
- Change notifications. When the app found new or deleted photos, its notification never reached the picker. The app now uses the Android API for cloud media changes, so the picker syncs again on its own. (#30)
- Deleted photos. The app could mark deletions as seen on the server before the picker read them, so the picker could miss them. Repeated change checks also restarted the sync for the same changes. Each set of changes now triggers one sync, and the app keeps it until the picker reads the deletions and the server confirms them. (#30)
Full Changelog: https://github.com/Dreaming-Codes/immich-cloud-media/compare/v2.1.1...v2.1.2
Permissions
7 permissions requested
