README

Added documentation for Sync Mode feature
2024-08-18 12:06:59 +02:00 · 2024-08-18 12:06:59 +02:00 · 92493ad85b
commit 92493ad85b
parent 946193750d
1 changed files with 79 additions and 3 deletions
--- a/README.md
+++ b/README.md
@ -21,6 +21,7 @@ This script is mostly based on the following original script: [REDVM/immich_auto
 4. [How It Works (with Examples)](#how-it-works)
 5. [Automatic Album Sharing](#automatic-album-sharing)
 6. [Cleaning Up Albums](#cleaning-up-albums)
+7. [Dealing with External Library Changes](#dealing-with-external-library-changes)

 ## Usage
 ### Bare Python Script
@ -35,7 +36,8 @@ This script is mostly based on the following original script: [REDVM/immich_auto
    ```
 3. Run the script
    ```
-    usage: immich_auto_album.py [-h] [-r ROOT_PATH] [-u] [-a ALBUM_LEVELS] [-s ALBUM_SEPARATOR] [-c CHUNK_SIZE] [-C FETCH_CHUNK_SIZE] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [-k] [-i IGNORE] [-m {CREATE,CLEANUP,DELETE_ALL}] [-d] [-x SHARE_WITH] [-o {viewer,editor}] root_path api_url api_key
+    usage: immich_auto_album.py [-h] [-r ROOT_PATH] [-u] [-a ALBUM_LEVELS] [-s ALBUM_SEPARATOR] [-c CHUNK_SIZE] [-C FETCH_CHUNK_SIZE] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [-k] [-i IGNORE] [-m {CREATE,CLEANUP,DELETE_ALL}] [-d] [-x SHARE_WITH] [-o {viewer,editor}] [-S {0,1,2}]
+                            root_path api_url api_key

    Create Immich Albums from an external library path based on the top level folders

@ -72,6 +74,9 @@ This script is mostly based on the following original script: [REDVM/immich_auto
                            <userName>=<shareRole> must be used, where <shareRole> must be one of 'viewer' or 'editor'. May be specified multiple times to share albums with more than one user. (default: None)
      -o {viewer,editor}, --share-role {viewer,editor}
                            The default share role for users newly created albums are shared with. Only effective if --share-with is specified at least once and the share role is not specified within --share-with. (default: viewer)
+      -S {0,1,2}, --sync-mode {0,1,2}
+                            Synchronization mode to use. Synchronization mode helps synchronizing changes in external libraries structures to Immich after albums have already been created. Possible Modes: 0 = do nothing; 1 = Delete any empty albums; 2 = Trigger offline asset removal (REQUIRES
+                            API KEY OF AN ADMIN USER!) (default: 0)
    ```

 __Plain example without optional arguments:__
@ -103,6 +108,7 @@ The environment variables are analoguous to the script's command line arguments.
 | DELETE_CONFIRM     | no | Confirm deletion of albums when running in mode CLEANUP or DELETE_ALL. If this flag is not set, these modes will perform a dry run only. Has no effect in mode CREATE (default: False). <br>Refer to [Cleaning Up Albums](#cleaning-up-albums).|
 | SHARE_WITH     | no | A single or a colon (`:`) separated list of existing user names (or email addresses of existing users) to share newly created albums with. If the the share role should be specified by user, the format <userName>=<shareRole> must be used, where <shareRole> must be one of `viewer` or `editor`. May be specified multiple times to share albums with more than one user. (default: None) Sharing only happens if an album is actually created, not if new assets are added to it.  <br>Refer to [Automatic Album Sharing](#automatic-album-sharing).|
 | SHARE_ROLE     | no | The role for users newly created albums are shared with. Only effective if `SHARE_WITH` is not empty and no explicit share role was specified for at least one user. (default: viewer), allowed values: viewer, editor |
+| SYNC_MODE     | no | Synchronization mode to use. Synchronization mode helps synchronizing changes in external libraries structures to Immich after albums have already been created. Possible Modes: <br>0 = do nothing<br>1 = Delete any empty albums<br>2 = Trigger offline asset removal (REQUIRES API KEY OF AN ADMIN USER!)<br>(default: 0)<br>Refer to [Dealing with External Library Changes](#dealing-with-external-library-changes). |

 #### Run the container with Docker

@ -129,8 +135,6 @@ docker run --name immich-folder-album-creator -e TZ="Europe/Berlin" -e CRON_EXPR

 Adding the container to Immich's `docker-compose.yml` file:
 ```yml
-version: "3.8"
-
 #
 # WARNING: Make sure to use the docker-compose.yml of the current release:
 #
@ -308,3 +312,75 @@ To actually delete albums, the option `-d/--delete-confirm` (or env variable `DE

 __WARNING ⚠️__  
 Deleting albums cannot be undone! The only option is to let the script run again and create new albums base on the passed arguments and current assets in Immich.
+
+## Dealing with External Library Changes
+
+Due to their nature, external libraries may be changed by the user without Immich having any say in it.  
+Two examples of this are the user deleting or renaming folders in their external libraries after the script has created albums, or the user moving single files from one folder to another. The script would create new albums from renamed folders or add images to their new album after they have been moved.  
+Immich itself deals with this by marking images/videos it no longer sees in their original location as "offline". This can lead to albums being completely populated by "offline" files only (if the folder was renamed or deleted) while they exist normally in a new album or with single images being offline in one album, while existing normally in their new albums.  
+There is an administrative option to trigger deletion of "offline assets" from libraries in the Immich Admin Interface. However, in the first example this might leave behind empty albums if the album only contained offline files.
+
+To clean up this mess this script offers an option called `Sync Mode`. It is an optional argument / environment variable that may have values from 0 to 2.
+The following behaviors wil be triggered by the different values:
+  - `0`: No syncing (default)
+  - `1`: Delete all empty albums at the end of a run
+  - `2`: Trigger offline asset removal for all libraires (⚠️ This function requires the API key of an Admin User!)
+
+The complete syncing process consists of two stages:
+1. Trigger Offline Asset Removal
+This will start a background job for each library to find and delete files from Immich's database that are marked as 'offline'. It is asynchronous and might take some time (depending on the size of the databases and the numver of offline files).
+Offline Asset Removal can only be triggered by Administrators, so the API Key used for this sync mode must be one of an Administrator. This might not be the same you use for creating albums!
+
+2. Delete Empty Albums
+Step 1 might leave behind empty albums for a different user. The script is capable of removing empty albums at the end of a run to clean up after Offline Asset Removal.
+⚠️ It is __not__ possible for the script to distinguish between an album that was left behind empty after Offline Asset Removal and a manually created album with no images added to it! All empty albums of that user will be deleted!
+
+It is up to you whether you want to use the full capabilities Sync Mode offers, parts of it or none.  
+An example for the Immich `docker-compose.yml` stack when using full Sync Mode might look like this:
+```yml
+#
+# WARNING: Make sure to use the docker-compose.yml of the current release:
+#
+# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
+#
+# The compose file on main may not be compatible with the latest release.
+#
+
+name: immich
+
+services:
+  immich-server:
+    container_name: immich_server
+    volumes:
+     - /path/to/my/photos:/external_libs/photos
+  ...
+  immich-folder-album-creator-offline-asset-removal:
+    container_name: immich_folder_album_creator
+    image: salvoxia/immich-folder-album-creator:latest
+    restart: unless-stopped
+    environment:
+      API_URL: http://immich_server:3001/api
+      # Admin User API Key
+      API_KEY: yyyyyyyyyyyyyyyyyy
+      ROOT_PATH: /thisIsADummyPathThatDoesNotExist
+      CRON_EXPRESSION: "0 * * * *"
+      TZ: Europe/Berlin
+      # Regularly trigger offline asset removal
+      SYNC_MODE: "2"
+  immich-folder-album-creator:
+    container_name: immich_folder_album_creator
+    image: salvoxia/immich-folder-album-creator:latest
+    restart: unless-stopped
+    environment:
+      API_URL: http://immich_server:3001/api
+      API_KEY: xxxxxxxxxxxxxxxxx
+      ROOT_PATH: /external_libs/photos
+      # Run 10 minutes past the hour to give Offline Asset Removal time to work
+      CRON_EXPRESSION: "10 * * * *"
+      TZ: Europe/Berlin
+      # Delete empty albums after each run
+      SYNC_MODE: "1"
+```
+
+The `immich-folder-album-creator-offline-asset-removal` service has the one and only purpose of triggering Offline Asset Removal, since we do not want to create albums for the Admin User. Thus, a dummy `ROOT_PATH` is passed so that the script will never find any assets to create albums from. `SYNC_MODE` is set to `2` to regularly trigger Offline Asset Removal.  
+The `immich-folder-album-creator` service is the normal service for creating albums from an external library. The cron job triggers 10 minutes past the hour, whereas Offline Asset Removal is trigger at the full hour. This gives the job 10 minutes of time to run before any empty albums are deleted at the end of the run due to `SYNC_MODE` being set to `1`.