lijianfei.com

动态照片（Live Photo / Motion Photo / Moving Photo）凭借“静止照片的构图仪式感 + 短视频的灵动现场感”，已成为移动端影像体验的核心标配。然而，苹果（Apple）、谷歌（Google/Android）与华为（HarmonyOS）三大主流生态各自筑起了坚固的技术高墙：从专有容器格式、私有元数据标签、非对称仿射变换矩阵，到封闭的原生播放器 API，不同阵营之间的动态照片跨端流转长期处于严重的“协议孤岛”状态。

开源跨平台动态照片工具包 MotionPhotoKit（基于 Kotlin Multiplatform 与平台原生能力构建）给出了一套极具工业美感的系统性解法。它将复杂的系统相册来源、网络传输介质与平台原生播放彻底解耦，定义了中立规范的 Portable Motion Photo v1 协议，实现了三大平台间毫秒级的高保真互通、播放与相册双向回存。本文将深入该项目的底层源码，深度拆解其全链路架构演进与音视频工程实战。

1. 行业现状：三大阵营的“活照片”格式割裂困局

在深入架构前，我们必须先理清 iOS、Android 与 HarmonyOS 底层究竟是如何存储和驱动动态照片的。正是这三种截然不同的底层设计，造就了跨平台交互的巨大阻碍：

在过往的主流社交与内容应用（如微信、小红书、微博、Telegram）中，一旦用户尝试跨平台发送 Live Photo，最常见的降级处理无外乎两种：要么被直接剥离视频沦为普通静态死板照片，要么被暴力压缩为一段 2~3 秒的短视频。前者抹杀了现场声音与生动瞬间，后者则丢弃了高画质静止主帧，并在 Feed 流滑动时造成严重的音画抢占与性能开销。

2. 核心破局之道：三界分离与 Portable Motion Photo v1 规范

面对三大平台的碎片化现状，MotionPhotoKit 确立了极其清晰的架构设计哲学：

“来源差异只存在于发送端，播放器绝不猜测来源；网络中间层只传输规范化的单一中立介质。”

基于这套理念，系统将整个处理管线划分为三个完全独立的物理边界：

1. 系统相册来源格式（Source Formats）：负责吸纳各平台的私有资产并进行严格规范化；
2. 网络传输协议（Canonical Wire Protocol）：标准化跨端交换媒介；
3. 平台播放与存储格式（Native Playback & Saving）：各平台原生的高性能硬件呈现与双向落盘。

flowchart TD
    subgraph Senders["发送端：解包、规范化与像素烘焙"]
        A1["Apple Live Photo\n(PHAsset / MOV + JPEG)"] --> B1["AppleLivePhotoExporter\n(AVFoundation + ImageIO)"]
        A2["Android Motion Photo\n(XMP 单文件 / 伴生对)"] --> B2["AndroidMotionPhotoExporter\n(Media3 Transformer + ExifInterface)"]
        A3["HarmonyOS Moving Photo\n(photoAccessHelper 资源)"] --> B3["MotionPhotoSystemAssetImporter\n(ArkTS MediaKit + ByteKMP)"]
    end

    B1 --> C["规范化标准件：Portable Motion Photo v1"]
    B2 --> C
    B3 --> C

    subgraph Wire["跨平台中立协议 (Portable v1)"]
        C --> D1["still.jpg (方向写入像素，恒等变换)"]
        C --> D2["motion.mp4 (H.264，消隐黑边，无音视频延迟)"]
        C --> D3["manifest.json (确定性 SHA-256 Revision 与帧时间戳)"]
    end

    subgraph Receivers["接收端：原生播放与相册双向回存"]
        D1 & D2 & D3 --> H["宿主并发调度器\n(MotionPhotoResourceCoordinator)"]
        H --> E1["iOS 运行时\n(AppleLivePhotoPreparer)\n零二次编码无损装配 MOV/JPEG -> PHLivePhotoView"]
        H --> E2["Android 运行时\n(AndroidMotionPhotoPlayer)\nMedia3 ExoPlayer + Poster 毫秒防闪"]
        H --> E3["HarmonyOS 运行时\n(HarmonyMotionPhotoPlayer)\nArkUI 原生 MovingPhotoView"]
    end

2.1 Portable Motion Photo v1 组成剖析

Portable v1 由三份最小完备资产构成：

1. still.jpg：MIME 为 image/jpeg。静态图像素已执行物理重绘，EXIF Orientation 强制重置为 Normal（值为 1），所有旋转与镜像均直接烘焙进像素阵列；
2. motion.mp4：MIME 为 video/mp4（H.264 编码）。展示变换（Display Transform）强制为恒等矩阵（Identity Matrix），彻底脱离 QuickTime Matrix 与 MP4 旋转头信息依赖；
3. manifest.json：描述媒体元信息的轻量 JSON 契约。

2.2 确定性内容寻址：Revision 生成算法

为了在海量 Feed 流和复杂分布式网络中实现极致的去重与局部缓存复用，Portable v1 杜绝使用随机 UUID 或服务端业务 ID 作为媒体标识，而是采用 确定性内容寻址（Content-Addressable）。

其校验和算法规范如下：

• 对静态图和视频分别计算标准的 SHA-256 摘要（格式为 sha256:<64位小写十六进制>）；
• 核心标识 revision 严格按照以下规范化 UTF-8 文本拼接后二次哈希：

Revision Payload = stillChecksum + "\n" + motionChecksum + "\n" + stillPresentationTimeMillis

// PortableMotionPhotoChecksum.kt
fun calculateRevision(
    stillChecksum: String,
    motionChecksum: String,
    stillPresentationTimeMillis: Long,
): String {
    val payload = "$stillChecksum\n$motionChecksum\n$stillPresentationTimeMillis"
    return MotionPhotoSha256Hasher.hash(payload)
}

无论素材源自哪个平台、何时导出，只要媒体像素内容和关键帧时间一致，三大平台计算得出的 revision 100% 相同。这为接收端的全局磁盘 LRU 缓存、网络请求去重提供了坚不可摧的幂等保障。

3. 发送端深度剖析：规范化管线与避坑实录

发送端的核心职责是“格式抹平与陷阱修正”。各平台音视频管线在导出动态照片时，存在大量隐蔽的底层深坑。

3.1 Apple 端的深水区：Clean Aperture 黑边与 Timed Metadata 抽离

在 AppleLivePhotoExporter.kt 中，针对 Apple 原生素材的处理极其硬核：

避坑 1：HEVC 编码画布与 Clean Aperture 导致的非对称黑边

iPhone 拍摄的伴生视频在底层经常采用大于实际显示区域的编码尺寸（例如由于防抖或硬件编解码对齐预留了 Padding）。系统在 preferredTransform 中保留了基于编码画布的原点平移量。如果直接导出会导致画面一侧出现异常黑边。

MotionPhotoKit 通过 CoreMedia 底层 API 提取真实呈现尺寸（Clean Aperture），并重新计算几何包围盒进行坐标归零：

// AppleLivePhotoExporter.kt 核心片段：消除非对称黑边
val presentationSize = CMVideoFormatDescriptionGetPresentationDimensions(
    videoDesc = formatDescription.reinterpret(),
    usePixelAspectRatio = true,
    useCleanAperture = true,
)
val transformedBounds = CGRectApplyAffineTransform(
    CGRectMake(0.0, 0.0, presentationSize.width, presentationSize.height),
    preferredTransform,
)
val bounds = transformedBounds.useContents {
    TransformedBounds(
        minX = minOf(origin.x, origin.x + size.width),
        minY = minOf(origin.y, origin.y + size.height),
        width = kotlin.math.abs(size.width),
        height = kotlin.math.abs(size.height),
    )
}
// 重新拼接平移修正矩阵，将视频方向硬编码烘焙进像素
val normalizedTransform = CGAffineTransformConcat(
    preferredTransform,
    CGAffineTransformMakeTranslation(-bounds.minX, -bounds.minY),
)

避坑 2：精确捕获 still-image-time 关键帧

Apple 的 Live Photo 视频中，静态照片对应的时间戳并非固定在视频正中，而是存储在一个极短的 Timed Metadata Track 中。如果简单读取 sample 的 presentation timestamp，部分系统版本会将其错误映射至 0 秒起点。

库中设计了双重交叉校验算法：同时读取 Timed Metadata 轨道的 trackEndSeconds 与内部 sample 的微小持续时间（通常小于 50 毫秒），唯有两者有效且在合理范围内时才判定为真实封面时间戳，否则平滑降级至视频中点。

// AppleLivePhotoExporter.kt：提取精准定格时间戳
private fun readStillPresentationTime(asset: AVAsset, durationMillis: Long): Long {
    val reader = AVAssetReader(asset = asset, error = null)
    // 遍历 AVMediaTypeMetadata 轨道并提取 timed sample buffer...
    // 精确锁定 markerSeconds，避免首帧跳跃
    return (markerSeconds * 1_000.0).roundToLong().coerceIn(0L, durationMillis)
}

3.2 Android 端的精准拆解：XMP 字节提取与硬件转码

在 Android 侧（AndroidMotionPhotoExporter.kt 与 AndroidMotionPhotoFileExtractor.kt），面临的核心挑战是多厂商变种与单文件解构：

1. Media3 容器字节拆分：针对标准 Google Motion Photo 单文件容器，通过 Media3 的元数据扫描器解析 XMP 目录，直接定位视频起止偏移量，采用 NIO FileChannel零拷贝（Zero-Copy）抽取为纯净的静态 JPEG 与 MP4 临时文件；
2. 伴生文件优雅降级：若未命中 XMP 单文件规范，自动探测同目录、同名 Stem 的 _COVER.jpg / .mp4 资源对，或探测相册授予的 live_photo 伴生视频 URI；
3. 图像与视频方向固化：
   • 静态图通过 ExifInterface 获取角度，通过 Bitmap.createBitmap 重建像素并将 EXIF 设为 Normal；
   • 伴生视频送入 Media3 Transformer，挂载 Presentation.createForWidthAndHeight 与特效管道，彻底将顺时针旋转 90/180/270 度的变换烧录入 MP4 视频帧中。

4. 传输与调度核心：并发限流与请求合并（Coalescing）

动态照片在 Feed 流（如瀑布流、列表页）展示时，瞬间会有数十个甚至上百个 Cell 涌入屏幕。如果每个 Cell 都无序触发网络拉取，瞬时并发会迅速击穿带宽并导致主线程卡顿。

motionphoto-core 抽象了高度工业化的 MotionPhotoResourceCoordinator，其设计包含三大核心机制：

sequenceDiagram
    autonumber
    participant Cell1 as Cell A (View 1)
    participant Cell2 as Cell B (View 2 相同资源)
    participant Coord as MotionPhotoResourceCoordinator
    participant Loader as Host ResourceLoader (网络/磁盘)

    Cell1->>Coord: load(Resource-A, progressListener1)
    activate Coord
    Note over Coord: Mutex 锁定：创建 Entry 并启动 Lazy 协程
    Coord->>Loader: 获得 Semaphore 许可，发起单次网络下载
    activate Loader

    Cell2->>Coord: load(Resource-A, progressListener2)
    Note over Coord: 检测到在途请求 (In-Flight Coalescing)<br>waiterCount++，挂载 Listener，不发新请求！

    Loader-->>Coord: 下载完成，交付 Local Resource
    deactivate Loader
    Coord-->>Cell1: 唤醒 Deferred.await() -> 返回资源
    Coord-->>Cell2: 唤醒 Deferred.await() -> 返回资源
    deactivate Coord

1. 单资源在途请求合并（In-Flight Request Coalescing）：
   利用 Kotlin 协程的 Mutex 与 Deferred。当列表快速滑动或同一个动态照片在多处显示时，相同的 resourceKey 只会产生一次真实的底层 Loader 调用。后续调用者自动作为 waiter 挂载，共享数据流与进度广播；
2. 信号量全局控频（Concurrency Limiting）：
   通过 Semaphore(maxConcurrentLoads)（默认允许 4~8 路）严格约束同时进行的网络与本地化任务，超出部分在协程挂起队列等待，保护移动端网络栈与 I/O；
3. 细粒度级联取消（Cascade Cancellation）：
   当用户快速滑过 Cell 时，View 会触发解绑。Coordinator 会减少当前任务的 waiterCount；唯有当所有关注者均注销时，才会向底层的 MotionPhotoResourceLoadRequest 发送 cancel()，立即掐断底层网络连接。

5. 接收端与渲染黑科技：无缝装配原生播放器

接收端如何将标准的 Portable v1（普通 JPEG + 普通 MP4）重新喂给各平台的专属播放器？这是整套架构中最精彩的音视频工程实现。

5.1 iOS 端神来之笔：零二次编码的无损重封装（Pass-through Remux）

苹果的 PHLivePhotoView 是一个黑盒，它在底层强制要求两点：

• 静态图必须包含包含特定 UUID 的 Apple Maker 字典；
• 视频轨必须包含一致 UUID 的 QuickTime Content Identifier 元数据，以及 Timed Metadata 形式的封面标记。

如果为了播放而使用编码器重新压制 MOV，不仅手机会剧烈发热，画质衰减，更会产生数秒的严重卡顿。AppleLivePhotoPreparer.kt 的实现极其惊艳：它实现了纯内存级的流式重封装（Pass-through Remux），完全不触碰像素解码与重新压缩！

flowchart LR
    subgraph Inputs["标准 Portable 输入"]
        J["still.jpg"]
        M["motion.mp4"]
    end

    subgraph Preparer["AppleLivePhotoPreparer (零二次编码)"]
        J -->|ImageIO 无损写入| P1["MakerApple:17\n(UUID)"] --> OS["paired-still.jpg"]
        M -->|AVAssetReader 解封装 Track| AR["H.264 Video Track\nAAC Audio Track"]
        AR -->|AVAssetWriter 裸流直通复用| AW["AVAssetWriter\n(AVFileTypeQuickTimeMovie)"]
        AW -->|注入 QuickTime 元数据| P2["com.apple.quicktime.content.identifier\n+ still-image-time"] --> OV["paired-motion.mov"]
    end

    subgraph Native["系统组件呈现"]
        OS & OV --> PL["PHLivePhoto.request(...)"]
        PL --> V["PHLivePhotoView (原生流畅手势播放)"]
    end

关键步骤 1：通过 ImageIO 为静态图植入 MakerApple 元数据

利用 CoreGraphics 与 ImageIO，直接打开输入流并在写入目的地字典中压入 kCGImagePropertyMakerAppleDictionary，键值为 "17"，内容为新生成的 UUID。全过程只做元数据覆写，耗时小于 5 毫秒：

// AppleLivePhotoPreparer.kt
val makerApple = createRetainingDictionary(1)
val assetKey = CFStringCreateWithCString(null, "17", kCFStringEncodingUTF8)
val assetValue = CFStringCreateWithCString(null, contentIdentifier, kCFStringEncodingUTF8)
CFDictionarySetValue(makerApple, assetKey, assetValue)
CFDictionarySetValue(properties, kCGImagePropertyMakerAppleDictionary, makerApple)
CGImageDestinationAddImageFromSource(destination, source, 0UL, properties)

关键步骤 2：通过 AVAssetReader/Writer 实现 MOV 裸流直通转封装

创建 AVAssetWriter（格式指定为 AVFileTypeQuickTimeMovie），视频轨道和音频轨道全部 不设置输出编码字典（OutputSettings 设为 null）。这意味着原始 H.264 NALU 与 AAC 采样包直接从 MP4 解封装后被原样拷贝入 MOV 容器。

随后，向视频头部动态挂载 AVMetadataIdentifierQuickTimeMetadataContentIdentifier，并在 stillPresentationTimeMillis 对应的微秒处附加 AVTimedMetadataGroup。整个转封装过程在 A16/A17 芯片上仅需 10~30 毫秒，且保持 100% 原始画质！

5.2 Android 端毫秒级防闪黑与解码器生命周期管理

在 Android 平台上，直接使用 ExoPlayer 播放动态照片面临两大顽疾：

1. 缓冲与解码首帧闪烁：启动播放时由于解码器初始化，屏幕容易出现短暂黑帧；
2. 硬件解码器配额耗尽：Android 设备单进程硬件解码器实例有限（许多低端机型仅支持 16 个并发解码器）。如果在 RecyclerView 中为每个可见 Cell 保持活跃的 Player，快速滑动必崩。

AndroidMotionPhotoPlayer.kt 采用了精妙的双层视图设计与分级休眠策略：

┌────────────────────────────────────────────────────────┐
│               AndroidMotionPhotoPlayer                 │
│                                                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  顶层：ImageView (Cover Poster 占位封面)           │  │
│  │  • 默认可见，承载高清静态图                        │  │
│  │  • 接收 onRenderedFirstFrame 事件后瞬间 INVISIBLE │  │
│  │  • 播放结束或异常时瞬间 VISIBLE 兜底              │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │  底层：Media3 PlayerView (ExoPlayer)             │  │
│  │  • 负责循环渲染伴生视频                          │  │
│  │  • 列表滑出可视区域 (setActive=false) 立即 release│  │
│  │  • 重新滑入可视区域时按需重建 Player              │  │
│  └──────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────┘

• 首帧绝对平滑切换：
  静态图 ImageView 始终覆盖在 PlayerView 上方。当且仅当 ExoPlayer 回调 onRenderedFirstFrame() 时，ImageView 才隐藏。用户视觉上看到的是静态照片无缝丝滑地“动”了起来，没有任何黑屏或跳帧；
• 分级休眠与复用代数（Generation）：
  当 Cell 离屏时，View 仅保留当前的封面 Bitmap 和资源模型，ExoPlayer 实例立即彻底释放，归还底层 MediaCodec 资源；当 Cell 重新可见时再惰性拉起。通过每次绑定递增的 generation 令牌，彻底杜绝快速滑动时旧任务异步回调覆盖新数据的 Race Condition。

6. 双向闭环：将 Portable 回存至三大原生系统相册

真正工业级的动态照片 SDK 绝不能只管播放，必须形成“导入 → 传输 → 播放 → 导出回存”的完整生命周期闭环。MotionPhotoKit 在三端均提供了极为优雅的系统相册双向回存能力。

6.1 iOS：原子化 Live Photo 资产创建

在 AppleMotionPhotoLibrarySaver.kt 中，利用经过 AppleLivePhotoPreparer 准备好的成对文件，调用 PhotoKit 的原子批处理提交：

// iOS 保存到系统相册
PHPhotoLibrary.shared().performChanges({
    let request = PHAssetCreationRequest.forAsset()
    request.addResource(with: .photo, fileURL: pairedStillUrl, options: nil)
    request.addResource(with: .pairedVideo, fileURL: pairedMotionUrl, options: nil)
}, completionHandler: { success, error in ... })

保存成功后返回相册的原生 localIdentifier，用户在系统相册中打开即带有官方“实况”角标与长按播放效果。

6.2 Android：基于 Media3 Muxer 的标准 Motion Photo 1.0 合成

Android 端不依赖厂商私有反射，直接借助 Media3 的 MuxerUtil 官方能力，将宿主下载的静态图与视频重新打包为符合 Google 规范的标准单文件 Motion Photo：

// AndroidMotionPhotoLibrarySaver.kt 核心写入逻辑
private fun writeStandardMotionPhoto(
    still: File,
    motion: File,
    presentationTimeMs: Long,
    destination: OutputStream,
) {
    still.inputStream().use { stillInput ->
        motion.inputStream().use { motionInput ->
            MuxerUtil.createMotionPhotoFromJpegImageAndBmffVideo(
                stillInput,
                presentationTimeMs * 1_000L,
                motionInput,
                MimeTypes.VIDEO_MP4,
                Channels.newChannel(destination),
            )
        }
    }
}

结合 Android 10+ 的 MediaStore Pending 机制（通过 IS_PENDING=1 占位并流式写入，完成后置为 0），无需申请容易被拒的外部存储全量读写权限，即可将标准的动态照片落盘至系统图库。

6.3 HarmonyOS：纯血鸿蒙双资源协同提交

在 ArkTS 侧的 MotionPhotoLibrarySaver.ets 中，通过鸿蒙 Next 的 @kit.MediaLibraryKit，发起包含动态照片子类型的变更请求：

// HarmonyOS 系统相册写入
const options: photoAccessHelper.CreateOptions = {
  title: `MotionPhoto_${Date.now()}`,
  subtype: photoAccessHelper.PhotoSubtype.MOVING_PHOTO
}
const changeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(
  context,
  photoAccessHelper.PhotoType.IMAGE,
  'jpg',
  options
)
// 挂载独立成对资源
changeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, stillUri)
changeRequest.addResource(photoAccessHelper.ResourceType.VIDEO_RESOURCE, motionUri)

const helper = photoAccessHelper.getPhotoAccessHelper(context)
await helper.applyChanges(changeRequest)

7. 架构思考与工程哲学：为什么不采用 Compose Multiplatform UI？

许多跨平台开发者可能会产生疑问：既然已经使用了 Kotlin Multiplatform（KMP），为什么 UI 层不直接使用 Compose Multiplatform 实现一个通用的播放 View，而是大费周章地在三端分别封装原生视图？

该项目作者在设计决策中给出了极具说服力的回答：

1. 避免宿主强绑 Runtime 依赖：
   在很多大型移动 App 架构中，UI 栈可能基于 UIKit / SwiftUI、传统的 Android View 体系，或者纯血鸿蒙的 ArkUI。如果 SDK 在 UI 层强推 Compose Multiplatform，将迫使宿主引入庞大的 Compose Runtime 和重型依赖，严重影响接入意愿；
2. 原生交互细节与硬件层面的无可替代性：
   • Apple 的 PHLivePhotoView 原生具备 3D Touch 压感、触觉震动反馈（Haptic Feedback）以及官方的“实况照片”徽标微动动画，这些系统级交互是用自绘 UI 极难低成本复刻的；
   • 鸿蒙系统的 MovingPhotoView 与系统桌面、相册手势具有高度的交互一致性；
   • Android 原生 Media3 / ExoPlayer 则具备对各类 SoC 芯片视频解码器最成熟的兼容性与功耗控制策略。

因此，“KMP 专注沉淀跨端数据契约、格式编解码、并发控制与生命周期状态机；原生层负责轻量级 View 承载与交互呈现”，成为了多媒体 SDK 设计中最值得借鉴的黄金分割线。

8. 总结与落地启示

MotionPhotoKit 的架构演进向移动端与音视频开发者展示了如何优雅地化解跨平台“协议孤岛”：

• 界限分明（Boundaries）：绝不在核心协议层迎合任何单一平台的私有实现，将一切平台差异隔离在发送端 Exporter；
• 传输规范（Canonical Format）：中立、纯粹的 Portable v1 规范，消除了复杂的旋转矩阵与动态格式推测；
• 极致性能（Performance）：iOS 端的无损重封装与 Android 端的双层防闪黑设计，兼顾了顶级画质与超低延迟；
• 全生命周期闭环（Lifecycle）：从相册提取、网络调度、列表流式播放到相册回存，无死角覆盖端到端业务场景。

对于正在规划或重构社交动态、即时通讯、相册同步或电商晒单业务的工程团队而言，MotionPhotoKit 的整体设计和细节把控无疑是一份含金量极高的工程实战蓝本。

原文链接与参考资料

• GitHub 开源仓库：ronny917/MotionPhotoKit - Cross-platform motion photo toolkit for Android, iOS, and HarmonyOS
• Google Media3 官方文档：Media3 Muxer & Android Motion Photo Specification
• Apple 开发者规范：Apple PhotoKit & Live Photo Programming Guide
• 华为鸿蒙开发者中心：HarmonyOS NEXT photoAccessHelper & MovingPhotoView 开发指南