media-downloader/docs/REVIEW_QUEUE_STRUCTURE.md

Review Queue Directory Structure

Overview

The review queue maintains the same directory structure as the final destination to keep files organized and make it clear where they came from.

Directory Structure

When a file doesn't match face recognition and is moved to review:

Original destination:  /opt/immich/md/social media/instagram/posts/filename.mp4
↓
Review location:      /opt/immich/review/social media/instagram/posts/filename.mp4

Examples

Instagram Post:

/opt/immich/md/social media/instagram/posts/evalongoria_20251101.jpg
→
/opt/immich/review/social media/instagram/posts/evalongoria_20251101.jpg

Instagram Story:

/opt/immich/md/social media/instagram/stories/evalongoria_story.mp4
→
/opt/immich/review/social media/instagram/stories/evalongoria_story.mp4

TikTok Reel:

/opt/immich/md/social media/tiktok/reels/video.mp4
→
/opt/immich/review/social media/tiktok/reels/video.mp4

Database Storage

When files are moved to review, the database stores:

1. file_path: Current location in review directory

   /opt/immich/review/social media/instagram/posts/filename.mp4
   

2. metadata.intended_path: Original intended destination

   {
     "intended_path": "/opt/immich/md/social media/instagram/posts/filename.mp4"
   }
   

Implementation

move_module.py (for new downloads)

base_path = Path("/opt/immich/md")
if destination.is_relative_to(base_path):
    relative_path = destination.relative_to(base_path)
    review_dest = Path("/opt/immich/review") / relative_path
else:
    review_dest = Path("/opt/immich/review") / source.name

retroactive_face_scan.py (for existing files)

base_path = Path(SCAN_BASE_DIR)  # /opt/immich/md
file_path_obj = Path(file_path)

if file_path_obj.is_relative_to(base_path):
    relative_path = file_path_obj.relative_to(base_path)
    review_path = Path(REVIEW_DIR) / relative_path
else:
    review_path = Path(REVIEW_DIR) / file_path_obj.name

Review UI Operations

Keep Operation

When user clicks "Keep" in Review UI:

1. Reads metadata.intended_path from database
2. Moves file from /opt/immich/review/... to intended_path
3. Updates database file_path to final location
4. Removes intended_path from metadata

Delete Operation

• Deletes file from review directory
• Removes database entry

Add Reference Operation

1. Extracts face encoding from file
2. Adds to face recognition references
3. Moves file to intended_path
4. Updates database

Benefits

1. Organization: Easy to see file types and sources at a glance
2. Clarity: Maintains context of where file came from
3. Batch Operations: Can select all files from a specific platform/type
4. Filtering: Can filter review queue by platform or source
5. Restoration: Simple to move files back to intended location

Version

Updated in v6.6.0 (2025-11-01)