留刻（MomentStays）使用手册
适用版本：留刻 1.4.0（macOS 12 或更高版本） 本手册介绍图形界面（App）的全部功能，以及附带的命令行工具。英文版见 USER_GUIDE.md。
高清候选封面选择与多照片导出从 1.2.0 起包含在安装包中，较早版本的安装包没有这些选项。
留刻在 Mac 上把 Android 动态照片（Motion Photo）转换成 Apple 实况照片（Live Photo），也能反向转换。全过程遵循三条原则：
- 封面帧不变——你选定的那一帧仍是封面，按真实时间线对齐到帧；
- 音视频不重新编码——视频与音频只重新封装，逐个样本校验，保留原有质量；图片格式转换与候选帧导出可能需要图片编码；
- HDR 如实保留——能保留的增益图原样保留，处理不了的明确报告，绝不伪造。
所有转换与校验都在本机完成，不上传任何照片。
目录
- 1. 快速上手
- 2. 界面与导入
- 3. 转换方向与格式支持
- 4. 核心机制一：封面帧如何定位
- 5. 核心机制二：不重新编码与逐样本校验
- 6. 核心机制三：HDR 的处理方式
- 7. 辅助轨：一般人不知道的第二条视频轨
- 8. 系统图库：识别、导入与监测
- 9. 批量、交付与共享
- 10. 设置全表
- 11. 清单（manifest）与报告
- 12. 命令行工具（CLI）
- 13. 疑难排解
- 14. 已知限制
1. 快速上手
打开 DMG，将 MomentStays（留刻）拖入右侧的 Applications，再从「应用程序」启动。安装窗口仅显示应用与 Applications 链接，以箭头示意拖拽方向。手册通过应用内帮助按钮打开，许可文件保存在应用包内。
- 打开留刻，点「添加照片」，或把文件直接拖进队列；也可以从菜单选择「扫描系统照片图库…」直接从「照片」图库取图。
- 确认转换方向：安卓 → 苹果实况（默认）或苹果实况 → 安卓。
- 在顶部「保存到」及「更多选项…」中核对输出方式（保存到文件夹 / 导入图库 / 共享等）、目标格式与 HDR 选项。
- 点「开始转换」（快捷键 ⌘Return）。参数在任务开始时会被快照锁定，运行中不可修改。
- 完成后在报告里查看每张照片的结果；点「最近结果…」可以重试交付、定位文件或打开输出文件夹。
转换一份照片会生成一个结果目录（见 §9 的命名规则），而不是散落的文件。
首次打开提示：发布版为自签名（ad-hoc），未做 Apple 公证。若 macOS 拦截首次打开，请到「系统设置 → 隐私与安全性」放行，或在访达中 Control-点按应用图标选择「打开」。安装后的 App 不依赖 Python、FFmpeg、ExifTool 或 Homebrew。
2. 界面与导入
2.1 照片队列
界面采用单一工作台。顶部集中放置转换方向、添加照片、保存位置与「更多选项…」。照片区常驻「待转换 / 已完成 / 静态照片 / 需检查 / 全部」分类及数量，默认显示待转换。右侧预览默认关闭，可通过「预览」按钮或 ⌥⌘P 打开；窄窗口自动调整布局。界面跟随系统深浅色外观，强调色采用接近琥珀色的系统原生橙色。
扫描与转换采用受内存预算约束的有限并行处理。已确认的静态照片单独计数并跳过，不占动态转换进度；来源清单变化时会要求重新扫描。
照片区域可在缩略图与列表之间切换，较窄时自动显示列表。列表仍显示文件名、格式/HDR、可用时的封面时间与状态；选中照片后可查看厂商、文件路径及识别详情。
打开预览窗格后，照片下方有时间条：封面标记表示原始封面位置，鼠标悬浮时在卡片中显示对应的视频帧和实际时间，移开后恢复静态照片。缺失或有歧义的封面会提示，无法读取的视频不提供伪造预览。预览只读取原始动态主轨，不修改封面。
分类只筛选显示，开始转换仍处理全部已选来源，其中已确认的静态照片会跳过。历史任务通过「最近结果…」打开。
2.2 四种导入来源
| 来源 | 说明 |
|---|---|
| 选择文件 | 文件选择器，可多选 |
| 选择文件夹 | 递归读取其中照片 |
| 拖放 | 把文件直接拖入队列区域 |
| 扫描系统图库 | 通过 PhotoKit 枚举图库资产并识别格式，可限定相册范围（见 §8） |
2.3 快捷键
| 快捷键 | 功能 |
|---|---|
| ⌘O | 选择照片 |
| ⌘R | 重新扫描 |
| ⌘Return | 开始转换 |
| ⌘. | 停止 |
| ⌘, | 导出设置 |
2.4 任务运行规则
- 点「开始」后，本次任务的全部参数形成快照，运行期间设置锁定。
- 点「停止」会先发出取消信号，等引擎清理完毕才允许开始新任务；旧任务迟到的回调不会覆盖新任务的状态。
- 报告标题会区分「转换报告」与「已停止的任务」。
3. 转换方向与格式支持
厂商支持的口径是「解析器能验证的布局」，不是对所有机型与固件版本的承诺。编辑过、被聊天软件转发过的照片可能已经丢失内嵌视频，丢失的视频无法凭静态图恢复。
3.1 安卓 → 苹果
| 输入 | 说明 |
|---|---|
| Google 兼容 Motion Photo（JPEG） | 支持主 XMP、Extended XMP，以及经完整验证的封面元数据恢复 |
华为 / 荣耀（LIVE_ 尾标） |
含以原始帧号记录封面的特殊路径（见 §4） |
| 三星 SEF | 含 SEF 尾标结构 |
| 三星 HEIC | 仅已验证的 mpvd/SEF 布局；保留原始 HEVC 图像项目，不转码为 JPEG |
| OPPO / 一加 | OPPO 容器布局 |
| vivo V2 | vivo V2 容器布局 |
输出为 Live Photo 配对：静态图（JPEG/HEIC）+ 独立 MOV。静态图与 MOV 通过内容标识（ContentIdentifier）配对，输出只包含经验证的静态图像载荷与必要扩展，动态视频与音频只存在于 MOV 中。
3.2 苹果 → 安卓
按 Apple 内容标识匹配完整静态图与 MOV，读取其中的 still-image-time 定时标记并对齐实际视频帧。
| 目标 | 厂商 |
|---|---|
| JPEG | Google/通用、小米、三星（写 SEF 尾标）、华为、荣耀、OPPO、vivo V2 |
| HEIC | 仅三星；保留已有图像、缩略图、增益图编码与属性。JPEG 不会为此重新编码成 HEIC。Google 与小米的动态照片不使用 HEIC，这两个目标请用 JPEG |
4. 核心机制一：封面帧如何定位
封面时间指动态视频中被选作封面的那个瞬间，与照片的拍摄日期是两回事，不要混淆。
转换时，留刻读取源文件记录的封面时间，沿实际媒体时间线映射到真实帧，再写入 Live Photo 的 still-image-time 定时标记；反向转换时读回该标记，恢复安卓侧的封面位置。
关键规则：
- 半帧容差：帧对齐会逐帧核对，默认容差为半帧；对齐误差会记录在清单中（
snap_error_seconds）。 - 拒绝猜测：源时间缺失、有歧义或超出视频范围时一律报错，绝不默认用视频中点、拍摄日期或文件尾部的数字顶替。确实想用中点，必须在高级参数里主动选择「使用视频中点」。
- 两条时间线（时间域）：封面时间可能记在样本时间线（media）或播放时间线（presentation，含 edit list）上。自动模式同时检查两者；若两者指向不同的帧，会报错并请你指定时间域（见 §10 高级参数）。带负 PTS 的视频需要显式的时间线处理，否则保留原片并报错。
- 华为/荣耀帧号路径：部分华为/荣耀文件记录的是原始封面帧号而非时间戳，引擎会按帧号定位；帧号越界直接报错，不推测。
- 从视频元数据恢复：主 XMP 缺失时，若内嵌视频里带有封面时间元数据，引擎可据此恢复原始封面时间，并在结果中给出警告说明来源。
- 写后回读：MOV 写入后会回读验证封面标记仍然存在且封面时长等于实际帧时长，不通过则整份结果不发布。
5. 核心机制二：不重新编码与逐样本校验
- 视频与音频以原始压缩样本直接重新封装（remux），不解码、不重编码；输出会逐样本核对哈希、大小、数量与时间戳（PTS），并校验输出轨道数与输入一致、时间线位移不超过容差。
- 静态主图有「编码哈希」校验：只对编码数据（不含元数据）计算哈希，转换前后必须一致，否则判定失败；同时断言导出的静态图里不残留内嵌媒体。
- 静态图 EXIF 中的内容标识、MOV 内的标识与清单中的 UUID 必须三方一致。
发布与源文件保护：
- 原子发布：结果先写到暂存目录，全部校验通过后才一次性发布；覆盖旧结果时，也是新结果完整校验后才原子替换。
- 源文件指纹：转换前后比对源文件 SHA-256；若转换期间源文件被其他程序改动，本次结果不发布。
- 输出位置硬规则：输出文件夹必须位于原片目录之外（GUI 与 CLI 均强制），避免边读边写与误覆盖原片。
遇到同名旧结果时：
- 同源、同设置且旧结果清单校验通过 → 标记为
resumed（已验证，跳过重复转换）； - 内容或设置不同 → 报错且不覆盖，请换输出目录，或在弹窗中明确选择覆盖；
- 若旧结果未保留荣耀私有 HDR 静态扩展，续转会被拒绝并提示覆盖重转。
批次中每份结果的状态为四种之一：converted（已转换）、resumed（已验证跳过）、skipped（已跳过）、failed（失败）。
6. 核心机制三：HDR 的处理方式
| 输入情况 | 处理 |
|---|---|
| 已有 Ultra HDR（JPEG 增益图） | 增益图与参数原样保留，主图保留原始编码 |
| 旧 Apple 增益图（HEIC/JPEG） | 按 Apple 公开的 Rec.709 亮度模型转换成 Ultra HDR 增益图；只重编码增益图本身，SDR 主图从不重编码。增益头程（stops）有效范围为 (0, 16] |
| ISO 增益数据（ISO/TS 21496-1） | 参数完整可解释时保留编码图像、仅补充元数据，可升级为 Ultra HDR + ISO 输出 |
| HEIC 直通 | 保留编码图像项目、辅助数据与受支持属性；tmap 等变体在 HEIC 内保留，不臆测成旧增益模型 |
| 荣耀私有 EHDR | 静态扩展以不透明数据原样保留并做字节校验。注意：保留不等于 Apple 设备能按荣耀私有模型渲染 |
| SDR | 保持 SDR，不凭空生成增益图 |
| 未知/私有 HDR（未知 tmap、PQ/HLG、复杂 HEIF 等） | 不静默转成 SDR、不虚构增益图，明确报告；可选择保留原 HEIC 编码 |
细节与边界：
- Ultra HDR 成片需要 ICC 配置：文件无 ICC 时，仅当 EXIF 明确标注 sRGB 才补 sRGB ICC，其余情况报错，不猜测色彩空间。
- GUI 的「尝试兼容非 Ultra HDR」开关（默认开）控制旧 Apple 增益图等兼容路径；苹果 → 安卓的 JPEG 输出采用 Ultra HDR，普通 SDR 不生成增益图。
- HEIC 转 JPEG 的限制：若 HEIC 内含无法在 macOS 12 安全提取的 HDR（如某些 tmap/增益轨），转换会明确失败并提示改走「保留 HEIC 原编码」或提供受支持的 Apple HDR 增益图。
- 编辑版照片可能已丢失增益图，报告中会标注「编辑版无 HDR 增益图」；应用不会把原片的增益图挪用到编辑版上。
7. 辅助轨：一般人不知道的第二条视频轨
7.1 什么是辅助轨
部分动态照片的内嵌视频里不止一条视频轨：与封面对应的连续动态视频是主运动轨；同容器里的第二条视频轨叫辅助影像轨（简称辅助轨）。实测样片中，辅助轨可能只有 1 帧、分辨率却更高（如 2048px 宽）——它更像一张高清关键帧，而不是一段视频。引擎的规则是：一张动态照片最多允许一条辅助轨。
注意别与另外两个概念混淆：JPEG 里的 MPF 辅助图像（增益图等，清单字段 auxiliary_sha256 指它）和 HEIC 的辅助数据，都不是这里说的辅助轨。辅助轨特指视频辅助轨。
7.2 导出模式
在「导出设置 → 输出内容」中选择（仅安卓 → 苹果方向）：
| 模式 | 行为 |
|---|---|
| 仅 Live Photo（默认） | 只用选定轨道生成 Live Photo |
| Live Photo ＋ 辅助轨 | 生成 Live Photo 之外，把辅助轨另存为独立文件 <原名>.auxiliary.mov。请与实况配对分开保存 |
| 仅导出辅助轨 | 只导出辅助轨为独立 MOV（结果目录后缀 .auxiliary-export），不生成 Live Photo、不含音频；此模式下交付目标只能是文件夹 |
| Live Photo ＋ 高清候选照片 | 导出选定封面的 Live Photo，并为其余高清封面分别导出照片；可选择全部实况或仅主照片实况 |
原片没有辅助轨时，独立辅助视频操作会报错；多照片模式仍会导出原始封面的 Live Photo，并在详情中报告没有额外候选。
7.3 拿辅助轨当动态视频？有条件
「视频轨道」可以在主运动轨 / 辅助影像轨之间切换，但规则很严：
- 辅助轨帧数少于 2 帧直接拒绝：「辅助轨只有 X 帧，不能作为动态视频」。单帧辅助轨永远不会被拉伸伪造成动态视频。
- 选辅助轨时，封面时间必须能映射到辅助轨自己的时间线；映射不上会报错，绝不回退主轨、也不改封面。
- 多帧辅助轨可以正常选轨转换，清单中会记录
selected_video_role = "secondary"。
界面里也会直接提示：「辅助轨可能只有一帧，不能代替连续动态视频。」
7.4 独立导出的规格
- 前置条件：原片必须恰有 2 条视频轨。
- 只导视频、不含音频（清单字段
audio_included: false）。 - 同样逐样本直通封装、写后校验：输出必须恰 1 条视频轨，压缩数据哈希、样本大小与 PTS 数量与源一致。
- 结果详情会写明：「辅助轨已单独导出：宽 × 高，N 帧，时长；无音频，未重新编码」。
- 重要：独立辅助轨 MOV 是普通视频，不要与 Live Photo 配对一起导入图库。
7.5 高级：修复零时长辅助轨
个别辅助轨唯一帧的时长字段为 0，系统读不到有效样本，默认导出会失败。高级参数里有开关「允许修复辅助轨的零时长」（默认关闭）：
- 只改导出副本中辅助轨的时长字段（借用主轨最短正时长帧的时长），压缩样本字节与样本时间戳完全不变；
- 原片布局无法严格验证时拒绝修复，不冒险；
- 修复会记录在清单中（
duration_repair字段，含修复前后时长与「样本时间戳未改变」标记），结果里也会出现相应警告； - 仅对独立导出有意义，「仅 Live Photo」模式下该开关不可用。
7.6 在应用中选择高清候选封面
照片卡片的「封面」菜单可以切换原始照片与辅助轨中的高清候选。列表视图可右键选择「选择高清候选封面…」。选择按照片分别保存，转换运行期间不能修改。
切换封面只替换静态照片，并将实况封面标记移到对应时间；连续动态仍使用主运动轨。Google 高清帧元数据中的时间优先于辅助轨自身的 PTS，不能映射到主视频的候选不能用于实况封面。
候选画面会按视频方向解码为 JPEG；不会挪用原始封面的 HDR 增益图。零时长帧仅在临时解码副本补帧长，不改原片或导出主视频的时间表。此过程不代表照片编码的无损直拷。
7.7 多照片模式的两种交付方式
选择「Live Photo ＋ 高清候选照片」后，可在「候选照片的格式」中选择：
- 每张都导出为 Live Photo：原始封面和各辅助候选分别形成实况配对，每对有独立标识和对应封面时间，并各保存一份完整主运动视频，占用更多空间。
- 主照片实况，其余静态照片：选定封面形成一对 Live Photo，其余高清封面导出为独立 JPEG/HEIC 照片。若主封面选用辅助候选，原始静态照片也会另存。
辅助候选文件使用 .candidate-001.jpg 等名称；另存的原封面使用 .original 后缀。全部实况模式同时生成同名 MOV。导入系统图库时，每份候选作为独立照片入库，不藏在同一资产的 alternatePhoto 中。默认只保存文件，选择图库交付后才入库。
候选 JPEG 内记录其相对视频时间和候选序号；JSON 清单开启时还会记录完整的封面选择、解码及配对校验信息。未验证任意厂商的 HDR 辅助视频能保留 HDR。
8. 系统图库：识别、导入与监测
留刻只用公开的 PhotoKit 接口访问「照片」图库，不直接读写图库文件。图库权限在你首次进入图库功能时才申请，应用启动时不会自动索取。
8.1 扫描与识别
- 查询包括个人图库、共享相簿与同步来源；来源相册可选只读相册，输出相册仍须可写。窗口分别显示系统图库可见图片总数、当前方向/相册候选数与实际授权状态。数量明显不符时，请查看「照片 → 设置 → 通用」的「用作系统照片图库」按钮：灰色代表当前已是系统图库；可点击代表当前打开的是另一图库。不要仅为排查数量而直接切换图库，切换可能影响 iCloud 同步。
- 「安卓 → 苹果实况」枚举范围内的所有可见图片，包括被系统标记为 Live Photo 的图片，再读取原件识别；窗口的「待检查照片」数量不代表已识别的 Motion Photo 数量。「苹果实况 → 安卓」只列出 Live Photo。视频、隐藏项目等不计入此图片列表，因此数量不一定等于「照片」应用的项目总数。
- 扫描可限定在某个相册范围内进行；界面分别显示「扫描资产 / 读取原件 / 识别格式」的进度。
- 识别靠实际解析原件（厂商标记、XMP、容器结构、视频边界），不仅凭扩展名、文件名或 HDR 标记下结论。普通静态图会被跳过，不算失败；带动态标记但视频已丢失的，会显示具体原因，不猜测恢复。
- 扫描结果标注：厂商、动态类型、原片/编辑版、HDR 状态、是否需要从 iCloud 下载原件。
- 本应用自己生成并导入的资产会被本地标识排除，避免反复转换的循环。
8.2 原片与编辑版
图库版本（导出设置）二选一，默认未修改原片（保留原始 HDR）：
- 原片：使用成对的原始照片 + 配对视频；
- 编辑版：「当前编辑版（可能无 HDR）」，只用成对的编辑后全尺寸资源；缺任何一半都会说明原因，不混配、不自动回退到原片。
8.3 直接导入图库
- 仅安卓 → 苹果方向可导入图库。导入时静态图与配对视频在同一次图库请求中创建为一张 Live Photo，再关联到目标相册；默认相册名为 「留刻转换结果」，可改选其他用户相册。
- 导入前再次校验：内容标识匹配、视频带封面定时标记、静态图无残留内嵌媒体；独立辅助轨不会被当作配对视频附加；JSON 清单不会被导入为照片资源。
- 保留原始资源文件名、拍摄日期与位置（优先图库信息，缺失时才用文件元数据）；写入后回读新资产核对 Live Photo 属性、文件名、日期、位置与相册归属，全部确认后才显示「已导入」。
- 按阶段重试：导入失败只重试导入（保留已校验文件）；相册关联失败只重试关联，绝不重复创建资产，避免图库里出现重复照片。
- 去重记录保存在
~/Library/Application Support/Motion-Live/（内部数据目录沿用旧名，有意保留）：imports.json等记录着来源资产、设置、校验摘要与目标资产。记录损坏时会停止写入并报错，以防重复导入；目标资产被你在图库中删除后会标为缺失，不自动补回；状态无法确认的标为「待核对」，不盲目重试。
8.4 iCloud 与增量监测
- 图库资源可能只存在 iCloud。扫描会标注「需下载原件」；下载与监测均为自愿开启（opt-in），在图库选择界面勾选，退出即停止。
- 增量监测（运行期间）：启用后，应用会在运行期间监测所选相册与方向的新增、修改与删除，底部状态栏显示「正在监测所选图库范围」并提供「停止监测」。应用退出即停止，没有后台常驻；重启后靠重新枚举 + 本地记录核对。macOS 12 的限制下不做跨重启的持久监测。
9. 批量、交付与共享
9.1 交付目标
| 交付方式 | 安卓→苹果 | 苹果→安卓 |
|---|---|---|
| 保存到文件夹 | ✓ | ✓ |
| 导入系统图库 | ✓ | — |
| 文件夹并导入图库 | ✓ | — |
| 直接共享 | — | ✓ |
| 文件夹并共享 | — | ✓ |
「仅导出辅助轨」模式下只能保存到文件夹。主按钮文案会随交付方式变化（如「转换并导入图库」「导出辅助轨」）。
9.2 输出命名
每个源文件生成一个结果目录（静态图与 MOV 默认名为 photo.jpg / photo.mov，原始文件名记录在清单的 original_filename 中，输出文件的修改时间沿用源文件时间）：
| 情形 | 目录名 |
|---|---|
| 安卓 → 苹果 | <相对路径>.livephoto（内含静态图 + MOV，及开启时的清单） |
| 仅导出辅助轨 | <相对路径>.auxiliary-export |
| 苹果 → 安卓 | <相对路径>.motionphoto |
9.3 系统共享（苹果 → 安卓）
- 批次结束后，对成功文件统一弹一次系统共享菜单，传的是最终文件本体（
.MP.jpg/.MP.heic），不传缩略图或 NSImage，避免被系统重编码。 - 默认不共享 JSON 清单、结果目录或配对 MOV；部分成功时只共享成功文件并显示失败数；全部失败或任务被停止时不自动弹菜单。
- 取消共享不影响「转换成功」的状态；状态只记录「已交给共享应用」，不宣称对方已收到。
- 共享出去的文件仍可能被第三方服务修改，接收端是否字节不变、HDR/动态/封面是否完好，要以对方实测为准。
9.4 报告与最近结果
- 报告可按 全部 / 已转换 / 已恢复 / 已跳过 / 失败 筛选；每条可查看完整原因、复制详情、在访达中显示结果文件。即使关闭了清单导出，本次报告仍可在应用内查看。
- 「最近结果…」可重试交付、查看文件、打开输出文件夹、清理应用自身任务缓存。清理永远不会删除你输出文件夹里的文件，也不会动图库资产；共享进行期间禁止清理。
10. 设置全表
打开方式：顶部「更多选项…」打开设置面板。带 * 的为高级参数，默认折叠。
| 分组 | 设置 | 选项 / 默认值 |
|---|---|---|
| 方向 | 转换方向 | 安卓→苹果实况（默认）/ 苹果实况→安卓 |
| 输出位置 | 输出方式 | 见 §9.1，随方向与模式联动 |
| 输出位置 | 目标相册名 | 默认「留刻转换结果」，留空回退默认 |
| 输出位置 | 图库版本 | 未修改原片（默认）/ 当前编辑版 |
| 输出内容（→苹果） | 导出模式 | 仅 Live Photo（默认）/ ＋辅助轨 / 仅辅助轨 |
| 输出内容（→苹果） | 视频轨道 | 主运动轨（默认）/ 辅助影像轨 |
| HDR（→苹果） | 尝试兼容非 Ultra HDR | 默认开 |
| 目标格式（→安卓） | 目标厂商 | Google/通用（默认）、小米、三星、华为、荣耀、OPPO、vivo V2 |
| 目标格式（→安卓） | 照片格式 | JPEG·Ultra HDR / HEIC·保留原编码（仅三星可选，其余厂商强制 JPEG） |
| 图像质量（→安卓） | 保留 JPEG 原图编码 | 默认开（开时不重压） |
| 图像质量（→安卓） | 主图质量 / 增益图质量 | 滑杆 1%–100%，默认均为 95% |
| 校验与报告 | 导出清单与 JSON 报告 | 默认关（见 §11） |
| 高级 * | 封面时间未记录时 | 报告错误（默认，推荐）/ 使用视频中点 |
| 高级 * | 封面时间的含义（时间域） | 自动检查（默认，推荐）/ media（样本时间）/ presentation（播放时间） |
| 高级 * | 允许修复辅助轨的零时长 | 默认关（见 §7.5） |
高级区警示原文：「自动模式检查封面位置，遇到歧义会报告错误。仅在了解原片时间轴时修改。」
11. 清单（manifest）与报告
每个结果目录在开启「导出清单与 JSON 报告」时包含一份 manifest.json（该开关默认关：关时仅导出媒体，但内部校验照常进行，本次报告仍可在应用内查看；图库导入不依赖清单文件）。清单主要字段：
| 字段 | 含义 |
|---|---|
source / source_sha256 |
源文件路径与指纹 |
identifier |
本次配对的内容标识 UUID |
source_format |
识别到的源格式（如 samsung-sef、vivo-v2） |
source_timestamp_us / source_timestamp_tag |
源封面时间与来源标签 |
timing |
时间线报告：时间域、封面秒数、对齐误差 snap_error_seconds、计时策略（源 XMP / 视频元数据 / 华为帧号 / 中点）、所选轨道与角色、帧数与分辨率 |
hdr |
输入/输出 HDR 状态与原因 |
primary_coding_sha256 |
静态主图编码哈希 |
auxiliary_sha256 |
静态图内 MPF 辅助图像（增益图等）逐张哈希——注意这是图像辅助数据，不是 §7 的视频辅助轨 |
auxiliary_video |
辅助轨导出信息（轨道号、帧数、分辨率、时长、哈希、是否含音频、零时长修复记录） |
output_sha256 / warnings |
输出文件哈希与全部警告 |
批次报告文件名为 report-<日期>-<时间>-<随机>.json，含计数与逐文件结果，历史报告不自动删除。
隐私提醒：报告与清单可能包含源文件路径、EXIF、日期与哈希，请只保存在本地，不要公开上传。留刻本身不上传任何内容。
12. 命令行工具（CLI）
仓库附带一个独立的 Python 命令行工具，与 App 共用原生引擎的部分能力。范围提醒：CLI 只提供 Google Motion Photo（JPEG）工作流，不包含 App 的 HEIC、厂商容器、辅助轨与图库功能。
环境：Python 3.9+、macOS 12+、Xcode Command Line Tools。首次运行会自动编译原生组件（有提示），之后直接使用。
# 在仓库根目录
./motion-live --help
./motion-live --version # 0.1.0
# 1) 只读扫描：查看封面时间、HDR 与格式问题（文件或目录，递归）
./motion-live scan ~/Photos/待转换
# 2) 批量转换（输出目录必填，必须位于输入目录之外）
./motion-live convert ~/Photos/待转换 -o ~/Photos/已转换
# 3) 校验已有结果与转换时记录的校验值是否一致
./motion-live verify ~/Photos/已转换/sample.jpg.livephoto
convert 的选项：
| 选项 | 默认 | 说明 |
|---|---|---|
--missing-time {error,midpoint} |
error |
缺封面时间时报错；midpoint 用视频中点，必须主动选择 |
--legacy-hdr {auto,preserve} |
auto |
auto 尝试转换已有的旧 Apple 增益图；普通 SDR 不生成 HDR；preserve 原样保留 |
--time-domain {auto,media,presentation} |
auto |
检查样本与播放两条时间线，歧义时报错；可显式指定 |
行为说明：输入只接受 .jpg/.jpeg（跳过符号链接）；普通静态 JPEG 记为 skipped，损坏的动态照片记为 failed，有失败时退出码为 1；每份结果生成 <原名>.livephoto/ 目录（photo.jpg + photo.mov + manifest.json），并在输出根目录写批次报告；已存在且指纹/设置一致的结果记为 resumed，不一致则报错要求更换输出目录。CLI 发布采用不覆盖的一次性原子发布，并把源文件的访问/修改时间保留到输出上。
解析严格性（了解即可）：动态照片的判定依赖 GCamera XMP 与容器结构，视频必须位于文件尾部并通过完整的 box 结构校验，绝不靠搜索文件签名猜测；Ultra HDR 声明了却没有 MPF 辅助图会直接报错。
13. 疑难排解
| 现象 / 报错 | 原因与处理 |
|---|---|
| 导入后在 iPhone 上不动 | 多半是文件未经转换直接拷贝，或配对/封面标记不完整。用留刻转换并通过图库导入或配对文件传输后，在「照片」中长按即可播放 |
| 「封面时间缺失」 | 源文件没有可验证的封面时间。确认原片未经聊天软件/编辑器处理；确需继续时在高级参数改「使用视频中点」（结果会注明策略） |
| 「封面时间有歧义（media / presentation 指向不同帧）」 | 两条时间线不一致。在高级参数中指定时间域，或换回未经编辑的原片 |
| 「辅助轨只有 1 帧，不能作为动态视频」 | 预期行为。改用主运动轨，或用「仅导出辅助轨」把它单独导出为普通视频 |
| 「原片没有辅助视频轨」 | 该照片只有一条视频轨，辅助轨相关模式不适用 |
| 「同名输出已存在且内容或设置不同」 | 旧结果与本次不一致，应用拒绝覆盖。换输出目录，或在弹窗中明确选择覆盖 |
| 「图库去重记录不可读，已停止写入」 | 去重记录损坏时为防重复导入而停写。检查 ~/Library/Application Support/Motion-Live/ 下记录文件，或联系开发者 |
| HEIC 转 JPEG 时提示 HDR 不能安全提取 | 该 HEIC 的 HDR 结构不受支持。改选「HEIC · 保留原编码」输出 |
| 转换后 HDR 不显示 | 可能用了图库「编辑版」（编辑版可能无增益图），改用未修改原片；或源本身是 SDR/未知私有 HDR，报告中会写明原因 |
| 首次打开被 macOS 拦截 | 自签名未公证。在「系统设置 → 隐私与安全性」放行，或访达中 Control-点按 → 打开 |
| 图库扫描不到/提示需下载原件 | 资源只在 iCloud。在图库选择界面开启下载选项后重试 |
14. 已知限制
- 平台：仅 macOS 12+；当前主要在 Intel / macOS 12 上验证，Apple Silicon 真机验证进行中；iOS 版未发布。
- 签名：ad-hoc 签名，无 Developer ID 与 Apple 公证（见 §1 首次打开说明）。
- 构建：从源码构建默认 Intel；
--arm64/--universal需显式指定。 - 厂商格式：只支持解析器可验证的布局，不承诺所有机型、固件与编辑后图片；被编辑/分享过的动态照片可能已经丢视频，无法恢复。
- 图库真实环境：图库入库后的真实播放、再导出、HDR 显示、权限撤销等系统行为仍在持续验收中；自动化回归覆盖的是合成样片，不等同于全部真实设备表现。
- 监测边界：图库增量监测仅在应用运行期间、仅限所选范围，无后台常驻。
- 共享边界：第三方共享服务仍可能修改文件，接收端效果以实测为准。
- CLI 局限：仅 Google Motion Photo JPEG 工作流（见 §12）。
本手册依据留刻当前源码、产品说明与校验范围编写。若手册与应用内提示不一致，以应用内提示与结果报告为准。