SZAVPlayer

中文说明

SZAVPlayer 是一个基于 AVPlayer，以 Swift 编写的轻量级音视频播放库。支持缓存和视频图像输出。

功能

• 封装 AVPlayer 和 AVPlayerItem 的状态变化，并统一输出，大大降低了音频/视频播放的实现成本。
• 基于 AVAssetResourceLoaderDelegate 完全控制 AVPlayer 数据加载。通过范围请求和相应的缓存，可以立即响应播放器的请求。它还可以在弱网和无网环境下正常播放缓存的音频/视频。
• 支持视频图像输出，可同时绘制到多个视图中。
• 异步加载 AVAsset，不阻塞主线程。
• 支持手动设置缓存大小，也支持清理。

主要流程

提示

如果您发现在模拟器中始终播放失败，请尝试完全退出模拟器并重新启动。这是模拟器的一个bug。

使用

1. 创建播放器并设置代理。

   let player = SZAVPlayer()
   player.delegate = self
   
   audioPlayer = player

2. 使用 URL 设置播放器。

   // uniqueID is to identify wether they are the same audio. If set to nil will use urlStr to create one.
   let config = SZAVPlayerConfig(urlStr: audio.url, uniqueID: nil)
   audioPlayer.setupPlayer(config: config)

   或者

   // If you want play video, pass an additional parameter `isVideo`.
   let config = SZAVPlayerConfig(urlStr: video.url, uniqueID: nil, isVideo: true, isVideoOutputEnabled: true/false)
   videoPlayer.setupPlayer(config: config)

3. 实现 SZAVPlayerDelegate。

   extension AudioViewController: SZAVPlayerDelegate {
   
       func avplayer(_ avplayer: SZAVPlayer, refreshed currentTime: Float64, loadedTime: Float64, totalTime: Float64) {
           progressView.update(currentTime: currentTime, totalTime: totalTime)
       }
   
       func avplayer(_ avplayer: SZAVPlayer, didChanged status: SZAVPlayerStatus) {
           switch status {
           case .readyToPlay:
               SZLogInfo("ready to play")
               if playerStatus == .playing {
                   audioPlayer.play()
               }
           case .playEnd:
               SZLogInfo("play end")
               handlePlayEnd()
           case .loading:
               SZLogInfo("loading")
           case .loadingFailed:
               SZLogInfo("loading failed")
           case .bufferBegin:
               SZLogInfo("buffer begin")
           case .bufferEnd:
               SZLogInfo("buffer end")
               if playerStatus == .stalled {
                   audioPlayer.play()
               }
           case .playbackStalled:
               SZLogInfo("playback stalled")
               playerStatus = .stalled
           }
       }
   
       func avplayer(_ avplayer: SZAVPlayer, didReceived remoteCommand: SZAVPlayerRemoteCommand) -> Bool {
           return false
       }
   
   }

4. 替换新音频。

   // The setupPlayer function will automatically determine if it has been setup before. 
   // If it is, it will directly call the replacePalyerItem function to replace the new audio.
   audioPlayer.setupPlayer(config: config)

   或者

   // or just use this function.
   audioPlayer.replace(urlStr: audio.url, uniqueID: nil)

   这两个函数具有相同效果。

5. 启用视频图像输出。

   • 将 isVideoOutputEnabled 设置为 true。

   let config = SZAVPlayerConfig(urlStr: video.url, uniqueID: nil, isVideo: true, isVideoOutputEnabled: true)
   videoPlayer.setupPlayer(config: config)

   • 实现播放器代理函数。

   func avplayer(_ avplayer: SZAVPlayer, didOutput videoImage: CGImage) {
       videoOutputView1.layer.contents = videoImage
   }

   • 释放播放器时调用 removeVideoOutput 函数。

   videoPlayer.removeVideoOutput()

6. 设置播放器到指定时间。

   audioPlayer.seekPlayerToTime(time: currentTime, completion: nil)

7. 设置最大缓存大小。

   // Unit: MB, if reached the max size, it will automatically trim the cache.
   SZAVPlayerCache.shared.setup(maxCacheSize: 100)

8. 清除所有缓存。

   SZAVPlayerCache.shared.cleanCache()

9. 播放本地文件。因为本地文件不需要经过自定义加载过程，所以直接将 disableCustomLoading 设置为 true。

   let config = SZAVPlayerConfig(urlStr: audio.url, uniqueID: nil)
   config.disableCustomLoading = true
   audioPlayer.setupPlayer(config: config)

示例

示例项目实现了完整的播放示例，包括播放/暂停/上一曲/下一曲/跳转到指定时间/清除缓存等。

要运行示例项目，首先克隆仓库，然后从示例目录执行 pod install。

要求

• iOS 10.0+
• Swift 5.0+

安装

CocoaPods

SZAVPlayer 通过 CocoaPods 提供。要安装它，只需在 Podfile 中添加以下行：

pod 'SZAVPlayer'

Carthage

Carthage 是一个去中心化的依赖管理器，它构建您的依赖并提供二进制框架。要将 SZAVPlayer 集成到您的 Xcode 项目中，使用 Carthage 进行指定，并在您的 Cartfile 中指定它。

github "eroscai/SZAVPlayer" ~> 1.1.1

Swift 包管理器

从 Xcode 11 开始，您可以使用 Swift 包管理器 将 SZAVPlayer 添加到您的项目中。

• 选择文件 > Swift 包 > 添加包依赖。在“选择包仓库”对话框中输入 https://github.com/eroscai/SZAVPlayer.git。
• 如果尚未添加，请将 CoreServices.framework 和 AVFoundation.framework 添加到您的项目中。（如果有人知道如何自动完成此操作，请告诉我）。

作者

eroscai，[email protected]

许可

SZAVPlayer 在 MIT 许可下可用。有关更多信息，请参阅 LICENSE 文件。