个人自用存档项目 / Personal archive, not a polished product.
这不是稳定产品:这是作者自己用着顺手写的工具,没有 Developer ID 签名、没有公证、没有自动测试矩阵、没有跨设备样例覆盖。仓库内的全部文档(README、
docs/WORKING_NOTES.md)和注释均由 AI 生成,仅作记录用途,可能滞后于代码或存在偏差,请以源代码为准。务必先做数据备份:本工具会调用 PhotoKit 修改你本机的「照片」图库(新建资源、新建相册),并会在源文件旁边生成副本。虽然代码层面有「原文件永不修改」的硬约束,但任何会动照片库的工具都有出错的可能。导入前请确保:
- iCloud 照片图库已经完整同步/备份到另一台设备或云端的快照;
- 原始安卓 Motion Photo 文件留一份独立备份(不要把唯一一份直接喂给本工具);
- 在小批量样本上先验证一次,再批量导入。
仓库以"现状"提供,不附带任何担保,作者不为数据损失负责。
MotionTrans 是一个 macOS / iOS 上的 Swift 工具,用于在 Android 系 Motion Photo(OPPO / Google / Samsung / Xiaomi 风格的「动态照片」单文件) 和 Apple Live Photo(静态图 + pairedVideo 一对) 之间互转。
主要解决的是「直接把安卓动态照片拖进 Apple Photos 不显示成 Live Photo」的问题——根因不是容器封装,而是 Apple Live Photo 要求一组特定 metadata(Apple MakerNote tag 17、com.apple.quicktime.content.identifier、com.apple.quicktime.still-image-time 定时元数据轨,且 still-image-time 的 sample duration 必须是一帧时长,否则 PhotoKit 会以 3302 错误拒绝)。本项目专门处理这些细节,使安卓动态照片能以 Live Photo 形态进入 Apple Photos。
核心约束(写在代码里的硬性原则):
- 原输入文件永不修改。所有写入只发生在副本或临时目录。
- 视频默认不重编码:内嵌 MP4 → MOV 走
ffmpeg -c copy+ AVFoundation 样本直通。 - 静态图不重压:JPEG 扫描数据保持原样,写 Apple MakerNote / EXIF 时间前后用 SHA-256 校验。
- UltraHDR / gain map 字节保留,不展平为 SDR。
- 失败即报错,绝不有损降级:当某个 Motion Photo 被判定但所有无损 Live Photo 变体都被 Photos 拒绝时,直接报该文件失败并带文件名进入失败清单,不做有损重编码。
- 自动识别 XMP
Container:Directory、MicroVideoOffset/MediaDataOffset、以及从文件尾部扫描 MP4ftyp三种布局的 Motion Photo。 - 静态图:从原 JPEG 中切出扫描数据,移除 Android Motion Photo XMP 声明(避免 Photos 看到自相矛盾的「含 video/mp4 但实际没有」),保留
hdrgm:Version/Primary,GainMap/ MPF gain map 字节。 - 视频:byte slicing 提取内嵌 MP4,
ffmpeg -c copy重封装为 MOV,再由 AVFoundation 写入 Live Photo metadata。 - 导入 PhotoKit:
.photo+.pairedVideo配对资源,加入motiontrans_MMdd_N自动编号相册。 - 流式输出进度行
[progress] done/total name供 GUI 解析。 - 批次结束打印结构化汇总:成功(实况/静态/视频)/失败/跳过/HDR 提示,并打印失败和跳过文件清单。
- EXIF 时间兜底:醒图(Xingtu)等相机不写 EXIF 拍摄时间,会导致 Photos 用导入时间。当且仅当文件完全没有常见 EXIF 时间字段时,用文件 mtime 回填
IFD0:DateTime/ExifIFD:DateTimeOriginal/ExifIFD:DateTimeDigitized。已有任意时间字段或yyyy:MM:dd HH:mm:ss字符串时零修改。支持 JPEG APP1 EXIF、PNGeXIfchunk、HEIC/HEIF 已有 Exif item。可用--no-file-time-fallback关闭。
仅在 macOS app 中支持。从 Photos picker 选择 iCloud / 本地照片库中的 Live Photo,导出为单个 .jpg Motion Photo 文件:
- JPEG still 资源直接复用原字节,只在 JPEG 头部插入 Android / OPPO Motion Photo XMP APP1 段。
- HEIC still 资源以最高质量转 JPEG(这是有损步骤,无法绕过)。
- pairedVideo 资源经
ffmpeg -c copy重封装为 MP4,音视频码流不重编码。 - 静态普通照片直接导出 JPEG,不伪造动态照片。
- 默认输出目录
~/Pictures/motiontrans_export,可在 app 内修改并记住。
MotionTrans/
├─ Sources/MotionTrans/ # 共享核心(CLI + iOS 都用)
│ ├─ CLI.swift # 命令行参数解析
│ ├─ main.swift # CLI 主流程(macOS)
│ ├─ MotionPhotoParser.swift # 解析 Android Motion Photo 三种布局
│ ├─ JPEGAppleMetadata.swift # JPEG 写 Apple MakerNote + EXIF 时间
│ ├─ AndroidXMPRewriter.swift # 删除 Android Motion Photo XMP 声明
│ ├─ LivePhotoMovieWriter.swift # MP4→MOV + Live Photo metadata(含 macOS ffmpeg 函数)
│ ├─ PhotosImporter.swift # PhotoKit 导入 + 自动编号相册
│ ├─ Verifier.swift # 校验 Live Photo 三件套
│ ├─ HEICExifMetadata.swift # HEIC/HEIF EXIF 时间补齐
│ ├─ PNGExifMetadata.swift # PNG eXIf chunk 时间补齐
│ ├─ TIFFDateTimeEditor.swift # 纯 TIFF IFD 编辑
│ ├─ ImageEXIFDateTimeWriter.swift # 按文件头分派到 JPEG/PNG/HEIC
│ └─ Utilities.swift # AppError / Logger / Data 扩展 / Shell(macOS)
├─ AppSources/MotionTransApp/main.swift # macOS SwiftUI app(导入 + 导出)
├─ iOS/ # iOS 端
│ ├─ Sources/ # App.swift / Core.swift / LivePhotoConverter.swift / DocumentPicker.swift
│ ├─ project.yml # xcodegen 工程描述
│ ├─ Info.plist
│ └─ MotionTrans.xcodeproj # 由 xcodegen 生成
├─ Tests/MotionTransTests/ # Swift Testing 单元测试(PNG EXIF)
├─ scripts/build_dmg.sh # 打包 .app + .dmg
├─ docs/WORKING_NOTES.md # 详细工作文档(AI 生成,含排查历史)
└─ Package.swift # SwiftPM 包(macOS CLI)
需要 macOS 13+、Swift 6 工具链、本机安装 ffmpeg(用于 MP4→MOV 重封装和 HEVC 元数据重写)。
swift build
.build/debug/motiontrans --helprelease 构建:
swift build -c release
.build/release/motiontrans --help./scripts/build_dmg.sh输出:
dist/MotionTrans.app
dist/MotionTrans.dmg
签名是 ad-hoc(codesign --sign -),没有 Developer ID、没有公证。首次打开时 macOS 可能拦截,需在「系统设置 → 隐私与安全性」里点「仍要打开」。app 内调用 motiontrans CLI 二进制(打包进 .app/Contents/Resources/),仍依赖系统 PATH 中的 ffmpeg——可用 brew install ffmpeg 安装。
iOS 端只做导入方向(安卓 Motion Photo → iPhone Live Photo),不能起子进程也没有系统 ffmpeg,所以共享核心被编进 app,macOS-only 的 Shell / ffmpeg / exiftool 调用都在 #if os(macOS) 守卫下。视频走 AVFoundation 样本直通,无重编码。
构建(需要 Xcode + xcodegen):
cd iOS
xcodegen generate
open MotionTrans.xcodeproj
# 在 Xcode 里选 Apple ID team、连真机、Run不签名构建并打包为 ipa:
cd iOS
xcodegen generate
xcodebuild -project MotionTrans.xcodeproj -scheme MotionTrans \
-configuration Release -sdk iphoneos \
CODE_SIGNING_ALLOWED=NO build
# 之后用 .app 打包成 ipa;安装仍需 Xcode / Sideloadly / AltStore 签名侧载未签名的 ipa 路径示例:iOS/dist/MotionTrans-unsigned.ipa。
.build/debug/motiontrans convert "6 月 8 日导入" -v不指定 -o 时,目录输入 "6 月 8 日导入" 会输出到同级 "6 月 8 日导入_LivePhoto",包含拆分好的 .jpg + .mov。
.build/debug/motiontrans convert input.jpg -o live_output --import -v--import 会调用 PhotoKit 把生成的 Live Photo pair 加入照片图库。默认相册名为 motiontrans_MMdd_N,例如 motiontrans_0706_1;同日第二次导入自动递增为 motiontrans_0706_2。用 --album 指定固定名称时原样使用、不加编号:
.build/debug/motiontrans convert input.jpg --import --album "我的相册" -v只想导入、不在磁盘留 pair:
.build/debug/motiontrans convert input.jpg --import --no-export-pair -v--no-export-pair 时 pair 写入系统临时目录,导入完成自动清理,源文件夹旁边不会留下 _LivePhoto 文件夹。GUI 即采用此模式。
.build/debug/motiontrans convert folderA folderB some_file.jpg --import --recursive -v多个输入会合并去重后一次性处理,共用同一个相册、同一份汇总。
.build/debug/motiontrans convert input --no-file-time-fallbackmotiontrans convert <input...> [-o <dir>] [--import] [--album <name>]
[--export-pair | --no-export-pair]
[--recursive] [--no-file-time-fallback] [-v]
motiontrans verify --image <jpg/heic> --movie <mov>
默认 --export-pair 开启。--no-export-pair 与 --import 一起使用才有意义(否则无事可做)。
.build/debug/motiontrans verify \
--image live_output_swift_batch/IMG20260601171640.jpg \
--movie live_output_swift_batch/IMG20260601171640.mov检查项:
- 静态图 Apple MakerNote 中的 content identifier 存在
- MOV 的 QuickTime
com.apple.quicktime.content.identifier与静态图一致 - MOV 含
com.apple.quicktime.still-image-time定时元数据轨
任一项缺失即 exit 1。
==== 导入结果 ====
[stats] total=216 live=133 still=67 video=15 failed=0 skipped=1 hdr=88
总文件 216:成功 215(实况 133,静态 67,视频 15),失败 0,跳过 1
提示:88 个实况检测到 UltraHDR/gain map,已保留原始 HDR 字节
跳过文件 (1):
- notes.txt: 非媒体文件 (.txt)
结论:✅ 成功导入 215,另有 1 个非媒体文件被跳过(见上),请确认是否遗漏
失败和跳过永远会带文件名列出,便于核对。只有失败才会 exit 1;仅跳过时 exit 0。
dist/MotionTrans.app 有两个模式(顶部 segmented control 切换):
- 拖入或点选 OPPO / Android 动态照片文件或文件夹。
- 预览分项统计(实况 / 静态 / 视频 / 跳过)。
- 「缺失时间用文件修改时间补」开关,对应
--no-file-time-fallback。 - 点「开始导入」后流式读取 CLI 输出的
[progress]行驱动真进度条。 - 结果卡片展示成功 / 实况 / 静态 / 视频 / 失败 / 跳过 / HDR 提示 / 结论;失败和跳过可展开看每项原因。
- 原始 CLI 日志收进折叠的「查看本次日志」。
- 历史记录存在
~/Library/Application Support/MotionTrans/history.json(上限 200 条)。
- 点「选择 iCloud 照片」打开 Photos picker(支持多选)。
- 选导出文件夹,默认
~/Pictures/motiontrans_export。 - Live Photo → 单文件
.jpgMotion Photo;HEIC still → 最高质量 JPEG;pairedVideo →ffmpeg -c copy重封装 MP4。 - 普通静态照片直接导出为 JPEG。
iOS app 仅做导入方向(安卓 Motion Photo → iPhone Live Photo)。结构与 macOS app 类似:UIDocumentPicker 选文件或文件夹 → 扫描分类 → 「开始导入」→ 进度条 + 结果卡片 + 历史。相册命名同为 motiontrans_MMDD_N。视频走 AVFoundation 样本直通,被 Photos 拒绝时先去音轨再无损试一次,仍拒绝则报错,绝不有损重编码。
iOS 不能起子进程,所以共享核心直接编进 app,Shell / ffmpeg / exiftool 函数在 #if os(macOS) 下不可用,iOS 路径完全走 AVFoundation。
按 XMP 字段判断是否为 Motion Photo 候选:
GCamera:MotionPhoto="1"
GCamera:MicroVideo="1"
GCamera:MicroVideoOffset=...
GCamera:MediaDataOffset=...
Item:Semantic="MotionPhoto"
Item:Mime="video/mp4"
命中候选后按以下顺序定位内嵌 MP4:
- XMP
Container:Directory中的Item:Semantic="MotionPhoto"/Item:Mime="video/mp4"条目(按Item:Length+Item:Padding从文件尾部倒推 offset)。 - XMP
MicroVideoOffset/MediaDataOffset单字段。 - 从文件尾部向前扫描 MP4
ftypbox。
如果 XMP 中只有 Primary, GainMap 而没有 Motion Photo 字段,则按静态 UltraHDR JPG 处理。
Android Motion Photo 的原始 JPG 通常结构是:
Primary JPEG + (GainMap JPEG) + embedded MP4
输出 still 为:
Primary JPEG + (GainMap JPEG) ← 移除 Android Motion Photo XMP,加 Apple MakerNote
动作:
- 用
AndroidXMPRewriter删除GCamera:MotionPhoto/MicroVideoOffset/OpCamera:OLivePhotoVersion等声明,以及Container:Item中的MotionPhoto/video/mp4项,保留hdrgm:Version、Primary,GainMap、MPF。 - 用
JPEGAppleMetadata.addContentIdentifier写 Apple MakerNote tag 17。优先复用现有 MakerNote 存储区;空间不足时如果 ExifIFD 存在则在 ExifIFD 中新增条目;都不行就报错,不重压 JPEG。 - 写入前后对 JPEG 扫描数据算 SHA-256 校验,保证扫描字节不动。
- UltraHDR/gain map 字节原样保留,不转换为 Apple HDR。
ffmpeg -y -v error -i input.mp4 -map 0 -c copy output.mov随后 AVFoundation 写 Live Photo metadata:
- 顶层
com.apple.quicktime.content.identifier= 与静态图相同的 asset identifier。 - 新建 metadata 轨
com.apple.quicktime.still-image-time,sample duration 必须是一帧时长(按视频轨 nominalFrameRate 计算)。这是 Photos 接受 stream-copy MOV 的关键。
如果 stream-copy MOV 被 Photos 拒绝(PHPhotosErrorDomain 3302),按以下顺序尝试无损变体,全部失败则报错,不做有损转码:
- 直通 MP4(不经过 ffmpeg remux,AVFoundation 直接读 MP4 写 Live Photo metadata)。
- 去掉音轨再直通(video-only passthrough)。
ffmpeg -c copy -bsf:v hevc_metadata=...仅重写 HEVC VUI 色彩 metadata(不动码流)。
醒图等相机导出的 JPEG 没有 EXIF 拍摄时间,Photos 会用导入时刻当拍摄时间。ImageEXIFDateTimeWriter 按文件头分派:
- JPEG:在 EXIF APP1 段内原地插入 IFD0:DateTime / ExifIFD:DateTimeOriginal / ExifIFD:DateTimeDigitized 条目,同步更新 APP1 长度字段。
- PNG:插入或更新
eXIfchunk,不动IDAT。 - HEIC/HEIF:解析 ISO BMFF box 树,找
meta/iinf中 type 为Exif的 item,从iloc取数据位置,编辑 TIFF,新 TIFF data 追加到文件末尾包成freebox,更新iloc指向。不动mdat。仅编辑已有、可定位的 Exif item,不创建新的 HEIF metadata item。
任意一种常见 EXIF 时间字段(包括 GPS 时间、SubSecTime、OffsetTime 等)已存在,或 TIFF payload 内已有 yyyy:MM:dd HH:mm:ss 字符串,就零修改。原文件永不修改——exportPair=true 时写到 output 副本;exportPair=false 时写到临时目录再导入;iOS 永远写临时目录。
let request = PHAssetCreationRequest.forAsset()
request.addResource(with: .pairedVideo, fileURL: movieURL, options: movieOptions)
request.addResource(with: .photo, fileURL: imageURL, options: imageOptions)相册命名:motiontrans_MMdd 为基名,导入前扫描已有 motiontrans_MMdd_* 相册取最大编号 +1,得到 motiontrans_MMdd_N。用户用 --album 指定固定名称时原样使用、不加编号。
photo resource (JPEG) ──直接复用字节──┐
photo resource (HEIC) ──CGImageDestination 最高质量 JPEG──┐
pairedVideo resource ──ffmpeg -c copy──→ MP4
│
└── 和 JPEG 字节拼接成单个 .jpg Motion Photo
在 JPEG 头部插入 GCamera/OpCamera/Container XMP APP1
主要是 OPPO JPG Motion Photo(见 docs/WORKING_NOTES.md):
- 216 个文件的混合目录:成功 215(实况 133 + 静态 67 + 视频 15),失败 0,跳过 1(
.txt)。 - 88 个实况检测到 UltraHDR/gain map,原始 HDR 字节保留。
- 静态 UltraHDR JPG 从 Photos 导出原始资源后与输入
cmp逐字节一致。 - Live Photo pairedVideo 从 Photos 导出后与输出 MOV
cmp逐字节一致。 - 视频轨为 HEVC/AAC,码流字节未变;色彩标签更像 P3/full-range SDR,不是 HDR10 PQ 或 HLG。
Google Pixel / Samsung / Xiaomi 等其他厂商样例未充分验证,需要更多真实样本测试。
swift test当前测试覆盖 PNG EXIF 时间补齐:
- 无
eXIf时插入最小 TIFF EXIF chunk,不触碰IDAT。 - 二次调用不重复写。
- 已有 IFD0:DateTime / DateTimeOriginal / DateTimeDigitized / 私有日期时间字符串时不写。
- 统一入口按文件扩展名分派到 PNG。
端到端导入 Photos 的行为未自动化,需要手动跑小批量样例验证。
- 重点验证了 OPPO JPG Motion Photo。HEIC Motion Photo 解析骨架已搭好但未充分验证;静态 HEIC/HEIF 的 EXIF 时间补齐只编辑已有、可定位的 Exif item,不创建新的 HEIC Exif item。
- Google Pixel / Samsung / Xiaomi 需要更多真实样本。
- 转换后的静态图文件不可能和原 Motion Photo JPG 一样大(内嵌 MP4 被拆出去了,且新增了 Apple MakerNote、移除了 Android Motion Photo XMP),但扫描数据和 gain map 字节保留;这不是画质损失。
- UltraHDR/gain map 作为原始字节保留,不转换为 Apple HDR。
- HEIC Live Photo 反向导出到 Android Motion Photo 时 still 必须转 JPEG(最高质量,仍是 lossy),pairedVideo 保持 stream copy。
- macOS app 需要本机安装
ffmpeg(用于 MP4→MOV 重封装和 HEVC 元数据重写)。 - macOS app 是 ad-hoc 签名,未做 Developer ID 公证;首次打开需在系统设置里放行。
- iOS app 未签名,安装仍需 Xcode / Sideloadly / AltStore 签名侧载。
- 输出目录同名文件会被覆盖(
copyMedia会先删除目标再复制)。 - 实机测试覆盖有限:CLI/macOS app/iOS app 的导入行为只在小批量样例上验证过,大批量、跨设备、HEIC 路径等仍可能踩坑。
如果你装了 exiftool 和 ffprobe,可以这样核查产物:
# 验证静态图
exiftool -G1 -s -a -ContentIdentifier -XMP-hdrgm:all -DirectoryItemSemantic -MPF:all image.jpg
# 验证 MOV
exiftool -ee -G1 -s -a -ContentIdentifier -StillImageTime movie.mov
ffprobe -v error -show_streams movie.mov
# 验证视频 packet payload 字节数(应与原始内嵌 MP4 一致)
ffprobe -v error -select_streams v -show_entries packet=size -of csv=p=0 movie.mov | awk '{s+=$1} END{print s}'- 本仓库不保证功能正确、不保证数据安全、不提供任何担保。
- 文档由 AI 生成,可能滞后或偏差,请以源代码为准。
- 出问题请自行排查;可以提 issue 记录复现步骤,但不承诺修复。
- 再次提醒:导入照片库前请先备份。
本项目分别借鉴以下项目的格式经验,不是把几个项目拼起来:
- MotionFlow:Android Motion Photo 拆包思路,尤其是从 JPEG 后部定位内嵌 MP4。
- LimitPoint/LivePhoto:Apple Live Photo 必需 metadata 结构。
- Apple-photo-to-UltraHDR-motion-photo:Apple HDR / Android UltraHDR / Motion Photo 之间的格式边界。
详见 docs/WORKING_NOTES.md 的「参考项目分工」一节。
本项目不附带明确的开源许可。作为个人自用存档发布,保留全部权利。可以阅读、参考、自行编译运行,但不授予再分发或商用权利。如果你希望用特定许可(MIT / Apache-2.0 等),可以 fork 后自行更换。