iOS Live Photo linking script

[JacobBumgarner]

Hi All,
I wanted to share a utility script I made to automate the process of linking iOS Live Photos to their Live Video counterparts. The script was written in Python and uses the Immich API link the identified assets.

Background

When I originally imported my iOS .photoslibrary to Immich using the Immich CLI, several thousand of my Live Photos weren't linked to their Live Video assets correctly. I think this was a result of my .photoslibrary being about a decade old and having gone through multiple macOS updates.

Because I had several thousands photos that needed linked, I decided to create a utility script to automate this process. The script can be cloned from my repo below.

Linking Script

GitHub Repo:
https://github.com/JacobBumgarner/immich-live-photo-linker

The script has several safe-guard features and leaves a trail that allows the actions to be reverted by a separate script. Instructions can be seen in the repo's README.

Example usage for reference:

# Dry run
python link_livephoto_videos.py --dry-run

# Test run (links a single asset to confirm process)
python link_livephoto_videos.py --test-run

# Full run
python link_livephoto_videos.py

Here is an example of the full run I ran on my Immich data base:

jacob@server:~/immich_scripts$ python link_livephoto_videos.py 
1/2: Identifying unlinked Live Photo assets...
Identified 1753 unlinked Live Photos.
Example Unlinked Live Photo/Video File Information:
    - Live Photo Original Filename: 2DE2659F-F48E-4396-91E3-A4C302231853.heic
    - Live Photo Creation Date: 2022-06-03T21:02:35.193Z
    - Live Video Original Filename: 2DE2659F-F48E-4396-91E3-A4C302231853_3.mov
    - Live Video Creation Date: 2022-06-03T21:02:34.000Z
Would you like to link these assets? [y/n] y

2/2: Linking Live Photos and Live Video assets...
Record of identified Live Photo/Video assets saved to: linked_assets_2025_01_26_044630.csv
Merging asset: 1753/1753
Update Summary:
Successfully linked 1753 files.
Live Photos linking complete!

Once this is done, a timestamped csv file of the linked assets will be produced. In the instance of linking issues, you can use this audit file to revert the asset links via:

python unlink_livephoto_videos.py --linked-csv "linked_assets_ymdhms.csv"

Info

I wrote this script such that it may be of use to others in the community facing the same issue. Of course, use the script at your own risk, and make sure you have a data base backup in case anything goes wrong.