fb-metadata-recovery 0.1.0

Recover original publish dates for Facebook photos/videos via Graph API

fb-metadata-recovery

Recover original publish dates for Facebook photos and videos that get stripped during upload.

The Problem

When you upload photos/videos to Facebook, the original EXIF metadata (including capture date) is stripped. When you later use Facebook's "Download Your Information" tool, the compressed files have incorrect or missing dates. This tool helps you rebuild that metadata.

Quick Start

pip install fb-metadata-recovery
fb-recovery download -o ~/fb_photos

How It Works

1. Download your photos from Facebook via Graph API (organized by album)
2. Parse your Facebook bulk download HTML files for metadata
3. Match items using perceptual hashing to handle Facebook's re-compression
4. Recover original publish dates and rename files accordingly

Setup

1. Get a Facebook Access Token

1. Go to Facebook Graph API Explorer
2. Create or select an app
3. Click Generate Access Token
4. Select permissions:
   • user_photos - Access your photos
   • user_videos - Access your videos
   • user_posts - Access your posts (optional)
5. Copy the token

2. Download Your Information from Facebook

1. Go to Facebook Settings → Your Information → Download Your Information
2. Select:
   • Format: JSON
   • Quality: High (for best matching)
   • Date range: All time
   • Select: Posts, Photos, Videos
3. Download and extract the ZIP file

Usage

Download All Photos (by album)

fb-recovery download -o ~/fb_photos

Creates folder structure:

fb_photos/
├── Total Carnage/
│   ├── 2012-04-10_Total Carnage_3771498489821.jpg
│   └── ...
├── Halloween 2011/
│   ├── 2011-11-13_Halloween 2011_2636658399528.jpg
│   └── ...
└── download_metadata.json

Parse Facebook Bulk Download

fb-recovery parse ~/Downloads/facebook-yourname-20240101/ -o metadata.json

Extracts dates, camera info, and captions from Facebook's HTML export.

Match & Recover Dates

fb-recovery match metadata.json --bulk-dir ~/fb_export/ -o report.csv

Matches photos between Graph API and bulk download to recover original dates.

Full Pipeline

fb-recovery full --bulk-dir ~/Downloads/facebook-export/ -o output/

Output Formats

File	Description
photos_metadata.csv	Photos with dates, camera info, CDN URLs
videos_metadata.csv	Videos with dates, titles, file paths
download_metadata.json	Full metadata for all media
recovery_report.csv	Matched items with recovered dates

Commands

Command	Description
fb-recovery download	Download all photos via Graph API (by album)
fb-recovery parse	Parse Facebook HTML export for metadata
fb-recovery match	Match scan results against bulk download
fb-recovery scan	List all photos/videos from Graph API
fb-recovery full	Run full pipeline

Token Caching

Your access token is cached at ~/.fb-metadata-recovery/token.json with restricted permissions (600). To clear it:

rm ~/.fb-metadata-recovery/token.json

Privacy

This tool runs entirely locally. Your access token and media files never leave your machine. No data is sent to third parties.

License

MIT