How the Synology Photos App Fix Triggers Indexing After Downloads in docker-icloudpd

The Synology Photos app fix manipulates file timestamps to force the Synology indexing daemon to recognize newly downloaded HEIC files, ensuring they appear in the Photos app without manual intervention.

The Synology Photos app fix is a specialized feature in the docker-icloudpd container that solves a specific integration problem: Synology’s Photos app does not automatically detect media files downloaded by external tools. By enabling the synology_photos_app_fix configuration option, users can automate the indexing trigger, ensuring every HEIC file downloaded from iCloud immediately appears in their Synology library.

How the Synology Photos App Fix Works

When enabled, the fix executes a precise sequence of filesystem operations that generate the exact metadata change events the Synology Photos daemon monitors. This process runs automatically after each successful download batch completes.

Configuration and Activation

The feature is controlled by the synology_photos_app_fix boolean flag, which defaults to false as defined in init_config.sh at line 168. To activate the fix, set the environment variable or configuration file entry to true:

# In your docker-compose environment or icloudpd.conf

synology_photos_app_fix=true

Once enabled, the main synchronization script sync-icloud.sh invokes the fix function at lines 2326-2329 immediately after the download phase completes:

if [ "${synology_photos_app_fix}" = true ]; then
   synology_photos_app_fix
fi

The Timestamp Manipulation Process

The synology_photos_app_fix() function, implemented at lines 1635-1650 in sync-icloud.sh, performs a four-step timestamp dance for every newly downloaded HEIC file:

1. Parse the sync log – The function greps /tmp/icloudpd/icloudpd_sync.log for lines containing "Downloaded /" and ending with ".HEIC", extracting the absolute path of each new file.

2. Create a temporary reference – For each HEIC file, it creates an empty companion file with the extension .TMP and copies the original file’s timestamps to it using touch --reference. This preserves the original capture date metadata.

3. Trigger the indexing event – The script first runs touch "${heic_file}" to update the file’s access and modification timestamps to the current time, forcing the filesystem to emit a change event that the Synology Photos daemon detects. It then immediately restores the original timestamps by re-applying the reference from the .TMP file, ensuring the photo retains its correct chronological placement in the library.

4. Clean-up – Unless the user has set persist_temp_files, the temporary .TMP reference file is deleted.

Implementation Details in sync-icloud.sh

The complete implementation relies on precise shell operations within the sync-icloud.sh script. Here is the core function that performs the timestamp manipulation:

synology_photos_app_fix()
{
   IFS=$'\n'
   log_info "Fixing Synology Photos App import issue..."
   for heic_file in $(grep "Downloaded /" /tmp/icloudpd/icloudpd_sync.log \
                      | grep -i ".HEIC" | cut --delimiter " " --fields 9-)
   do
      log_debug "Create empty date/time reference file ${heic_file%.*}.TMP"
      run_as "touch --reference=\"${heic_file}\" \"${heic_file%.*}.TMP\""
      log_debug "Set time stamp for ${heic_file} to current: $(date)"
      run_as "touch \"${heic_file}\""
      log_debug "Set time stamp for ${heic_file} to original: $(date -r "${heic_file%.*}.TMP" +"%a %b %e %T %Y")"
      run_as "touch --reference=\"${heic_file%.*}.TMP\" \"${heic_file}\""
      log_debug "Removing temporary file ${heic_file%.*}.TMP"
      if [ -z "${persist_temp_files}" ]; then rm "${heic_file%.*}.TMP"; fi
   done
   IFS="${OLDIFS}"
}

This function is invoked conditionally based on the configuration flag, ensuring the fix only runs when explicitly enabled by the user.

Summary

The Synology Photos app fix in docker-icloudpd solves the integration gap between iCloud downloads and Synology’s media indexing daemon through precise filesystem timestamp manipulation:

• Configuration: Enable by setting synology_photos_app_fix=true in your container environment.
• Trigger: The fix runs automatically in sync-icloud.sh after each download batch completes.
• Mechanism: It creates temporary reference files, updates HEIC file timestamps to trigger indexing events, then restores original metadata to preserve chronological order.
• Scope: Currently targets HEIC files specifically by parsing the icloudpd_sync.log for downloaded images.

Frequently Asked Questions

What file types does the Synology Photos app fix support?

The current implementation specifically targets HEIC files (High Efficiency Image Container). The synology_photos_app_fix() function in sync-icloud.sh greps the sync log for entries ending in .HEIC (case-insensitive), meaning JPEG or other formats downloaded by icloudpd are not currently processed by this fix.

Do I need to manually rescan my Synology Photos library after enabling this fix?

No manual rescan is required when the Synology Photos app fix is enabled. The timestamp manipulation sequence—specifically the touch command that updates the file’s modification time—generates the exact filesystem events that the Synology Photos indexing daemon monitors. This forces automatic detection and import of newly downloaded media without user intervention.

Will enabling this fix preserve my photos' original capture dates?

Yes, the fix preserves original capture dates through a reference file technique. Before modifying timestamps, the script creates a temporary .TMP file with touch --reference to store the original metadata. After triggering the indexing event with a fresh timestamp, it immediately restores the original dates by re-applying the reference. This ensures photos appear in correct chronological order within the Synology Photos timeline.

Can I keep the temporary .TMP files for debugging purposes?

Yes, you can prevent cleanup of temporary files by setting the persist_temp_files environment variable or configuration option. By default, the synology_photos_app_fix() function removes the .TMP reference files immediately after restoring timestamps. However, if persist_temp_files is set to any non-empty value, the conditional cleanup at the end of the function is skipped, leaving the temporary files in place for troubleshooting or verification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}