Snapchat Memories Downloader

A powerful Python tool to download Snapchat memories from your data export with full metadata preservation, parallel downloads, and overlay support.

Features

• 📥 Parallel Downloads - Download multiple files simultaneously for faster processing
• 📊 Progress Bar - Real-time progress with ETA and download speed (using tqdm)
• 🔄 Resume Support - Interrupt and restart without re-downloading existing files
• 📅 Date Preservation - Preserves original creation dates in file metadata
• 📍 GPS Coordinates - Embeds location data in EXIF metadata
• 🎨 Overlay Merging - Optionally apply Snapchat filters/stickers to images and videos
• 🎬 Video Metadata - Sets creation time and GPS using ffmpeg
• 📁 Smart Naming - Files named with timestamps for easy chronological sorting
• 📝 Logging - Detailed log file for tracking errors and progress

Installation

1. Install Python Dependencies

pip install -r requirements.txt

Or manually:

pip install requests pillow piexif tqdm

2. Install ffmpeg (Optional but Recommended)

ffmpeg is required for video metadata and overlay merging.

macOS:

brew install ffmpeg

Windows:

winget install ffmpeg

Linux:

sudo apt install ffmpeg

Quick Start

Command Line Usage

# Basic download
python3 download_via_json.py memories_history.json

# Specify output folder
python3 download_via_json.py memories_history.json -o my_memories

# With 8 parallel downloads (faster)
python3 download_via_json.py memories_history.json -p 8

# With overlay merging (applies Snapchat filters/stickers)
python3 download_via_json.py memories_history.json --merge-overlay

# Full example
python3 download_via_json.py memories_history.json -o my_memories -p 4 --merge-overlay

Interactive Mode

Run without arguments for interactive prompts:

python3 download_via_json.py

Command Line Options

Option	Description
json_file	Path to the memories_history.json file
-o, --output	Output directory (default: downloads)
-p, --parallel	Number of parallel downloads (default: 4)
-q, --quiet	Quiet mode - reduced output
--merge-overlay	Merge overlay PNG onto images and videos
--log	Custom log file path (default: <output>/download.log)
-h, --help	Show help message

Getting Your Snapchat Data Export

1. Open Snapchat → Profile → ⚙️ Settings
2. Go to Privacy Controls → My Data
3. Click Submit Request
4. Wait for email (usually 24-48 hours)
5. Download and extract the ZIP file
6. Find json/memories_history.json

Example Output

Loading JSON from: memories_history.json
Found 39993 media items to download
Estimated download size: 195.3 GB
Disk space: Disk space OK: 450.2 GB available

Starting download with 4 parallel workers...
Overlay merging: ENABLED
Log file: downloads/download.log

Downloading: 45%|████████████      | 18000/39993 [1:30:00<1:50:00, 3.33file/s]

✓ Statistics:
  Downloaded: 18000 new files (85.2 GB)
  Skipped: 0 existing files
  Errors: 5 files failed
  Total processed: 18000 of 39993
  Time elapsed: 5400.0 seconds
  Average speed: 15.78 MB/s

Output Files

File Naming

YYYYMMDD_HHMMSS_<index>.<extension>

Examples:

• 20240506_231811_1.jpg - Image from May 6, 2024 at 11:18:11 PM
• 20240507_143245_2.mp4 - Video from May 7, 2024 at 2:32:45 PM

Metadata Preserved

Type	File Timestamp	EXIF Date	GPS Location
Images (.jpg)	✅	✅	✅
Videos (.mp4)	✅	✅ (with ffmpeg)	✅ (with ffmpeg)

About Overlays

Snapchat delivers some media as ZIP files containing:

• -main.jpg or -main.mp4 - The original media
• -overlay.png - Filters, stickers, text, etc.

Without --merge-overlay

• Extracts only the main image/video
• Faster processing
• No filters/stickers visible

With --merge-overlay

• Composites the overlay onto the media
• Images: Quick (PIL compositing)
• Videos: Slower (requires ffmpeg re-encoding, use -p 2)
• Preserves your Snapchat creativity!

Repair Scripts

If you've already downloaded files and some videos are broken (saved as ZIP files), use these repair scripts:

Quick Repair (No Overlay)

# Dry run first
python3 repair_video_zips.py /path/to/downloads --dry-run

# Run repair
python3 repair_video_zips.py /path/to/downloads

# Faster with more workers
python3 repair_video_zips.py /path/to/downloads -p 8

Repair with Overlay

# Keep original for comparison
python3 repair_video_zips_with_overlay.py /path/to/downloads --keep-original

# Standard repair with overlay
python3 repair_video_zips_with_overlay.py /path/to/downloads

Script	Purpose	Speed
repair_video_zips.py	Extract videos without overlay	Fast
repair_video_zips_with_overlay.py	Extract + apply overlay	Slower (re-encodes)

Performance Tips

1. Parallel Downloads: Use -p 4 to -p 8 for downloads (network-bound)
2. Video Overlay: Use -p 2 when using --merge-overlay (CPU-bound)
3. Resume: If interrupted, just re-run - existing files are skipped
4. Disk Space: Check available space before large downloads
5. Download Quickly: Snapchat URLs expire - download soon after receiving export

Troubleshooting

"No download URL found"

• Check your JSON file has the Media Download Url field
• URLs may have expired - request a new export

"Downloaded HTML instead of media"

• Download URLs have expired
• Request a new Snapchat data export

ffmpeg errors

• Ensure ffmpeg is installed and in your PATH
• Run ffmpeg -version to verify

Overlay not applied

• Ensure --merge-overlay flag is used
• Check log file for specific errors
• Some overlays may be corrupted in the export

File Structure

Snapchat_Memories_Export_Helper/
├── download_via_json.py          # Main downloader
├── repair_video_zips.py          # Repair script (no overlay)
├── repair_video_zips_with_overlay.py  # Repair script (with overlay)
├── requirements.txt              # Python dependencies
├── README.md                     # This file
└── downloads/                    # Default output folder
    ├── download.log              # Log file
    ├── 20240101_120000_1.jpg
    ├── 20240102_153045_2.mp4
    └── ...

Requirements

• Python 3.7+
• requests
• pillow
• piexif
• tqdm (optional, for progress bar)
• ffmpeg (optional, for video metadata and overlays)

License

Free to use and modify for personal use.

Disclaimer

This tool is not affiliated with Snapchat. It helps users organize their own personal data exports. Use in accordance with Snapchat's Terms of Service.