Metadata-Version: 2.4
Name: fb-metadata-recovery
Version: 0.1.0
Summary: Recover original publish dates for Facebook photos/videos via Graph API
Project-URL: Homepage, https://github.com/WOODSEE-DIGI/fb-metadata-recovery
Project-URL: Repository, https://github.com/WOODSEE-DIGI/fb-metadata-recovery
Project-URL: Issues, https://github.com/WOODSEE-DIGI/fb-metadata-recovery/issues
Author: WOODSEE-DIGI
License-Expression: MIT
License-File: LICENSE
Keywords: backup,facebook,metadata,photos,recovery,videos
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: imagehash>=4.3.1
Requires-Dist: pillow>=10.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tqdm>=4.66.0
Description-Content-Type: text/markdown

# fb-metadata-recovery

[![PyPI version](https://badge.fury.io/py/fb-metadata-recovery.svg)](https://pypi.org/project/fb-metadata-recovery/)
[![Python](https://img.shields.io/pypi/pyversions/fb-metadata-recovery)](https://pypi.org/project/fb-metadata-recovery/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
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](https://developers.facebook.com/tools/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)

```bash
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

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

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

### Match & Recover Dates

```bash
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

```bash
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:

```bash
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
