LiveMaoPo

OPPO 实况照片导入工具：在 Mac 上原生导入照片、视频与实况照片。
无需 Android 开发者模式，无需 USB 调试，全程通过 macOS PTP 与系统照片图库完成。

Native macOS importer for OPPO photos, videos, and Live Photos over USB PTP — no Android developer mode or USB debugging required.

为什么需要它

OPPO 实况照片通常以“JPEG 静态图 + 内嵌视频”的单文件形式保存在手机中，不能直接作为 Apple Live Photo 导入 macOS 照片图库。本项目会识别 OPPO 实况照片，转换出具有相同资源标识符的 JPEG/MOV 配对文件，再通过 PhotoKit 以原生 Live Photo 形式写入系统图库。

与依赖 ADB 的工具不同，本应用面向普通用户：手机只需解锁并选择 USB「照片传输 (PTP)」模式，不需要开启开发者选项，也不会改变手机安全设置。

主要功能

• 原生 USB 连接：使用 macOS ImageCaptureCore/PTP 发现设备，不依赖 ADB、驱动或后台服务
• 实况照片转换：识别 OPPO Live Photo 容器并转换为 Apple Live Photo
• 照片与视频导入：支持 JPEG、PNG、HEIC/HEIF、DNG、MP4、MOV、M4V 与 3GP
• 快速预览：优先使用设备缩略图；视频仅稀疏读取首尾数据生成首帧
• 截图兼容：设备没有提供缩略图时，按需下载一次原件生成预览，并复用于后续导入
• 智能去重：先比较文件名、大小与时间，仅对歧义候选执行 MD5 校验
• 时间范围筛选：最近 1/3/7/14/30 天、自定义起始日期或全部媒体
• 透明扫描进度：持续显示 PTP 枚举数量、累计耗时和当前处理阶段
• 连接冲突保护：检测“预览”和“图像捕捉”，待用户安全退出后自动继续，不会强制关闭其他 App
• 离线设备识别：内置 Google Play Supported Devices 的 OPPO/OnePlus/realme 型号快照

隐私与安全

• 应用运行时不连接云服务，不上传照片、视频、文件名或设备信息
• 媒体只在手机、本机临时缓存与 macOS 照片图库之间流转
• 不需要开发者模式、USB 调试、Root 或设备端安装任何应用
• 设备型号目录是随应用打包的离线快照；只有维护者手动运行更新脚本时才访问 Google 数据源

下载与安装

在项目的 Releases 页面下载最新的 LiveMaoPo-macOS-v2.2.zip，解压后将 App 移到“应用程序”目录。

当前公开构建使用 ad-hoc 签名，尚未经过 Apple Developer ID 公证。首次打开时如被 Gatekeeper 阻止：

1. 在 Finder 中右键 App，选择“打开”；或
2. 前往“系统设置 → 隐私与安全性”，确认打开该应用。

请只从本项目的 GitHub Releases 下载，并核对 Release 中提供的 SHA-256。

使用方法

1. 解锁 OPPO 手机并通过 USB 连接 Mac
2. 点击手机的 USB 通知，选择「照片传输 (PTP)」或「传输照片」
3. macOS 询问是否允许配件连接时选择「允许」
4. 启动 App；如果提示“预览”或“图像捕捉”冲突，请自行保存文档并安全退出对应应用
5. 选择时间范围，点击「扫描媒体」
6. 在预览列表中选择照片或视频，点击「开始导入」

关于首次扫描速度

PTP 不提供按拍摄日期查询的接口。即使选择“最近 7 天”，macOS 首次连接时仍需从手机读取完整媒体目录，然后应用才能进行日期筛选。拥有上万项媒体的设备可能需要数分钟。

扫描界面会每秒显示：

• PTP 会话是否仍在工作
• 系统已经枚举的媒体数量
• 已累计耗时
• 当前处于目录准备、日期筛选、去重还是预览阶段

同一次物理连接中，系统目录准备结果会被持续复用。请保持手机解锁，并避免在扫描过程中切换 USB 模式。

系统要求

• macOS 14 Sonoma 或更高版本
• Apple Silicon Mac（当前 Release 为 arm64 构建）
• 支持 USB 照片传输模式的 OPPO/OnePlus/realme 手机
• macOS“照片”图库访问权限

从源码构建

需要 Xcode Command Line Tools 和 Swift 6：

git clone https://github.com/MasonPanHB/LiveMaoPo.git
cd LiveMaoPo
swift test
make
open "LiveMaoPo.app"

调试构建：

make debug

正式构建会生成并 ad-hoc 签名 LiveMaoPo.app。

实现原理

ICDeviceBrowser（USB 热插拔）
  → PTPDeviceManager（会话预检与设备生命周期）
    → PTPMediaService（唯一长连接会话）
      ├─ 全量目录枚举 → 日期/目录/类型筛选
      ├─ 设备缩略图 → JPEG 内嵌预览 → 按需原件回退
      ├─ 视频稀疏首帧 → AVFoundation 解码
      └─ 按需下载 → Live Photo 转换 → PhotoKit 导入

OPPO Live Photo 的典型文件结构：

| JPEG 静态图 | GainMap（可选） | MP4 视频 |

转换过程会生成共享 UUID，将其写入静态图 MakerNote 与 QuickTime 元数据，并创建 still-image-time 轨道，最后通过 PhotoKit 以 .photo 与 .pairedVideo 资源配对导入。

更完整的架构、性能策略和已知限制见 架构与实现机制。

项目结构

Sources/
├── App/          SwiftUI 应用入口与主界面
├── Models/       媒体、设备与用户设置模型
├── SafetyCore/   可独立测试的路径、格式与安全规则
├── Services/     PTP、Live Photo 转换与 PhotoKit 导入服务
├── Utilities/    元数据、XMP、进程与文件工具
├── ViewModels/   扫描、选择和导入状态管理
└── Views/        可复用界面组件

更新设备型号目录

型号目录来自 Google 官方的 Play Supported Devices，运行时完全离线。维护者可手动更新：

python3 scripts/update_oppo_device_catalog.py
swift test

生成的 Sources/SafetyCore/OPPODeviceModels.generated.swift 应与代码一起提交。

参与贡献

欢迎提交 Issue 和 Pull Request。复现 PTP 问题时，请提供 macOS 版本、手机市场型号、USB 模式以及应用显示的阶段和耗时；请勿上传包含个人照片、序列号或其他隐私信息的日志。

具体流程见 CONTRIBUTING.md，安全问题请参阅 SECURITY.md。

免责声明

本项目是独立的开源社区项目，与 OPPO、OnePlus、realme、Apple 或 Google 无隶属或背书关系。相关商标归各自权利人所有。

许可证

本项目基于 MIT License 发布。