AudioburstPlayer 0.3.6

AudioburstPlayer 0.3.6

×

由 Aleksander Kobylak，Kamil Halko，Gal Klein，Yosi Wigman 维护。

 
依赖于
Alamofire~> 5.0.0-rc.2
SwiftGen~> 6.0
IBPCollectionViewCompositionalLayout~> 0.6.7
Cache~> 5.2.0
lottie-ios~> 3.1.5
SDWebImage= 5.4.0
OwlKit= 1.1.1
 

AudioburstPlayer 0.3.6

  • 作者
  • Audioburst

AudioburstPlayer iOS SDK

介绍

AudioburstPlayer 是 iOS 上的 SDK，用于播放预先安排的音频项目播放列表 - 或 'bursts' - 这些是从现场广播和付费播客中获取的短语音音频片段。

特性

AudioburstPlayer 提供两种模式：紧凑模式和全屏模式。两者提供以下特性：

  • 播放播放列表中的任何“burst”
  • 跳转到下一个或上一个“burst”
  • 继续收听（切换到“burst”的较长时间版本）
  • 在单个“burst”内向前或向后移动播放头
  • 显示“burst”标题和节目名称
  • 播放列表在后台持续播放
  • 可以从锁定屏幕控制播放列表
  • 通过替代音频输出播放播放列表：耳机、蓝牙设备或 AirPlay
  • 查看/滚动播放列表中的“burst”
  • 支持暗黑模式

需求

  • iOS 12.0+
  • Xcode 11

开始

本指南为添加 AudioburstPlayer 到 iOS 应用提供快速入门教程。使用 CocoaPods 可以进行 AudioburstPlayer 的安装。《AudioburstPlayerDemo》 应用展示了 AudioburstPlayer 的所有功能。

先决条件

Audioburst API 密钥

库需要通过 Audioburst Publisher 获取应用程序密钥。还有一个体验 ID 通常可用于在设置过程中选择的定制播放列表主题的唯一标识符。

将 AudioburstPlayer 添加到您的应用程序

步骤 1. 添加 AudioburstPlayer 依赖

您可以使用 CocoaPods 通过将其添加到您的 Podfile 来安装 AudioburstPlayer

platform :ios, '12.0'
use_frameworks!

target 'MyApp' do
    pod 'AudioburstPlayer', '~> 0.2.3'
end

为了避免使用可可豆 Pod 1.10.x+ 时出现构建错误和警告，请添加 post_install 操作

post_install do |installer|
  installer.pods_project.targets.each do |target|
   target.build_configurations.each do |config|
    config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'NO'
    config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
   end
  end
 end

第二步：初始化 AudioburstPlayer

AudioburstPlayer 需要一个应用程序密钥才能工作。播放器可以通过两种方式进行配置：通过获取经验 ID 后的 Audioburst 出版社，或者通过传递自定义配置。

import AudioburstPlayer
使用应用程序密钥和经验 ID 初始化 AudioburstPlayer
let player = ABPlayer(appKey: "YOUR_APP_KEY", experienceId: "YOUR_EXPERIENCE_ID")
使用应用程序密钥和自定义配置初始化 AudioburstPlayer
let configuration = ABPlayer.Configuration(appKey: "YOUR_APP_KEY",
                                           playerAction: ...,
                                           mode: ...,
                                           theme: ...,
                                           accentColor: ...,
                                           autoPlay: ...)
let player = ABPlayer(configuration: configuration)

参数说明

  • appKey - 字符串 - 从 Audioburst 出版社 获得的应用程序密钥，
  • playerAction - PlayerAction 枚举 - 库当前支持的播放列表类型之一，
  • mode - PlayerMode 枚举 - 您想要播放器出现的模式（按钮或横幅），
  • theme - PlayerTheme 枚举 - 播放器的主题（暗或亮），
  • accentColor - 字符串 - 播放器中强调色的颜色。它需要以 # 字符开始的十六进制值，
  • autoPlay - 布尔值 - 播放器是否在加载播放列表后自动播放。

可能的 playerAction 值

  • channel(category: String)
  • userGenerated(id: String)
  • source(id: String)
  • account(id: String)
  • voice(data: Data?)

上述大多数选项接受 String 作为参数（category 或 id）。voice 播放列表是一种特殊的类型，将接受从 PCM 文件中获取的字节数组，该数组应包含用户想要听什么声音的指示。

步骤 3. 加载 Audioburst 内容

调用方法加载 Audioburst 内容以获取紧凑型播放器视图控制器。根据 Audioburst 发布者设置的模式，您将获得按钮播放器或横幅播放器视图控制器。建议的视图容器大小为：高度 100 点，宽度：全屏宽度

player.load() { [weak self] result in
    if case let .success(viewController) = result {
        self.addViewControllerAsChild(viewController, parentView: self.playerViewContainer)
    }
}

加载内容后，使用 player.openFullscreenPlayer() 可程序化打开全屏播放器。如果未加载内容，调用此方法将在错误监听器（AudioburstPlayerErrorListener.onError()）中抛出错误 AudioburstPlayerError.contentNotReady

要将容器设置为全屏，可覆盖容器 UIView 中的方法（这将允许容器下方的视图触摸传递）

override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
        let hitView = super.hitTest(point, with: event)
        return hitView == self ? nil : hitView
}

您还可以使用示例应用中提供的自定义类 PassthroughView

要加载播放列表并获取紧凑型播放器，您还可以使用 initialize() 和 showPlayer() 方法。

player.initialize() { result in 
  switch result {
      case .success:
           // handle successful initialization 
      case .failure(let error):
           // handle error 
   }
}

初始化成功后，您可以获取播放器视图控制器

let playerVC = player.showPlayer()

showPlayer() 返回播放器视图控制器的新实例或已创建的视图控制器。

您可以使用 hidePlayer() 方法隐藏紧凑型播放器（按钮或横幅）。

player.hidePlayer()

步骤 4. 按需播放/暂停内容

使用简单的 play() 方法在任何时间请求 AudioburstPlayer 开始播放。

player.play()

如果播放列表尚未加载，此方法调用将使库记住请求，然后在加载过程完成后自动启动播放。

您还可以使用 pause() 方法暂停播放。

player.pause()

步骤 5. 传递已记录的 PCM 文件

AudioburstPlayer 可处理包含播放请求的原始音频文件。您可以记录一条语音命令，说明您想听什么，然后将其上传到您的设备并使用 AudioburstPlayer 进行播放。

func load(voiceData: Data, completion: @escaping (_ result: Result<UIViewController, AudioburstPlayerError>) -> Void)
 player?.load(voiceData: data) { result in
 		//actions after loading voice data playlist
 }

load函数接受Data作为参数。PCM文件中包含的请求将被处理，并加载发现的爆发式播放列表。如果没有找到任何爆发式播放，将调用AudioburstPlayerErrorListener。如果已创建播放器视图控制器，播放列表将加载到当前播放器视图控制器中（并在完成时返回当前实例）。如果没有创建播放器视图控制器，将创建带有加载播放列表的新视图控制器实例，并在完成时返回。请记住，在播放任何PCM文件之前，必须初始化SDK。

步骤6. 以编程方式控制浮动（按钮）播放器

当您选择使用浮动（按钮）播放器时，可以通过以下函数集更好地控制其位置和状态。

func set(position: CGPoint)

此函数接受包含x和y坐标的CGPoint。它将允许您移动浮动播放器并放置在任何位置。如果在此之前调用此函数，库将记住该位置，并将在玩家视图控制器添加到视图层次结构后立即在请求的位置显示它。

player.set(position:  CGPoint(x: 100, y: 200))

func set(playerState: CompactPlayerState)

浮动播放器可以显示以下状态之一

  • Floating - 默认状态。以小圈的形式显示。
  • Expanded - 显示附加信息和播放控制按钮的状态。
  • Sticky - 最小化并附加到一边边缘的播放器。可以在这几个状态之间转换
  • 从Floating到Expanded - 播放器将动画展开。
  • 从Expanded到Floating - 播放器将动画折叠。
  • 从Floating到Sticky - 将找到最近的边缘并附加到它。
  • 从Sticky到Floating - 将从边缘分离。

您可以使用此函数控制外观

player.set(playerState: .sticky)

如果在播放器加载/添加到视图层次结构之前调用此函数，库将记住请求状态，并且当播放器视图控制器添加到视图层次结构时将显示该状态。

func getPlayerStatus() -> CompactPlayerStatus?

此函数可用于获取 CompactPlayerStatus

position: CGPoint 是浮动玩家的当前坐标

state: CompactPlayerState 是浮动玩家的当前状态

lastActivation: Date? 是浮动玩家被用户最后一次使用的日期。如果没有对玩家进行任何操作，则可能为 null。

当浮动玩家尚未显示时，此函数可能返回 null。

第 7 步：处理错误

AudioburstPlayerError 枚举用于代表在 AudioburstPlayer 中发生的错误。为了处理错误，请让您的类实现 AudioburstPlayerErrorListener 协议，例如

extension ViewController: AudioburstPlayerErrorListener {
    func onError(error: AudioburstPlayerError) {
         self.showAlert(withTitle: "Error", message: error.localizedDescription)
    }
}

并为播放器添加监听器

player.add(errorListener: self)

别忘了取消监听器

player.remove(errorListener: self)

第 8 步：处理播放器事件

为了处理播放器事件，请让您的类实现 AudioburstPlayerListener 协议，例如

extension ViewController: AudioburstPlayerListener {
    func onClose() {
        removeViewControllerAsChild(compactPlayerVC)
    }
}

并为播放器添加监听器

player.add(playerListener: self)

别忘了取消播放器监听器

player.remove(playerListener: self)

显示播放列表视图

使用 AudioburstPlayer，您还可以让用户选择他们想听哪个播放列表。为此，请使用以下方法

let playlistsVC = player.showPlaylistsView(configuration: configuration, completion: { result in
		switch result {
      case .success(let playerVC):
      		//handle adding player view controller to the app 
      case .failure(let error):
      		//handle error here 
    }
})

方法 showPlaylistsView() 返回要显示在宿主应用中的播放列表视图控制器，在加载选定的播放列表后，执行 completion 块。使用成功结果，提供播放器视图控制器（如果没有之前加载播放器视图，则为新实例，或当前播放器的视图实例）。

在使用工具栏上的关闭按钮后，将执行 AudioburstPlayerListener 的 onPlaylistsClose() 方法。

PlaylistViewConfiguration 对象允许您以以下方式自定义播放列表视图

  • showToolbar - Bool - 是否显示工具栏

  • toolbarTitle - String - 应作为工具栏标题显示的文本

  • showMyPlaylists - Bool - “我的播放列表”是特殊类型的播放列表部分

  • sectionLayout - SectionLayout 枚举 - 您可以选择是否将播放列表瓷砖以网格或水平轮播格式显示。

  • closeOnPlaylistLoad - Bool - 标志，用于控制在选择任何播放列表后是否应调用 onPlaylistsClose() 方法，该方法来自 AudioburstPlayerListener。

获取播放列表信息

您还可以使用 AudioburstPlayer 请求特定播放列表的信息，并在您的应用中将它渲染给用户。将您希望获取的播放列表信息传递给 getPlaylist 函数，并等待结果。

player.getPlaylist(action: .channel(category: "1")) { result in
            //handle result here
}

播放播放列表

从 getPlaylist 函数返回的每个 ABPlaylist 包含一组 ABBurst 列表。您可以让您的用户选择其中一个，并使用其 id 使该 ABBurst 出现在播放列表的开始位置。

player.playPlaylist(action: .channel(category: "1"), burstId: "35hx7zwe3", completion: { result in
      switch result {
      case .success(let vc):
          //handle showing player view controller 
      case .failure(let error):
          //handle error 
      }
})

其他配置

过滤已收听的内容

默认情况下，播放器会过滤掉所有用户已经收听的内容。使用 shouldFilterListenedBursts 属性来更改此行为或获取当前设置。

player.shouldFilterListenedBursts = false

依赖项

AudioburstPlayer 使用的库（作为 pod 依赖项安装）。

  • Alamofire
  • SwiftGen
  • IBPCollectionViewCompositionalLayout
  • Cache
  • lottie-ios
  • SDWebImage
  • OwlKit

隐私政策

隐私政策

服务条款

服务条款