Skip to content
BranchesTags

Repository files navigation

PhotoDateRescue

License: MIT Platform: macOS | Windows core Language: Python

安卓换 iPhone 后，照片和视频可能会全部挤到“导入当天”。PhotoDateRescue 会从本地导出的安卓相册里读取可用时间信息，生成时间线修复后的安全副本，方便你重新导入 Apple Photos / iCloud。

它不修改原始文件，不自动导入 Apple Photos，不上传照片或视频。你可以先小批量验证，确认没问题后再处理大图库。

适合解决什么问题

  • 安卓迁移到 iPhone 后，微信、QQ、下载图、截图等照片显示成错误导入日期。
  • 部分视频缺少 Apple Photos 能识别的创建时间，导入后时间线混乱。
  • 想先生成报告、人工抽查，再把修复后的副本手动导入 Apple Photos / iCloud。

快速下载

普通用户建议先用图形界面，不需要从源码开始。

系统 下载什么 适合谁 注意
macOS Releases 里的 PhotoDateRescue-v*-macOS.zip 不想用终端的普通用户 未签名，首次打开请右键选择“打开”
Windows Releases 里的 PhotoDateRescue-v*-windows-exe-alpha.zip 想试用 Windows 图形界面的用户 alpha 版，未签名，不内置 ExifTool / FFmpeg
源码 / CLI git clone 后用 Python 安装 开发者、高级命令用户、需要 Motion Photo / Live Photo 实验流程的用户 见下方“源码安装 / CLI”

macOS 下载后：

  1. 打开 Releases。
  2. 下载最新版本里的 PhotoDateRescue-*-macOS.zip。
  3. 解压后右键点击 PhotoDateRescue.app，选择“打开”。

如果 macOS 提示“无法验证开发者”，这是未签名开源工具的常见提示。确认来源是本仓库 Release 后，请使用右键“打开”，不要直接双击。

Windows 下载后：

  1. 打开 Releases。
  2. 下载最新版本里的 PhotoDateRescue-*-windows-exe-alpha.zip。
  3. 解压后运行 PhotoDateRescue.exe。
  4. 如果 Windows SmartScreen 拦截，这是未签名 alpha 包的常见提示。确认来源是本仓库 Release 后，再选择继续运行。

先装依赖

PhotoDateRescue 的核心依赖是 ExifTool；如果要处理视频，建议同时安装 FFmpeg。

依赖 是否需要 用来做什么
ExifTool 必需 读取和写入照片 / 视频时间元数据
FFmpeg / FFprobe 推荐 改善视频时间读取和视频副本处理
adb 可选 从安卓手机导出媒体目录，并尽量保留文件修改时间
makelive 仅 macOS 高级流程可选 实验性生成 Apple Live Photo 兼容输出

macOS 依赖

推荐用 Homebrew：

brew install exiftool ffmpeg

如果要尝试高级 Apple Live Photo 输出，再安装 makelive：

uv tool install makelive

也可以参考 makelive releases page 安装预编译包。

Windows 依赖

Windows .exe alpha 不内置 ExifTool / FFmpeg，需要你在电脑上单独安装。

ExifTool 推荐这样装：

  1. 打开 ExifTool 官网：https://exiftool.org/。
  2. 下载 Windows Executable。
  3. 解压后把 exiftool(-k).exe 重命名为 exiftool.exe。
  4. 新建目录，例如 C:\Tools\exiftool\，把 exiftool.exe 放进去。
  5. 把 C:\Tools\exiftool 加到 Windows 的用户 Path 环境变量。
  6. 重新打开 PhotoDateRescue，或者在应用里点击“重新检查”。

FFmpeg 推荐用 PowerShell 安装：

winget install Gyan.FFmpeg

如果不能使用 winget，也可以从 Gyan FFmpeg builds 下载，解压后把其中的 bin 目录加入 Path。

装好后，在 PowerShell 里验证：

exiftool -ver
ffmpeg -version
ffprobe -version

如果这些命令能输出版本号，说明系统环境已经准备好。图形界面里也可以看“环境状态”，再点击“重新检查”。

图形界面使用步骤

macOS 和 Windows 的普通照片 / 视频修复流程基本一致：

  1. 先把安卓手机里的照片和视频导出到电脑上的普通文件夹。
  2. 打开 PhotoDateRescue。
  3. 在“环境状态”里确认 ExifTool 已找到；视频较多时也建议确认 FFmpeg 已找到。
  4. 选择“安卓导出文件夹”。
  5. 选择一个单独的“安全输出文件夹”。
  6. 先扫描，查看摘要和报告。
  7. 再生成修复后的安全副本。
  8. 抽查少量输出文件，确认时间线正确后，再手动导入 Apple Photos / iCloud。

不要把输出文件夹选成原始文件夹，也不要在确认结果前删除手机或电脑里的原始照片。

默认输出结构：

PhotoDateRescue-output/
  scan-report/
  repaired-media/
  live-work/
  live-output/

更详细的小白指南：

核心能力

  • 扫描照片 / 视频目录并生成结构化报告。
  • 为照片和视频生成修复后的副本，不改动源文件。
  • 识别伪装后缀，例如 .jpg 实际是 PNG、WEBP、HEIC。
  • 优先使用媒体内嵌时间，缺失时回退到文件修改时间和创建时间。
  • 支持常见安卓缓存、回收站、缩略图目录过滤。
  • 支持通过 adb pull -a 导出安卓媒体目录并尽量保留文件时间。
  • 提供中文终端向导 photodaterescue wizard，适合不想手写长命令的用户。
  • 支持安卓 Motion Photo 审计、提取与跨平台配对包；macOS 可选尝试 Apple Live Photo 兼容输出。

支持范围和边界

当前支持：

  • 图片：jpg、jpeg、png、webp、heic、heif
  • 视频：mp4、mov、m4v、3gp
  • macOS：优先验证平台，支持图形界面、CLI、普通照片 / 视频修复和高级 Motion Photo / Live Photo 实验流程。
  • Windows：支持图形界面 alpha、核心扫描、报告、普通照片 / 视频修复、adb 导出和跨平台配对包。
  • 普通照片和视频修复逻辑尽量使用通用元数据，其他安卓设备理论上可用，但仍建议先小样本验证。
  • 已针对小红书保存的 Camera_XHS_* + xhs_live_photo_* sidecar 结构做配对识别；可识别带 Xiaomi 机型信息和 MicroVideo / MotionPhoto 标记的小米原生相机嵌入式动态照片候选，并已在 macOS + makelive 下完成小样本元数据写入验证。

暂不承诺：

  • 直接写入 Apple Photos / iCloud
  • 自动删除重复照片
  • gif
  • HEIC / AVIF 嵌入式动态照片提取
  • Windows 上构建 Apple Photos 可识别的 Live Photo
  • 所有安卓品牌的 Motion Photo / Live Photo 私有格式恢复

安全原则

PhotoDateRescue 默认按“先保护数据，再修复时间线”的方式工作：

  • 不修改源文件。
  • 不自动导入 Apple Photos / iCloud。
  • 不自动删除重复项。
  • 所有修复结果写入你指定的输出目录。
  • 高风险文件会进入报告，建议人工确认后再处理。

源码安装 / CLI

如果你想使用终端向导、开发版本，或者高级 Motion Photo / Live Photo 命令，可以从源码安装。

macOS 源码安装

git clone https://github.com/Teddy-creator/PhotoDateRescue.git
cd PhotoDateRescue

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .[dev]

Windows 源码安装

Windows 源码运行适合暂时不想用 .exe alpha，或者想自己运行 photodaterescue-gui 的用户。

git clone https://github.com/Teddy-creator/PhotoDateRescue.git
cd PhotoDateRescue

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .[dev]

安装完成后，普通用户优先运行：

photodaterescue doctor
photodaterescue wizard

如果想使用图形界面，可以在源码安装后运行：

photodaterescue-gui

Windows 图形界面只承诺普通照片 / 视频时间线修复，不承诺 Live Photo 构建或 Apple Photos 识别。详细说明见 docs/manual/windows-gui-source-guide.md。

实验性 Windows .exe 打包说明见 docs/packaging/windows-exe-alpha.md。该包不内置 ExifTool / FFmpeg，且未签名。

CLI 快速开始

大多数命令行用户直接使用中文向导即可：

photodaterescue doctor
photodaterescue wizard

向导会引导你选择原始媒体目录、输出目录、排除常见缓存目录、扫描报告、生成修复副本，并按需排查安卓动态照片。Windows 下向导会跳过 Apple Live Photo 构建，只处理普通照片 / 视频时间线；动态照片可通过高级命令保留为静态图 + 短视频配对包。

高级用法

从安卓设备导出媒体

photodaterescue android-pull \
  --device-path /sdcard/DCIM \
  --device-path /sdcard/Pictures \
  --device-path /sdcard/Movies \
  --output /path/to/android-export

android-pull 内部使用 adb pull -a，这对微信、QQ 等来源的视频很重要，因为它们可能没有可靠的内嵌时间，只能依赖文件修改时间。

Windows 下也可以使用 android-pull，前提是 adb.exe 已经加入 PATH。如果没有加入 PATH，可以显式传入路径：

photodaterescue android-pull `
  --adb "C:\Android\platform-tools\adb.exe" `
  --device-path /sdcard/DCIM `
  --device-path /sdcard/Pictures `
  --device-path /sdcard/Movies `
  --output C:\Users\you\Pictures\android-export

扫描媒体目录

photodaterescue scan \
  --input /path/to/android-export \
  --report /path/to/report

带缓存目录过滤的例子：

photodaterescue scan \
  --input /path/to/android-export \
  --report /path/to/report \
  --exclude "Pictures/.thumbnails" \
  --exclude "Pictures/.gs*" \
  --exclude "DCIM/.globalTrash"

扫描报告包括：

  • summary.json
  • files.csv
  • high_risk.csv

生成修复副本

photodaterescue repair \
  --input /path/to/android-export \
  --output /path/to/repaired-media \
  --report /path/to/report

建议先导入少量修复样本到 Apple Photos，确认时间线正确后再批量导入。

恢复安卓 Motion Photo / Live Photo

macOS 用户如需生成 Apple Live Photo 兼容输出，可以先 dry-run：

photodaterescue rescue-live \
  --input /path/to/android-export \
  --work-dir /path/to/live-work \
  --output /path/to/live-output \
  --exclude "Pictures/.thumbnails" \
  --dry-run

确认报告后再真正生成输出：

photodaterescue rescue-live \
  --input /path/to/android-export \
  --work-dir /path/to/live-work \
  --output /path/to/live-output \
  --exclude "Pictures/.thumbnails"

motion-extract 会在 extraction.csv 和 extracted_pairs.csv 中写出 source_type、source_reason，用于区分小米原生相机嵌入式动态照片、通用 Motion Photo / MicroVideo 候选等来源。 中文向导和 rescue-live-manifest.json 也会汇总这些来源统计，方便先看有多少小米原生候选能进入提取流程。可提取出静态图 + 短视频配对，不等于 Apple Photos 一定识别为 Live Photo。

Windows 用户或不想依赖 makelive 时，只建议生成跨平台配对包：

photodaterescue rescue-live \
  --input /path/to/android-export \
  --work-dir /path/to/live-work \
  --output /path/to/live-output \
  --exclude "Pictures/.thumbnails" \
  --dry-run

photodaterescue live-build \
  --backend portable-pair \
  --pairs-csv /path/to/live-work/motion-audit/pairs.csv \
  --source-root /path/to/android-export \
  --output /path/to/live-pairs \
  --report /path/to/live-pair-report

portable-pair 会把静态图、短视频和 pair.json 放在同一个配对目录里，方便后续检查和实验。它只表示“动态照片关系被保留下来”，不是 Apple Live Photo，不保证 Apple Photos 会直接识别成 Live Photo。

如果你已经有一对图片 / 视频，可以用只读检查命令看看它们是否带有 Apple Live Photo 常见配对元数据：

photodaterescue live-inspect \
  --image /path/to/IMG_001.jpg \
  --video /path/to/IMG_001.mov

live-inspect 只读取元数据，不修改文件。它能提示 Content Identifier 是否匹配、是否疑似存在 Apple Maker Notes、视频时长等信息；但最终能否被 Apple Photos 识别，仍需要真实导入验收。

如果你已经通过 motion-audit 或 rescue-live --dry-run 得到了 pairs.csv，可以批量生成只读诊断报告：

photodaterescue live-probe \
  --pairs-csv /path/to/live-work/motion-audit/pairs.csv \
  --source-root /path/to/android-export \
  --report /path/to/live-probe-report

live-probe 会写出 live-probe.csv、errors.csv 和 live-probe-manifest.json。它不会修改原始图片或视频，主要用于判断哪些配对已经有匹配的 Apple Live Photo 元数据信号、哪些在 Windows 写入实验上会被缺少 Apple Maker Notes 等问题挡住。

命令总览

  • doctor：检查本机依赖。
  • wizard：运行中文终端向导。
  • android-pull：通过 adb pull -a 导出安卓媒体目录。
  • scan：扫描媒体目录并写出报告。
  • repair：生成修复后的媒体副本。
  • motion-audit：只读审计疑似安卓动态照片 / Live Photo 候选。
  • motion-extract：从嵌入式 JPEG 动态照片中提取视频。
  • live-build：从图片 / 视频配对生成输出副本；makelive 后端用于 macOS Apple Live Photo，portable-pair 后端用于跨平台配对包。
  • live-inspect：只读检查图片 / 视频配对中的 Live Photo 元数据信号。
  • live-probe：批量只读检查 pairs.csv 中的 Live Photo 元数据信号。
  • rescue-live：串联 Motion Photo 审计、提取和 Live Photo 构建流程。
  • reconcile：对比候选导出目录和已修复基线目录。
  • classify-unmatched：分类对账后的剩余文件。
  • materialize-unmatched：把分类后的剩余文件复制或移动到实体分类目录。

大图库建议流程

  1. 优先使用 photodaterescue wizard 走推荐流程。
  2. 如果要从安卓设备导出，优先使用 photodaterescue android-pull，这样更容易保留文件修改时间。
  3. 先扫描，再修复，不要跳过报告检查。
  4. 先导入少量样本到 Apple Photos 验证。
  5. 验证正确后，再批量导入修复后的副本。
  6. 如需恢复安卓动态照片，先使用向导或 rescue-live --dry-run；Windows 仅保留配对包，macOS 才尝试 Apple Live Photo 输出。

隐私与数据安全

PhotoDateRescue 只处理本地文件，不会主动上传照片、视频或报告。

但请注意，报告中可能包含文件名、拍摄时间、绝对路径等隐私信息。发布 issue、分享日志或提交测试样本前，请先确认没有包含真实个人媒体文件和隐私路径。

更多说明见：

  • docs/privacy-and-data-safety.md
  • docs/release-checklist.md
  • docs/manual/apple-photos-import-checklist.md
  • docs/packaging/macos-gui.md

开发与测试

source .venv/bin/activate
python -m pytest -q
photodaterescue --help

Roadmap

  • 补充更多真实 Apple Photos 导入验证说明。
  • 扩展不同安卓厂商 Motion Photo 样本兼容性。
  • 继续完善 Windows 普通照片 / 视频修复文档和真实设备验证。
  • 保持 Windows 动态照片边界清晰：支持审计、提取、跨平台配对包，不承诺 Apple Live Photo 构建。
  • 在有真实样本支撑后，再考虑 HEIC / AVIF 嵌入式动态照片提取。

License

PhotoDateRescue is released under the MIT License.

Copyright (c) 2026 C1oud.

About

Mac-first tool for safely repairing photo timeline metadata after Android to iPhone migrations.

Resources

Readme
MIT license
Activity

Stars

8 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages