fix-media-dates

Fix photo/video timestamps using a date/time prefix embedded in filenames.

This is mainly useful when media has lost metadata but filenames still contain the capture time (e.g. for Immich imports).

What It Does

The tool extracts a datetime from the start of each filename and then:

• JPEG / WebP (.jpg, .jpeg, .webp): writes EXIF DateTimeOriginal in-place (no recompression).
• HEIC / HEIF (.heic, .heif): writes DateTimeOriginal via exiftool, and aligns filesystem mtime/atime.
• Timestamp-only formats (.mov, .mp4, .avi, .mpg, .tiff, .png): aligns filesystem mtime/atime.

Live Photo pairing (MOV-only): when processing a still image with a parsable datetime, if a same-stem .mov exists in the same directory and the .mov filename does not contain a parsable datetime prefix, the tool sets that .mov file's mtime/atime to match the still.

Filename Patterns

The date prefix must appear at the beginning of the filename.

Supported prefixes:

• Full datetime: YYYY-MM-DD<sep>HH<sep>MM<sep>SS
  • <sep> is any single non-digit character (e.g. _, -, ., space)
  • Examples:
    • 2025-11-29 18.52.49.mov
    • 2025-09-28_18-04-17_IMG_5641.heic
• Date only: YYYY-MM-DD (time defaults to 12:00:00)
• Year-month: YYYY-MM (day defaults to 01, time defaults to 12:00:00)

If month or day is 00, it is normalized to 01.

Times are interpreted as local time when converting to filesystem timestamps.

Requirements

• Python 3.x
• piexif (required for JPEG/WebP EXIF updates)
• exiftool (required for HEIC/HEIF metadata updates)

Install Python deps:

python -m pip install piexif

Install exiftool (macOS via Homebrew):

brew install exiftool

Usage

Process current directory (non-recursive):

python exiffromfilename.py

Process a directory:

python exiffromfilename.py -d /path/to/media

Recursive:

python exiffromfilename.py -d /path/to/media -r

Force updates even if existing metadata/timestamps already exist:

python exiffromfilename.py -d /path/to/media -r -f

Process specific file(s) (repeat --path):

python exiffromfilename.py --path /path/to/a.heic --path /path/to/b.jpg
python exiffromfilename.py --path /path/to/a.png --path /path/to/b.webp -f

Notes:

• When --path is provided, --recursive is not allowed and --directory is ignored.
• The tool edits files in place. Test on a small copy first and keep backups.

showexif.py

Print a timestamp for one or more files:

python showexif.py /path/to/file.jpg /path/to/file.heic /path/to/file.png

Default behavior:

1. Try EXIF DateTimeOriginal via piexif.
2. If missing/unreadable, try exiftool (useful for HEIC/HEIF).
3. If still missing, fall back to filesystem mtime.

Flags:

python showexif.py --exif-only /path/to/file.jpg
python showexif.py --mtime-only /path/to/file.png