Snapchat Memories and Chat Media Caption Adder and Metadata Restoration Tool

📖 Overview

This tool rebuilds a user's Snapchat Memories and Chat Media, restoring pictures, videos, and voice messages with accurate timestamps, GPS coordinates, and captions where available. It ensures your files appear correctly with all necessary metadata attached to the media files in Windows File Explorer and iCloud Photos, with media properly displayed in map and timeline views.

🎬 YouTube Video Demonstration

---

✨ Key Features

• Restores date, time, and GPS metadata to Memories
• Adds overlays / captions to Memories
• Merges multi-clip video Memories
• Processes Chat Media and voice messages with date metadata
• Photos and Videos compatible with Apple Photos
• Renames files by date and time

---

📌 Table of Contents

• 📖 Overview
• 🎬 YouTube Video Demonstration
• ✨ Key Features
• 📸 Memories
• 📩 Chat Media
• 🧩 Extensive Feature List / How it Works
• ⬇️ Clone or Download the Repository
• 📦 Downloading Your Snapchat Data and Moving its Folders
  • Step 1 - Request your Snapchat data
  • Step 2 - Download your Memories
  • Step 3 - Extract all memory ZIP files into one folder
    • 🪟 Windows
    • 🍏 macOS
  • Step 4 - Move Chat Media
  • Step 5 - Locate the JSON metadata file
  • Final input folder structure
• ⚙️ Installation
  • 1. Install Python
    • 🪟 Windows
    • 🍏 macOS
  • 2. Install Required Programs
    • 🧾 Download ExifTool
    • 🧩 Download FFmpeg & FFprobe
  • 3. Install Required Python Packages
• 🗂️ Final Folder Setup
• ▶️ How to Run Script
• 📤 Importing to Apple Photos
  • 🪟 Windows
  • 🍏 MacOS
• 🔒 System Security Reminders
  • 🪟 Windows
  • 🍏 macOS
• 🧹 Files Not Required to Run the Script
• 🪪 License
• 🙌 Acknowledgments & Background

Memories

Chat Media

---

🧩 Extensive Feature List / How it Works

List of all tool’s features along with a high-level explanation of how each function operates. (For a deeper look, see the Code_Logic file in the repository.)

🕒 Embeds Date, Time, and Location Metadata for Memories

• Restores each memory’s metadata by matching its filename’s unique ID to the corresponding record in the memories_history.json file.
• Extracts each file’s date, time, and GPS coordinates from memories_history.json, converting from UTC to the memory’s local timezone based on its GPS coordinates (with correct DST handling).
• Uses the system timezone when GPS data is unavailable.
• Embeds GPS metadata that is fully compatible with Apple Photos, ensuring photos and videos appear correctly in the Map view.
• Creates two output folders ensuring correct display across systems:
  • memories location time/ — timestamps converted to the GPS location’s timezone.
  • memories system time/ — timestamps converted to the system’s timezone (recommended for Apple Photos).

🖼️ Memories Overlay Support (Captions & Filters)

• Matches image and video _main files with their corresponding _overlay.png.
• Applies overlays to all media types and orientations (including videos saved from outside apps like TikTok) with proper scaling and positioning.
• Produces both overlayed and non-overlayed versions of each file, ensuring identical date, time, and GPS metadata across both.

🎬 Merging Multi-Clip Video Memories

• Detects long-form video memories split into multiple clips by matching .mp4 files with identical GPS coordinates and timestamps within 10 seconds of each other.
• Merges these clips into a single video, preserving metadata and chronological order.

💬 Chat Media Handling

• Extracts the date from each filename and embeds it into file metadata.
• Sets all Chat Media timestamps to 12:00 PM since no time data is provided by Snapchat.
• Skips video thumbnail images to avoid redundancy.
• Separates saved Chat Media into organized folders:
  • chat media/ — for images and videos.
  • chat media voice messages/ — for saved voice notes.

🏷️ File Renaming

• Memories:
  • Renames files using the format YYYY-MM-DD_HH-MM-SS (adds _overlay if applicable).
  • If multiple files share the same timestamp, adds incremental numbering (_1, _2, etc.) to avoid duplicates.
• Chat Media:
  • Uses format YYYY-MM-DD_chat_media_# for images/videos and YYYY-MM-DD_voice_message_# for voice messages.
  • Also adds incremental numbering for duplicates (_1, _2, etc.).

---

⬇️ Clone or Download the Repository

If you have Git installed:

git clone https://github.com/sean-mehra/Snapchat_Memories_Tool.git
cd Snapchat_Memories_Tool

💡 Alternatively:
If you’re not using Git, go to the repository webpage and click
Code → Download ZIP, then extract it.

The downloaded folder may have a -main written at the end of the filename. You can remove it making sure the folder name is Snapchat_Memories_Tool to remain consistent with the rest of the directions here.

---

📦 Downloading Your Snapchat Data and Moving its Folders

⚠️ Export format notice ⚠️
Snapchat has changed how My Data exports work.
Older exports came with all Memories already bundled inside a memories/ folder.
New exports instead provide a memories_history.html file which links to where users have to download individual ZIP files for each memory.

This tool was originally designed for the older format but fully supports the current export system — it just requires one extra step of manually consolidating the memories files.

To use this tool, you must first export your data from Snapchat.

Step 1 - Request your Snapchat data

1. Go to Snapchat’s My Data page.

2. Log in with your Snapchat account.

3. Make sure the following boxes are selected:

   • ✅ Memories
   • ✅ JSON Files
   • ✅ Chat Media

4. Select All Time for the date range and enter an email where Snapchat can send your export link.

5. Wait for Snapchat to email you a download link (this may take a while).

6. Download and extract the main ZIP file.

⚠️ Important:

If you have a past version of Snapchat's "My Data" export where all the memories came in their own dedicated memories/ folder:

Put the content of that memories folder into Snapchat_Memories_Tool/input/memories/ and you can skip steps 2 and 3 in this section and go straight to Step 4 - Move Chat Media

However, if you are exporting your data now:

Snapchat requires users to download all their memories in individual zipped files through their website.

Steps provided for the setup below.

Step 2 - Download your Memories (new export format)

After extracting the ZIP, find and open memories_history.html in the mydata~X/html/

This will open a webpage with your Snapchat Memories all listed avaliable to download.

Wait for all the downloads to complete. Each memory will download as its own ZIP file.

Step 3 - Extract all memory ZIP files into one folder

Now extract all downloaded memory ZIP files and put the contents into Snapchat_Memories_Tool/input/memories/.

If you do not need help doing this go straight to Step 4 - Move Chat Media

This can be done manually. However, manually opening each unzipped folder then copying and pasting its contents into a seperate folder can be time consuming depending on how many folders Snapchat generates, so listed below are steps to help guide users on how to do this in a streamlined fashion:

First create a seperate folder that will temporarily be dedicated to put all the extracted unzipped folders into one place.
(For this example I named the folder memories temp)

🪟 Windows

Windows does not natively allow users to extract multiple zipped files at once.
In order to accomplish this a zip tool needs to be used — for this example I am using 7-Zip.

Open the 7zFM Application and open the folder with all the zipped files (here it is the downloads folder)

Go to view and select Type so all the zipped files are next to each other

Highlight all the zipped files and press Extract

Enter the path for the memories temp folder

The program will extract them into multiple unzipped folders.

For the next steps continue here.

🍏 macOS

Sort by Kind by clicking the column heading so all the zipped files are next to each other (if one of those headings is not there right click the heading row and select it from the options)

Look for the Zipped files and highlight them. Right-click and select Open With > Archive Utility.

Your system will extract them into multiple unzipped folders.

Next move the extracted folders to the memories temp folder

Now open the memories temp folder

Click the search bar in the top-right corner. Then type "." into the search.

This will display every file inside every subfolder.

Select all the photo and video files then drag or copy and paste them into Snapchat_Memories_Tool/input/memories/

Step 4 - Move Chat Media

Now move the Contents of the chat_media folder into Snapchat_Memories_Tool/input/chat_media/:

👉 Final goal:

• All memory media → input/memories/
• All chat media → input/chat_media/

Step 5 - Locate the JSON metadata file

In your exported Snapchat data, locate: memories_history.json in the json/ folder

Copy this file into your input/ folder.

Final input folder structure

Once everything is ready, your folder should look like this:

Snapchat_Memories_Tool/
  input/
    memories/
    chat_media/
    memories_history.json

---

⚙️ Installation

1. Install Python

This tool is written in Python, so Python 3 must be installed before running the script.

🪟 Windows

Windows does not include Python by default.

1. Download Python from the official website:
   https://www.python.org/downloads/windows/
2. Run the installer.
3. Important: Check the box “Add Python to PATH” during installation.
4. Finish the install and restart PowerShell.

🍏 macOS

macOS includes an old version of Python by default. Depending on the version it may or not be able to run this script.
You must have a modern version of Python 3 installed.

1. Download Python for macOS:
   https://www.python.org/downloads/macos/
2. Open the .pkg installer and complete setup.
3. Restart Terminal.

To verify installation:

python3 --version

If successful, you should see something like:

Python 3.x.x

💡 Tip: If both python and python3 work on your system, use whichever one prints a Python 3 version.

2. Install Required Programs

• 🧾 Download ExifTool — used to read and write photo and video metadata.

  1. Locate the downloaded file — it will usually be named exiftool(-k).exe on Windows or exiftool on Mac.
  2. If you see “(-k)” in the name, rename it to exiftool.exe.

     ⚠️ The “-k” flag keeps the window open and can interfere with automated processing.

  3. Move the single exiftool.exe (Windows) into the same folder as snapchat_metadata.py (the Snapchat_Memories_Tool/ folder).

     ⚠️ For Mac standard package should already place it in /usr/local/bin for easy Terminal access

• 🧩 Download FFmpeg & FFprobe — used to process and merge videos.

  1. Download the ZIP file for your operating system.
  2. Extract the ZIP file.
  3. Inside the extracted folder, open the bin (or contents) folder — you’ll find a file named ffmpeg.exe (Windows) or ffmpeg (Mac).
  4. For windows move that files into the same folder as snapchat_metadata.py (the Snapchat_Memories_Tool/ folder).

     ⚠️ For Mac move files into /usr/local/bin

  To verify they are working, open Terminal or PowerShell and type:

  ffmpeg -version
  ffprobe -version

  If version info appears, you’re ready to go ✅

💡 Note:
On some systems, when ExifTool and FFmpeg are downloaded they may already be available through your terminal. However, to avoid any path or permission issues, this guide recommends placing both executables directly in the same folder as snapchat_metadata.py for guaranteed compatibility.

💡 Optional (Advanced Users):
If you prefer, you can install FFmpeg and ExifTool globally using a package manager like Chocolatey (Windows) or Homebrew (Mac).

Windows (Chocolatey):

choco install ffmpeg exiftool

Mac (Homebrew):

brew install ffmpeg exiftool

⚠️ Important:
Don’t mix installs. Use either a global install or local executables in this folder — not both.
If you use Chocolatey/Homebrew (global), do not place exiftool.exe, ffmpeg.exe, or ffprobe.exe in the project folder, or the script may fail to detect the correct one.

3. Install Required Python Packages

Open your terminal or PowerShell and run this command once:

pip install pytz tzlocal timezonefinder Pillow

If successful, you’ll see a message similar to:

Successfully installed pytz tzlocal timezonefinder Pillow

---

🗂️ Final Folder Setup

Place your exported Snapchat data into the input folder.

• Make sure you’ve already exported your data and moved files following the 📦 Downloading Your Snapchat Data and Moving its Folders instructions.
• Include these three items inside the input/ folder:
  • memories/ — folder containing exported Memories (photos/videos)
  • chat_media/ — folder containing saved media from chats (photos/videos/voice messages)
  • memories_history.json — metadata file with date, time, and GPS data

💡 Tip:
If your downloaded memories and chat_media folders from Snapchat's 'My Data' export contains a large number of files, consider selecting only the specific photos or videos you want to process.
Processing a large amount of files can take a long time depending on your system’s speed and the number of memories.

Your project folder should look like this:

Snapchat_Memories_Tool/
│
├── input/
│   ├── chat_media/                (downloaded from Snapchat My Data)
│   ├── memories/                  (downloaded from Snapchat My Data)
│   └── memories_history.json      (downloaded from Snapchat My Data)
│
├── output/
│   ├── chat media/                (processed chat photos & videos)
│   ├── chat media voice messages/ (processed voice messages)
│   ├── memories location time/    (Memories using GPS-local timezone)
│   └── memories system time/      (Memories using system-local timezone)
│
├── exiftool.exe   (for Windows)   (ExifTool executable for metadata)
├── ffmpeg.exe     (for Windows)   (FFmpeg executable for video processing)
├── ffprobe.exe    (for Windows)   (FFprobe executable for video processing)
├── snapchat_metadata.py           (main Python script)
├── README.md                      (directions)
├── LICENSE.txt                    (project license)
├── Code_Logic.md                  (explanation of how each function works)
└── examples/                      (demonstration images for README.md)

(Image examples are for windows)
(Make sure to include ffprobe as well)

The input folder should contain your memories, chat_media, and memories_history.json files as downloaded from the Snapchat “My Data” portal.

⚙️ Note:
Most users should place both ffmpeg.exe and exiftool.exe in the main project folder (as shown above).
However, if you’ve installed them globally using Chocolatey (Windows), Homebrew (Mac), or the package already gets placed in /usr/local/bin (Mac)
do not also place copies in the folder — the script will automatically detect your global installation.

---

▶️ How to Run Script

1. Type this in your terminal or PowerShell to open the project folder:

   cd path/to/Snapchat_Memories_Tool

2. Type this to run the script:

   python snapchat_metadata.py

3. Wait for processing to finish.

• output/chat media/ → Photos and videos from saved chats with corrected timestamps
• output/chat media voice messages/ → Voice messages from saved chats with corrected timestamps
• output/memories location time/ → Memories timestamps converted to GPS timezone
• output/memories system time/ → Memories timestamps converted to your system’s timezone

4. View or upload your results.
   • Files in memories location time sort correctly by title when viewed in File Explorer (recommended for Windows).
   • Files in memories system time display accurate timestamps and map locations when uploaded to iCloud Photos (recommended for Apple Photos).
   • Files in chat media and chat media voice messages will appear with accurate creation dates and fully restored metadata.

💡 Note:
The filenames in both memories location time/ and memories system time/ folders use the GPS-local time for consistency and accurate chronological sorting by name, so only the timestamp internal metadata differs between both folders.
While script is running you might briefly see temporary files appear in your project folder (for example, names like temp_concat_12345.mp4 or exiftool_tmp). These are automatically created by FFmpeg or ExifTool, while re-encoding videos and writing metadata. They are automatically deleted once processing finishes, so you don’t need to remove them manually.

---

📤 Importing to Apple Photos

After processing completes, when importing to Apple Photos follow next steps to ensure timestamps and GPS data display correctly across all Apple devices.

🪟 Windows (via iCloud for Windows)

1. Open the iCloud Photos folder in File Explorer.
2. Copy or drag the processed files from output/memories system time/ into the iCloud Photos folder in file explorer.
3. Wait for them to sync — they’ll appear in your iPhone’s Photos app with correct timestamps and GPS data and can be sorted by Date Captured.

🍏 macOS

1. Open the Photos app.
2. Select the processed files you want from the output/memories location time/ folder and copy or drag them to the Photos App.
3. These photos and vidoes will have the correct date and map locations automatically and can be sorted by Date Captured. They will also show up as a part of the Import section of photos.

🕓 Note on time display:
Apple Photos on iPhone automatically adjusts timestamps using GPS location data, while the macOS Photos app typically displays the embedded timestamp as-is.
This means photos may appear unchanged in time on Mac but will display the correct localized time when viewed on iPhone.

iPhone Photo:

Mac Photo:

💡 Important Notes:
If uploaded files fail to appear, try renaming them or clearing cached versions in iCloud Photos.
If a video’s preview image doesn’t appear right away, just wait — Photos will generate it shortly.
On Windows when using iCloud for Windows always upload from output/memories system time/ — Apple Photos automatically adjusts for GPS timezones.
On Mac when importing to Photos App always use output/memories location time/
Using the wrong one can cause timestamps to appear double-adjusted.
Run the script and upload your files while your device is in the same timezone.
Uploading from a different timezone than where the script was run can shift timestamps by several hours.

For users utilizing the latest version of "My Data" Exports there may be some photo and/or video files that were not put in any zipped folders when downloaded. They appear to mostly be photos and videos saved to Snapchat Memories from the camera roll.
These can be uploaded to iCloud Photos as well but their times will be in UTC time and they will not have any geolocation metadata

---

🔒 System Security Reminders

🪟 Windows

Windows may block outside downloads the first time you run them.

If you see a popup saying:

"Windows protected your PC"

This is normal — Windows is warning you because the tools were downloaded from the internet.

To allow them:

1. Click More info
2. Click Run anyway

Once approved the first time, they will run normally.

💡 Tip: If Windows deletes the file immediately after download, check Windows Security → Virus & threat protection → Protection history and restore it.

🍏 macOS

macOS may block outside applications when you first download them.

If you see a message such as:

"application cannot be opened because it is from an unidentified developer."

or the script appears to do nothing — macOS likely blocked the tool.

To allow them:

1. Open System Settings
2. Go to Privacy & Security
3. Scroll down to the Security section
4. Click Allow Anyway next to the application
5. Run the script again

💡 Tip:
Sometimes macOS hides the popup behind other windows.
If you don’t see a warning, still check System Settings → Privacy & Security.

---

🧹 Files Not Required to Run the Script

• .git — Git version tracking folder
• .gitignore — excludes unnecessary files from commits
• .DS_Store — macOS system file
• .gitkeep — placeholder to preserve empty directories on GitHub
• README — directions on how to run script
• examples/ — demonstration images for the README.md file
• Code_Logic — documentation for users interested in detailed function breakdowns
• LICENSE — legal terms for using and sharing this project

---

🪪 License

This project is licensed under a custom non-commercial license.
See the LICENSE file for full details.

---

🙌 Acknowledgments & Background

I understand that this tool may not be easy to use for non-developers, which is why I have included detailed explanations throughout this README and created a full video tutorial to guide users step-by-step.

If you still encounter issues, you can upload this README.md and the snapchat_metadata.py file into a generative AI tool such as ChatGPT or Gemini and ask for assistance. It can assist you throughout the setup and even help you troubleshoot.

This tool was originally built for Snapchat’s older export format where all Memories were delivered in a single memories/ folder.
Snapchat has since moved to a system where memories must be downloaded individually through memories_history.html. While this tool still fully supports the new format, it now requires users to manually consolidate those files first.

This project was created through extensive testing and iteration using Python, ExifTool, and FFmpeg with real exported Snapchat data from across multiple years. It was inspired by the need to restore accurate metadata and organization to Snapchat Memories and Chat Media after exporting a user’s data from the Snapchat website.

While other developers have built similar tools in the past, they do not handle timezone-based adjustments for memories, compile video memories, or process chat_media files. Additionally, many existing programs rely on active download links from the memories_history.json file. Unlike many existing tools, this project does not depend on Snapchat’s expiring download URLs. It processes already-downloaded media directly, ensuring usability even after the download links expire.