Home - Xentraxx/GooglePhotosTakeoutHelper GitHub Wiki

Google Photos Takeout Helper 📸

Transform your chaotic Google Photos Takeout into organized photo libraries with proper dates, albums, and metadata.

What This Tool Does

When you export photos from Google Photos using Google Takeout, you get a mess of folders with weird .json files and broken timestamps. This tool:

  • ✅ Organizes photos chronologically with correct dates
  • ✅ Restores album structure with multiple handling options
  • ✅ Fixes timestamps from JSON metadata and EXIF data
  • ✅ Writes GPS coordinates and timestamps back to media files
  • ✅ Removes duplicates automatically
  • ✅ Handles special formats (HEIC, Motion Photos, etc.)
  • ✅ Fixes mismatches of file name and mime type

Key Features

🔄 8-Step Processing Pipeline

  1. Extension Fixing - Correct mismatched file extensions
  2. Media Discovery - Find and classify all media files
  3. Duplicate Removal - Eliminate duplicates using content hashing
  4. Date Extraction - Determine timestamps from multiple sources
  5. EXIF Writing - Embed metadata into files
  6. Album Detection - Smart folder classification
  7. File Organization - Strategy-based file moving
  8. Timestamp Sync - Final timestamp alignment (Windows)

📁 Flexible Album Handling

  • Shortcut Mode: Space-efficient symbolic links (recommended)
  • Duplicate Copy: Physical copies in all locations
  • Reverse Shortcut: Album-centric organization
  • JSON Mode: Programmatic album metadata
  • Nothing Mode: Simple chronological organization

🌍 Advanced Metadata Processing

  • GPS Coordinates: Extract and embed location data
  • Date Intelligence: Multiple extraction methods with accuracy scoring
  • Format Support: JPEG, HEIC, RAW, Motion Photos, and more
  • ExifTool Integration: Comprehensive metadata handling

Architecture Highlights

GPTH is built using clean architecture principles with:

  • Domain-Driven Design for maintainable code
  • Pipeline Pattern for sequential processing
  • Strategy Pattern for album handling modes
  • Service Container for dependency management
  • Immutable Data Models for thread safety

Getting Started

  1. Installation and Setup - Download and configure GPTH
  2. Quick Start Guide - Process your first export
  3. Album Handling Modes - Choose your organization strategy
  4. Configuration Options - Customize your processing

Documentation Structure

📖 User Guides

Learn how to use GPTH effectively for your photo organization needs.

⚙️ Technical Documentation

Understand the architecture, processing pipeline, and advanced features.

🛠️ Troubleshooting

Solve common issues and optimize performance for your specific setup.

📋 Reference

Complete command-line documentation and configuration options.

Project Status

Current Version: v4.1.1-Xentraxx (Documentation was created based on this version) Maintenance: Active development with bug fixes and feature improvements

Acknowledgment: This project builds upon the original work by TheLastGimbus. We are grateful for their foundational contributions to the Google Photos Takeout ecosystem.

Quick Links