wake-ios/wake/SharedUI/Media/README.md

SharedUI/Media

媒体通用视图与组件。

WakeVideoPlayer

一个遵循项目 Theme 风格的 SwiftUI 视频播放组件，基于 AVKit 封装。

支持：

• 播放 / 暂停
• 进度条拖动（支持拖动中不打断播放进度回调）
• 静音切换
• 全屏播放（fullScreenCover）
• 自动隐藏控件（播放中 2.5s 无操作自动隐藏）
• 自动播放与循环播放
• 自定义填充模式（videoGravity）

用法示例

import SwiftUI

struct DemoVideoCard: View {
    var body: some View {
        WakeVideoPlayer(
            url: URL(string: "https://devstreaming-cdn.apple.com/videos/wwdc/2020/10653/4/17B5F5F3-4D9E-4BAE-8E8F-2C3C7A01F3F2/cmaf.m3u8")!,
            autoPlay: false,
            isLooping: true,
            showsControls: true,
            allowFullscreen: true,
            muteInitially: false,
            videoGravity: .resizeAspectFill
        )
        .frame(height: 220)
        .clipShape(RoundedRectangle(cornerRadius: Theme.CornerRadius.large, style: .continuous))
        .shadow(color: Theme.Shadows.cardShadow.color, radius: Theme.Shadows.cardShadow.radius, x: Theme.Shadows.cardShadow.x, y: Theme.Shadows.cardShadow.y)
        .padding()
    }
}

初始化参数

• url: URL 必填。视频资源地址，支持网络或本地文件 URL。
• autoPlay: Bool = true 首次出现是否自动播放。
• isLooping: Bool = false 是否循环播放。
• showsControls: Bool = true 是否显示自定义控制层。
• allowFullscreen: Bool = true 是否允许进入全屏播放。
• muteInitially: Bool = false 初始是否静音。
• videoGravity: AVLayerVideoGravity = .resizeAspectFill 视频填充模式，如 .resizeAspect / .resizeAspectFill。
• fallbackURL: URL? = nil 备用码流地址（建议提供 H.264/HLS）。当检测到资源为 HEVC 且当前环境不支持硬解码（如模拟器）时，自动使用该地址播放。

注意事项

• 如果是新加入的文件，确保在 Xcode 中将 WakeVideoPlayer.swift 添加到对应 Target，否则无法被编译。
• 远程流地址需确保允许跨域与 HTTPS，示例使用 Apple 公共 HLS 资源。
• 如果需要画中画（PiP）、双击快退/快进、手势亮度/音量等高级功能，可在此基础上扩展。

HEVC/H.265 支持说明与降级策略

• 模拟器通常不支持 HEVC 硬解码，表现为“只有声音、无画面”。真机（A9 及以上设备）通常支持。
• 组件会在加载时异步分析资源轨道编码；若检测到 HEVC 且当前环境不支持硬解码，则：
  • 若提供了 fallbackURL（建议为 H.264 或多码率 HLS），将自动切换播放该备用源；
  • 若未提供 fallbackURL，会显示顶部黄色提示，建议在真机测试或提供备用码流。

示例：

WakeVideoPlayer(
    url: URL(string: "https://example.com/video_h265.mp4")!,
    fallbackURL: URL(string: "https://example.com/video_h264.m3u8")!,
    autoPlay: true,
    isLooping: false,
    showsControls: true,
    allowFullscreen: true,
    muteInitially: false,
    videoGravity: .resizeAspect
)
.frame(height: 220)

建议优先使用 HLS（.m3u8）主清单，内含多编码/多分辨率分流，兼容性更佳。