<commit_before># PLPlayerKit

PLPlayerKit 是一个适用于 iOS 的音视频播放器 SDK，可高度定制化和二次开发，特色是支持 RTMP 和 HLS 直播流媒体播放。

功能特性

- [x] RTMP 直播流播放
- [x] HLS 播放
- [x] 高可定制
- [x] 音频后台播放
- [x] 无 ffmpeg 依赖

## 内容摘要

- [快速开始](#1-快速开始)
	- [配置工程](#配置工程)
	- [示例代码](#示例代码)
- [关于 2.0 版本](#关于2.0版本)
- [版本历史](#版本历史)

## 快速开始

### 配置工程

- 配置你的 Podfile 文件，添加如下配置信息

```
pod 'PLPlayerKit'
```

- 安装 CocoaPods 依赖

```
pod update
```
or
```
pod install
```

- Done! 运行你工程的 workspace

### 示例代码

在需要的地方添加

```Objective-C
#import <PLPlayerKit/PLPlayer.h>
```

初始化

```Objective-C
// 初始化 Player
PLPlayer *player = [PLPlayer playerWithURL:self.url];

// 设定代理 (optional)
player.delegate = self;
```

开始／暂停操作

```Objective-C
// 准备播放器
__weak typeof(self) wself = self;
[self.player prepareToPlayWithCompletion:^(NSError *error) {
    if (!error) {
        __strong typeof(wself) strongSelf = wself;
        UIView *playerView = strongSelf.player.playerView;
        [strongSelf.view addSubview:playerView];
    }
}];
   
// 播放
[self.player play];
	
// 暂停
[self.player pause];
	
// 停止
[self.player stop];
```

播放器状态获取

```
// 实现 <PLPlayerDelegate> 来控制流状态的变更
- (void)player:(nonnull PLPlayer *)player statusDidChange:(PLPlayerStatus)state {
	// 这里会返回流的各种状态，你可以根据状态做 UI 定制及各类其他业务操作
	// 除了 Error 状态，其他状态都会回调这个方法
}

- (void)player:(nonnull PLPlayer *)player stoppedWithError:(nullable NSError *)error {
	// 当发生错误时，会回调这个方法
}
```

## 音频部分的特别说明

因为 iOS 的音频资源被设计为单例资源，所以如果在 player 中做的任何修改，对外都可能造成影响，并且带来不能预估的各种问题。

为了应对这一情况，PLPlayerKit 采取的方式是检查是否可以播放及是否可以进入后台，而在内部不做任何设置。具体是通过扩展 `AVAudioSession` 来做到的，提供了两个方法，如下：

```
/*!
 * @description 检查当前 AVAudioSession 的 category 配置是否可以播放音频. 当为 AVAudioSessionCategoryAmbient,
 * AVAudioSessionCategorySoloAmbient, AVAudioSessionCategoryPlayback, AVAudioSessionCategoryPlayAndRecord 
 * 中的一种时为 YES, 否则为 NO.
 */
+ (BOOL)isPlayable;

/*!
 * @description 检查当前 AVAudioSession 的 category 配置是否可以后台播放. 当为 AVAudioSessionCategoryPlayback,
 * AVAudioSessionCategoryPlayAndRecord 中的一种时为 YES, 否则为 NO.
 */
+ (BOOL)canPlayInBackground;
```

分辨可以检查是否可以播放以及当前 category 的设置是否可以后台播放。

## 已知 issues

- 当时间戳错乱时，player 当前处理有待优化，可能会因时间戳导致音频有卡顿现象。可以触发这一问题的行为有：
    - 推流端推流开始后，切换推流质量
    - Android 推流 SDK 切换前后至摄像头

## 版本历史

- 2.0.3 ([Release Notes](https://github.com/pili-engineering/PLPlayerKit/blob/master/ReleaseNotes/release-notes-2.0.3.md) && [API Diffs](https://github.com/pili-engineering/PLPlayerKit/blob/master/APIDiffs/api-diffs-2.0.3.md))<commit_msg>Update README && Close #50 && Close #57 && Close #58 && Close #59 && Close #60 && Close #62<commit_after># PLPlayerKit

PLPlayerKit 是一个适用于 iOS 的音视频播放器 SDK，可高度定制化和二次开发，特色是支持 RTMP 和 HLS 直播流媒体播放。

功能特性

- [x] RTMP 直播流播放
- [x] HLS 播放
- [x] 高可定制
- [x] 音频后台播放
- [x] 无 ffmpeg 依赖

## 内容摘要

- [快速开始](#1-快速开始)
	- [配置工程](#配置工程)
	- [示例代码](#示例代码)
- [关于 2.0 版本](#关于2.0版本)
- [版本历史](#版本历史)

## 快速开始

### 配置工程

- 配置你的 Podfile 文件，添加如下配置信息

```
pod 'PLPlayerKit'
```

- 安装 CocoaPods 依赖

```
pod update
```
or
```
pod install
```

- Done! 运行你工程的 workspace

### 示例代码

在需要的地方添加

```Objective-C
#import <PLPlayerKit/PLPlayer.h>
```

初始化

```Objective-C
// 初始化 Player
PLPlayer *player = [PLPlayer playerWithURL:self.url];

// 设定代理 (optional)
player.delegate = self;
```

开始／暂停操作

```Objective-C
// 准备播放器
__weak typeof(self) wself = self;
[self.player prepareToPlayWithCompletion:^(NSError *error) {
    if (!error) {
        __strong typeof(wself) strongSelf = wself;
        UIView *playerView = strongSelf.player.playerView;
        [strongSelf.view addSubview:playerView];
    }
}];
   
// 播放
[self.player play];
	
// 暂停
[self.player pause];
	
// 停止
[self.player stop];
```

播放器状态获取

```Objective-C
// 实现 <PLPlayerDelegate> 来控制流状态的变更
- (void)player:(nonnull PLPlayer *)player statusDidChange:(PLPlayerStatus)state {
	// 这里会返回流的各种状态，你可以根据状态做 UI 定制及各类其他业务操作
	// 除了 Error 状态，其他状态都会回调这个方法
}

- (void)player:(nonnull PLPlayer *)player stoppedWithError:(nullable NSError *)error {
	// 当发生错误时，会回调这个方法
}
```

## 音频部分的特别说明

因为 iOS 的音频资源被设计为单例资源，所以如果在 player 中做的任何修改，对外都可能造成影响，并且带来不能预估的各种问题。

为了应对这一情况，PLPlayerKit 采取的方式是检查是否可以播放及是否可以进入后台，而在内部不做任何设置。具体是通过扩展 `AVAudioSession` 来做到的，提供了两个方法，如下：

```Objective-C
/*!
 * @description 检查当前 AVAudioSession 的 category 配置是否可以播放音频. 当为 AVAudioSessionCategoryAmbient,
 * AVAudioSessionCategorySoloAmbient, AVAudioSessionCategoryPlayback, AVAudioSessionCategoryPlayAndRecord 
 * 中的一种时为 YES, 否则为 NO.
 */
+ (BOOL)isPlayable;

/*!
 * @description 检查当前 AVAudioSession 的 category 配置是否可以后台播放. 当为 AVAudioSessionCategoryPlayback,
 * AVAudioSessionCategoryPlayAndRecord 中的一种时为 YES, 否则为 NO.
 */
+ (BOOL)canPlayInBackground;
```

分辨可以检查是否可以播放以及当前 category 的设置是否可以后台播放。

## 已知 issues

- 当时间戳错乱时，player 当前处理有待优化，可能会因时间戳导致音频有卡顿现象。可以触发这一问题的行为有：
    - 推流端推流开始后，切换推流质量
    - Android 推流 SDK 切换前后至摄像头

## 版本历史

- 2.0.3 ([Release Notes](https://github.com/pili-engineering/PLPlayerKit/blob/master/ReleaseNotes/release-notes-2.0.3.md) && [API Diffs](https://github.com/pili-engineering/PLPlayerKit/blob/master/APIDiffs/api-diffs-2.0.3.md))
{'fraction_non_alphanumeric': 0.14401294498381878, 'fraction_numerical': 0.008090614886731391, 'mean_word_length': 4.470132743362832, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7600280', 'n_tokens_mistral': 2693, 'n_tokens_neox': 2866, 'n_words': 370}