feat: beta background sync (#21243)

* feat: ios background sync

# Conflicts:
#	mobile/ios/Runner/Info.plist

* feat: Android sync

* add local sync worker and rename stuff

* group upload notifications

* uncomment onresume beta handling

* rename methods

---------

Co-authored-by: shenlong-tanwen <139912620+shalong-tanwen@users.noreply.github.com>
Co-authored-by: Alex <alex.tran1502@gmail.com>

mobile/android/app/src/main/kotlin/app/alextran/immich/ImmichApp.kt

@@ -5,15 +5,15 @@ import androidx.work.Configuration
 import androidx.work.WorkManager
 
 class ImmichApp : Application() {
-    override fun onCreate() {
-        super.onCreate()
-        val config = Configuration.Builder().build()
-        WorkManager.initialize(this, config)
-        // always start BackupWorker after WorkManager init; this fixes the following bug:
-        // After the process is killed (by user or system), the first trigger (taking a new picture) is lost.
-        // Thus, the BackupWorker is not started. If the system kills the process after each initialization
-        // (because of low memory etc.), the backup is never performed.
-        // As a workaround, we also run a backup check when initializing the application
-        ContentObserverWorker.startBackupWorker(context = this, delayMilliseconds = 0)
-    }
-}
+  override fun onCreate() {
+    super.onCreate()
+    val config = Configuration.Builder().build()
+    WorkManager.initialize(this, config)
+    // always start BackupWorker after WorkManager init; this fixes the following bug:
+    // After the process is killed (by user or system), the first trigger (taking a new picture) is lost.
+    // Thus, the BackupWorker is not started. If the system kills the process after each initialization
+    // (because of low memory etc.), the backup is never performed.
+    // As a workaround, we also run a backup check when initializing the application
+    ContentObserverWorker.startBackupWorker(context = this, delayMilliseconds = 0)
+  }
+}

mobile/android/app/src/main/kotlin/app/alextran/immich/MainActivity.kt

@@ -1,8 +1,10 @@
 package app.alextran.immich
 
+import android.content.Context
 import android.os.Build
 import android.os.ext.SdkExtensions
-import androidx.annotation.NonNull
+import app.alextran.immich.background.BackgroundWorkerApiImpl
+import app.alextran.immich.background.BackgroundWorkerFgHostApi
 import app.alextran.immich.images.ThumbnailApi
 import app.alextran.immich.images.ThumbnailsImpl
 import app.alextran.immich.sync.NativeSyncApi
@@ -12,19 +14,26 @@ import io.flutter.embedding.android.FlutterFragmentActivity
 import io.flutter.embedding.engine.FlutterEngine
 
 class MainActivity : FlutterFragmentActivity() {
-  override fun configureFlutterEngine(@NonNull flutterEngine: FlutterEngine) {
+  override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
     super.configureFlutterEngine(flutterEngine)
-    flutterEngine.plugins.add(BackgroundServicePlugin())
-    flutterEngine.plugins.add(HttpSSLOptionsPlugin())
-    // No need to set up method channel here as it's now handled in the plugin
+    registerPlugins(this, flutterEngine)
+  }
 
-    val nativeSyncApiImpl =
-      if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R || SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) < 1) {
-        NativeSyncApiImpl26(this)
-      } else {
-        NativeSyncApiImpl30(this)
-      }
-      NativeSyncApi.setUp(flutterEngine.dartExecutor.binaryMessenger, nativeSyncApiImpl)
-      ThumbnailApi.setUp(flutterEngine.dartExecutor.binaryMessenger, ThumbnailsImpl(this))
+  companion object {
+    fun registerPlugins(ctx: Context, flutterEngine: FlutterEngine) {
+      flutterEngine.plugins.add(BackgroundServicePlugin())
+      flutterEngine.plugins.add(HttpSSLOptionsPlugin())
+
+      val messenger = flutterEngine.dartExecutor.binaryMessenger
+      val nativeSyncApiImpl =
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R || SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) < 1) {
+          NativeSyncApiImpl26(ctx)
+        } else {
+          NativeSyncApiImpl30(ctx)
+        }
+      NativeSyncApi.setUp(messenger, nativeSyncApiImpl)
+      ThumbnailApi.setUp(messenger, ThumbnailsImpl(ctx))
+      BackgroundWorkerFgHostApi.setUp(messenger, BackgroundWorkerApiImpl(ctx))
+    }
   }
 }

mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorker.g.kt

@@ -0,0 +1,238 @@
+// Autogenerated from Pigeon (v26.0.0), do not edit directly.
+// See also: https://pub.dev/packages/pigeon
+@file:Suppress("UNCHECKED_CAST", "ArrayInDataClass")
+
+package app.alextran.immich.background
+
+import android.util.Log
+import io.flutter.plugin.common.BasicMessageChannel
+import io.flutter.plugin.common.BinaryMessenger
+import io.flutter.plugin.common.EventChannel
+import io.flutter.plugin.common.MessageCodec
+import io.flutter.plugin.common.StandardMethodCodec
+import io.flutter.plugin.common.StandardMessageCodec
+import java.io.ByteArrayOutputStream
+import java.nio.ByteBuffer
+private object BackgroundWorkerPigeonUtils {
+
+  fun createConnectionError(channelName: String): FlutterError {
+    return FlutterError("channel-error",  "Unable to establish connection on channel: '$channelName'.", "")  }
+
+  fun wrapResult(result: Any?): List<Any?> {
+    return listOf(result)
+  }
+
+  fun wrapError(exception: Throwable): List<Any?> {
+    return if (exception is FlutterError) {
+      listOf(
+        exception.code,
+        exception.message,
+        exception.details
+      )
+    } else {
+      listOf(
+        exception.javaClass.simpleName,
+        exception.toString(),
+        "Cause: " + exception.cause + ", Stacktrace: " + Log.getStackTraceString(exception)
+      )
+    }
+  }
+}
+
+/**
+ * Error class for passing custom error details to Flutter via a thrown PlatformException.
+ * @property code The error code.
+ * @property message The error message.
+ * @property details The error details. Must be a datatype supported by the api codec.
+ */
+class FlutterError (
+  val code: String,
+  override val message: String? = null,
+  val details: Any? = null
+) : Throwable()
+private open class BackgroundWorkerPigeonCodec : StandardMessageCodec() {
+  override fun readValueOfType(type: Byte, buffer: ByteBuffer): Any? {
+    return     super.readValueOfType(type, buffer)
+  }
+  override fun writeValue(stream: ByteArrayOutputStream, value: Any?)   {
+    super.writeValue(stream, value)
+  }
+}
+
+/** Generated interface from Pigeon that represents a handler of messages from Flutter. */
+interface BackgroundWorkerFgHostApi {
+  fun enableSyncWorker()
+  fun enableUploadWorker(callbackHandle: Long)
+  fun disableUploadWorker()
+
+  companion object {
+    /** The codec used by BackgroundWorkerFgHostApi. */
+    val codec: MessageCodec<Any?> by lazy {
+      BackgroundWorkerPigeonCodec()
+    }
+    /** Sets up an instance of `BackgroundWorkerFgHostApi` to handle messages through the `binaryMessenger`. */
+    @JvmOverloads
+    fun setUp(binaryMessenger: BinaryMessenger, api: BackgroundWorkerFgHostApi?, messageChannelSuffix: String = "") {
+      val separatedMessageChannelSuffix = if (messageChannelSuffix.isNotEmpty()) ".$messageChannelSuffix" else ""
+      run {
+        val channel = BasicMessageChannel<Any?>(binaryMessenger, "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFgHostApi.enableSyncWorker$separatedMessageChannelSuffix", codec)
+        if (api != null) {
+          channel.setMessageHandler { _, reply ->
+            val wrapped: List<Any?> = try {
+              api.enableSyncWorker()
+              listOf(null)
+            } catch (exception: Throwable) {
+              BackgroundWorkerPigeonUtils.wrapError(exception)
+            }
+            reply.reply(wrapped)
+          }
+        } else {
+          channel.setMessageHandler(null)
+        }
+      }
+      run {
+        val channel = BasicMessageChannel<Any?>(binaryMessenger, "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFgHostApi.enableUploadWorker$separatedMessageChannelSuffix", codec)
+        if (api != null) {
+          channel.setMessageHandler { message, reply ->
+            val args = message as List<Any?>
+            val callbackHandleArg = args[0] as Long
+            val wrapped: List<Any?> = try {
+              api.enableUploadWorker(callbackHandleArg)
+              listOf(null)
+            } catch (exception: Throwable) {
+              BackgroundWorkerPigeonUtils.wrapError(exception)
+            }
+            reply.reply(wrapped)
+          }
+        } else {
+          channel.setMessageHandler(null)
+        }
+      }
+      run {
+        val channel = BasicMessageChannel<Any?>(binaryMessenger, "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFgHostApi.disableUploadWorker$separatedMessageChannelSuffix", codec)
+        if (api != null) {
+          channel.setMessageHandler { _, reply ->
+            val wrapped: List<Any?> = try {
+              api.disableUploadWorker()
+              listOf(null)
+            } catch (exception: Throwable) {
+              BackgroundWorkerPigeonUtils.wrapError(exception)
+            }
+            reply.reply(wrapped)
+          }
+        } else {
+          channel.setMessageHandler(null)
+        }
+      }
+    }
+  }
+}
+/** Generated interface from Pigeon that represents a handler of messages from Flutter. */
+interface BackgroundWorkerBgHostApi {
+  fun onInitialized()
+
+  companion object {
+    /** The codec used by BackgroundWorkerBgHostApi. */
+    val codec: MessageCodec<Any?> by lazy {
+      BackgroundWorkerPigeonCodec()
+    }
+    /** Sets up an instance of `BackgroundWorkerBgHostApi` to handle messages through the `binaryMessenger`. */
+    @JvmOverloads
+    fun setUp(binaryMessenger: BinaryMessenger, api: BackgroundWorkerBgHostApi?, messageChannelSuffix: String = "") {
+      val separatedMessageChannelSuffix = if (messageChannelSuffix.isNotEmpty()) ".$messageChannelSuffix" else ""
+      run {
+        val channel = BasicMessageChannel<Any?>(binaryMessenger, "dev.flutter.pigeon.immich_mobile.BackgroundWorkerBgHostApi.onInitialized$separatedMessageChannelSuffix", codec)
+        if (api != null) {
+          channel.setMessageHandler { _, reply ->
+            val wrapped: List<Any?> = try {
+              api.onInitialized()
+              listOf(null)
+            } catch (exception: Throwable) {
+              BackgroundWorkerPigeonUtils.wrapError(exception)
+            }
+            reply.reply(wrapped)
+          }
+        } else {
+          channel.setMessageHandler(null)
+        }
+      }
+    }
+  }
+}
+/** Generated class from Pigeon that represents Flutter messages that can be called from Kotlin. */
+class BackgroundWorkerFlutterApi(private val binaryMessenger: BinaryMessenger, private val messageChannelSuffix: String = "") {
+  companion object {
+    /** The codec used by BackgroundWorkerFlutterApi. */
+    val codec: MessageCodec<Any?> by lazy {
+      BackgroundWorkerPigeonCodec()
+    }
+  }
+  fun onLocalSync(maxSecondsArg: Long?, callback: (Result<Unit>) -> Unit)
+{
+    val separatedMessageChannelSuffix = if (messageChannelSuffix.isNotEmpty()) ".$messageChannelSuffix" else ""
+    val channelName = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.onLocalSync$separatedMessageChannelSuffix"
+    val channel = BasicMessageChannel<Any?>(binaryMessenger, channelName, codec)
+    channel.send(listOf(maxSecondsArg)) {
+      if (it is List<*>) {
+        if (it.size > 1) {
+          callback(Result.failure(FlutterError(it[0] as String, it[1] as String, it[2] as String?)))
+        } else {
+          callback(Result.success(Unit))
+        }
+      } else {
+        callback(Result.failure(BackgroundWorkerPigeonUtils.createConnectionError(channelName)))
+      } 
+    }
+  }
+  fun onIosUpload(isRefreshArg: Boolean, maxSecondsArg: Long?, callback: (Result<Unit>) -> Unit)
+{
+    val separatedMessageChannelSuffix = if (messageChannelSuffix.isNotEmpty()) ".$messageChannelSuffix" else ""
+    val channelName = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.onIosUpload$separatedMessageChannelSuffix"
+    val channel = BasicMessageChannel<Any?>(binaryMessenger, channelName, codec)
+    channel.send(listOf(isRefreshArg, maxSecondsArg)) {
+      if (it is List<*>) {
+        if (it.size > 1) {
+          callback(Result.failure(FlutterError(it[0] as String, it[1] as String, it[2] as String?)))
+        } else {
+          callback(Result.success(Unit))
+        }
+      } else {
+        callback(Result.failure(BackgroundWorkerPigeonUtils.createConnectionError(channelName)))
+      } 
+    }
+  }
+  fun onAndroidUpload(callback: (Result<Unit>) -> Unit)
+{
+    val separatedMessageChannelSuffix = if (messageChannelSuffix.isNotEmpty()) ".$messageChannelSuffix" else ""
+    val channelName = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.onAndroidUpload$separatedMessageChannelSuffix"
+    val channel = BasicMessageChannel<Any?>(binaryMessenger, channelName, codec)
+    channel.send(null) {
+      if (it is List<*>) {
+        if (it.size > 1) {
+          callback(Result.failure(FlutterError(it[0] as String, it[1] as String, it[2] as String?)))
+        } else {
+          callback(Result.success(Unit))
+        }
+      } else {
+        callback(Result.failure(BackgroundWorkerPigeonUtils.createConnectionError(channelName)))
+      } 
+    }
+  }
+  fun cancel(callback: (Result<Unit>) -> Unit)
+{
+    val separatedMessageChannelSuffix = if (messageChannelSuffix.isNotEmpty()) ".$messageChannelSuffix" else ""
+    val channelName = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.cancel$separatedMessageChannelSuffix"
+    val channel = BasicMessageChannel<Any?>(binaryMessenger, channelName, codec)
+    channel.send(null) {
+      if (it is List<*>) {
+        if (it.size > 1) {
+          callback(Result.failure(FlutterError(it[0] as String, it[1] as String, it[2] as String?)))
+        } else {
+          callback(Result.success(Unit))
+        }
+      } else {
+        callback(Result.failure(BackgroundWorkerPigeonUtils.createConnectionError(channelName)))
+      } 
+    }
+  }
+}

mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorker.kt

@@ -0,0 +1,162 @@
+package app.alextran.immich.background
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.work.ListenableWorker
+import androidx.work.WorkerParameters
+import app.alextran.immich.MainActivity
+import com.google.common.util.concurrent.ListenableFuture
+import com.google.common.util.concurrent.SettableFuture
+import io.flutter.FlutterInjector
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.embedding.engine.dart.DartExecutor.DartCallback
+import io.flutter.embedding.engine.loader.FlutterLoader
+import io.flutter.view.FlutterCallbackInformation
+
+private const val TAG = "BackgroundWorker"
+
+enum class BackgroundTaskType {
+  LOCAL_SYNC,
+  UPLOAD,
+}
+
+class BackgroundWorker(context: Context, params: WorkerParameters) :
+  ListenableWorker(context, params), BackgroundWorkerBgHostApi {
+  private val ctx: Context = context.applicationContext
+
+  /// The Flutter loader that loads the native Flutter library and resources.
+  /// This must be initialized before starting the Flutter engine.
+  private var loader: FlutterLoader = FlutterInjector.instance().flutterLoader()
+
+  /// The Flutter engine created specifically for background execution.
+  /// This is a separate instance from the main Flutter engine that handles the UI.
+  /// It operates in its own isolate and doesn't share memory with the main engine.
+  /// Must be properly started, registered, and torn down during background execution.
+  private var engine: FlutterEngine? = null
+
+  // Used to call methods on the flutter side
+  private var flutterApi: BackgroundWorkerFlutterApi? = null
+
+  /// Result returned when the background task completes. This is used to signal
+  /// to the WorkManager that the task has finished, either successfully or with failure.
+  private val completionHandler: SettableFuture<Result> = SettableFuture.create()
+
+  /// Flag to track whether the background task has completed to prevent duplicate completions
+  private var isComplete = false
+
+  init {
+    if (!loader.initialized()) {
+      loader.startInitialization(ctx)
+    }
+  }
+
+  override fun startWork(): ListenableFuture<Result> {
+    Log.i(TAG, "Starting background upload worker")
+
+    loader.ensureInitializationCompleteAsync(ctx, null, Handler(Looper.getMainLooper())) {
+      engine = FlutterEngine(ctx)
+
+      // Retrieve the callback handle stored by the main Flutter app
+      // This handle points to the Flutter function that should be executed in the background
+      val callbackHandle =
+        ctx.getSharedPreferences(BackgroundWorkerApiImpl.SHARED_PREF_NAME, Context.MODE_PRIVATE)
+          .getLong(BackgroundWorkerApiImpl.SHARED_PREF_CALLBACK_HANDLE, 0L)
+
+      if (callbackHandle == 0L) {
+        // Without a valid callback handle, we cannot start the Flutter background execution
+        complete(Result.failure())
+        return@ensureInitializationCompleteAsync
+      }
+
+      // Start the Flutter engine with the specified callback as the entry point
+      val callback = FlutterCallbackInformation.lookupCallbackInformation(callbackHandle)
+      if (callback == null) {
+        complete(Result.failure())
+        return@ensureInitializationCompleteAsync
+      }
+
+      // Register custom plugins
+      MainActivity.registerPlugins(ctx, engine!!)
+      flutterApi =
+        BackgroundWorkerFlutterApi(binaryMessenger = engine!!.dartExecutor.binaryMessenger)
+      BackgroundWorkerBgHostApi.setUp(
+        binaryMessenger = engine!!.dartExecutor.binaryMessenger,
+        api = this
+      )
+
+      engine!!.dartExecutor.executeDartCallback(
+        DartCallback(ctx.assets, loader.findAppBundlePath(), callback)
+      )
+    }
+
+    return completionHandler
+  }
+
+  /**
+   * Called by the Flutter side when it has finished initialization and is ready to receive commands.
+   * Routes the appropriate task type (refresh or processing) to the corresponding Flutter method.
+   * This method acts as a bridge between the native Android background task system and Flutter.
+   */
+  override fun onInitialized() {
+    val taskTypeIndex = inputData.getInt(BackgroundWorkerApiImpl.WORKER_DATA_TASK_TYPE, 0)
+    val taskType = BackgroundTaskType.entries[taskTypeIndex]
+
+    when (taskType) {
+      BackgroundTaskType.LOCAL_SYNC -> flutterApi?.onLocalSync(null) { handleHostResult(it) }
+      BackgroundTaskType.UPLOAD -> flutterApi?.onAndroidUpload { handleHostResult(it) }
+    }
+  }
+
+  /**
+   * Called when the system has to stop this worker because constraints are
+   * no longer met or the system needs resources for more important tasks
+   * This is also called when the worker has been explicitly cancelled or replaced
+   */
+  override fun onStopped() {
+    Log.d(TAG, "About to stop BackupWorker")
+
+    if (isComplete) {
+      return
+    }
+
+    Handler(Looper.getMainLooper()).postAtFrontOfQueue {
+      if (flutterApi != null) {
+        flutterApi?.cancel {
+          complete(Result.failure())
+        }
+      }
+    }
+
+    Handler(Looper.getMainLooper()).postDelayed({
+      complete(Result.failure())
+    }, 5000)
+  }
+
+  private fun handleHostResult(result: kotlin.Result<Unit>) {
+    if (isComplete) {
+      return
+    }
+
+    result.fold(
+      onSuccess = { _ -> complete(Result.success()) },
+      onFailure = { _ -> onStopped() }
+    )
+  }
+
+  /**
+   * Cleans up resources by destroying the Flutter engine context and invokes the completion handler.
+   * This method ensures that the background task is marked as complete, releases the Flutter engine,
+   * and notifies the caller of the task's success or failure. This is the final step in the
+   * background task lifecycle and should only be called once per task instance.
+   *
+   * - Parameter success: Indicates whether the background task completed successfully
+   */
+  private fun complete(success: Result) {
+    isComplete = true
+    engine?.destroy()
+    flutterApi = null
+    completionHandler.set(success)
+  }
+}

mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorkerApiImpl.kt

@@ -0,0 +1,92 @@
+package app.alextran.immich.background
+
+import android.content.Context
+import android.provider.MediaStore
+import android.util.Log
+import androidx.core.content.edit
+import androidx.work.BackoffPolicy
+import androidx.work.Constraints
+import androidx.work.Data
+import androidx.work.ExistingWorkPolicy
+import androidx.work.OneTimeWorkRequest
+import androidx.work.WorkManager
+import java.util.concurrent.TimeUnit
+
+private const val TAG = "BackgroundUploadImpl"
+
+class BackgroundWorkerApiImpl(context: Context) : BackgroundWorkerFgHostApi {
+  private val ctx: Context = context.applicationContext
+  override fun enableSyncWorker() {
+    enqueueMediaObserver(ctx)
+    Log.i(TAG, "Scheduled media observer")
+  }
+
+  override fun enableUploadWorker(callbackHandle: Long) {
+    updateUploadEnabled(ctx, true)
+    updateCallbackHandle(ctx, callbackHandle)
+    Log.i(TAG, "Scheduled background upload tasks")
+  }
+
+  override fun disableUploadWorker() {
+    updateUploadEnabled(ctx, false)
+    WorkManager.getInstance(ctx).cancelUniqueWork(BACKGROUND_WORKER_NAME)
+    Log.i(TAG, "Cancelled background upload tasks")
+  }
+
+  companion object {
+    private const val BACKGROUND_WORKER_NAME = "immich/BackgroundWorkerV1"
+    private const val OBSERVER_WORKER_NAME = "immich/MediaObserverV1"
+
+    const val WORKER_DATA_TASK_TYPE = "taskType"
+
+    const val SHARED_PREF_NAME = "Immich::Background"
+    const val SHARED_PREF_BACKUP_ENABLED = "Background::backup::enabled"
+    const val SHARED_PREF_CALLBACK_HANDLE = "Background::backup::callbackHandle"
+
+    private fun updateUploadEnabled(context: Context, enabled: Boolean) {
+      context.getSharedPreferences(SHARED_PREF_NAME, Context.MODE_PRIVATE).edit {
+        putBoolean(SHARED_PREF_BACKUP_ENABLED, enabled)
+      }
+    }
+
+    private fun updateCallbackHandle(context: Context, callbackHandle: Long) {
+      context.getSharedPreferences(SHARED_PREF_NAME, Context.MODE_PRIVATE).edit {
+        putLong(SHARED_PREF_CALLBACK_HANDLE, callbackHandle)
+      }
+    }
+
+    fun enqueueMediaObserver(ctx: Context) {
+      val constraints = Constraints.Builder()
+        .addContentUriTrigger(MediaStore.Images.Media.INTERNAL_CONTENT_URI, true)
+        .addContentUriTrigger(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, true)
+        .addContentUriTrigger(MediaStore.Video.Media.INTERNAL_CONTENT_URI, true)
+        .addContentUriTrigger(MediaStore.Video.Media.EXTERNAL_CONTENT_URI, true)
+        .setTriggerContentUpdateDelay(5, TimeUnit.SECONDS)
+        .setTriggerContentMaxDelay(1, TimeUnit.MINUTES)
+        .build()
+
+      val work = OneTimeWorkRequest.Builder(MediaObserver::class.java)
+        .setConstraints(constraints)
+        .build()
+      WorkManager.getInstance(ctx)
+        .enqueueUniqueWork(OBSERVER_WORKER_NAME, ExistingWorkPolicy.REPLACE, work)
+
+      Log.i(TAG, "Enqueued media observer worker with name: $OBSERVER_WORKER_NAME")
+    }
+
+    fun enqueueBackgroundWorker(ctx: Context, taskType: BackgroundTaskType) {
+      val constraints = Constraints.Builder().setRequiresBatteryNotLow(true).build()
+
+      val data = Data.Builder()
+      data.putInt(WORKER_DATA_TASK_TYPE, taskType.ordinal)
+      val work = OneTimeWorkRequest.Builder(BackgroundWorker::class.java)
+        .setConstraints(constraints)
+        .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 1, TimeUnit.MINUTES)
+        .setInputData(data.build()).build()
+      WorkManager.getInstance(ctx)
+        .enqueueUniqueWork(BACKGROUND_WORKER_NAME, ExistingWorkPolicy.REPLACE, work)
+
+      Log.i(TAG, "Enqueued background worker with name: $BACKGROUND_WORKER_NAME")
+    }
+  }
+}

mobile/android/app/src/main/kotlin/app/alextran/immich/background/MediaObserver.kt

@@ -0,0 +1,34 @@
+package app.alextran.immich.background
+
+import android.content.Context
+import android.util.Log
+import androidx.work.Worker
+import androidx.work.WorkerParameters
+
+class MediaObserver(context: Context, params: WorkerParameters) : Worker(context, params) {
+    private val ctx: Context = context.applicationContext
+
+    override fun doWork(): Result {
+        Log.i("MediaObserver", "Content change detected, starting background worker")
+
+        // Enqueue backup worker only if there are new media changes
+        if (triggeredContentUris.isNotEmpty()) {
+            val type =
+                if (isBackupEnabled(ctx)) BackgroundTaskType.UPLOAD else BackgroundTaskType.LOCAL_SYNC
+            BackgroundWorkerApiImpl.enqueueBackgroundWorker(ctx, type)
+        }
+
+        // Re-enqueue itself to listen for future changes
+        BackgroundWorkerApiImpl.enqueueMediaObserver(ctx)
+        return Result.success()
+    }
+
+    private fun isBackupEnabled(context: Context): Boolean {
+        val prefs =
+            context.getSharedPreferences(
+                BackgroundWorkerApiImpl.SHARED_PREF_NAME,
+                Context.MODE_PRIVATE
+            )
+        return prefs.getBoolean(BackgroundWorkerApiImpl.SHARED_PREF_BACKUP_ENABLED, false)
+    }
+}