Android播放器SDK开发集成
1 概述
1.1 SDK简介
1.1.1 SDK业务简介
网易云视频播放器 Android SDK (以下简称“播放器 SDK”) 是网易官方推出的软件开发工具包，提供简单，便捷的开发接口，帮助开发者在 Android 平台上快速开发播放器应用，提供稳定、高效、流畅的直播和点播拉流服务。
1.1.2 SDK技术简介
播放器 SDK 支持直播和点播，包括协议解析、网络拉流、数据解析、视频解码、音频解码、视频显示、音频播放、音视频同步等基本模块。
1.2 设备和系统要求
- 开发环境：支持 Android Studio 或者 Eclipse 集成开发环境。
- 运行环境：Android 4.0 及以上的所有系统。
- CPU架构：支持 armv5、armv7、x86、arm64 架构。
1.3 功能特性
- 支持 HTTP、RTMP、HLS 协议的流媒体播放
- 支持常见的视频文件格式播放（mp4、flv、mov、m3u8、webm）
- 支持常见的音频文件格式播放（mp3、aac）
- 支持 MediaCodec 硬件解码
- 支持多种画面预览模式（填充，拉伸，裁剪）
- 支持 armv5、armv7、x86、arm64 架构
- 支持 Android 4.0及以上系统
- 支持音频后台播放
- 可高度定制化播放器UI控件
- 优化 RTMP 直播首屏秒开
- 优化 RTMP 直播累积延时
- 支持YUV／PCM数据回调
- 支持加密视频解密播放
- 支持点播倍速播放
- 支持多种播放策略
2 开发准备
2.1 准备工作
2.2 集成SDK
本文是根据官网的播放器 Demo 来介绍 SDK 的集成，可在网易云官网下载最新的播放器 Android Demo，来查看更多的实现细节。下载地址1 下载地址2
2.2.1 组件及资源
开发者需要将播放器 SDK 集成到应用中，包括 Jar 包、底层动态库及相关资源文件。每个应用需要独立集成 Jar 包及动态库，如下图所示：
播放器 SDK 包含 demo、libs两个部分，在网易云视频官网可以下载 Demo 和 SDK 包。
demo部分： 里面包含一个示例工程，为了方便开发中更加简单方便的使用播放器SDK，提供在播放器SDK基础上封装的 playerkit 组件，Demo中通过调用 playerkit 组件来实现音视频播放，开发者通过可以仿照Demo通过调用 playerkit 组件或者直接调用播放器SDK相关接口进行接入。
libs目录： 存放播放器 SDK 的 Java 依赖包和底层动态链接库，文件列表如下：
libs
├── armeabi
│ ├── libneliveplayer.so
│ ├── libnelpengine.so
│ ├── libnelprender.so
├── armeabi-v7a
│ ├── libneliveplayer.so
│ ├── libnelpengine.so
│ ├── libnelprender.so
├── x86
│ ├── libneliveplayer.so
│ ├── libnelpengine.so
│ ├── libnelprender.so
├── arm64-v8a
│ ├── libneliveplayer.so
│ ├── libnelpengine.so
│ ├── libnelprender.so
└── NELivePlayer.jar (Java层代码)将这些文件拷贝到你的工程的libs目录下，同时将NELivePlayer.jar加入工程，即可完成配置。
2.2.2 快速集成
- 导入库文件
1 使用libs库集成
集成添加播放器 SDK 到 App 工程，如下图红色框中所示。- (1) 创建应用程序的 Android 工程。
- (2) 将 SDK 中的 Jar 包添加到 App 工程的 libs 目录下，并在工程属性中设置依赖此 Jar 包。
- (3) 选取同 CPU 类型匹配的 so 动态库压缩包，并解压到工程目录的 libs 目录。
需要修改build.gradle文件，确保添加了NELivePlayer.jar文件和动态库文件的依赖：
dependencies {
compile fileTree(dir: 'libs', include: '*.jar')
}
sourceSets {
main {
jniLibs.srcDirs = ['libs']
}
}2 使用gradle库集成
从播放器SDK版本1.8.0开始，提供gradle方式集成播放器SDK，在gradle文件添加对应依赖，示例如下：
compile 'com.netease.nimlib:neliveplayer:1.9.0'- 配置工程权限
SDK 需要访问网络、读写 SD 卡、获取设备信息等权限。在AndroidManifest.xml中加入以下配置：
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.netease.neliveplayer.demo" >
<uses-sdk
android:minSdkVersion="14"
android:targetSdkVersion="22" />
<!-- 权限声明 -->
<!-- 允许程序打开网络套接字 -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- 允许程序向外部存储设备写数据 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- 允许程序向外部存储设备读数据 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<!-- 允许程序获取网络相关信息 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!-- 允许程序获取Wifi网络状态信息 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<!-- 允许程序获得设备信息 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<application
android:allowBackup="true"
android:icon="@drawable/ic_launcher"
android:label="@string/app_name"
android:theme="@style/AppTheme" >
<!-- 欢迎页面activity，默认竖屏模式 -->
<activity
android:name=".NEWelcomeActivity"
android:label="@string/app_name"
android:screenOrientation="portrait">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<!-- 播放设置页面activity，默认竖屏模式 -->
<activity
android:name=".NEMainActivity"
android:label="@string/app_name"
android:screenOrientation="portrait"
android:configChanges="orientation|keyboardHidden|screenSize"
/>
<!-- 播放页面activity，默认横屏模式 -->
<activity
android:name=".NEVideoPlayerActivity"
android:label="@string/app_name"
android:screenOrientation="landscape"
android:configChanges="orientation|keyboardHidden|screenSize"
/>
<!-- 申明本地电话状态（通话状态）的广播接收器，第三方APP集成时，如果需要在App中处理播放器与本地电话的交互请加上此接收器 -->
<!-- receiver中的com.netease.neliveplayer.demo请替换为自己的包名 -->
<receiver android:name="com.netease.neliveplayer.demo.receiver.IncomingCallReceiver">
<intent-filter>
<action android:name="android.intent.action.PHONE_STATE" />
</intent-filter>
</receiver>
</application>
</manifest>- 代码混淆配置
为了保证正常使用SDK，请在proguard-project.txt文件中添加以下代码：-keep class com.netease.neliveplayer.**{*;}
3 API概览
3.1 接口说明
| 类别 | API名称 | 功能 |
|---|---|---|
| 创建播放实例 | create | 使用Context创建播放器实例 |
| 销毁播放实例 | release | 释放播放器实例的所有资源 |
| 设置缓冲策略 | setBufferStrategy | 设置缓冲策略, 在prepareAsync前调用 |
| 设置解码模式 | setHardwareDecoder | 设置是否开启硬件解码, 在prepaerAsync前调用 |
| 设置是否自动播放 | setShouldAutoplay | 设置prepareAsync完成后是否自动播放，若设置成false，需要手动调用start()进行播放, 在prepareAsync前调用 |
| 设置用于显示的surfaceView | setDisplay | 设置显示用的surfaceView，在prepareAsync前调用 |
| 设置用于显示的surface | setSurface | 设置用于显示的surface，可以是surfaceView和TextureView |
| 设置播放地址 | setDataSource | 设置播放地址，在prepareAsync前调用 |
| 获取播放地址 | getDataSource | 获取设置的源文件路径 |
| 设置自动重试信息 | setAutoRetryConfig | 设置自动重试信息 |
| 播放预处理 | prepareAsync | 预处理播放器，为播放做准备，适用于非加密视频 |
| 播放预处理 | prepareAsyncWithDecryptionToken | 预处理播放器，为播放做准备，适用于使用解密相关信息解密的视频的预处理 |
| 播放预处理 | prepareAsyncWithDecryptionKey | 预处理播放器，为播放做准备，适用于使用解密密钥息解密的视频的预处理 |
| 获取媒体信息 | getMediaInfo | 获取媒体信息，包括解码器类型，码流格式等, 需要在收到onPrepare的通知后调用 |
| 设置是否精确seek | setAccurateSeek | 设置是否精确seek |
| 设置静音 | setMute | 设置是否静音 |
| 设置镜像 | setMirror | 该接口只支持软解，如需硬解镜像请使用TextureView的setScaleX |
| 截图 | getSnapshot | 截图功能仅在软件解码条件下支持，硬件解码不支持, 需要在收到onPrepare的通知后调用 |
| 获取版本号 | getVersion | 获取播放器的版本号 |
| 开始播放 | start | 开始播放，或者暂停后恢复播放 |
| 停止播放 | stop | 停止播放 |
| 暂停播放 | pause | 暂停播放,只适用于在点播时调用，不支持直播 |
| 复位播放实例 | reset | 复位播放器至未初始化状态 |
| 获取视频的宽度 | getVideoWidth | 获取视频的宽度, 需要在收到onPrepare的通知后调用 |
| 获取视频的高度 | getVideoHeight | 获取视频的高度, 需要在收到onPrepare的通知后调用 |
| 获取播放状态 | isPlaying | 检测是否正在播放 |
| 设置到指定时间点播放 | seekTo | 设置到指定时间点播放，需要在收到onPrepare的通知后调用，只适用于点播 |
| 获取当前播放位置的时间点 | getCurrentPosition | 获取当前播放位置的时间点 单位: ms, 需要在收到onPrepare的通知后调用 |
| 获取多媒体文件总时长 | getDuration | 获取多媒体文件总时长，只适用于点播 单位: ms, 需要在收到onPrepare的通知后调用 |
| 获取当前已缓存位置的时间点 | getPlayableDuration | 获取当前已缓存位置的时间点 单位:ms, 需要在收到onPrepare的通知后调用 |
| 设置音量 | setVolume | 设置音量(0.0 ~ 1.0, 0.0为静音，1.0为最大) |
| 设置循环播放 | 设置循环播放(0，不循环；-1无限循环；1循环一次，2循环两次，以此类推) | |
| 获取是否循环播放 | 获取是否循环播放 | |
| 设置循环播放 | setLoopCount | 设置循环播放次数(0: 不循环；-1: 无限循环；1: 循环一次，2: 循环两次，以此类推) |
| 获取循环次数 | getLoopCount | 获取是循环播放次数 |
| 设置播放速度 | setPlaybackSpeed | 设置播放速度，只适用于点播 |
| 设置拉流超时时间 | setPlaybackTimeout | 设置拉流超时时间 单位: 秒, 需要在设置播放路径接口后调用 |
| 设置点播时本地外挂字幕文件 | setSubtitleFile | 设置点播时本地外挂字幕文件路径 |
| 切换播放地址 | switchContentUrl | 播放过程中切换播放地址，适用于非加密视频 |
| 切换播放地址 | switchContentUrlWithDecryptionToken | 播放过程中使用解密信息切换加密播放地址 |
| 切换播放地址 | switchContentUrlWithDecryptionKey | 播放过程中使用解密密钥切换加密播放地址 |
| 获取音轨信息 | getAudioTracksInfo | 获取当前播放媒体的音轨信息，需要在prepare完成后调用 |
| 获取音轨序号 | getSelectedAudioTrack | 获取当前选择的音轨序号，需要在prepare完成后调用 |
| 切换音轨 | setSelectedAudioTrack | 切换音轨，需要在prepare完成后调用 |
| 设置是否开启同步回调 | setSyncOpen | 设置是否开启同步时间戳、同步内容信息回调 |
| 获取播放实时数据 | getMediaRealTimeInfo | 获取播放实时数据 |
| 获取正在播放的时间戳 | getCurrentRealTime | 获取正在播放的时间戳 |
| 获取正在播放的同步时间戳 | getCurrentSyncTimestamp | 获取正在播放的同步时间戳 |
| 设置当前正在播放的时间戳回调 | setOnCurrentRealTimeListener | 设置当前正在播放的时间戳回调 |
| 设置当前正在播放的同步时间戳回调 | setOnCurrentSyncTimestampListener | 设置当前正在播放的同步时间戳回调 |
| 设置自定义信息回调 | setOnCurrentSyncContentListener | 设置当前正在播放的音视频流里附带的内容信息回调 |
| 设置视频帧数据的回调 | setOnVideoFrameFilterListener | 注册获取视频帧数据的回调，用户需要实现回调函数OnVideoFrameFilterListener来接收视频帧 |
| 设置音频回调数据的参数 | setAudioPcmDataConfig | 配置PCM回调数据的参数信息，需要在prepare前调用 |
| 设置音频帧数据的回调 | setOnAudioFrameFilterListener | 注册获取音频帧数据的回调，用户需要实现回调函数OnAudioFrameFilterListener来接收音频帧 |
| 设置预处理完成的监听器 | setOnPreparedListener | 设置预处理完成的监听器，在视频预处理完成后回调 |
| 设置视频播放完成的监听器 | setOnCompletionListener | 设置视频播放完成的监听器，在视频播放完成后调用，视频播放完成后会回调onCompletion或者onError |
| 设置缓存变化的监听器 | setOnBufferingUpdateListener | 设置缓存变化的监听器，在网络视频流缓存变化时调用 |
| 设置指定时间点播放的监听器 | setOnSeekCompleteListener | 设置指定时间点播放的监听器，在调用seekTo操作设置到指定时间点播放完成时调用 |
| 设置视频大小变化的监听器 | setOnVideoSizeChangedListener | 设置视频大小变化的监听器，在视频大小发生变化时调用 |
| 设置播放错误的监听器 | setOnErrorListener | 设置播放错误的监听器，在播放发生错误时调用，收到回调时可以进行播放重试或者提示播放错误等操作 |
| 设置状态变化的监听器 | setOnInfoListener | 设置状态变化的监听器，在有状态变化时调用 |
| 设置字幕回调结果的监听器 | setOnSubtitleListener | 设置字幕回调结果的监听器，在字幕信息变化时调用 |
| 添加预调度拉流链接地址 | addPreloadUrls | 添加预调度拉流链接地址，添加后SDK会进行自动预调度处理，预调度结果会进行缓存 |
| 移除预调度拉流链接地址 | removePreloadUrls | 移除预调度拉流链接地址，从预调度结果缓存中删除该拉流地址相关预调度信息 |
| 查询预调度拉流链接地址的结果信息 | queryPreloadUrls | 查询预调度拉流链接地址的结果信息，查询预调度结果缓存中所有的预调度信息 |
3.2 总体参数介绍
- 状态类型
| 参数 | 说明 |
|---|---|
| NELP_BUFFERING_START | 标识缓冲开始 |
| NELP_BUFFERING_END | 标识缓冲结束 |
| NELP_FIRST_VIDEO_RENDERED | 标识视频第一帧显示 |
| NELP_FIRST_AUDIO_RENDERED | 标识音频第一帧显示 |
| NELP_NET_STATE_BAD | 标识网络状态比较差 |
- 播放模式类型
| 参数 | 说明 |
|---|---|
| NELPTOPSPEED | 直播极速模式 |
| NELPLOWDELAY | 直播低延时模式 |
| NELPFLUENT | 直播流畅模式 |
| NELPANTIJITTER | 点播抗抖动模式 |
| NELPDELAYPULLUP | 直播延时追赶模式 |
- 密钥校验结果类型
| 参数 | 说明 |
|---|---|
| NELP_NO_ENCRYPTION | 密钥校验结果：视频未加密,可以进行下一步播放操作 |
| NELP_ENCRYPTION_CHECK_OK | 密钥校验结果：密钥正确,SDK内部会自动进行prepare操作，可以进行下一步播放操作 |
| NELP_ENCRYPTION_UNSUPPORT_PROTOCAL | 密钥校验结果：拉流协议不支持 |
| NELP_ENCRYPTION_KEY_CHECK_ERROR | 密钥校验结果：密钥错误 |
| NELP_ENCRYPTION_INPUT_INVALIED | 密钥校验结果：输入的地址无法播放 |
| NELP_ENCRYPTION_GET_KEY_TIMEOUT | 密钥校验结果：获取密钥超时 |
| NELP_ENCRYPTION_UNKNOWN_ERROR | 密钥校验结果：未知错误 |
- 播放器错误类型
| 参数 | 说明 |
|---|---|
| NELP_EN_HTTP_CONNECT_ERROR | HTTP连接失败 |
| NELP_EN_RTMP_CONNECT_ERROR | RTMP连接失败 |
| NELP_EN_STREAM_PARSE_ERROR | 解析失败 |
| NELP_EN_BUFFERING_ERROR | 缓冲失败 |
| NELP_EN_AUDIO_OPEN_ERROR | 音频相关操作初始化失败 |
| NELP_EN_VIDEO_OPEN_ERROR | 视频相关操作初始化失败 |
| NELP_EN_STREAM_IS_NULL | 没有音视频流 |
| NELP_EN_AUDIO_DECODE_ERROR | 音频解码失败 |
| NELP_EN_VIDEO_DECODE_ERROR | 视频解码失败 |
| NELP_EN_AUDIO_RENDER_ERROR | 音频播放失败 |
| NELP_EN_VIDEO_RENDER_ERROR | 视频播放失败 |
| NELP_EN_UNKNOWN_ERROR | 未知错误 |
4 如何使用SDK API接口
4.1 实现播放功能
Android SDK 的 API 形式与 MediaPlayer 基本保持一致，通过 NELivePlayer 跟底层 so 动态库进行交互。详细的流程可参见 Demo 源代码，开发指南中使用API接口来介绍如何实现音视频媒体播放功能，Demo 源代码中将API接口封装成playerkit组件让开发中更加简单方便的集成播放器SDK。使用API接口实现播放功能包括：
- 1.导入播放器jar包和so库文件
- 2.初始化播放器(init)和创建播放器实例(create)
- 3.监听播放器的相关通知(setOnPreparedListener、setOnInfoListener等)
- 4.将显示图层添加到需要显示的页面上（setDisplay、setSurface）
- 5.设置播放模式、解码类型、播放地址等静态参数（setBufferStrategy、setHardwareDecoder等）
- 6.调用prepareAsync预处理视频源，等待接收onPrepared预处理完成通知
- 7.收到prepare完成通知后，调用start进行播放（如果设置了setShouldAutoplay，可以不用调用start）
- 8.播放过程中根据需要设置动态参数（setVolume、seekTo等）
- 9.调用release释放播放器，资源释放后收到资源释放通知
4.1.0 初始化播放器
4.1.0.1 API介绍
NELivePlayer为播放器提供的接口类，初始化播放器调用该类的静态方法 init 。
4.1.0.2 API原型
/**
* 初始化SDK,使用播放器时必须先进行初始化才能进行后续操作。
*
* @param context 调用上下文
* @param config sdk配置信息
*/
public static void init(Context context, NESDKConfig config);4.1.0.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| context | Context | 上下文信息,请使用ApplicationContext传入 |
| config | NESDKConfig | sdk配置信息 |
4.1.0.4 示例
NESDKConfig config = new NESDKConfig();
//如果需要应用层上报播放数据，那么设置dataUploadListener，默认SDK内部上报播放数据
config.dataUploadListener = mOnDataUploadListener;
NELivePlayer.OnDataUploadListener mOnDataUploadListener = new NELivePlayer.OnDataUploadListener() {
@Override
public boolean onDataUpload(String url, String data) {
LogUtil.d(TAG, "onDataUpload url:" + url + ", data:" + data);
return true;
}
@Override
public boolean onDocumentUpload(String url, Map<String, String> params, Map<String, String> filepaths) {
LogUtil.d(TAG, "onDataUpload url:" + url + ", params:" + params+",filepaths:"+filepaths);
return true;
}
};
//如果需要开启动态加载功能，那么设置dynamicLoadingConfig，默认关闭
config.dynamicLoadingConfig = new NEDynamicLoadingConfig();
config.dynamicLoadingConfig.isDynamicLoading = true;
//使用Armeabiv7a架构示例，使用其他架构可以参考修改
config.dynamicLoadingConfig.isArmeabiv7a = true;
config.dynamicLoadingConfig.armeabiv7aUrl = 客户服务器地址 + "LivePlayer_Android_SDK_" + PlayerManager.getSDKInfo(this).version + "_" + "armeabi-v7a" + ".zip";
//动态加载准备完成时回调
config.dynamicLoadingConfig.onDynamicLoadingListener = mOnDynamicLoadingListener;
private static NELivePlayer.OnDynamicLoadingListener mOnDynamicLoadingListener = new NELivePlayer.OnDynamicLoadingListener() {
@Override
public void onDynamicLoading(final NEDynamicLoadingConfig.ArchitectureType type, final boolean isCompleted) {
Handlers.sharedHandler(DemoCache.getContext()).post(new Runnable() {
@Override
public void run() {
Toast.makeText(DemoCache.getContext(), "type:" + type + "isCompleted:" + isCompleted, Toast.LENGTH_SHORT).show();
}
});
LogUtil.d(TAG, "type:" + type + "，isCompleted:" + isCompleted);
}
};
NELivePlayer.init(this,config);4.1.0.5 特殊说明
动态加载功能说明：
(1)NESDKConfig 里面包含so库动态加载配置信息 dynamicLoadingConfig ，如果APP需要对so进行动态加载，可以进行配置，注意动态加载功能目前不支持 Google Play 上架。 (2)动态加载需要开发者拥有自己的服务器并且在服务器上部署我们的so库文件，文件在官网下载SDK压缩文件的DynamicLoading文件夹中，开发者需要将该文件夹下的文件部署到自己服务器上，以便SDK从开发者的服务器下载SO库文件。 (3)使用动态加载功能可以参考上述示例中的动态加载代码，以使用Armeabiv7a架构为例，其他架构可参照修改，首先打开该架构的开关NEDynamicLoadingConfig#isArmeabiv7a，然后设置该架构对应的动态so库文件的下载地址NEDynamicLoadingConfig#armeabiv7aUrl，这样SDK启动时会从该地址下载对应的动态so库文件，下载完成会回调NEDynamicLoadingConfig#onDynamicLoadingListener，开发者只有收到下载并准备好so库文件的完成回调才能继续后续播放器播放的操作。此外，使用动态加载功能时，在继续后续播放器播放的操作时应该先通过NELivePlayer#isDynamicLoadReady接口检查是否下载并准备好so库文件。
4.1.1 创建播放器实例
4.1.1.1 API介绍
NELivePlayer为播放器提供的接口类，创建播放器实例调用该类的静态方法 create 。
4.1.1.2 API原型
/**
* 创建播放器实例
* @return 播放器实例
*/
public static NELivePlayer create();4.1.1.3 示例
private NELivePlayer mLivePlayer = null;
mLivePlayer = NELivePlayer.create();4.1.2 设置播放缓冲策略
4.1.2.1 API介绍
设置缓冲策略, 在prepareAsync前调用。
4.1.2.2 API原型
/**
* 设置缓冲策略, 在prepareAsync前调用
* 默认使用NELPLOWDELAY为直播低延时模式。
* 直播建议采用极速模式、低延时模式、流畅模式、直播延时追赶模式，点播和本地视频建议采用抗抖动模式(点播不能用直播的4种模式)，在prepareAsync前调用。
* @param bufferStrategy 缓冲策略
* @see NEBufferStrategy#NELPTOPSPEED
* @see NEBufferStrategy#NELPLOWDELAY
* @see NEBufferStrategy#NELPFLUENT
* @see NEBufferStrategy#NELPANTIJITTER
*/
public abstract void setBufferStrategy(int bufferStrategy);4.1.2.3 参数说明
bufferStrategy缓冲策略模式：
| 参数 | 类型 | 说明 |
|---|---|---|
| NELPTOPSPEED | int | 直播极速模式 |
| NELPLOWDELAY | int | 直播低延时模式 |
| NELPFLUENT | int | 直播流畅模式 |
| NELPANTIJITTER | int | 点播抗抖动模式 |
| NELPDELAYPULLUP | int | 直播延时追赶模式 |
4.1.2.4 示例
private int mBufferStrategy = NEBufferStrategy.NELPLOWDELAY; //直播低延时
mLivePlayer.setBufferStrategy(mBufferStrategy);4.1.2.5 特殊说明
直播请使用直播的四种模式，点播请使用点播抗抖动模式。
4.1.3 设置解码模式
4.1.3.1 API介绍
设置是否开启硬件解码模式，默认是软件解码
4.1.3.2 API原型
/**
* 设置是否开启硬件解码, 在prepareAsync前调用
* 默认使用软件解码
* @param isOpen: true:开启硬件解码 false:软件解码
*/
public abstract void setHardwareDecoder(boolean isOpen);4.1.3.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| isOpen | boolean | true:开启硬件解码 false:软件解码 |
4.1.3.4 示例
private boolean mHardwareDecoder = false;
mLivePlayer.setHardwareDecoder(mHardwareDecoder); // false 为软件解码， true 为硬件解码4.1.4 设置监听
4.1.4.1 API介绍
设置 listener 对播放过程进行监听，并根据监听结果做出相应的处理。
4.1.4.2 API原型
/**
* 注册一个回调函数，在视频预处理完成后调用
*
* @param listener 预处理完成的监听器
*/
public abstract void setOnPreparedListener(OnPreparedListener listener);
/**
* 注册一个回调函数，在视频播放完成后调用
*
* @param listener 视频播放完成的监听器
*/
public abstract void setOnCompletionListener(OnCompletionListener listener);
/**
* 注册一个回调函数，在网络视频流缓存变化时调用
*
* @param listener 网络视频流缓存变化的监听器
*/
public abstract void setOnBufferingUpdateListener(OnBufferingUpdateListener listener);
/**
* 注册一个回调函数，在seek操作完成时调用
*
* @param listener seek操作完成的监听器
*/
public abstract void setOnSeekCompleteListener(OnSeekCompleteListener listener);
/**
* 注册一个回调函数，在视频大小发生变化时调用
*
* @param listener 视频大小发生变化时的监听器
*/
public abstract void setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener);
/**
* 注册一个回调函数，在播放发生错误时调用
*
* @param listener 播放发生错误时的监听器
*/
public abstract void setOnErrorListener(OnErrorListener listener);
/**
* 注册一个回调函数，在有状态变化时调用
* 诸如缓存开始、缓存结束、视频第一帧、音频第一帧、拉流时网络状态码(例如302跳转状态)等状态时的回调
*
* @param listener 有警告发生时的监听器
*/
public abstract void setOnInfoListener(OnInfoListener listener);
/**
* 设置当前正在播放的时间戳回调
* 支持软件解码和硬件解码时回调，支持纯音频、音视频文件时回调，建议优先使用 setOnCurrentSyncTimestampListener 回调时间戳
*
* @param interval 回调的时间间隔(单位：毫秒 ms)
* @param listener 时间戳回调
* @return
*/
public abstract void setOnCurrentRealTimeListener(long interval, OnCurrentRealTimeListener listener);
/**
* 设置当前正在播放的时间戳回调
* 支持软件解码时回调，支持音视频文件，不支持硬件解码时回调，不支持纯音频文件时回调
*
* @param interval 回调的时间间隔(单位：毫秒 ms)
* @param listener 时间戳回调
* @return
*/
public abstract void setOnCurrentSyncTimestampListener(long interval, OnCurrentSyncTimestampListener listener);
/**
* 设置当前正在播放的音视频流里附带的内容信息回调
* 支持软件解码和硬件解码时回调，支持音视频文件，不支持纯音频文件时回调，回调中的内容信息是需要推流端推流时发送的，否则没有。
* @param listener 时间戳回调
* @return
*/
public abstract void setOnCurrentSyncContentListener(OnCurrentSyncContentListener listener);4.1.4.3 参数说明
各种 listener 的详细描述可参见 API 文档。
4.1.4.4 示例
mLivePlayer.setOnPreparedListener(mPreparedListener);
mLivePlayer.setOnVideoSizeChangedListener(mSizeChangedListener);
mLivePlayer.setOnCompletionListener(mCompletionListener);
mLivePlayer.setOnErrorListener(mErrorListener);
mLivePlayer.setOnBufferingUpdateListener(mBufferingUpdateListener);
mLivePlayer.setOnInfoListener(mInfoListener);
mLivePlayer.setOnSeekCompleteListener(mSeekCompleteListener);
mLivePlayer.setOnCurrentRealTimeListener(mIntervalTime,mOnCurrentRealTimeListener);
mLivePlayer.setOnCurrentSyncTimestampListener(mIntervalTime, mOnCurrentSyncTimestampListener);
mLivePlayer.setOnCurrentSyncContentListener( mOnCurrentSyncContentListener);
mLivePlayer.setOnSubtitleListener(mOnSubtitleListener);4.1.5 设置数据源
4.1.5.1 API介绍
设置数据源，在prepareAsync前调用。
4.1.5.2 API原型
/**
* 设置播放地址，在prepareAsync前调用
*
* @param path 待播放文件的路径
* @return 是否设置成功，true 成功，false 失败
* @throws IOException
* @throws IllegalArgumentException
* @throws SecurityException
* @throws IllegalStateException
*/
public abstract boolean setDataSource(String path)
/**
* 设置播放地址和播放配置项，在prepareAsync前调用
* @param path 待播放文件的路径
* @param config 播放配置项（配置缓存本地信息和解密信息）
* @throws IOException
* @throws IllegalArgumentException
* @throws SecurityException
* @throws IllegalStateException
* @return 是否设置成功，true 成功，false 失败
*/
public abstract boolean setDataSource(String path, NEDataSourceConfig config)4.1.5.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| path | String | 待播放文件的路径 |
| config | NEDataSourceConfig | 播放配置项 |
4.1.5.4 示例
//只设置播放地址
mLivePlayer.setDataSource(mUri.toString());//设置数据源，返回 true 成功，返回 false 失败
//同时设置播放地址和播放参数
NEDataSourceConfig dataSourceConfig = new NEDataSourceConfig();
mLivePlayer.setDataSource(videoPath, dataSourceConfig);4.1.6 设置显示控件
4.1.6.1 API介绍
使用setDisplay或者setSurface将显示图层添加到需要显示的页面上。
4.1.6.2 API原型
/**
* 设置显示用的surfaceView，在prepareAsync前调用
*
* @param sh 显示Surface关联的SurfaceHolder, 为null时视频不显示
*/
public abstract void setDisplay(SurfaceHolder sh);
/**
* 设置用于显示的surface，可以是surfaceView和TextureView
*
* @param surface
*/
public abstract void setSurface(Surface surface);4.1.6.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| sh | SurfaceHolder | Surface监听器，提供访问和控制SurfaceView背后的Surface 相关的方法 |
| surface | Surface | 由屏幕显示内容合成器所管理的原生缓冲器的句柄 |
4.1.6.4 示例
//若用户显示的 View 继承 SurfaceView，则通过 setDisplay() 接口将 SurfaceHolder 传到底层用于显示。
mLivePlayer.setDisplay(mSurfaceHolder); //设置显示surface
//若用户显示的 View 继承 TextureView，则通过 setSurface() 接口将 SurfaceTexture 传到底层用于显示。
mLivePlayer.setSurface(mSurface); //设置显示surface4.1.7 设置自动重试参数
4.1.7.1 API介绍
从 v2.1.0 开始，播放器SDK内部加入了自动重试功能，可以通过该接口来配置自动重试参数。
4.1.7.2 API原型
/**
* 配置自动重试信息
* @param config 配置参数
*/
public abstract void setAutoRetryConfig(NEAutoRetryConfig config);4.1.7.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| config | NEAutoRetryConfig | 自动重试的配置类 |
4.1.7.4 示例
AutoRetryConfig autoRetryConfig = new AutoRetryConfig();
// 重试三次
autoRetryConfig.count = 3;
// 设置默认重试时间间隔为1s
autoRetryConfig.delayDefault = 1000;
// 设置三次重试的间隔分别为 100ms, 500ms, 3s
autoRetryConfig.delayArray = new long[]{100, 500, 3000};
// 设置重试时的回调
autoRetryConfig.retryListener = new NEAutoRetryConfig.OnRetryListener() {
@Override
public void onRetry(int what, int extra) {
showToast("开始重试，错误类型：" + what + "，附加信息：" + extra);
}
};
// 将重试配置设置给播放器
mLivePlayer.setAutoRetryConfig(autoRetryConfig);4.1.8 预处理视频文件
4.1.8.1 API介绍
预处理视频文件，准备播放，预处理完成后，sdk会有一个回调，需要先注册一个 OnPreparedListener 获取准备完成的回调。
4.1.8.2 API原型
/**
* 预处理播放器，为播放做准备
*
* @throws IllegalStateException
*/
public abstract void prepareAsync() ;4.1.8.3 示例
mLivePlayer.prepareAsync();
//预处理完成后，sdk会有一个回调，需要先注册一个 OnPreparedListener 获取准备完成的回调，步骤(4)已经注册了。
OnPreparedListener mPreparedListener = new OnPreparedListener() {
public void onPrepared(NELivePlayer mp) {
mLivePlayer.start();
};4.1.9 使用密钥预处理视频文件(旧)
4.1.9.1 API介绍
该接口未来会废弃，建议用户使用新的解密方式解密。flv和hls点播加密视频获取密钥然后预处理视频文件(直播流和非flv、hls点播视频可以忽略该步骤)。对于flv和hls点播的加密视频，需要密钥进行解密，然后再进行播放，用户需要调用该接口来获取密钥并验证密钥的正确性,如果校验正确那么自动进行prepareAsync操作，校验结果OnDecryptionListener中进行回调。
4.1.9.2 API原型
/**
* 设置解密相关信息然后预处理播放器
* 获取密钥并对密钥做相关的校验,如果校验正确那么自动进行prepareAsync操作，校验结果OnDecryptionListener中进行回调
* 该接口需要在setDataSource后调用, 不能与prepareAsyncWithDecryptionKey、prepareAsync同时使用
*
* @param transferToken 获取密钥所需的令牌
* @param accid 视频云用户创建的其子用户id
* @param token 视频云用户子用户的token
* @param appKey 开发者平台分配的AppKey
* @param listener 密钥校验结果的回调,校验正确才能继续prepareAsync操作
*/
public abstract void prepareAsyncWithDecryptionToken(String transferToken, String accid, String token, String appKey, OnDecryptionListener listener);4.1.9.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| transferToken | String | 获取密钥所需的令牌 |
| accid | String | 用户创建的其子用户id |
| token | String | 用户子用户的token |
| appKey | String | 开发者平台分配的AppKey |
| listener | OnDecryptionListener | 密钥校验结果的回调,校验正确才能继续prepareAsync操作 |
4.1.9.4 示例
mLivePlayer.prepareAsyncWithDecryptionToken(transferToken, accid, token, appKey, mDecryptionListener);
OnDecryptionListener decryptionListener = new OnDecryptionListener() {
@Override
public void onDecryption(int ret) {
Log.i(TAG, " ret = " + ret);
switch (ret) {
case NEKeyVerifyResultType.NELP_NO_ENCRYPTION:
case NEKeyVerifyResultType.NELP_ENCRYPTION_CHECK_OK:
mCurrState = PREPARING;
break;
case NEKeyVerifyResultType.NELP_ENCRYPTION_UNSUPPORT_PROTOCAL:
break;
case NEKeyVerifyResultType.NELP_ENCRYPTION_KEY_CHECK_ERROR:
break;
case NEKeyVerifyResultType.NELP_ENCRYPTION_INPUT_INVALIED:
break;
case NEKeyVerifyResultType.NELP_ENCRYPTION_GET_KEY_TIMEOUT:
break;
case NEKeyVerifyResultType.NELP_ENCRYPTION_UNKNOWN_ERROR:
break;
default:
break;
}
}
};4.1.10 使用密钥预处理视频文件(新)
4.1.10.1 API介绍
建议用户使用新的解密方式解密。flv和hls点播加密视频获取密钥然后预处理视频文件(直播流和非flv、hls点播视频可以忽略该步骤)。对于flv和hls点播的加密视频，需要密钥进行解密，然后再进行播放，用户需要调用该接口来获取密钥并验证密钥的正确性,如果校验正确那么自动进行prepareAsync操作，校验结果OnDecryptionListener中进行回调。 使用setDataSource接口的NEDataSourceConfig参数设置解密配置信息，然后调用prepareAsync接口预处理，解密错误会在onError中回调，解密成功会在onInfo中回调。
4.1.10.2 API原型
/**
* 设置播放地址和播放配置项，在prepareAsync前调用
* @param path 待播放文件的路径
* @param config 播放配置项（配置缓存本地信息和解密信息）
* @throws IOException
* @throws IllegalArgumentException
* @throws SecurityException
* @throws IllegalStateException
* @return 是否设置成功，true 成功，false 失败
*/
public abstract boolean setDataSource(String path,NEDataSourceConfig config)
/**
* 预处理播放器，为播放做准备
* @throws IllegalStateException
*/
public abstract void prepareAsync()4.1.10.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| config | NEDataSourceConfig | 播放配置项（配置缓存本地信息和解密信息） |
4.1.10.4 示例
NEDataSourceConfig dataSourceConfig = new NEDataSourceConfig();
// 配置解密信息
if (decryptionCode == DecryptionConfigCode.CODE_DECRYPTION_INFO) {
dataSourceConfig.decryptionConfig = new NEDecryptionConfig(transferToken, accid, appKey, token);
}else if (decryptionCode == DecryptionConfigCode.CODE_DECRYPTION_KEY) {
dataSourceConfig.decryptionConfig = new NEDecryptionConfig(flvKey, flvKeyLen);
}
// 配置本地缓存
if(enableCache) {
dataSourceConfig.cacheConfig = new NECacheConfig(true, cachePath);
}
mLivePlayer.setDataSource(videoPath, dataSourceConfig);
mLivePlayer.prepareAsync();4.1.11 开始播放
4.1.11.1 API介绍
预处理完成后，调用 start 开始播放。
4.1.11.2 API原型
/**
* 开始播放
*
* @throws IllegalStateException
*/
public abstract void start() throws IllegalStateException;4.1.11.3 示例
mLivePlayer.start();4.1.11.4 特殊说明
进行媒体播放控制需要注意：
(1) 在 OnPreparedListener 监听到prepare完成后，可以通过 getDuration() 接口来获取文件总时长，通过 getCurrentPosition() 来获取当前播放位置，并用于设置播放进度条，拖动操作可以通过调用 seekTo() 接口。这几个接口均只适用于点播。
(2) 可通过 自定义SurfaceView或者TextureView接口来自定义画面显示模式，Demo中的playerkit组件封装了可直接使用的SurfaceView和TextureView，有四种显示模式，包括:_
VideoScaleMode.NONE = 0; //原始大小
VideoScaleMode.FIT = 1; //等比例放大，有一边贴黑边
VideoScaleMode.FILL = 2; //全屏，画面会拉伸
VideoScaleMode.FULL = 3; //全屏，等比例放大，有一边有裁剪注意：该方法为demo中playerkit组件提供的示例，用户可以参考该示例进行设置，也可以根据自己的实际需求进行计算并设置，该部分不属于SDK的范畴。
4.1.12 退出播放
4.1.12.1 API介绍
退出播放，释放播放器实例和资源。
4.1.12.2 API原型
/**
* 释放播放器所有资源
*/
public abstract void release();4.1.12.3 示例
mLivePlayer.release();4.1.12.4 特殊说明
退出播放并释放相关资源，资源释放成功后会有相应的通知，通知以广播的形式进行接收，具体接收方式见下述2.4节 第9条。若退出后再次进入播放，需要等待资源释放成功后才能进入。
4.2 播放器的相关回调
4.2.1 预处理回调
4.2.1.1 API介绍
预处理完成后调用，可以在该回调内添加处理逻辑，该监听器用于监听播放器的预处理过程，主要包括：创建播放所需资源、获取媒体流等，当 预处理完成后，SDK 会回调该对象的 onPrepared 接口，若setShouldAutoplay设置为ture，则会在收到该回调的同时自动播放，若setShouldAutoplay设置为false，则需要在该回调中调用start()接口手动播放。
4.2.1.2 API原型
/**
* 播放器预处理监听类
*
* @author netease
*/
public interface OnPreparedListener {
/**
* 预处理完成后调用，可以在该函数内添加处理逻辑
*
* @param mp 播放器实例
*/
void onPrepared(NELivePlayer mp);
}4.2.1.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| mp | NELivePlayer | 播放器实例 |
4.2.1.4 示例
mLivePlayer.setOnPreparedListener(mPreparedListener);
OnPreparedListener mPreparedListener = new OnPreparedListener() {
public void onPrepared(NELivePlayer mp) {
}
};4.2.2 视频大小变化回调
4.2.2.1 API介绍
视频大小发生变化时的回调，该监听器用于监听当前播放的视频文件的分辨率大小，在视频文件的分辨率发生变化时会触发该回调，用户可以根据分辨率信息来调整UI布局。
4.2.2.2 API原型
/**
* 视频大小发生变化时的监听类
*
* @author netease
*/
public interface OnVideoSizeChangedListener {
/**
* 视频大小发生变化时调用，可以在该函数内添加处理逻辑
*
* @param mp 播放器实例
* @param width 视频宽度
* @param height 视频高度
* @param sar_num 像素宽高比的分子
* @param sar_den 像素宽高比的分母
*/
void onVideoSizeChanged(NELivePlayer mp, int width, int height,
int sar_num, int sar_den);
}4.2.2.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| mp | NELivePlayer | 播放器实例 |
| width | int | 视频宽度 |
| height | int | 视频高度 |
| sar_num | int | 像素宽高比的分子 |
| sar_den | int | 像素宽高比的分母 |
4.2.2.4 示例
mLivePlayer.setOnVideoSizeChangedListener(mSizeChangedListener);
OnVideoSizeChangedListener mSizeChangedListener = new OnVideoSizeChangedListener() {
public void onVideoSizeChanged(NELivePlayer mp, int width, int height, int sarNum, int sarDen) {
if (mVideoWidth == mp.getVideoWidth() && mVideoHeight == mp.getVideoHeight()) {
return;
}
LogUtil.i(TAG, "onVideoSizeChanged: width = " + width + " height = " + height);
};4.2.3 播放完成回调
4.2.3.1 API介绍
在播放完成后调用，该监听器用于监听播放结束的消息，对于点播文件或本地文件，播放结束后会触发该回调。对于直播来说，播放器无法判断直播是否结束，只能通过业务服务器来进行通知。若主播推流结束，播放器可能会读取不到数据超时退出，进入onError回调。
4.2.3.2 API原型
/**
* 播放完成的监听类
*
* @author netease
*/
public interface OnCompletionListener {
/**
* 播放完成后调用，可以在该函数内添加处理逻辑
*
* @param mp 播放器实例
*/
void onCompletion(NELivePlayer mp);
}4.2.3.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| mp | NELivePlayer | 播放器实例 |
4.2.3.4 示例
mLivePlayer.setOnCompletionListener(mCompletionListener);
private OnCompletionListener mCompletionListener = new OnCompletionListener() {
public void onCompletion(NELivePlayer mp) {
}
};4.2.4 错误回调
4.2.4.1 API介绍
该监听器用于监听播放过程中发生的错误消息，发生任何错误，都会触发该回调。在播放发生错误的时候，用户想继续播放，则可以在收到该回调后释放上次播放的资源，重新初始化，播放。
4.2.4.2 API原型
/**
* 播放发生错误时的监听类
*
* @author netease
*/
public interface OnErrorListener {
/**
* 播放发生错误时调用，可以在该函数内添加处理逻辑
*
* @param mp 播放器实例
* @param what 错误类型,参考 NEErrorType 中的错误类型 {@link NEErrorType}
* @param extra 附加信息
*/
boolean onError(NELivePlayer mp, int what, int extra);
}4.2.4.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| mp | NELivePlayer | 播放器实例 |
| what | int | 错误码 |
| extra | int | 扩展错误信息 |
4.2.4.4 示例
mLivePlayer.setOnErrorListener(mErrorListener);
private OnErrorListener mErrorListener = new OnErrorListener() {
public boolean onError(NELivePlayer mp, int what, int extra) {
LogUtil.d(TAG, "Error: " + what + "," + extra);
return true;
}
};4.2.5 状态变化回调
4.2.5.1 API介绍
该监听器用于监听播放器的状态消息，播放过程中状态发生变化时会触发该回调，用户可以根据自己应用层的业务逻辑来做相应的处理。比如收到NELP_BUFFERING_START消息，说明此时网络状况不好，播放处于卡顿状态，此时可以在播放界面上加载一个缓冲中的动画，等收到NELP_BUFFERING_END的消息，说明缓冲结束，可以开始播放了，此时可以把缓冲动画关闭。
4.2.5.2 API原型
/**
* 状态监听类
* 诸如缓存开始、缓存结束、视频第一帧、音频第一帧、拉流时网络状态码(例如302跳转状态)等状态时的回调
*
* @author netease
*/
public interface OnInfoListener {
/**
* 在状态变化时调用，可以在该函数内添加处理逻辑
*
* @param mp 播放器实例
* @param what 状态类型，参考 NEPlayStatusType 中的状态类型 {@link NEPlayStatusType}
* @param extra 附加信息
*/
boolean onInfo(NELivePlayer mp, int what, int extra);
}4.2.5.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| mp | NELivePlayer | 播放器实例 |
| what | int | 状态码 |
| extra | int | 扩展信息 |
4.2.5.4 示例
mLivePlayer.setOnInfoListener(mInfoListener);
private OnInfoListener mInfoListener = new OnInfoListener() {
public boolean onInfo(NELivePlayer mp, int what, int extra) {
return true;
}
};4.2.6 拖动完成回调
4.2.6.1 API介绍
该监听器只适用于点播,用于监听 seek 操作完成的消息，当调用的 seekTo 方法到指定的位置播放，seek成功后会触发该回调。
4.2.6.2 API原型
/**
* seek操作完成时的监听类
*
* @author netease
*/
public interface OnSeekCompleteListener {
/**
* Seek操作完成后调用，可以在该函数内添加处理逻辑
*
* @param mp 播放器实例
*/
void onSeekComplete(NELivePlayer mp);
}4.2.6.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| mp | NELivePlayer | 播放器实例 |
4.2.6.4 示例
mLivePlayer.setOnSeekCompleteListener(mSeekCompleteListener);
private OnSeekCompleteListener mSeekCompleteListener = new OnSeekCompleteListener() {
@Override
public void onSeekComplete(NELivePlayer mp) {
mSeekEndTime = System.currentTimeMillis();
}
};4.2.7 字幕解析的回调
4.2.7.1 API介绍
该监听器在是否显示外挂字幕时调用，需要设置外挂字幕路径后才能有回调。
4.2.7.2 API原型
/**
* 外挂字幕文件解析后的字幕的回调
* @author netease
*/
public interface OnSubtitleListener {
/**
* 回调的字幕信息
* @param isShow 是否展示，true为显示，false为隐藏
* @param id 字幕标号
* @param subtitle 字幕文本
*/
void onSubtitle(boolean isShow,int id,String subtitle);
}4.2.7.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| isShow | boolean | 是否展示 |
| id | int | 字幕标号 |
| subtitle | String | 字幕文本 |
4.2.7.4 示例
private NELivePlayer.OnSubtitleListener mOnSubtitleListener = new NELivePlayer.OnSubtitleListener() {
@Override
public void onSubtitle(boolean isShow, int id, String subtitle) {
LogUtil.i(TAG, "OnSubtitleListener" );
}
};
mLivePlayer.setOnSubtitleListener(mOnSubtitleListener);4.3 播放控制
4.3.1 切换播放地址
4.3.1.1 API介绍
在播放过程中，用户可以直接调用 switchContentUrl(url)来切换播放地址。
4.3.1.2 API原型
/**
* 播放过程中切换播放地址，第一次播放不能调用该接口，仅支持当前播放结束切换到下一个视频，或者播放过程中切换下一个视频
*
* @param url 播放地址
*/
public abstract void switchContentUrl(String url);4.3.1.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| url | String | 播放地址 |
4.3.1.4 示例
String url = "http://xxx.xxx.xxx.xxx/xxx.flv";
mLivePlayer.switchContentUrl(url);4.3.1.5 特殊说明
注意：该接口仅限于播放过程中切换播放地址或播放完成后播放下一个视频，第一次播放时不能调用该接口
4.3.2 切换播放地址，同时可以配置解密信息以及本地缓存设置
4.3.2.1 API介绍
在播放过程中，用户可以直接调用 switchContentUrl(String url, NEDataSourceConfig config) 来切换播放地址， 并同时配置解密信息及本地缓存设置。
该接口从 v2.1.0 版本开始加入。
4.3.2.2 API原型
/**
* 播放过程中切换播放地址，第一次播放不能调用该接口，仅支持当前播放结束切换到下一个视频，或者播放过程中切换下一个视频
* @param url 播放地址
* @param config 播放配置项（配置缓存本地信息和解密信息）
*/
public abstract void switchContentUrl(String url, NEDataSourceConfig config);4.3.2.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| url | String | 播放地址 |
| config | NEDataSourceConfig | 播放配置项（配置缓存本地信息和解密信息） |
4.3.2.4 示例
String url = "http://xxx.xxx.xxx.xxx/xxx.flv";
NEDataSourceConfig dataSourceConfig = new NEDataSourceConfig();
// 配置解密信息
if (decryptionCode == DecryptionConfigCode.CODE_DECRYPTION_INFO) {
dataSourceConfig.decryptionConfig = new NEDecryptionConfig(transferToken, accid, appKey, token);
} else if (decryptionCode == DecryptionConfigCode.CODE_DECRYPTION_KEY) {
dataSourceConfig.decryptionConfig = new NEDecryptionConfig(flvKey, flvKeyLen);
}
// 配置本地缓存
if(enableCache) {
dataSourceConfig.cacheConfig = new NECacheConfig(true, cachePath);
}
// 调用switch接口
mLivePlayer.switchContentUrl(url, dataSourceConfig);4.3.2.5 特殊说明
注意：该接口仅限于播放过程中切换播放地址或播放完成后播放下一个视频，第一次播放时不能调用该接口
4.3.3 解密信息切换播放地址
4.3.3.1 API介绍
在播放过程中，用户可以直接调用 switchContentUrlWithDecryptionToken 来使用解密信息切换加密播放地址。
该接口从 v2.1.0 版本开始被标记为废弃，请使用 switchContentUrl(String url, NEDataSourceConfig config) 接口代替。
4.3.3.2 API原型
/**
* 播放过程中使用解密信息切换加密播放地址，第一次播放不能调用该接口，仅支持当前播放结束切换到下一个视频，或者播放过程中切换下一个视频
* 获取密钥并对密钥做相关的校验,如果校验正确那么自动进行prepareAsync拉流操作，校验结果OnDecryptionListener中进行回调
* 该接口不能与switchContentUrlWithDecryptionKey、switchContentUrl同时使用
*
* @param url 播放地址
* @param transferToken 获取密钥所需的令牌
* @param accid 视频云用户创建的其子用户id
* @param token 视频云用户子用户的token
* @param appKey 开发者平台分配的AppKey
* @param listener 密钥校验结果的回调,校验正确才能继续拉流操作
*/
public abstract void switchContentUrlWithDecryptionToken(String url, String transferToken, String accid, String token, String appKey, OnDecryptionListener listener);4.3.3.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| transferToken | String | 获取密钥所需的令牌 |
| accid | String | 用户创建的其子用户id |
| token | String | 用户子用户的token |
| appKey | String | 开发者平台分配的AppKey |
| listener | OnDecryptionListener | 密钥校验结果的回调 |
4.3.3.4 示例
String url = "http://xxx.xxx.xxx.xxx/xxx.flv";
String transferToken = "xxx";
String accid = "xxx";
String appKey = "xxx";
String token = "xxx";
mLivePlayer.switchContentUrlWithDecryptionToken(url, transferToken, accid, token, appKey, mDecryptionListener);4.3.3.5 特殊说明
注意：该接口仅限于播放过程中切换播放地址或播放完成后播放下一个视频，第一次播放时不能调用该接口
4.3.4 截图
4.3.4.1 API介绍
在软件解码的条件下，SDK 支持截图功能，可以在 VideoView 中调用 getSnapshot(bitmap) 接口来实现截图功能。截图结果以 bitmap 格式返回，开发者可根据自己的需求保存成 jpg 或 png 格式，并保存到指定位置。
4.3.4.2 API原型
/**
* 截图，仅在软件解码条件下支持，硬件解码不支持, 需要在收到onPrepare的通知后调用
*
* @param bitmap 截图结果，以Bitmap格式保存，可以转成jpg格式或png格式
* @return true: 截图成功 false: 截图失败
*/
public abstract boolean getSnapshot(Bitmap bitmap);4.3.4.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| bitmap | Bitmap | 截图结果，以Bitmap格式保存，可以转成jpg格式或png格式 |
4.3.4.4 示例
mLivePlayer.getSnapshot(bitmap)4.3.5 切换音轨
播放器从 v2.0.0 开始支持多音轨切换功能，可以实现视频内嵌多音轨间的无缝切换。
4.3.5.1 相关接口及说明
/**
* 获取当前播放媒体的音轨信息，需要在prepare完成后调用
*
* @return 音轨信息数组或null, 数组大小代表音轨数目
*/
public abstract NEAudioTrackInfo[] getAudioTracksInfo();
/**
* 获取当前选择的音轨序号，需要在prepare完成后调用
*
* @return 当前的音轨序号，或者-1
*/
public abstract int getSelectedAudioTrack();
/**
* 切换音轨，需要在prepare完成后调用。
*
* @param index 需要切换的音轨序号，音轨数量通过 getSelectedAudioTrack 返回的数组大小确定。
* @return 成功返回0，否则表示切换失败。
*/
public abstract int setSelectedAudioTrack(int index);音轨信息类 NEAudioTrackInfo 中可获取的内容
/**
* 获取音轨的编码格式
*/
public String getCodecName();
/**
* 获取音轨的采样率
*/
public int getSampleRate();
/**
* 获取音轨的声道数
*/
public int getChannels();
/**
* 获取音轨的码率
*/
public long getBitrate();
/**
* 获取音轨的语言信息
*/
public String getLanguage();
/**
* 获取音轨的名称
*/
public String getTitle();4.3.5.2 调用示例
// 获取当前播放媒体的音轨信息
mAudioTracksInfo = player.getAudioTracksInfo();
// 获取当前播放的音轨序号
mSelectedAudioTrack = player.getSelectedAudioTrack();
// 设置用户选择的音轨
if (audioTrackToSelect < mAudioTracksInfo.length) {
player.setSelectedAudioTrack(audioTrackToSelect);
}4.3.6 获取播放实时数据
4.3.6.1 API介绍
通过获取播放实时数据接口可以获取实时的播放数据，方便应用层获取到数据进行监控和上报。
4.3.6.2 API原型
/**
* 获取播放实时数据
* 用于应用层监控播放器播放情况
* @return 实时数据结果
*/
public abstract NEMediaRealTimeInfo getMediaRealTimeInfo() ;4.3.6.3 参数说明
NEMediaRealTimeInfo类型说明：
| 参数 | 类型| 说明 |
| :--------|:--------|:--------|
| videoReceiveBitRate | int | 视频下载码率 |
| audioReceiveBitrate | int | 音频下载码率 |
| videoReceiveFrameRate | int | 视频原下载帧率 |
| videoPlayFrameRate | int | 视频播放帧率 |
| videoCacheDuration | long | 视频缓冲区数据时长 |
| audioCacheDuration | long | 音频缓冲区数据时长 |
| videoCacheBytes | long | 视频缓冲区数据大小 |
| audioCacheBytes | long | 音频缓冲区数据大小 |
| avPtsDiff | float | 音视频同步时的时间差 |
4.3.6.4 示例
NEMediaRealTimeInfo statisticsData = mLivePlayer.getMediaRealTimeInfo();4.4 时间戳校对方案
4.4.1 真实时间戳方案
4.4.1.1 API介绍
真实时间戳方案包括查询真实时间戳和监听真实时间戳。
4.4.1.2 API原型
/**
* 获取正在播放的时间戳
*
* @return
*/
public abstract long getCurrentRealTime();
/**
* 设置当前正在播放的时间戳回调
* 支持软件解码和硬件解码时回调，支持纯音频、音视频文件时回调，建议优先使用 setOnCurrentSyncTimestampListener 回调时间戳
*
* @param interval 回调的时间间隔(单位：毫秒 ms)
* @param listener 时间戳回调
* @return
*/
public abstract void setOnCurrentRealTimeListener(long interval, OnCurrentRealTimeListener listener);4.4.1.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| interval | long | 回调的时间间隔(单位：毫秒 ms) |
| listener | OnCurrentRealTimeListener | 时间戳回调 |
4.4.1.4 示例
long realtime = mLivePlayer.getCurrentRealTime();
mLivePlayer.setOnCurrentRealTimeListener(mIntervalTime, mOnCurrentRealTimeListener);
private NELivePlayer.OnCurrentRealTimeListener mOnCurrentRealTimeListener = new NELivePlayer.OnCurrentRealTimeListener() {
@Override
public void onCurrentRealTime(long realTime) {
LogUtil.i(TAG, "OnCurrentRealTimeListener,onCurrentRealTime:" + realTime);
}
};4.4.2 同步时间戳方案
4.4.2.1 API介绍
同步时间戳方案包括开启同步时间戳、同步内容信息回调、查询同步时间戳和监听同步时间戳。
4.4.2.2 API原型
/**
* 设置是否开启同步时间戳、同步内容信息回调
* 如果使用同步时间戳、同步内容信息回调相关功能，需要先打开该开关
* {@link NELivePlayer#setOnCurrentSyncContentListener}
* {@link NELivePlayer#getCurrentSyncTimestamp}
* {@link NELivePlayer#setOnCurrentSyncTimestampListener}
* @return 是否设置成功
*/
public abstract boolean setSyncOpen(boolean isOpen);
/**
* 获取正在播放的时间戳
*
* @return
*/
public abstract long getCurrentSyncTimestamp();
/**
* 设置当前正在播放的时间戳回调
* 支持软件解码时回调，支持音视频文件，支持软件解码和硬件解码时回调，不支持纯音频文件时回调
*
* @param interval 回调的时间间隔(单位：毫秒 ms)
* @param listener 时间戳回调
* @return
*/
public abstract void setOnCurrentSyncTimestampListener(long interval, OnCurrentSyncTimestampListener listener);4.4.2.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| interval | long | 回调的时间间隔(单位：毫秒 ms) |
| listener | OnCurrentSyncTimestampListener | 同步时间戳回调 |
4.4.2.4 示例
private NELivePlayer.OnCurrentSyncTimestampListener mOnCurrentSyncTimestampListener = new NELivePlayer.OnCurrentSyncTimestampListener() {
@Override
public void onCurrentSyncTimestamp(long timestamp) {
LogUtil.i(TAG, "OnCurrentSyncTimestampListener,onCurrentSyncTimestamp:" + timestamp);
}
};
mLivePlayer.setSyncOpen(true);
mLivePlayer.setOnCurrentSyncTimestampListener(mIntervalTime, mOnCurrentSyncTimestampListener);
long synctime = mLivePlayer.getCurrentSyncTimestamp();4.5 拉流地址预调度
为了进一步减少首屏时间，可以通过预调度模块进行拉流地址的预调度，从而减少播放器拉流播放时的等待时间，优化拉流播放时用户体验。
4.5.1 添加预调度拉流链接地址
4.5.1.1 API介绍
添加预调度拉流链接地址，添加后SDK会进行自动预调度处理，预调度结果会进行缓存。
4.5.1.2 API原型
/**
* 添加预调度拉流链接地址
* @param urls 拉流链接地址
*/
public static void addPreloadUrls(ArrayList<String> urls);4.5.1.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| urls | ArrayList |
拉流链接地址 |
4.5.1.4 示例
ArrayList<String> urls = new ArrayList<>();
urls.add("xxx");
NELivePlayer.addPreloadUrls(urls);4.5.2 移除预调度拉流链接地址
4.5.2.1 API介绍
移除预调度拉流链接地址，从预调度结果缓存中删除该拉流地址相关预调度信息。
4.5.2.2 API原型
/**
* 移除预调度拉流链接地址
* @param urls 拉流链接地址
*/
public static void removePreloadUrls(ArrayList<String> urls);4.5.2.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| urls | ArrayList |
拉流链接地址 |
4.5.2.4 示例
ArrayList<String> urls = new ArrayList<>();
urls.add("xxx");
NELivePlayer.removePreloadUrls(urls);4.5.3 查询预调度结果信息
4.5.3.1 API介绍
查询预调度拉流链接地址的结果信息，查询预调度结果缓存中所有的预调度信息。
4.5.3.2 API原型
/**
* 查询预调度拉流链接地址的结果信息
* @return Map<String,Integer> String是链接地址，Integer是状态,状态码参考 {@link NEPreloadUrlsStatus}
*/
public static Map<String,Integer> queryPreloadUrls();4.5.3.3 示例
Map<String, Integer> result = NELivePlayer.queryPreloadUrls();4.6 音视频数据回调
播放器提供音频数据和视频数据回调功能，第三方可以使用该数据进行自定义视频渲染显示和自定义音频播放、混音、混屏等功能。
4.6.1 音频数据回调
4.6.1.1 API介绍
首先设置音频回调数据参数，然后设置音频数据回调监听，在回调中会有音频数据输出。
4.6.1.2 API原型
/**
* 配置PCM回调数据的参数信息，需要在prepare前调用
*
* @param config 配置参数
* @return 非0表示失败
*/
public abstract int setAudioPcmDataConfig(NEAudioPcmConfig config);
/**
* 注册获取音频帧数据的回调，用户需要实现回调函数OnAudioFrameFilterListener来接收音频帧
* 只支持软件解码
* @param listener 回调的结果
* @return < 0 注册失败
*/
public abstract int setOnAudioFrameFilterListener(OnAudioFrameFilterListener listener);
/**
* 音频数据的回调
*/
public interface OnAudioFrameFilterListener {
/**
* 回调的结果
* @param audioRawData 音频数据结构,包含音频数据以及采样率、通道数等参数
*/
void onAudioFrameFilter(NEAudioRawData audioRawData);
}4.6.1.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| config | NEAudioPcmConfig | 音频回调数据的配置参数 |
| audioRawData | NEAudioRawData | 回调的音频数据 |
4.6.1.4 示例
player.setAudioPcmDataConfig(new NEAudioPcmConfig(-1, -1));
player.setOnAudioFrameFilterListener(onAudioFrameFilterListener);
private NELivePlayer.OnAudioFrameFilterListener onAudioFrameFilterListener = new NELivePlayer.OnAudioFrameFilterListener() {
@Override
public void onAudioFrameFilter(final NELivePlayer.NEAudioRawData audioRawData) {
//自定义音频数据操作
}
}4.6.2 视频数据回调
4.6.2.1 API介绍
通过设置视频数据回调监听，在回调中会有视频数据输出。
4.6.2.2 API原型
/**
* 注册获取视频帧数据的回调，用户需要实现回调函数OnVideoFrameFilterListener来接收视频帧
* 只支持软件解码
* @param format 回调的视频数据格式，例如NELP_YUV420
* @param listener 回调的结果
* @return < 0 注册失败
*/
public abstract int setOnVideoFrameFilterListener(int format, OnVideoFrameFilterListener listener);
/**
* 视频数据的回调
*/
public interface OnVideoFrameFilterListener {
/**
* 回调的结果
* @param videoRawData 视频数据结构,包含视频数据以及宽高等参数
*/
void onVideoFrameFilter(NEVideoRawData videoRawData);
}4.6.2.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| format | int | 目前只支持设置NELivePlayer.NELP_YUV420 |
| videoRawData | NEVideoRawData | 回调的视频数据 |
4.6.2.4 示例
player.setOnVideoFrameFilterListener(NELivePlayer.NELP_YUV420, onVideoFrameFilterListener);
private NELivePlayer.OnVideoFrameFilterListener onVideoFrameFilterListener = new NELivePlayer.OnVideoFrameFilterListener() {
@Override
public void onVideoFrameFilter(final NELivePlayer.NEVideoRawData videoRawData) {
//自定义视频数据操作
}
};4.6.3 多视频同步
4.6.3.1 API介绍
实现多个带有SEI时间戳信息的视频流的同步播放。
4.6.3.2 API原型
/**
* 将当前播放器实例的时钟跟目标播放器同步起来。
* 开启该功能需要保证两个流中均存在时间基准一致的同步时间戳信息，
* 当前播放器的播放进度将以同步时间戳信息为基准同步到目标播放器。
*
* 该接口需要在调用prepare接口前调用，否则无效。
* 调用该接口后，将自动开启同步时间戳解析功能。
*
* @param player 需要同步到的播放器实例。
*/
public abstract void syncClockTo(NELivePlayer player);
/**
* 获取是否开启同步时间戳、同步内容信息回调
* 如果使用同步时间戳、同步内容信息回调相关功能，需要先打开该开关
* {@link NELivePlayer#setOnCurrentSyncContentListener}
* {@link NELivePlayer#getCurrentSyncTimestamp}
* {@link NELivePlayer#setOnCurrentSyncTimestampListener}
* @return 是否设置成功
*/
public abstract boolean setSyncOpen(boolean isOpen);4.6.3.3 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| player | NELivePlayer | 需要同步到的主播放器实例 |
4.6.3.4 示例
注意：使用该功能时，需要同时开启主播放器的同步时间戳功能。
playerMaster.setSyncOpen(true);
playerSlave.syncClockTo(playerMaster);5 API文档
有关API的详细说明文档，可参见SDK包中docs，打开index.html查看，或者打开下面的在线文档。