From 110bddc17d2def2be5ccc36d479bc727d28f695c Mon Sep 17 00:00:00 2001 From: simulot Date: Mon, 7 Aug 2023 19:36:11 +0200 Subject: [PATCH] edit readme file --- readme.md | 66 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/readme.md b/readme.md index 8f4f83a0..08a3ce70 100644 --- a/readme.md +++ b/readme.md @@ -12,18 +12,25 @@ The Immich project fulfills all my requirements for managing my photos: - Continuously enhanced - ... -Now, I need to migrate my photos to the new system in bulk. Most of my photos are stored in a NAS directory, while photos taken with my smartphone are in the Google Photos application. Some of them are also stored on the NAS at full resolution. +Now, I need to migrate my photos to the new system in bulk. Most of my photos are stored in a NAS directory, while photos taken with my smartphone are in the Google Photos application often more compressed. + +To completely transition away from the Google Photos service, I must set up an Immich server, import my NAS-stored photos, and merge them with my Google Photos collection. However, there are instances where the same pictures exist in both systems, sometimes with varying quality. Of course, I want to keep only the best copy of the photo. + +The `immich-cli` installation isn't trivial on a client machine, and doesn't handle Google Photos Takeout archive oddities. -To completely transition away from the Google Photos service, I must set up an Immich server, import my NAS-stored photos, and merge them with my Google Photos collection. However, there are instances where the same pictures exist in both systems, sometimes with varying resolutions. Of course, I want to keep only the best copy of the photo. # Introducing `immich-go` -- import from folders. +- import from folder(s). - import from zipped archives without unzipping them. - import from Google Photos takeout archives, without unzipping them. + - use metadata files to get actual image names (and not the mangled names found in the archive) + - use metadata files to get album real names + - use date of capture fund in the json file - import only missing files or better files (an delete the inferior copy from the server). - import photos taken within a date range. -- create albums. +- create albums based on Google Photos albums or folder names. +- update immich albums with better images. - no installation. See my [motivation](#motivation) for proposing an alternative to the `immich-cli`. @@ -36,24 +43,19 @@ It could run on your PC or on your server. # Running `immich-go` The `immich-go` program uses the Immich API. Hence it need the server address and a valid API key. -# Common CLI switches - -`-server URL` URL of the Immich service
-`-key KEY` A key generated by the user. Uploaded photos will belong to the key's owner.
- - - -## The `upload` command -Upload photos and videos from a local folders, or zipped archives - ```sh -immich-go -server URL -key KEY upload [-albums] [-GooglePhotos] [-date DATE-RANGE] folder1|zip1 folder2|zip2.... +immich-go -server URL -key KEY [-albums] [-GooglePhotos] [-date DATE-RANGE] folder1|zip1 folder2|zip2.... ``` -### `upload` switches: -`-albums` albums are created either after folder names or Google Photos albums.
-`-GooglePhoto` import from a Google Photos structured archive.
+### switches: +`-server URL` URL of the Immich service.
+`-key KEY` A key generated by the user. Uploaded photos will belong to the key's owner.
+`-album "ALBUM NAME"` Import assets and place them into the album `ALBUM NAME`.
+`-GooglePhoto` import from a Google Photos structured archive, recreat Google Photo albums.
+ +**Date selection** + `-date YYYY-MM-DD` select photos taken during this day.
`-date YYYY-MM` select photos taken during this month.
`-date YYYY` select photos taken during this year.
@@ -65,7 +67,7 @@ immich-go -server URL -key KEY upload [-albums] [-GooglePhotos] [-date DATE-RANG The following command will import from a Google Photos takeout archive photos taken between the 1st and the 30th of June 2019 and create albums if any. ```sh immich-go -server=http://mynas:2283 -key=zzV6k65KGLNB9mpGeri9n8Jk1VaNGHSCdoH1dY8jQ -upload -albums -GooglePhotos -date=2019-06 ~/Download/takeout-20230715T073439Z-001.zip ~/Download/takeout-20230715T073439Z-002.zip +-albums -GooglePhotos -date=2019-06 ~/Download/takeout-20230715T073439Z-001.zip ~/Download/takeout-20230715T073439Z-002.zip ``` @@ -73,18 +75,17 @@ upload -albums -GooglePhotos -date=2019-06 ~/Download/takeout-20230715T073439Z-0 The local file is analyzed to get following data: - file size in bytes -- date of capture took from the takeout metadata, the exif data, or the file name with possible. -The index is made of the file name + the size in the same way used by the immich server. +- date of capture took from the takeout metadata, the exif data, or the file name with possible. The key is made of the file name + the size in the same way used by the immich server. Digital cameras often generate file names with a sequence of 4 digits, leading to generate duplicated names. If the names matches, the capture date must be compared. Tests are done in this order -1. the index is found in immich --> the name and the size match. We have the file, don't upload it. +1. the key is found in immich --> the name and the size match. We have the file, don't upload it. 1. the file name is found in immich and... 1. dates match and immich file is smaller than the file --> Upload it, and discard the inferior file 1. dates match and immich file is bigger than the file --> We have already a better version. Don't upload the file. 1. Immich don't have it. --> Upload the file. - +1. Update albums # Build form sources @@ -104,7 +105,7 @@ This program use following 3rd party libraries: # Motivation -The immich-cli tool does a great for importing a tone of files at full speed. However, I want more. So I write this utility for my onw purpose. Maybe, it could help some +The immich-cli tool does a great for importing a tone of files at full speed. However, I want more. So I write this utility for my onw purpose. Maybe, it could help some one else. ## Where the `immich-CLI` falls short @@ -125,18 +126,22 @@ The Google Photos Takeout service saves your collection as massive zip archives. After unzipping the archive, you can use the CLI tool to upload its contents. However, certain limitations exist: - Photos are organized in folders by year and albums. - Photos may be duplicated across year folders and albums. -- Photos might be compressed, potentially affecting the CLI's duplicate detection when comparing them to previously imported photos with finest details. +- Photos might be compressed in the takeout archive, affecting the CLI's duplicate detection when comparing them to previously imported photos with finest details. +- File and album names are mangled and correct names are found in JSON files +### Why the language GO? +The main reason is that my programming level in GO is higher than in Typescript language. +The second reason is the difficulty to deploy a Node.js program on a user machine. -# Wish list +# TODO list - [ ] binary releases - [ ] import vs upload flag - [X] check in the photo doesn't exist on the server before uploading - [X] but keep files with the same name: ex IMG_0201.jpg if they aren't duplicates - [ ] some files may have different names (ex IMG_00195.jpg and IMAGE_00195 (1).jpg) and are true duplicates - [X] replace the server photo, if the file to upload is better. - - [ ] TODO: Update any album with the new version of the asset + - [X] Update any album with the new version of the asset - [ ] delete local file after successful upload (not for import!) - [ ] upload XMP sidecar files - [ ] select or exclude assets to upload by @@ -154,19 +159,18 @@ After unzipping the archive, you can use the CLI tool to upload its contents. Ho - [X] handle archives without unzipping them - [X] manage multi-zip archives (related files are scattered across all zips) - [X] handle google albums in immich - - [X] manage duplicates assets (from Photo folder and Albums) + - [X] manage duplicates assets inside the archive - [X] don't import trashed files - [X] don't import failed videos - - [ ] handle Archives, + - [ ] handle Archives - [X] option to include photos taken by a partner (the partner may also uses immich for her/his own photos) - [X] Take capture time from: - [X] JPEG files - [X] MP4 files - [X] HEIC files - - [X] name of the file (fall back) + - [X] name of the file (fall back, any name containing date like Holidays_2022-07-25 21.59) - [ ] use tags placed in exif data - [ ] upload from remote folders - [ ] ssh - [ ] samba -- [ ]