c-l/immich-folder-album-creator
1
0
Fork 0
Code Releases Activity

Merge pull request #61 from Salvoxia/feature/archiveAssetsAfterAdding

Browse source 
Feature/archive assets after adding
This commit is contained in:
Salvoxia 2024-09-27 19:06:02 +00:00 committed by GitHub
commit e98dc62c1e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 139 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
README.md
View file

@ -23,8 +23,9 @@ This script is mostly based on the following original script: [REDVM/immich_auto
6. [Automatic Album Sharing](#automatic-album-sharing)
7. [Cleaning Up Albums](#cleaning-up-albums)
8. [Assets in Multiple Albums](#assets-in-multiple-albums)
9. [Setting Album Thumbnails](#setting-album-thumbnails)
10. [Dealing with External Library Changes](#dealing-with-external-library-changes)
9. [Setting Album Thumbnails](#setting-album-thumbnails)#
10. [Automatic Archiving](#automatic-archiving)
11. [Dealing with External Library Changes](#dealing-with-external-library-changes)
## Usage
### Bare Python Script
@ -39,8 +40,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}] [-S {0,1,2}] [-O {False,asc,desc}] [-A]
[-f PATH_FILTER] [--set-album-thumbnail {first,last,random,random-all,random-filtered}]
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}] [-O {False,asc,desc}] [-A] [-f PATH_FILTER] [--set-album-thumbnail {first,last,random,random-all,random-filtered}] [-v] [--find-archived-assets]
root_path api_url api_key
Create Immich Albums from an external library path based on the top level folders
@ -56,8 +57,8 @@ This script is mostly based on the following original script: [REDVM/immich_auto
Additional external libarary root path in Immich; May be specified multiple times for multiple import paths or external libraries. (default: None)
-u, --unattended Do not ask for user confirmation after identifying albums. Set this flag to run script as a cronjob. (default: False)
-a ALBUM_LEVELS, --album-levels ALBUM_LEVELS
Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be 0. If a range should be set, the start level and end level must be separated by a comma
like '<startLevel>,<endLevel>'. If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>. (default: 1)
Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be 0. If a range should be set, the start level
and end level must be separated by a comma like '<startLevel>,<endLevel>'. If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>. (default: 1)
-s ALBUM_SEPARATOR, --album-separator ALBUM_SEPARATOR
Separator string to use for compound album names created from nested folders. Only effective if -a is set to a value > 1 (default: )
-c CHUNK_SIZE, --chunk-size CHUNK_SIZE
@ -70,26 +71,30 @@ This script is mostly based on the following original script: [REDVM/immich_auto
-i IGNORE, --ignore IGNORE
Use either literals or glob-like patterns to ignore assets for album name creation. This filter is evaluated after any values passed with --path-filter. May be specified multiple times. (default: None)
-m {CREATE,CLEANUP,DELETE_ALL}, --mode {CREATE,CLEANUP,DELETE_ALL}
Mode for the script to run with. CREATE = Create albums based on folder names and provided arguments; CLEANUP = Create album nmaes based on current images and script arguments, but delete albums if they exist; DELETE_ALL = Delete all albums. If the mode is anything but CREATE, --unattended
does not have any effect. Only performs deletion if -d/--delete-confirm option is set, otherwise only performs a dry-run. (default: CREATE)
Mode for the script to run with. CREATE = Create albums based on folder names and provided arguments; CLEANUP = Create album nmaes based on current images and script arguments, but delete albums if they exist; DELETE_ALL = Delete all albums. If the
mode is anything but CREATE, --unattended does not have any effect. Only performs deletion if -d/--delete-confirm option is set, otherwise only performs a dry-run. (default: CREATE)
-d, --delete-confirm 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)
-x SHARE_WITH, --share-with SHARE_WITH
A user name (or email address of an existing user) to share newly created albums with. Sharing only happens if the album was actually created, not if new assets were added to an existing album. 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)
A user name (or email address of an existing user) to share newly created albums with. Sharing only happens if the album was actually created, not if new assets were added to an existing album. 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)
-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)
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)
-O {False,asc,desc}, --album-order {False,asc,desc}
Set sorting order for newly created albums to newest or oldest file first, Immich defaults to newest file first (default: False)
-A, --find-assets-in-albums
By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle them as usual. (default: False)
By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle them as usual. If --find-archived-assets is set as well, both options
apply. (default: False)
-f PATH_FILTER, --path-filter PATH_FILTER
Use either literals or glob-like patterns to filter assets before album name creation. This filter is evaluated before any values passed with --ignore. May be specified multiple times. (default: None)
--set-album-thumbnail {first,last,random,random-all,random-filtered}
Set first/last/random image as thumbnail for newly created albums or albums assets have been added to. If set to random-filtered, thumbnails are shuffled for all albums whose assets would not be filtered out or ignored by the ignore or path-filter options, even if no assets were added during
the run. If set to random-all, the thumbnails for ALL albums will be shuffled on every run. (default: None)
Set first/last/random image as thumbnail for newly created albums or albums assets have been added to. If set to random-filtered, thumbnails are shuffled for all albums whose assets would not be filtered out or ignored by the ignore or path-filter
options, even if no assets were added during the run. If set to random-all, the thumbnails for ALL albums will be shuffled on every run. (default: None)
-v, --archive Set this option to automatically archive all assets that were newly added to albums. If this option is set in combination with --mode = CLEANUP or DELETE_ALL, archived images of deleted albums will be unarchived. Archiving hides the assets from Immich's timeline. (default: False)
--find-archived-assets
By default, the script only finds assets that are not archived in Immich. Set this option to make the script discover assets that are already archived. If -A/--find-assets-in-albums is set as well, both options apply. (default: False)
```
__Plain example without optional arguments:__
@ -123,10 +128,11 @@ The environment variables are analoguous to the script's command line arguments.
| 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). |
| ALBUM_ORDER | no | Set sorting order for newly created albums to newest (`desc`) or oldest (`asc`) file first, Immich defaults to newest file first, allowed values: `asc`, `desc` |
| FIND_ASSETS_IN_ALBUMS | no | By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle them as usual. (default: `False`)<br>Refer to [Assets in Multiple Albums](#assets-in-multiple-albums). |
| FIND_ASSETS_IN_ALBUMS | no | By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle them as usual. If --find-archived-assets is set as well, both options apply. (default: `False`)<br>Refer to [Assets in Multiple Albums](#assets-in-multiple-albums). |
| PATH_FILTER | no | A colon `:` separated list of literals or glob-style patterns to filter assets before album name creation. (default: ``)<br>Refer to [Filtering](#filtering). |
| SET_ALBUM_THUMBNAIL | no | Set first/last/random image as thumbnail (based on image creation timestamp) for newly created albums or albums assets have been added to.<br> Allowed values: `first`,`last`,`random`,`random-filtered`,`random-all`<br>If set to `random-filtered`, thumbnails are shuffled for all albums whose assets would not be filtered out or ignored by the `IGNORE` or `PATH_FILTER` options, even if no assets were added during
the run. If set to random-all, the thumbnails for ALL albums will be shuffled on every run. (default: `None`)<br>Refer to [Setting Album Thumbnails](#setting-album-thumbnails). |
| SET_ALBUM_THUMBNAIL | no | Set first/last/random image as thumbnail (based on image creation timestamp) for newly created albums or albums assets have been added to.<br> Allowed values: `first`,`last`,`random`,`random-filtered`,`random-all`<br>If set to `random-filtered`, thumbnails are shuffled for all albums whose assets would not be filtered out or ignored by the `IGNORE` or `PATH_FILTER` options, even if no assets were added during the run. If set to random-all, the thumbnails for ALL albums will be shuffled on every run. (default: `None`)<br>Refer to [Setting Album Thumbnails](#setting-album-thumbnails). |
| ARCHIVE | no | Set this option to automatically archive all assets that were newly added to albums.<br>If this option is set in combination with `MODE` = `CLEANUP` or `DELETE_ALL`, archived images of deleted albums will be unarchived.<br>Archiving hides the assets from Immich's timeline. (default: `False`)<br>Refer to [Automatic Archiving](#automatic-archiving). |
| FIND_ARCHIVED_ASSETS | no | y default, the script only finds assets that are not archived in Immich. Set this option make the script discover assets that are already archived. If -A/--find-assets-in-albums is set as well, both options apply. (default: `False`)<br>Refer to [Automatic Archiving](#automatic-archiving). |
#### Run the container with Docker
@ -423,6 +429,18 @@ Furthermore, the script supports two additional modes that are applied __even i
> [!CAUTION]
> Updating album thumbnails cannot be reverted!
## Automatic Archiving
In Immich, 'archiving' an image means to hide it from the main timeline.
This script is capable of automatically archiving images it added to albums during the run to hide them from the timeline. To achieve this, run the script with option `--archive` or Docker environment variable `ARCHIVE=true`.
>[!IMPORTANT]
>Archiving images has the side effect that they are no longer detected by the script with default options. This means that if an album that was created with the `--archive` option set is deleted from the Immich user interface, the script will no longer find the images even though they are no longer assigned to an album.
To make the script find also archived images, run the script with the option `--find-archived-assets` or Docker environment variable `FIND_ARCHIVED_ASSETS=true`.
>[!WARNING]
>If the script is used to delete albums using `--mode=CLEANUP` or `--mode=DELETE_ALL` with the `--archive` option set, the script will automatically unarchive all assets of deleted albums to revert them to their prior state. If you manually archived selected assets in albums, this will be reverted!
## Dealing with External Library Changes
Due to their nature, external libraries may be changed by the user without Immich having any say in it.

9
docker/immich_auto_album.sh
View file

@ -114,6 +114,10 @@ if [ ! -z "$FIND_ASSETS_IN_ALBUMS" ]; then
args="--find-assets-in-albums $args"
fi
if [ ! -z "$FIND_ARCHIVED_ASSETS" ]; then
args="--find-archived-assets $args"
fi
if [ ! -z "$path_filter_list" ]; then
args="$path_filter_list $args"
fi
@ -122,6 +126,9 @@ if [ ! -z "$SET_ALBUM_THUMBNAIL" ]; then
args="--set-album-thumbnail \"$SET_ALBUM_THUMBNAIL\" $args"
fi
if [ ! -z "$ARCHIVE" ]; then
args="--archive $args"
fi
BASEDIR=$(dirname "$0")
echo $args
echo $args | xargs python3 -u $BASEDIR/immich_auto_album.py

111
immich_auto_album.py
View file

@ -86,9 +86,11 @@ parser.add_argument("-x", "--share-with", action="append", help="A user name (or
parser.add_argument("-o", "--share-role", default="viewer", choices=['viewer', 'editor'], help="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.")
parser.add_argument("-S", "--sync-mode", default=0, type=int, choices=[0, 1, 2], help="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!)")
parser.add_argument("-O", "--album-order", default=False, type=str, choices=[False, 'asc', 'desc'], help="Set sorting order for newly created albums to newest or oldest file first, Immich defaults to newest file first")
parser.add_argument("-A", "--find-assets-in-albums", action="store_true", help="By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle them as usual.")
parser.add_argument("-A", "--find-assets-in-albums", action="store_true", help="By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle them as usual. If --find-archived-assets is set as well, both options apply.")
parser.add_argument("-f", "--path-filter", action="append", help="Use either literals or glob-like patterns to filter assets before album name creation. This filter is evaluated before any values passed with --ignore. May be specified multiple times.")
parser.add_argument("--set-album-thumbnail", choices=ALBUM_THUMBNAIL_SETTINGS, help="Set first/last/random image as thumbnail for newly created albums or albums assets have been added to. If set to "+ALBUM_THUMBNAIL_RANDOM_FILTERED+", thumbnails are shuffled for all albums whose assets would not be filtered out or ignored by the ignore or path-filter options, even if no assets were added during the run. If set to "+ALBUM_THUMBNAIL_RANDOM_ALL+", the thumbnails for ALL albums will be shuffled on every run.")
parser.add_argument("-v", "--archive", action="store_true", help="Set this option to automatically archive all assets that were newly added to albums. If this option is set in combination with --mode = CLEANUP or DELETE_ALL, archived images of deleted albums will be unarchived. Archiving hides the assets from Immich's timeline.")
parser.add_argument("--find-archived-assets", action="store_true", help="By default, the script only finds assets that are not archived in Immich. Set this option to make the script discover assets that are already archived. If -A/--find-assets-in-albums is set as well, both options apply.")
args = vars(parser.parse_args())
@ -118,6 +120,8 @@ sync_mode = args["sync_mode"]
find_assets_in_albums = args["find_assets_in_albums"]
path_filter = args["path_filter"]
set_album_thumbnail = args["set_album_thumbnail"]
archive = args["archive"]
find_archived_assets = args["find_archived_assets"]
# Override unattended if we're running in destructive mode
if mode != SCRIPT_MODE_CREATE:
@ -146,6 +150,8 @@ logging.debug("sync_mode = %d", sync_mode)
logging.debug("find_assets_in_albums = %s", find_assets_in_albums)
logging.debug("path_filter = %s", path_filter)
logging.debug("set_album_thumbnail = %s", set_album_thumbnail)
logging.debug("archive = %s", archive)
logging.debug("find_archived_assets = %s", find_archived_assets)
# Verify album levels
if is_integer(album_levels) and album_levels == 0:
@ -301,7 +307,7 @@ def fetchServerVersion() -> dict:
return version
def fetchAssets(isNotInAlbum: bool) -> list:
def fetchAssets(isNotInAlbum: bool, findArchived: bool) -> list:
"""
Fetches assets from the Immich API.
@ -312,16 +318,37 @@ def fetchAssets(isNotInAlbum: bool) -> list:
----------
isNotInAlbum : bool
Flag indicating whether to fetch only assets that are not part
of an album or not.
of an album or not. If set to False, will find images in albums and
not part of albums
findArchived : bool
Flag indicating whether to only fetch assets that are archived. If set to False,
will find archived and unarchived images
Returns
---------
An array of asset objects
"""
assets = fetchAssetsWithOptions({'isNotInAlbum': isNotInAlbum})
if findArchived:
assets += fetchAssetsWithOptions({'isNotInAlbum': isNotInAlbum, 'isArchived': findArchived})
return assets
def fetchAssetsWithOptions(searchOptions: dict) -> list:
"""
Fetches assets from the Immich API using specific search options.
The search options directly correspond to the body used for the search API request.
Parameters
----------
searchOptions: dict
Dictionary containing options to pass to the search/metadata API endpoint
Returns
---------
An array of asset objects
"""
body = searchOptions
assets = []
# prepare request body
body = {}
body['isNotInAlbum'] = isNotInAlbum
# This API call allows a maximum page size of 1000
number_of_assets_to_fetch_per_request_search = min(1000, number_of_assets_to_fetch_per_request)
@ -485,7 +512,7 @@ def is_asset_ignored(asset: dict) -> bool:
return is_asset_ignored
def addAssetsToAlbum(albumId: str, assets: list[str]) -> int:
def addAssetsToAlbum(albumId: str, assets: list[str]) -> list[str]:
"""
Adds the assets IDs provided in assets to the provided albumId.
@ -504,14 +531,14 @@ def addAssetsToAlbum(albumId: str, assets: list[str]) -> int:
Returns
---------
The number of assets that were actually added to the album (excluding duplicates).
The asset UUIDs that were actually added to the album (not respecting assets that were already part of the album)
"""
apiEndpoint = 'albums'
# Divide our assets into chunks of number_of_images_per_request,
# So the API can cope
assets_chunked = list(divide_chunks(assets, number_of_images_per_request))
assets_added = 0
assets_added = list()
for assets_chunk in assets_chunked:
data = {'ids':assets_chunk}
r = requests.put(root_url+apiEndpoint+f'/{albumId}/assets', json=data, **requests_kwargs)
@ -530,9 +557,9 @@ def addAssetsToAlbum(albumId: str, assets: list[str]) -> int:
logging.warning("Error adding an asset to an album: %s", res['error'])
else:
cpt += 1
assets_added.append(res['id'])
if cpt > 0:
logging.info("%d new assets added to %s", cpt, album)
assets_added += cpt
return assets_added
@ -626,15 +653,44 @@ def setAlbumThumbnail(albumId: str, assetId: str):
The ID of the album for which to set the thumbnail
assetId : str
The ID of the asset to be set as thumbnail
Raises
----------
Exception if the API call fails
"""
apiEndpoint = f'albums/{albumId}'
data = {"albumThumbnailAssetId": assetId}
r = requests.patch(root_url+apiEndpoint, json=data, **requests_kwargs)
r.raise_for_status()
assert r.status_code == 200
def setAssetsArchived(assetIds: list[str], isArchived: bool):
"""
(Un-)Archives the assets identified by the passed list of UUIDs.
Parameters
----------
assetIds : list
A list of asset IDs to archive
isArchived : bool
Flag indicating whether to archive or unarchive the passed assets
Raises
----------
Exception if the API call fails
"""
apiEndpoint = f'assets'
data = {
"ids": assetIds,
"isArchived": isArchived
}
r = requests.put(root_url+apiEndpoint, json=data, **requests_kwargs)
if r.status_code != 204:
logging.error("Error setting assets archived: %s", r.json())
r.raise_for_status()
if insecure:
@ -717,18 +773,26 @@ if mode == SCRIPT_MODE_DELETE_ALL:
cpt = 0
for album in albums:
if deleteAlbum(album):
# If the archived flag is set it means we need to unarchived all images of deleted albums;
# In order to do so, we need to fetch all assets of the album we're going to delete
assets_in_album = []
if archive:
assets_in_album = fetchAlbumAssets(album['id'])
logging.info("Deleted album %s", album['albumName'])
cpt += 1
if len(assets_in_album) > 0 and archive:
setAssetsArchived([asset['id'] for asset in assets_in_album], False)
logging.info("Unarchived %d assets", len(assets_in_album))
logging.info("Deleted %d/%d albums", cpt, len(albums))
exit(0)
logging.info("Requesting all assets")
# only request images that are not in any album if we are running in CREATE mode,
# otherwise we need all images, even if they are part of an album
if mode == SCRIPT_MODE_CREATE and not find_assets_in_albums:
assets = fetchAssets(True)
if mode == SCRIPT_MODE_CREATE:
assets = fetchAssets(not find_assets_in_albums, find_archived_assets)
else:
assets = fetchAssets(False)
assets = fetchAssets(False, True)
logging.info("%d photos found", len(assets))
@ -802,9 +866,17 @@ if mode == SCRIPT_MODE_CLEANUP:
else:
cpt = 0
for album_to_delete in albums_to_delete:
# If the archived flag is set it means we need to unarchived all images of deleted albums;
# In order to do so, we need to fetch all assets of the album we're going to delete
assets_in_album = []
if archive:
assets_in_album = fetchAlbumAssets(album_to_delete['id'])
if deleteAlbum(album_to_delete):
logging.info("Deleted album %s", album_to_delete['albumName'])
cpt += 1
if len(assets_in_album) > 0 and archive:
setAssetsArchived([asset['id'] for asset in assets_in_album], False)
logging.info("Unarchived %d assets", len(assets_in_album))
logging.info("Deleted %d/%d albums", cpt, len(album_to_assets))
exit(0)
@ -884,14 +956,21 @@ logging.info("Adding assets to albums")
# Note: Immich manages duplicates without problem,
# so we can each time ad all assets to same album, no photo will be duplicated
albums_with_assets_added = list()
asset_uuids_added = list()
for album, assets in album_to_assets.items():
id = album_to_id[album]
number_of_assets_added = addAssetsToAlbum(id, assets)
if number_of_assets_added > 0:
assets_added = addAssetsToAlbum(id, assets)
if len(assets_added) > 0:
album_with_asset_added = dict()
album_with_asset_added['id'] = id
album_with_asset_added['albumName'] = album
albums_with_assets_added.append(album_with_asset_added)
asset_uuids_added += assets_added
# Archive assets
if archive and len(asset_uuids_added) > 0:
setAssetsArchived(asset_uuids_added, True)
logging.info("Archived %d assets", len(asset_uuids_added))
if set_album_thumbnail: