七牛Android播放器V1版本开发文档

1 概述

PLDroidPlayer 是一个适用于 Android 平台的音视频播放器 SDK，可高度定制化和二次开发，为 Android 开发者提供了简单、快捷的接口，帮助开发者在 Android 平台上快速开发播放器应用。

1.1 功能特性及版本号

功能特性/接口	描述	版本
支持软硬解自动切换	自动解码模式下，优先硬解，硬解失败自动切换到软解	v1.4.1(+)
支持 HTTPS 协议、speex 解码、mp4v 解码	无	v1.4.1(+)
提供接口获取 metadata 信息	用户可以调用接口获取播放的 metadata 信息	v1.4.1(+)
提供接口获取当前的播放状态	用户可以主动调用接口获取当前播放状态	v1.4.0(+)
支持设置封面	用户在播放开始前显示相关图片信息	v1.4.0(+)
支持带 IP 地址的播放 URL	URL 格式：“protocol://ip/path?domain=xxxx.com”	v1.3.0(+)
支持 DNS 解析优化	支持 DNS 提前解析和缓存管理	v1.3.0(+)
支持直播累积延时优化	优化直播过程中的累积延时	v1.2.3(+)
支持后台播放	支持退到后台只播放音频	v1.2.3(+)
支持音量设置	设置播放器音量，可实现静音功能	v1.2.2(+)
支持画面镜像翻转	由 PLVideoTextureView 提供，支持播放画面镜像翻转	v1.2.2(+)
支持首屏秒开	在网络条件好的情况下，可以实现秒开	v1.2.0(+)
PLMediaPlayer	类似 Android MediaPlayer，提供了播放器的核心功能	v1.2.0(+)
PLVideoView	类似 Android VideoView，基于 SurfaceView 的播放控件	v1.2.0(+)
PLVideoTextureView	类似 Android VideoView，基于 TextureView 的播放控件	v1.2.0(+)
支持画面旋转	由 PLVideoTextureView 提供，支持播放画面以 0度、90度、180度，270度进行旋转	v1.2.0(+)
支持设置画面预览模式	由 PLVideoView 和 PLVideoTextureView 提供，支持多种画面预览模式，包括：原始尺寸、适应屏幕、全屏铺满、16:9、4:3 等	v1.2.0(+)
支持 ARM, X86 芯片体系架构	无	v1.1.3(+)
支持 ARM64v8a 芯片体系架构	无	v1.1.1(+)
AVOptions	用于配置播放器参数，包括：超时时间、软硬件编解码	v1.1.1(+)
AudioPlayer	用于纯音频播放，支持后台运行（注：从 v1.2.0 开始被标记为 Deprecated，并使用 PLMediaPlayer 代替）	v1.1.0(+)
支持 ARMv7a 芯片体系架构	无	v1.0.0(+)
VideoView	基于 SurfaceView 的播放控件（注：从 v1.2.0 开始被标记为 Deprecated，并使用 PLVideoView 代替）	v1.0.0(+)

1.2 特性

• [x] Android Min API 9
• [x] 支持 RTMP 和 HLS 协议的直播流媒体播放
• [x] 支持常见的音视频文件播放（MP4、M4A、flv 等）
• [x] 支持 MediaCodec 硬件解码
• [x] 提供播放器核心类 PLMediaPlayer
• [x] 提供 PLVideoView 控件
• [x] 提供 PLVideoTextureView 控件
• [x] 支持多种画面预览模式
• [x] 支持画面旋转（0度，90度，180度，270度）
• [x] 支持画面镜像变换
• [x] 支持播放器音量设置，可实现静音功能
• [x] 支持纯音频播放
• [x] 支持后台播放
• [x] 支持首屏秒开
• [x] 支持直播累积延时优化
• [x] 支持带 IP 地址的播放 URL
• [x] 支持设置封面
• [x] 支持软硬解自动切换
• [x] 支持 HTTPS 协议、speex 解码、mp4v 解码
• [x] 可高度定制化的 MediaController
• [x] 支持 ARM, ARMv7a, ARM64v8a, X86 主流芯片体系架构

2 阅读对象

本文档为技术文档，需要阅读者：

• 具有基本的 Android 开发能力
• 准备接入七牛云直播

3 开发准备

3.1 设备以及系统要求

• 系统要求：Android 2.3 (API 9) 及其以

3.2 混淆

为了保证正常使用 SDK ，请在 proguard-rules.pro 文件中添加以下代码：

-keep class com.pili.pldroid.player.** { *; }
-keep class tv.danmaku.ijk.media.player.** {*;}

3.3 版本升级须知

v1.5.0

从 v1.5.0 开始，有如下重大更新：

• 需要在项目的 build.gradle 中删除如下配置：

    compile 'com.qiniu.pili:pili-android-qos:0.8.+'

v1.3.1

从 v1.3.1 开始，有如下重大更新：

• 需要在项目的 build.gradle 中加入如下语句：

dependencies {
    compile 'com.qiniu.pili:pili-android-qos:0.8.+'
}

• 更新了 PLMediaPlayer 的构造函数
  如果直接使用 PLMediaPlayer 进行播放的话，需要多添加一个 Context 参数

public PLMediaPlayer(Context context);
public PLMediaPlayer(Context context, AVOptions options);

v1.3.0

从 v1.3.0 开始，有如下重大更新：

• 新增 PLNetworkManager 类，提供 DNS 缓存管理服务

  如果需要使用 SDK 提供的 DNS 缓存管理服务，则需要在项目中加入如下配置：

// 添加 happydns 的依赖
dependencies {
    compile 'com.qiniu:happy-dns:0.2.+'
}
// 添加网络状态监测的权限
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

4 快速开始

4.1 开发环境

• Android Studio 开发工具，官方下载地址
• Android 官方开发 SDK，官方下载地址。

4.2 SDK 集成

首先，下载最新版本的 PLDroidPlayer SDK

4.2.1 导入 SDK

SDK 主要包含 demo 代码、 PLDroidPlayer jar 包，以及 sdk 依赖的动态库文件。

其中，release 目录下是需要拷贝到您的 Android 工程的所有文件，列表如下：

PLDroidPlayer SDK 支持 armv5、armv7、arm64 和 x86 多种 CPU 架构，目前市场上主流机型的 CPU 都采用的是 armv7 架构。您可以根据兼容性的需要，将 release 目录下的动态库，拷贝到您的工程对应的目录下，例如：armeabi-v7a 目录下的 so 则拷贝到工程的 jniLibs/armeabi-v7a 目录下。

同时，还需要将 pldroid-player-x.x.x.jar 包也拷贝到工程的 libs 目录下。

具体可以参考 SDK 包含的 demo 工程，集成后的工程示例如下：

4.2.2 修改 build.gradle

双击打开您的工程目录下的 build.gradle，确保已经添加了如下依赖，如下所示：

dependencies {
    compile files('libs/pldroid-player-x.x.x.jar')
    compile 'com.qiniu.pili:pili-android-qos:0.8.+'
}

4.2.3 添加相关权限

在 app/src/main 目录中的 AndroidManifest.xml 中增加如下 uses-permission 声明

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

4.3 使用 PLVideoView 或者 PLVideoTextureView 实现媒体播放功能

PLDroidPlayer SDK 提供的 PLVideoView 类和 PLVideoTextureView 类可以快速实现带界面的播放器功能，它们的接口与 Android 官方的 VideoView 类基本保持一致，其内部封装了 PLMediaPlayer 类所提供的播放功能。

他们的使用方法基本相同，唯一的区别在于 PLVideoView 类使用了 SurfaceView 来完成视频画面的渲染，而 PLVideoTextureView 采用了 TextureView 完成视频画面的渲染 ，因此，在这里合并在一起来介绍。

4.3.1 布局

如果采用 PLVideoView 的话，布局如下：

<com.pili.pldroid.player.widget.PLVideoView
        android:id="@+id/PLVideoView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:layout_gravity="center" />

如果采用 PLVideoTextureView 的话，布局如下：

<com.pili