SwiftUI 视频播放器 iOS 14+，macOS 11+，tvOS 14+

这是一个纯粹的软件包，没有任何第三方库。我的主要重点是性能。特别是如果您需要在背景中添加视频作为设计元素，在这种情况下，您会希望使用一个轻量级的组件，而不需要很多不必要的功能。希望它能对您有所帮助。

Apple 的 VideoPlayer 为 SwiftUI 中的视频播放提供了快速设置。但是，它不允许您隐藏或自定义默认的视频控件 UI，从而限制了其在自定义场景中的使用。或者，您需要使用 AVPlayerViewController，它包含大量功能，仅仅是为了禁用控件。相比之下，此解决方案充当模块化框架，允许您仅集成所需的功能，同时保持核心组件的轻量级。它提供了对播放的完全控制，包括添加自定义 UI 元素的能力，使其非常适合背景视频、工具提示、视频提示和其他自定义场景。此外，它还支持高级功能，例如字幕、无缝循环和实时滤镜应用。它还允许向视频流添加矢量图形，访问帧数据以进行自定义过滤，以及将 ML 或 AI 算法应用于视频处理，从而实现广泛的增强和修改等等。

此软件包使用声明式方法来声明视频组件的参数，这些参数基于构建块。此实现可能会让您深入了解 SwiftUI 在底层是如何工作的。您也可以通过常用方式传递参数。如果要分析软件包的性能，请在真机上进行。

  ExtVideoPlayer{
       VideoSettings{
           SourceName("swipe") 
       }
   } 

或

   ExtVideoPlayer(fileName: 'swipe')  

播放器的功能围绕双向 ⇆ 交互模型设计

• 命令和设置：通过这些，您可以指示播放器做什么以及如何做。设置定义环境和初始状态，而命令提供实时控制。就目前而言，您可以方便地逐个传递命令；也许稍后我会添加对批量命令的支持

• 事件反馈：通过事件处理，播放器与应用程序进行通信，告知应用程序可能需要注意的内部更改。由于媒体播放器的性质，尤其是在具有动态内容或用户交互的环境中，事件流可能会变得泛滥。为了有效地管理这一点并防止应用程序被大量传入事件淹没，系统每秒收集这些事件，并将它们作为批量返回。在 settings 中传递 Events() 以启用事件机制。

您可以通过蒙版修饰符轻松实现此效果

   ExtVideoPlayer(
       settings : $settings,
       command: $playbackCommand,
       VideoSettings{
          SourceName("swipe") 
      }
   )
   .mask{
       RoundedRectangle(cornerRadius: 25)
   }

也许这足以满足您的需求

该软件包包含涵盖关键功能的单元测试。虽然不是详尽的，但这些测试有助于确保核心组件按预期工作。UI 测试正在进行中，并在示例应用程序中开发。run_tests.sh 是一个示例脚本，它通过将测试命令封装到单个可执行文件中来自动化测试，从而简化执行过程。您可以配置脚本以运行与您的项目相关的特定测试环境。

请注意，使用来自 URL 的视频需要确保您有权使用和流式传输这些视频。由于其服务条款的限制，无法直接使用托管在 YouTube 等平台上的视频。

• 时间发布： 如果在初始化期间传递此参数，播放器将根据输入设置发布时间。您可以仅传递 TimePublishing 而不带任何值，以使用 1 秒的默认间隔，或者您可以传递特定的 CMTime 值来设置自定义间隔。| 1 秒（CMTime，1 秒，首选时间刻度为 600）如果未提供 TimePublishing，播放器将不会发出时间事件，这可以在不需要时间信息时提高性能。

• SourceName： 如果提供了有效的 URL（http 或 https），视频将从 URL 流式传输。如果不是 URL，系统将检查本地 bundle 中是否存在具有给定名称的视频。提供的本地名称可以包含扩展名，也可以不包含。系统首先检查本地名称是否包含扩展名。如果本地名称包含扩展名，则提取此扩展名并将其用作默认扩展名。如果本地名称不包含扩展名，系统将分配默认扩展名 .mp4 默认文件扩展名可以通过 Ext 参数设置。

• Loop： 视频到达结尾时是否应自动重新开始。如果未明确传递，视频将不会循环。

   @State public var playbackCommand: PlaybackCommand = .idle

@State 更新在 SwiftUI 中是异步和批处理的。当您分配

   playbackCommand = .play
   playbackCommand = .pause

SwiftUI 仅在同一运行循环周期中注册最后一次分配 (.pause)，而忽略 .play。为了确保在 .pause 之前应用 .play，您可以使用 Task 将第二次更新安排在下一个运行循环迭代中

.play → .pause

   playbackCommand = .play
   
   Task {
       playbackCommand = .pause
   }

.play → .pause → .play

    playbackCommand = .play

    Task { 
        playbackCommand = .pause
        Task { playbackCommand = .play } // This runs AFTER `.pause`
    }

在 SwiftUI 应用程序中使用视频播放器控件时，重要的是要了解命令处理的工作方式。具体来说，连续发出两个相同的命令将导致第二个命令被忽略。这是由于底层实现阻止冗余命令执行，以优化性能和用户体验（就 UI 更新而言）。

例如，如果您尝试连续两次暂停视频播放器，则第二个暂停命令将无效，因为播放器已处于暂停状态。同样，如果视频已经在播放，发送两个连续的播放命令也不会重新触发播放。

在某些情况下，您需要重新发出一个可能看起来是冗余的命令，但在特定条件下是必要的，您必须在两个相似的命令之间插入一个 idle 命令。idle 命令重置播放器的命令状态，允许后续命令被视为新操作进行处理。

.play → .idle → .play

    playbackCommand = .play

    Task {
        playbackCommand = .idle
        Task { playbackCommand = .play } // This runs AFTER `.idle`
    }

• 要使用这些命令，请不要忘记通过 EnableVector() 设置在设置中启用矢量层。
• 当主图层的边界更新时，会触发 boundsChanged 事件 (boundsChanged(CGRect))。当叠加层或自定义矢量层需要动态适应视频播放器尺寸或其他布局调整的变化时，此方法特别有用。为了有效地处理频繁的 boundsChanged 事件并提高性能，您可以使用节流函数来限制更新发生的频率。

此功能旨在用于视频文件已包含嵌入在其元数据中的多个字幕轨道（即，可读媒体轨道）的用例。换句话说，容器格式（例如 MP4、MOV 或 QuickTime）包含一个或多个字幕或隐藏式字幕轨道，可以在运行时选择。通过调用此函数并提供语言代码（例如，“en”、“fr”、“de”），您可以指示组件在资产的媒体选择组中查找相应的字幕轨道。如果找到匹配项，它将激活该字幕轨道；否则，将不会显示字幕。传递 nil 会完全禁用字幕。当您想要在多种嵌入式字幕语言之间切换或关闭它们而无需依赖外部字幕文件（如 SRT 或 WebVTT）时，此方法非常方便。

添加字幕的另一种选择是使用设置（请查看上面），您可以在其中将字幕作为单独的源文件（例如，SRT 或 WebVTT）提供。在这种情况下，字幕是动态加载和管理的，与视频并行，而无需将它们嵌入到视频文件中。这两种方法——使用嵌入式字幕轨道或通过设置添加字幕作为外部文件——都不会合并和本地保存带有字幕的结果视频。相反，字幕在播放期间动态呈现。

配置带有英文字幕的 HLS 播放列表

这是一个配置了英文字幕的 HLS 播放列表示例。字幕被定义为使用 WebVTT 或类似格式的单独轨道，并在主播放列表中引用。此设置允许在视频播放期间无缝呈现字幕，与视频流同步。

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,
    GROUP-ID="subs",
    NAME="English Subtitles",
    LANGUAGE="en",
    AUTOSELECT=YES,
    DEFAULT=YES,
    URI="subtitles_en.m3u8"

#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=3000000,
    RESOLUTION=1280x720,
    SUBTITLES="subs"
video_main.m3u8

如果在 settings: VideoSettings 中未传递 Events()，则事件机制将被禁用。您可以精确指定要接收哪些事件（例如，.itemStatusChangedAny），或者只需传递 .all 即可接收所有可用事件。添加此设置是为了提高性能，因为事件是通过 @State 更改发出的，这会触发视图更新。如果您不需要观察任何事件，禁用它们可以显着提高性能。

PlayerEventFilter - 此枚举提供了一种结构化的方式来过滤 PlayerEvent case。我决定引入一个与 PlayerEvent 对应的附加结构。所有带参数的 case 都被复制为 eventNameAny，以匹配该事件的任何变体，而不管其关联的值如何。如果您需要匹配特定事件参数的特定事件，请告诉我，我会添加它们。

    ExtVideoPlayer{
            VideoSettings{
                SourceName("swipe")
                Events([.durationAny, .itemStatusChangedAny]) // *Events([PlayerEventFilter])*
            }
        } 
        .onPlayerEventChange { events in
            // Here come only events [.durationAny, .itemStatusChangedAny]: any duration and any item status change events.
        } 

当 URL 在语法上有效但资源实际上不存在时（例如，404 响应或无法访问的服务器），AVPlayerItem.status 可能会无限期地保持 .unknown 状态。它可能永远不会转换为 .failed，并且如果播放从未开始，则 .AVPlayerItemFailedToPlayToEndTime 通知将不会触发。

解决方法和最佳实践 使用 HEAD 预先检查 URL

如果您想确保 URL 在传递给组件 (AVPlayerItem) 之前有效，请使用例如通过 URLSession 的简单 HEAD 请求来检查有效的 2xx 响应。

func checkURLExists(_ url: URL) async throws -> Bool {
    var request = URLRequest(url: url)
    request.httpMethod = "HEAD"

    let (_, response) = try await URLSession.shared.data(for: request)
    if let httpResponse = response as? HTTPURLResponse {
        return (200...299).contains(httpResponse.statusCode)
    }
    return false
}

当您使用 addVector 命令时，您可以动态地在视频流上添加新的矢量图形层（例如徽标或动画矢量）。这对于通过叠加层（例如品牌元素、动画图形）增强用户体验特别有用。

添加矢量层:

• addVector 命令接受 ShapeLayerBuilderProtocol 实例。此协议定义了基于给定几何图形（frame、bounds）构建 CAShapeLayer 的必要方法。
• clear 参数确定在添加新矢量层之前是否应移除现有矢量层。如果设置为 true，则所有现有矢量层都将被清除，并且仅显示新层。
• 矢量层将直接布局在视频流之上，使其看起来像是视频播放体验的一部分。

重要的生命周期注意事项：将矢量图形集成到 SwiftUI 视图中，尤其是在 onAppear 等生命周期事件期间，需要仔细考虑底层系统行为。当在视图出现时添加矢量时，开发人员可能会遇到构建器接收到帧和边界值为零的问题。这种差异源于 SwiftUI 视图的生命周期与 UIView 或 NSView 的生命周期（取决于平台）之间的内在不匹配。SwiftUI 将其大部分视图布局和渲染推迟到视图生命周期的后期阶段。为了缓解这些问题，可以在 onAppear 期间引入 небольшая задержка. 我稍后会尝试在初始配置中添加此命令，以涵盖您需要在视频流的早期阶段添加矢量层的情况。

• 亮度和对比度：这些设置也充当过滤器，但与过滤器堆栈分开管理。对亮度和对比度的调整是附加应用且独立于图像滤镜的。
• 持久设置：当过滤器堆栈被清除时，对亮度和对比度的更改不会重置。它们保持在其最后设置的值，必须由开发人员根据需要单独调整或重置。
• 独立管理：开发人员应通过其专用方法或属性管理亮度和对比度调整，以确保这些设置准确地反映在视频输出中。

    ExtVideoPlayer(fileName: 'swipe')    

或以声明方式

   ExtVideoPlayer{
           VideoSettings{
               SourceName("swipe")
               Subtitles("subtitles_eng")
               Ext("mp8") // Set default extension here If not provided then mp4 is default
               Gravity(.resizeAspectFill)
               TimePublishing()
               Events([.durationAny, .itemStatusChangedAny])
           }
       } 
       .onPlayerTimeChange { newTime in
           // Current video playback time
       }  
       .onPlayerEventChange { events in
           // Player events
       }

ExtVideoPlayer{
    VideoSettings{
        SourceName('https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_ts/master.m3u8')
    }
}

现在唯一需要的设置是 SourceName。

软件包中使用的 AVFoundation 框架支持广泛的视频格式和编解码器，包括基于文件的媒体和流媒体协议。以下是根据 Apple 文档组织的网格中列出的支持的视频类型、编解码器和流媒体协议。抱歉，没有检查所有编解码器和文件。

该软件包现在支持使用远程视频 URL，允许您直接从 Web 资源流式传输视频。这是对现有功能的扩展，现有功能主要侧重于本地视频文件。以下是如何在设置中指定远程 URL

ExtVideoPlayer{
    VideoSettings{
        SourceName('https://example.com/video')
        Gravity(.resizeAspectFill)  // Video content fit
    }
}

该软件包现在支持播放命令，允许您控制视频播放操作，例如播放、暂停和 Seek 到特定时间。

struct VideoView: View {
    @State private var playbackCommand: PlaybackCommand = .play

    var body: some View {
        ExtVideoPlayer(
            {
                VideoSettings {
                    SourceName("swipe")
                }
            },
            command: $playbackCommand
        )
    }
}

您可以将关于某些功能的视频提示引入应用程序，例如如何将位置添加到收藏夹。将循环视频提示放入背景或作为弹出窗口打开。

1. 多比特率

   • 视频以多个质量级别（例如，240p、360p、720p、1080p）编码，每个级别具有不同的比特率。

2. Manifest 文件

   • 服务器提供 Manifest 文件
     • 在 HLS 中：一个 .m3u8 文件，其中包含指向每个质量级别的视频片段的链接。

3. 片段

   • 视频被分成短片段，通常为 2-10 秒长。

4. 动态切换

   • 客户端（例如，AVQueuePlayer）根据当前的互联网速度动态调整播放质量
     • 以最合适的质量开始播放。
     • 随着连接速度的变化，在播放期间切换到更高或更低的质量。

• 即时质量调整：确保质量级别之间的平滑过渡，而不会中断播放。
• 最小的暂停和中断：减少缓冲并改善用户体验。
• 带宽效率：服务器仅发送适当的流，从而节省网络流量。

在此软件包的核心中，我使用了 AVQueuePlayer。以下是 AVQueuePlayer 自动启用的支持功能，无需传递任何额外的参数