How Sideways Copy Videos Works With video_path in docker-icloudpd

The sideways copy videos feature duplicates or moves downloaded iCloud videos to a secondary directory specified by video_path, preserving folder structure and permissions while supporting both incremental and full-archive modes.

The docker-icloudpd container supports a sideways copy videos capability that mirrors your downloaded videos to a separate location using the video_path environment variable. This feature, implemented in the sync-icloud.sh and launcher.sh scripts, creates a parallel video archive without interfering with iCloud Photo Downloader's primary download directory.

Configuration Requirements

To enable sideways copying, you must define three environment variables in your .env file or docker-compose.yml:

• sideways_copy_videos=true – Activates the feature
• video_path=/path/to/videos – The destination directory for video files
• sideways_copy_videos_mode=copy|move – Determines whether to duplicate or relocate files

According to launcher.sh at line 381, the container automatically creates the video_path directory during initialization and aligns its ownership and permissions with the main download directory. However, if you set sideways_copy_videos_mode=move, the script enforces that delete_after_download must also be true to prevent the same videos from being re-downloaded on subsequent syncs (see launcher.sh lines 20–24).

Runtime Validation

Before executing any file operations, sync-icloud.sh validates that video_path is properly configured. At lines 1526–1534, the script verifies the variable is defined and points to an existing directory. If validation fails, the container aborts with a descriptive error message rather than attempting partial copies.

How the Copy Process Works

The implementation distinguishes between two workflows: copying only newly downloaded videos or copying the entire existing archive.

Building the File List

The system uses different methods to identify videos depending on the operation scope:

Incremental copying (sideways_copy_videos): At lines 8198–8220 in sync-icloud.sh, the script parses the iCloudPD sync log located at /tmp/icloudpd/icloudpd_sync.log. It filters for .mov and .mp4 entries while excluding hevc.mov files, deduplicates the list, and derives destination sub-folders from the relative paths recorded in the log.

Full archive copying (sideways_copy_all_videos): When invoked with the --sideways-copy-all-videos flag, the script walks the entire download_path tree using the find command (lines 1538–1549). It collects all *.mp4 and *.mov files (again excluding hevc.mov) and maps the complete folder structure for replication under video_path.

Directory Creation and Permissions

For each required sub-directory under video_path, the script creates the directory if it does not exist and mirrors the source folder's ownership and permissions. At lines 1550–1559 in sync-icloud.sh, the implementation uses chown --reference and chmod --reference to ensure the secondary location maintains identical access controls to the primary download directory.

File Operations

The actual transfer occurs at lines 1665–1672:

• Copy mode: Executes cp --update=none --preserve to duplicate files while skipping existing entries and preserving timestamps
• Move mode: Executes mv --update=none --preserve to relocate files, but only when delete_after_download=true is confirmed

Each operation is logged via log_debug for audit purposes.

Usage Examples

Docker Compose Configuration

Mount a dedicated volume for your video archive and reference it in the environment:

services:
  icloudpd:
    image: boredazfcuk/docker-icloudpd:latest
    environment:
      - sideways_copy_videos=true
      - video_path=/videos/icloud
      - sideways_copy_videos_mode=copy
    volumes:
      - icloud-data:/data
      - /mnt/media/videos:/videos/icloud

Environment File for Copy Mode

sideways_copy_videos=true
video_path=/videos/icloud
sideways_copy_videos_mode=copy
delete_after_download=false

Environment File for Move Mode

sideways_copy_videos=true
video_path=/videos/icloud
sideways_copy_videos_mode=move
delete_after_download=true

Manual Full Archive Copy

To copy all existing videos without waiting for a new sync, execute inside the container:

./sync-icloud.sh --sideways-copy-all-videos

Summary

• The sideways copy videos feature creates a parallel video archive at the location specified by video_path
• launcher.sh handles directory creation and validates that move mode requires delete_after_download=true
• sync-icloud.sh implements two workflows: incremental copying from sync logs and full archive copying via find
• File permissions are preserved using --reference flags during directory creation
• The feature supports both copy (duplicate files) and move (relocate files) modes via sideways_copy_videos_mode

Frequently Asked Questions

What is the difference between copy and move mode?

Copy mode duplicates videos to video_path while keeping the originals in the iCloud download directory, suitable for creating backups or feeding media servers. Move mode relocates videos to video_path and removes them from the download directory, requiring delete_after_download=true to prevent re-download loops.

Can I use sideways copy with delete_after_download disabled?

You can use copy mode with delete_after_download=false, but move mode explicitly requires delete_after_download=true. The validation logic in launcher.sh prevents dangerous configurations that would cause continuous re-downloading of moved files.

How do I copy existing videos without re-downloading?

Invoke the manual command ./sync-icloud.sh --sideways-copy-all-videos inside the container. This triggers the sideways_copy_all_videos() function which scans your existing download_path for all video files and copies them to video_path without initiating a new iCloud sync.

What video file types are supported?

The feature processes files with .mov and .mp4 extensions while explicitly excluding hevc.mov files. This filtering occurs whether building the list from sync logs or walking the directory tree with find.

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