media-management

A Python CLI tool that traverses a source directory, extracts or normalizes timestamps (EXIF metadata, filenames, Google Takeout JSON, or file-modified dates), and copies media files into a structured destination organized by year.

Operations

• Recursively scans a source folder, skipping .json files.
• Determines each file’s “golden” timestamp via:
  1. EXIF/XMP metadata using exiftool (ExifToolHelper)
  2. Date embedded in the filename (e.g., YYYYMMDD_HHMMSS)
  3. Google Takeout JSON metadata (if present)
  4. Filesystem’s last-modified timestamp (as a fallback)
• Copies files into the destination under YYYY/YYYYMMDD_HHMMSS.ext
  • Renames duplicates by appending -1, -2, etc.
  • Injects EXIF metadata if absent
  • Sets the filesystem modified date to the golden timestamp

Requirements

• python
• uv
• exiftool

Arguments

Flag	Name	Description
-s	--source	Required. Path to the source directory containing media files.
-d	--destination	Required. Path to the directory where organized copies will be stored.

Execution:

python main.py --source /path/to/source --destination /path/to/output

You’ll end up with a neatly organized folder structure like:

Sorted/
└── 2023/
    ├── 20231111_032302.jpg
    ├── 20231211_040500.mp4
    └── ...
    2024/
    ├── 20241111_032302.jpg
    ├── 20241211_040500.mp4
    └── ...

Additional Resources

• Local Development
• Google Photos & Android Notes