在 Apple 平台用 AVKit 构建标准视频播放…

当需要在 iOS/UIKit/SwiftUI 中基于 AVFoundation 实现系统标准媒体播放体验，包括 AVPlayerViewController、VideoPlayer、PiP、AirPlay、字幕或播放速度时适用。

适用场景

解决思路

1. 配置音频会话：在 App 的 Background Modes 中启用 Audio, AirPlay, and Picture in Picture，即 `UIBackgroundModes` 中加入 `audio`。
2. 用 `AVAudioSession.sharedInstance()` 调用 `setCategory(.playback, mode: .moviePlayback)` 设置播放类别。
3. 不要在启动时立即激活音频会话；把 `setActive(true)` 延迟到真正开始播放时调用，避免提前打断其他音频。
4. 按需导入框架：`import AVKit` 用于 `AVPlayerViewController`、SwiftUI `VideoPlayer`、PiP；`import AVFoundation` 用于 `AVPlayer`、`AVPlayerItem`、`AVAsset`。
5. 使用 `AVPlayerViewController` 作为标准 UIKit 播放器，直接获得系统播放控件、PiP、AirPlay、字幕和画面分析；不要继承它。
6. 全屏播放：创建 `AVPlayer(url:)` 和 `AVPlayerViewController()`，设置 `playerVC.player = player`，用 `present(playerVC, animated: true)` 展示，并在 completion 中 `player.play()`。
7. 内嵌播放：把 `AVPlayerViewController` 作为子视图控制器，调用 `parent.addChild(playerVC)`，把 `playerVC.view` 加入容器，设置 `translatesAutoresizingMaskIntoConstraints = false` 并用约束固定四边，最后调用 `playerVC.didMove(toParent: parent)`。
8. 设置播放器关键属性：`showsPlaybackControls` 控制系统控件显隐；`videoGravity` 用 `.resizeAspect` 保持完整画面，用 `.resizeAspectFill` 裁剪填满；按需设置 `entersFullScreenWhenPlaybackBegins`、`exitsFullScreenWhenPlaybackEnds`、`updatesNowPlayingInfoCenter`。
9. 用 `contentOverlayView` 在视频层和传输控件之间添加非交互视图，如水印、logo。
10. 采用 `AVPlayerViewControllerDelegate` 处理全屏切换、PiP 生命周期、插播播放和媒体选择变化；用 transition coordinator 的 `animate(alongsideTransition:completion:)` 让自定义 UI 与全屏动画同步。
11. 在展示播放器前观察 `isReadyForDisplay`，只在 `isReadyForDisplay == true` 后显示播放器视图，避免黑屏闪烁。
12. SwiftUI 基础用法：用 `@State private var player: AVPlayer?` 保存播放器；在 `body` 中用 `if let player` 显示 `VideoPlayer(player: player).frame(height: 300)`，否则显示 `ProgressView()`；在 `.task` 中创建 `AVPlayer(url: url)`。
13. 给 SwiftUI `VideoPlayer` 添加 overlay：在 `VideoPlayer(player:) { ... }` 闭包中放 SwiftUI 视图，overlay 位于视频内容之上、系统播放控件之下；它可以交互，但只接收系统控件未处理的事件。
14. 需要 PiP 配置、代理回调或播放速度控制等 `VideoPlayer` 未暴露的能力时，用 `UIViewControllerRepresentable` 包装 `AVPlayerViewController`，或参考 `references/avkit-patterns.md` 的高级模式。
15. 为标准播放器启用 PiP：确认音频会话为 `.playback`、启用 Audio/AirPlay/PiP 后台模式、当前 `AVPlayerItem` 是可播放视频而非纯音频、当前播放上下文允许 PiP；`AVPlayerViewController` 默认启用 PiP。
16. 用 `allowsPictureInPicturePlayback` 控制是否允许 PiP；用 `canStartPictureInPictureAutomaticallyFromInline = true` 让内嵌/非全屏播放器在 App 进入后台时自动进入 PiP。
17. 实现 PiP 恢复界面：遵守 `AVPlayerViewControllerDelegate` 并实现 `playerViewController(_:restoreUserInterfaceForPictureInPictureStopWithCompletionHandler:)`，重新 present 或重新嵌入播放器，然后调用 `completionHandler(true)` 让系统完成恢复动画。
18. 自定义播放器启用 PiP：用 `AVPictureInPictureController(playerLayer:)` 或 sample buffer 内容源；创建前检查 `AVPictureInPictureController.isPictureInPictureSupported()`，启动前检查 `pipController.isPictureInPicturePossible`；设置 `delegate` 和 `canStartPictureInPictureAutomaticallyFromInline`。
19. 自定义 PiP 只能从用户点击 PiP 按钮的动作中调用 `pipController.startPictureInPicture()`，不要自动启动。
20. 处理广告/法律片段：插播区间可能来自媒体清单的 `AVPlayerItem.interstitialTimeRanges` 或 App 自己的 `AVPlayerInterstitialEventController`；iOS 上不要直接给 `interstitialTimeRanges` 赋值。
21. 仅在必须禁止跳过的广告或法律片段期间，把 `playerVC.requiresLinearPlayback = true`，片段结束后设回 `false`。
22. AirPlay 标准用法：使用 `AVPlayerViewController` 时，只要 App 配置、媒体、路由和设备支持外部播放，AirPlay 自动可用，无需额外代码；系统在检测到支持 AirPlay 的设备时会在传输控件中显示 AirPlay 按钮。
23. 独立 AirPlay 按钮：创建 `AVRoutePickerView(frame: CGRect(x: 0, y: 0, width: 44, height: 44))`，设置 `activeTintColor` 和 `prioritizesVideoDevices = true`，加入 `containerView`。
24. 外部播放：`AVPlayer` 默认允许外部播放；为 AirPlay 保持开启，或用 `player.allowsExternalPlayback = true` 显式恢复；仅在希望外部屏幕模式激活时自动切换外部播放时才设置 `usesExternalPlaybackWhileExternalScreenIsActive`。
25. 自定义播放速度：设置 `playerVC.speeds` 为 `AVPlaybackSpeed(rate:localizedName:)` 数组，例如 0.5、1.0、1.5、2.0；需要恢复默认时用 `AVPlaybackSpeed.systemDefaultSpeeds`。
26. iOS 上的跳过/定位：使用标准传输控件，并在自定义 App 控件中用 `AVPlayer.seek(...)`；不要把 `isSkipForwardEnabled`、`isSkipBackwardEnabled`、`skippingBehavior` 等 tvOS 为主的 API 用在 iOS 播放器实现中。
27. Now Playing：`AVPlayerViewController` 默认自动更新 `MPNowPlayingInfoCenter`；如果要手动管理，设置 `playerVC.updatesNowPlayingInfoCenter = false`。
28. 字幕/隐藏式字幕自动显示：只要媒体包含合适的文本轨道，AVKit 会自动处理；用户在 Settings > Accessibility > Subtitles & Captioning 中控制偏好。
29. 代码选择字幕：从 `player.currentItem?.asset` 调用 `loadMediaSelectionGroup(for: .legible)`，在 `group.options` 中按 `locale?.language.languageCode?.identifier == 'en'` 查找选项，再用 `player.currentItem?.select(english, in: group)` 选择。
30. iOS 上不要使用 tvOS-only 字幕 API：`allowedSubtitleOptionLanguages`、`requiresFullSubtitles` 和 `AVPlayerViewControllerDelegate` 的媒体选择回调仅 tvOS 可用；iOS 需要默认字幕时加载 `.legible` 媒体选择组并在 `AVPlayerItem` 上选择选项。
31. 在 HLS 中提供字幕：字幕/隐藏式字幕嵌入 HLS manifest，AVKit 从 `AVAsset` 的 `AVMediaSelectionGroup` 读取；本地文件需使用已包含 legible 字幕/CC 轨道的媒体，或先把这些轨道制作进可播放 asset 再交给 AVKit。
32. 避免错误：不要继承 `AVPlayerViewController`；用组合和委托，例如 `playerVC.delegate = coordinator`。
33. 避免错误：不要跳过 PiP 音频会话配置；设置 `.playback` 和 `.moviePlayback`，并在播放开始时 `setActive(true)`。
34. 避免错误：不要忘记 PiP 恢复代理方法及其 `completionHandler(true)`；否则用户点恢复无反应或动画卡住。
35. 避免错误：不要在 SwiftUI view 的 `init` 中创建 `AVPlayer`；用 `@State` 和 `.task` 延迟创建，避免每次 view 评估都重新创建。
36. Review checklist：确认音频会话 category 为 `.playback` 且 mode 为 `.moviePlayback`。
37. Review checklist：确认音频会话激活延迟到播放开始。
38. Review checklist：确认已在 `UIBackgroundModes` 添加 Audio, AirPlay, and Picture in Picture 后台模式。
39. Review checklist：确认没有继承 `AVPlayerViewController`。
40. Review checklist：用支持的视频媒体测试 PiP，不要只验证 App/设备设置。
41. Review checklist：确认已实现 PiP 恢复代理方法并调用 `completionHandler(true)`。
42. Review checklist：自定义 PiP 同时检查设备支持和当前 `isPictureInPicturePossible`。
43. Review checklist：自定义 PiP 仅从显式用户交互启动。
44. Review checklist：SwiftUI 中把 `AVPlayer` 延迟到 `.task` 创建，不要提前创建。
45. Review checklist：为内嵌播放器设置 `canStartPictureInPictureAutomaticallyFromInline`。
46. Review checklist：仅在必须的广告/法律片段期间切换 `requiresLinearPlayback`。
47. Review checklist：iOS 传输控件不要使用 tvOS-only skipping API。
48. Review checklist：需要 AirPlay 时不要意外禁用外部播放。
49. Review checklist：用真实媒体轨道测试字幕选择。
50. Review checklist：根据场景设置 video gravity，即 `.resizeAspect` vs `.resizeAspectFill`。
51. Review checklist：显示播放器视图前观察 `isReadyForDisplay`。
52. Review checklist：为网络流媒体内容处理错误，如 HLS 失败、超时。
53. 高级模式：需要自定义播放器 UI、interstitials、后台播放、错误处理时查阅 `references/avkit-patterns.md`；官方文档参考 AVKit framework、AVPlayerViewController、VideoPlayer、AVPictureInPictureController、AVRoutePickerView、AVPlaybackSpeed。

适用边界 · 注意事项

• 非 Apple 平台或非 Swift/AVFoundation 技术栈（如 Android、Web、Flutter 等）不适用。
• 只需要纯音频播放且不需要系统视频 UI、PiP、AirPlay、字幕时，不必用 AVKit。
• 需要完全自定义播放器 UI 且不想使用系统播放控件/PiP 时，应优先考虑更低层 AVPlayerLayer/AVPictureInPictureController，而不是 AVPlayerViewController/VideoPlayer。