# 📸 NextCloud Photos Management From version 4.0.0 onwards, the Tool can connect to your NextCloud account using WebDAV and manage your photo library. ### Features included: 1. Upload Album(s) (from folder) 2. Download Album(s) (into folder) 3. Upload ALL (from folder) 4. Download ALL (into folder) 5. Remove ALL Assets 6. Remove ALL Albums 7. Remove Albums by Name Pattern 8. Rename Albums by Name Pattern 9. Remove Empty Albums 10. Remove Duplicates Albums (currently no-op) 11. Merge Duplicates Albums (currently no-op) 12. Consolidate Albums Names You can apply filters in NextCloud modules. The available filters are: - **by Type:** - argument: `-type, --filter-by-type` - valid values: `image`, `video`, `all` - **by Dates:** - arguments: - `-from, --filter-from-date` - `-to, --filter-to-date` - valid formats: - `dd/mm/yyyy` - `dd-mm-yyyy` - `yyyy/mm/dd` - `yyyy-mm-dd` - `mm/yyyy` - `mm-yyyy` - `yyyy/mm` - `yyyy-mm` - `yyyy` - **by Country / City / Person:** - arguments: - `-country, --filter-by-country` - `-city, --filter-by-city` - `-person, --filter-by-person` - currently not available in WebDAV-based NextCloud integration (they are ignored with warning). The credentials are loaded from the `Config.ini` section below: ```ini # Configuration for NextCloud Photos [NextCloud Photos] NEXTCLOUD_URL = http://192.168.1.11:8080 NEXTCLOUD_MAX_PARALLEL_UPLOADS = 12 NEXTCLOUD_MAX_PARALLEL_DOWNLOADS= 16 NEXTCLOUD_USE_SYSTEM_PROXY = false NEXTCLOUD_USERNAME_1 = username_1 NEXTCLOUD_PASSWORD_1 = app_password_1 NEXTCLOUD_PHOTOS_FOLDER_1 = /Photos/ALL_Photos NEXTCLOUD_ALBUMS_FOLDER_1 = /Photos/Albums NEXTCLOUD_USERNAME_2 = username_2 NEXTCLOUD_PASSWORD_2 = app_password_2 NEXTCLOUD_PHOTOS_FOLDER_2 = /Photos/ALL_Photos NEXTCLOUD_ALBUMS_FOLDER_2 = /Photos/Albums NEXTCLOUD_USERNAME_3 = username_3 NEXTCLOUD_PASSWORD_3 = app_password_3 NEXTCLOUD_PHOTOS_FOLDER_3 = /Photos/ALL_Photos NEXTCLOUD_ALBUMS_FOLDER_3 = /Photos/Albums ``` > [!NOTE] > To use all those features, it is mandatory to use the argument _**`--client=nextcloud`**_ to specify NextCloud Photos as the service that you want to connect. > > If you want to connect to an account ID different that 1 (suffixed with _2 or _3) you can use the argument _**`-id, -account-id`**_ to specify the account 2 or 3 as needed. > [!TIP] > In Docker/Compose/Kubernetes, you can override these settings without editing `Config.ini` by using environment variables with the same key names, for example `NEXTCLOUD_URL`, `NEXTCLOUD_USERNAME_1`, `NEXTCLOUD_PASSWORD_1`, `NEXTCLOUD_PHOTOS_FOLDER_1`, `NEXTCLOUD_ALBUMS_FOLDER_1`. > Docker-secret style variables such as `NEXTCLOUD_PASSWORD_1_FILE=/run/secrets/nextcloud_password_1` are also supported. > Runtime precedence is: environment variable > `Config.ini` > template default. > [!TIP] > `NEXTCLOUD_MAX_PARALLEL_UPLOADS` controls parallel uploads. > Recommended values in LAN are usually between `8` and `16`. > [!NOTE] > For compiled binaries, macOS now uses `PhotoMigrator.command`. Linux and Synology SSH continue using `PhotoMigrator.bin`. Replace the binary name accordingly when following the CLI examples below. > > `NEXTCLOUD_MAX_PARALLEL_DOWNLOADS` controls parallel downloads. > Recommended values in LAN are usually between `12` and `24`. > > `NEXTCLOUD_USE_SYSTEM_PROXY=false` means PhotoMigrator connects directly and ignores `HTTP_PROXY` / `HTTPS_PROXY`. > [!WARNING] > Use `NEXTCLOUD_USE_SYSTEM_PROXY=true` only if your environment explicitly requires outbound proxy. > In LAN setups, enabling proxy by mistake can cause large per-request latency. ## Upload Albums (from Local Folder) into NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --upload-albums ` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud URL and account credentials (App Password recommended). - **Explanation:** - The Tool creates one album per subfolder inside `` and uploads supported assets. - In NextCloud implementation, files are uploaded under `NEXTCLOUD_ALBUMS_FOLDER_/`, and native Photos album association is handled automatically when supported. - By default only exact existing album names are reused and newly created albums keep the original source name. - Add `--prefer-canonical-album-names` if you want new destination albums to be created directly as the preferred clean keeper name. - Add `--consolidate-similar-albums` to also treat equivalent names such as `Album`, `Album_1`, `Album (2)`, `New_Album`, `New Album`, and `New_Album 1` as the same reusable album family. - When these behaviors are active, PhotoMigrator prefers the clean keeper name, merges the assets from numbered/underscored variants into that keeper, and reuses it for the incoming upload. - After the consolidation is confirmed, redundant NextCloud albums are removed automatically. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --upload-albums ./My_Albums_Folder ./PhotoMigrator.bin --client=nextcloud --upload-albums ./My_Albums_Folder --prefer-canonical-album-names --consolidate-similar-albums ``` Example: if `New_Album`, `New Album`, and `New_Album 1` exist, PhotoMigrator prefers `New Album` as the keeper, merges the assets from the other variants into it, uploads the incoming album there, and then removes the redundant variants. If no equivalent album already exists in the target and you upload `New_Album 1`, the same flag creates `New Album` directly. ## Download Albums from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --download-albums --output-folder ` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Downloads albums matching `` into `/Albums`. - You can use: - `ALL` to download all albums. - Patterns (for example `--download-albums "Trip*"`). - Multiple names in the same argument. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --download-albums "Album 1, Album 2" --output-folder ./Downloads ``` > [!WARNING] > `` must exist in your NextCloud library, otherwise nothing is downloaded. ## Upload All (from Local Folder) into NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --upload-all ` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials and `NEXTCLOUD_PHOTOS_FOLDER_` / `NEXTCLOUD_ALBUMS_FOLDER_`. - **Explanation:** - Uploads all supported assets from ``. - If `/Albums` exists, each subfolder is treated as an album. - Assets outside `Albums` are uploaded into `NEXTCLOUD_PHOTOS_FOLDER_`. - Album subfolders are uploaded into `NEXTCLOUD_ALBUMS_FOLDER_`. - You can also provide extra albums folders via `-AlbFolder, --albums-folders`. - Add `--prefer-canonical-album-names` if you want new destination album names inside this flow to be normalized to the preferred clean keeper. - Add `--consolidate-similar-albums` if you want album uploads inside this flow to treat equivalent names such as `Album`, `Album_1`, `Album (2)`, `New_Album`, `New Album`, and `New_Album 1` as the same reusable album family. - When these behaviors are active, PhotoMigrator prefers the clean keeper name, merges the assets from redundant variants into that keeper, and removes the redundant NextCloud albums afterwards. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --upload-all ./MyLibrary ./PhotoMigrator.bin --client=nextcloud --upload-all ./MyLibrary --prefer-canonical-album-names --consolidate-similar-albums ``` ## Download All from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --download-all ` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Downloads all albums and assets from `NEXTCLOUD_PHOTOS_FOLDER_`. - Albums are downloaded under `/Albums`. - Assets are downloaded under `/ALL_PHOTOS`. - If `NEXTCLOUD_ALBUMS_FOLDER_` is inside `NEXTCLOUD_PHOTOS_FOLDER_`, the albums subtree is excluded from the assets scan to avoid duplicate downloads. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --download-all ./MyLibrary ``` ## Remove All Assets from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --remove-all-assets` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Removes all assets from albums and non-album areas. - After removing assets, empty album folders are also removed. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --remove-all-assets ``` > [!CAUTION] > This process is irreversible. ## Remove All Albums from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --remove-all-albums --remove-albums-assets` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Removes all albums. - If `--remove-albums-assets` is set, it also removes assets associated to those albums. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --remove-all-albums --remove-albums-assets ``` > [!CAUTION] > This process is irreversible. ## Remove Albums by Name Pattern from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --remove-albums --remove-albums-assets` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Removes albums whose name matches ``. - The remove pattern can be plain text, a wildcard expression (for example `*Temp*` or `Temp*`), or a regular expression. - If `--remove-albums-assets` is set, assets inside removed albums are also removed. - If `--preview-album-actions` is set, the matching albums are listed and the tool asks for confirmation before deleting them. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --remove-albums "Temp" --preview-album-actions ./PhotoMigrator.bin --client=nextcloud --remove-albums "*Temp*" --preview-album-actions ./PhotoMigrator.bin --client=nextcloud --remove-albums "^Temp" --remove-albums-assets ``` > [!CAUTION] > This process is irreversible. ## Rename Albums by Name Pattern from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --rename-albums ` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Renames albums whose names match the provided pattern. - The rename pattern can be plain text (for example `--`), a wildcard expression (for example `*--*` or `--*`), or a regular expression. - If `--preview-album-actions` is set, the matching albums are listed and the tool asks for confirmation before renaming them. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --rename-albums "--" "-" --preview-album-actions ./PhotoMigrator.bin --client=nextcloud --rename-albums "--" "-" ./PhotoMigrator.bin --client=nextcloud --rename-albums "*--*" "-" ./PhotoMigrator.bin --client=nextcloud --rename-albums "\\d{4}-\\d{2}-\\d{2}" "DATE" ``` ## Remove Empty Albums from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --remove-empty-albums` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Removes albums that contain zero assets. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --remove-empty-albums ``` ## Remove Duplicates Albums from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --remove-duplicates-albums` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Current WebDAV integration keeps this operation as no-op. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --remove-duplicates-albums ``` > [!WARNING] > This operation is currently a no-op in NextCloud integration. ## Merge Duplicates Albums from NextCloud Photos: - **From:** v4.0.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --merge-duplicates-albums` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - Current WebDAV integration keeps this operation as no-op. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --merge-duplicates-albums ``` > [!WARNING] > This operation is currently a no-op in NextCloud integration. ## Consolidate Albums Names from NextCloud Photos: - **From:** v4.5.0 - **Usage:** - `./PhotoMigrator.bin --client=nextcloud --consolidate-albums-names --preview-album-actions` - **Pre-Requisites:** - Configure `Config.ini` with valid NextCloud credentials. - **Explanation:** - The Tool connects to NextCloud Photos and scans the albums that already exist in the cloud looking for equivalent album-name families. - It uses the same family-detection logic as `--consolidate-similar-albums`, so names such as `Album`, `Album_1`, `Album (2)`, `New_Album`, `New Album`, and `New_Album 1` are treated as the same family. - Assets from redundant variants are reassigned directly in NextCloud Photos to the preferred keeper album without uploading any new asset. - Once the reassignment is confirmed, the redundant album variants are removed. - If `--preview-album-actions` is set, the detected album families are listed and the tool asks for confirmation before applying the changes. - **Example of use:** ```bash ./PhotoMigrator.bin --client=nextcloud --consolidate-albums-names --preview-album-actions ``` --- ## ⚙️ Config.ini You can see how to configure the Config.ini file in this help section: [Configuration File](00-configuration-file.md) --- ## 🏠 [Back to Main Page](../README.md) --- ## 🎖️ Credits: I hope this can be useful for any of you. Enjoy it! (c) 2024-2026 by Jaime Tur (@jaimetur).