addmetadata

A Python CLI tool that extracts dates from video filenames and injects them as metadata so Apple Photos imports them with the correct date.

The Problem

Video files with dates in their filenames (e.g., clip-2012-07-28 17;53;41 (id)-appletv3.mp4) often lack proper metadata. When imported into Apple Photos, they default to 01-01-2000.

The Solution

This tool parses dates from filenames and writes them to the metadata fields that Apple Photos reads.

Prerequisites

1. Python 3.8+

2. exiftool - Install via Homebrew:

   brew install exiftool

Installation

cd addmetadata
pip install -r requirements.txt

Usage

GUI Mode (folder picker)

python -m addmetadata --gui

Or simply run without arguments to auto-launch the folder picker:

python -m addmetadata

Command Line

# Preview changes (recommended first step)
python -m addmetadata /Volumes/External/Videos --dry-run --verbose

# Process all files
python -m addmetadata /Volumes/External/Videos --verbose

# Force update even if dates exist
python -m addmetadata /Volumes/External/Videos --force

# Specify timezone and save report
python -m addmetadata /Volumes/External/Videos --timezone="-05:00" --report=changes.json

Options

Option	Description
--gui, -g	Open folder picker dialog
--dry-run, -n	Preview changes without modifying files
--force, -f	Update even if valid date already exists
--recursive, -r	Search subdirectories (default: true)
--no-recursive	Only process files in top-level directory
--timezone, -tz	Timezone offset (e.g., -05:00). Defaults to local
--verbose, -v	Show detailed progress
--report, -o	Save JSON report to specified file

Supported Filename Patterns

The tool recognizes these date formats in filenames:

Pattern	Example	Confidence
clip-YYYY-MM-DD HH;MM;SS (id)-suffix	clip-2012-07-28 17;53;41 (id)-appletv3.mp4	High
clip-YYYY-MM-DD HH;MM;SS-suffix	clip-2012-07-28 17;53;41-appletv3.mp4	High
YYYY-MM-DD HH;MM;SS anywhere	video_2012-07-28 17;53;41.mp4	Medium
YYYYMMDD_HHMMSS	20120728_175341.mp4	Low
YYYY-MM-DD (date only)	vacation-2012-07-28.mp4	Low

How It Works

The tool sets these metadata fields to ensure Apple Photos recognizes the date:

• QuickTime:CreateDate - Standard QuickTime creation date
• QuickTime:ModifyDate - Modification date
• Keys:CreationDate - Apple-specific field (with timezone offset)
• FileCreateDate - Filesystem creation date
• FileModifyDate - Filesystem modification date

Workflow

1. Dry run first to preview what will change:

   python -m addmetadata /path/to/videos --dry-run --verbose

2. Check a sample file before and after:

   exiftool -a -G1 -s -Time:All sample.mp4

3. Process files once satisfied:

   python -m addmetadata /path/to/videos --verbose

4. Import into Apple Photos - dates should now appear correctly