开发指南

服务端 API 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

产品概述

腾讯云视立方 Android 播放器组件是腾讯云开源的一款播放器组件,集质量监控、视频加密、极速高清、清晰度切换、小窗播放等功能于一体,适用于所有点播、直播播放场景。封装了完整功能并提供上层 UI,可帮助您在短时间内,打造一个媲美市面上各种流行视频 App 的播放软件。

若播放器组件满足不了您的业务的个性化需求,且您具有一定的开发经验,可以集成 视立方播放器 SDK,自定义开发播放器界面和播放功能。

准备工作

  1. 为了您体验到更完整全面的播放器功能,建议您开通 云点播 相关服务,未注册用户可注册账号 试用。若您不使用云点播服务,可略过此步骤,但集成后仅可使用播放器基础能力。
  2. 下载 Android Studio,您可以进入 Android Studio 官网 下载安装,如已下载可略过该步骤。

通过本文您可以学会

  1. 如何集成腾讯云视立方 Android 播放器组件
  2. 如何创建和使用播放器

集成准备

步骤1:项目下载

腾讯云视立方 Android 播放器组件的项目地址是 SuperPlayer_Android

您可通过 下载播放器组件 ZIP 包Git 命令下载 的方式下载腾讯云视立方 Android 播放器组件项目工程。

您可以直接下面播放器组件 ZIP 包,单击页面的 Code > Download ZIP 下载。

步骤2:集成指引

本步骤可指导您如何集成播放器,您可选择使用 Gradle 自动加载的方式,手动下载 aar 再将其导入到您当前的工程或导入 jar 和 so 库的方式集成项目。

  1. 下载 SDK + Demo 开发包,项目地址为 Android
  2. Demo/superplayerkit 这个 module 复制到工程中,然后进行下面的配置:
    • 在工程目录下的 setting.gradle 导入 superplayerkit
      include ':superplayerkit'
    • 打开 superplayerkit 工程的 build.gradle 文件修改 compileSdkVersion,buildToolsVersion,minSdkVersion,targetSdkVersion 和 rootProject.ext.liteavSdk 的常量值。

      compileSdkVersion 26
      buildToolsVersion "26.0.2"
      
      defaultConfig {
          targetSdkVersion 23
          minSdkVersion 19
      }
      
      dependencies {
          //如果要集成历史版本,可将 latest.release 修改为对应的版本,例如:8.5.290009
          implementation 'com.tencent.liteav:LiteAVSDK_Player:latest.release'
      }
      请参见上面的步骤,把 common 模块导入到项目,并进行配置。
  3. 通过在 gradle 配置 mavenCentral 库,自动下载更新 LiteAVSDK,打开 app/build.gradle,进行下面的配置:
    1. 在 dependencies 中添加 LiteAVSDK_Player 的依赖。
      dependencies {
           implementation 'com.tencent.liteav:LiteAVSDK_Player:latest.release'
           implementation project(':superplayerkit')
           // 播放器组件弹幕集成的第三方库
           implementation 'com.github.ctiao:DanmakuFlameMaster:0.5.3'
      }
      如果您需要集成历史版本的 LiteAVSDK_Player SDK ,可以在 MavenCentral 查看历史版本,然后通过下面的方式进行集成:
      dependencies {
           // 集成 8.5.10033 版本 LiteAVSDK_Player SDK
           implementation 'com.tencent.liteav:LiteAVSDK_Player:8.5.10033'
      }
    2. app/build.gradle defaultConfig 中,指定 App 使用的 CPU 架构(目前 LiteAVSDK 支持 armeabi 、 armeabi-v7a 和 arm64-v8a,可根据项目需求配置)。
      ndk {
           abiFilters "armeabi", "armeabi-v7a", "arm64-v8a"
      }
      如果之前没有使用过9.4以及更早版本的 SDK 的 下载缓存功能(TXVodDownloadManager 中的相关接口),并且不需要在9.5及后续 SDK 版本播放9.4及之前缓存的下载文件,可以不需要该功能的 so 文件,达到减少安装包的体积,例如:在9.4及之前版本使用了 TXVodDownloadManager 类的 setDownloadPath 和 startDownloadUrl 函数下载了相应的缓存文件,并且应用内存储了 TXVodDownloadManager 回调的 getPlayPath 路径用于后续播放,这时候需要 libijkhlscache-master.so 播放该 getPlayPath 路径文件,否则不需要。可以在 app/build.gradle 中添加:
      packagingOptions {
          exclude "lib/armeabi/libijkhlscache-master.so"
          exclude "lib/armeabi-v7a/libijkhlscache-master.so"
          exclude "lib/arm64-v8a/libijkhlscache-master.so"
      }
    3. 在工程目录的 build.gradle 添加 mavenCentral 库。
      repositories {
           mavenCentral()
      }
  4. 单击 Sync Now 按钮同步 SDK,如果您的网络连接 mavenCentral 没有问题,很快 SDK 就会自动下载集成到工程里。
您已经完成了腾讯云视立方 Android 播放器组件项目集成的步骤。

步骤3:配置 App 权限

在 AndroidManifest.xml 中配置 App 的权限,LiteAVSDK 需要以下权限:

<!--网络权限-->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!--点播播放器悬浮窗权限-->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<!--存储-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

步骤4:设置混淆规则

在 proguard-rules.pro 文件,将 TRTC SDK 相关类加入不混淆名单:

-keep class com.tencent.** { *; }
您已经完成了腾讯云视立方 Android 播放器组件 app 权限配置的步骤。

步骤5:使用播放器功能

本步骤,用于指导用户创建和使用播放器,并使用播放器进行视频播放。

  1. 创建播放器
    播放器主类为 SuperPlayerView,创建后即可播放视频, 支持集成 FileID 或者 URL 进行播放。在布局文件创建 SuperPlayerView:

    <!-- 播放器组件-->
    <com.tencent.liteav.demo.superplayer.SuperPlayerView
        android:id="@+id/superVodPlayerView"
        android:layout_width="match_parent"
        android:layout_height="200dp" />

  2. 配置 License 授权
    若您已获得相关 License 授权,需在 腾讯云视立方控制台 获取 License URL 和 License Key:

    image 若您暂未获得 License 授权,需先参见 视频播放 License 获取相关授权。
    获取到 License 信息后,在调用 SDK 的相关接口前,通过下面的接口初始化 License,建议在 Application 类中进行如下设置:
    public class MApplication extends Application {
    
        @Override
        public void onCreate() {
            super.onCreate();
            String licenceURL = ""; // 获取到的 licence url
            String licenceKey = ""; // 获取到的 licence key
            TXLiveBase.getInstance().setLicence(this, licenceURL, licenceKey);
            TXLiveBase.setListener(new TXLiveBaseListener() {
                @Override
                public void onLicenceLoaded(int result, String reason) {
                    Log.i(TAG, "onLicenceLoaded: result:" + result + ", reason:" + reason);
                }
            });
        }
    }
  3. 播放视频
    本步骤用于指导用户播放视频。腾讯云视立方 Android 播放器组件可用于直播和点播两种播放场景,具体如下:

    • 点播播放:播放器组件支持两种点播播放方式,可以 通过 FileID 播放 腾讯云点播媒体资源,也可以直接使用 [URL 播放] (#url) 地址进行播放。
    • 直播播放:播放器组件可使用 URL 播放 的方式实现直播播放。通过传入 URL 地址,即可拉取直播音视频流进行直播播放。腾讯云直播URL生成方式可参见 自主拼装直播 URL

      URL 可以是点播文件播放地址,也可以是直播拉流地址,传入相应 URL 即可播放相应视频文件。

      SuperPlayerModel model = new SuperPlayerModel();
      model.appId = 1400329073; // 配置 AppId
      model.url = "http://your_video_url.mp4";   // 配置您的播放视频 url
      mSuperPlayerView.playWithModelNeedLicence(model);

  4. 退出播放
    当不需要播放器时,调用 resetPlayer 清理播放器内部状态,释放内存。

    mSuperPlayerView.resetPlayer();

至此,您已经完成了腾讯云视立方 Android 播放器组件创建、播放视频和退出播放的能力即成。

功能使用

本章将为您介绍几种常见的播放器功能使用方式,更为完整的功能使用方式可参见 Demo 体验,播放器组件支持的功能可参见 能力清单

1、全屏播放

播放器组件支持全屏播放,在全屏播放场景内,同时支持锁屏、手势控制音量和亮度、弹幕、截屏、清晰度切换等功能设置。功能效果可在 腾讯云视立方 App > 播放器 > 播放器组件 中体验,单击界面右下角即可进入全屏播放界面。

在窗口播放模式下,可通过调用下述接口进入全屏播放模式:

mControllerCallback.onSwitchPlayMode(SuperPlayerDef.PlayerMode.FULLSCREEN);

全屏播放界面功能介绍

单击 返回,即可返回至窗口播放模式。

//单击后触发下面的接口
mControllerCallback.onBackPressed(SuperPlayerDef.PlayerMode.FULLSCREEN);
onSwitchPlayMode(SuperPlayerDef.PlayerMode.WINDOW);

2、悬浮窗播放

播放器组件支持悬浮窗小窗口播放,可在切换到其它应用时,不打断视频播放功能。功能效果可在 腾讯云视立方 App > 播放器 > 播放器组件 中体验,单击界面左上角返回,即可体验悬浮窗播放功能。

悬浮窗播放依赖于 AndroidManifest 中的以下权限:

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
// 切换悬浮窗触发的代码接口
mSuperPlayerView.switchPlayMode(SuperPlayerDef.PlayerMode.FLOAT);
//单击浮窗返回窗口触发的代码接口
mControllerCallback.onSwitchPlayMode(SuperPlayerDef.PlayerMode.WINDOW);

3、视频封面

播放器组件支持用户自定义视频封面,用于在视频接收到首帧画面播放回调前展示。功能效果可在 腾讯云视立方 App > 播放器 > 播放器组件 > 自定义封面演示 视频中体验。

  • 当播放器组件设置为自动播放模式 PLAY_ACTION_AUTO_PLAY 时,视频自动播放,此时将在视频首帧加载出来之前展示封面;
  • 当播放器组件设置为手动播放模式 PLAY_ACTION_MANUAL_PLAY 时,需用户单击播放后视频才开始播放。在单击播放前将展示封面;在单击播放后到视频首帧加载出来前也将展示封面。

视频封面支持使用网络 URL 地址或本地 File 地址,使用方式可参见下述指引。若您通过 FileID 的方式播放视频,则可直接在云点播内配置视频封面。

SuperPlayerModel model = new SuperPlayerModel();
model.appId = "您的 appid";
model.videoId = new SuperPlayerVideoId();
model.videoId.fileId = "您的 fileId"; 
//播放模式,可设置自动播放模式:PLAY_ACTION_AUTO_PLAY,手动播放模式:PLAY_ACTION_MANUAL_PLAY
model.playAction = PLAY_ACTION_MANUAL_PLAY;
//设定封面的地址为网络 url 地址,如果 coverPictureUrl 不设定,那么就会自动使用云点播控制台设置的封面
model.coverPictureUrl = "http://1500005830.vod2.myqcloud.com/6c9a5118vodcq1500005830/cc1e28208602268011087336518/MXUW1a5I9TsA.png" 
mSuperPlayerView.playWithModelNeedLicence(model);

4、视频列表轮播

播放器组件支持视频列表轮播,即在给定一个视频列表后:

  • 支持按顺序循环播放列表中的视频,播放过程中支持自动播放下一集也支持手动切换到下一个视频。
  • 列表中最后一个视频播放完成后将自动开始播放列表中的第一个视频。

功能效果可在 腾讯云视立方 App> 播放器 > 播放器组件 > 视频列表轮播演示视频中体验。

//步骤1:构建轮播的 List<SuperPlayerModel>
ArrayList<SuperPlayerModel> list = new ArrayList<>();
SuperPlayerModel model = new VideoModel();
model = new SuperPlayerModel();
model.videoId = new SuperPlayerVideoId();
model.appid = 1252463788;
model.videoId.fileId = "4564972819219071568";
list.add(model);

model = new SuperPlayerModel();
model.videoId = new SuperPlayerVideoId();
model.appid = 1252463788;
model.videoId.fileId = "4564972819219071679";
list.add(model);
//步骤2:调用轮播接口
mSuperPlayerView.playWithModelListNeedLicence(list, true, 0);

public void playWithModelListNeedLicence(List<SuperPlayerModel> models, boolean isLoopPlayList, int index);

接口参数说明

参数名 类型 描述
models List 轮播数据列表
isLoopPlayList boolean 是否循环
index int 开始播放的 SuperPlayerModel 索引

5、视频试看

播放器组件支持视频试看功能,可以适用于非 VIP 试看等场景,开发者可以传入不同的参数来控制视频试看时长、提示信息、试看结束界面等。功能效果可在 腾讯云视立方 App> 播放器 > 播放器组件 > 试看功能演示 视频中体验。

shikan1.png

shikan2.png

 方法一:
 //步骤1:创建视频 mode
 SuperPlayerModel mode = new SuperPlayerModel();
 //...添加视频源信息
 //步骤2:创建试看信息 mode
 VipWatchModel vipWatchModel = new VipWatchModel("可试看%ss,开通 VIP 观看完整视频",15);
 mode.vipWatchMode = vipWatchModel;
 //步骤3:调用播放视频方法
 mSuperPlayerView.playWithModelNeedLicence(mode);

 方法二:
 //步骤1:创建试看信息 mode
 VipWatchModel vipWatchModel = new VipWatchModel("可试看%ss,开通 VIP 观看完整视频",15);
  //步骤2:调用设置试看功能方法
 mSuperPlayerView.setVipWatchModel(vipWatchModel);

public VipWatchModel(String tipStr, long canWatchTime)

VipWatchModel 接口参数说明:

参数名 类型 描述
tipStr String 试看提示信息
canWatchTime Long 试看时长,单位为妙

6、动态水印

播放器组件支持在播放界面添加不规则跑动的文字水印,有效防盗录。全屏播放模式和窗口播放模式均可展示水印,开发者可修改水印文本、文字大小、颜色。功能效果可在 腾讯云视立方 App > 播放器 > 播放器组件 > 动态水印 演示视频中体验。

shuiyin.png

 方法一:
 //步骤1:创建视频 mode
 SuperPlayerModel mode = new SuperPlayerModel();
 //...添加视频源信息
 //步骤2:创建水印信息 mode
 DynamicWaterConfig dynamicWaterConfig = new DynamicWaterConfig("shipinyun", 30, Color.parseColor("#80FFFFFF"));
 mode.dynamicWaterConfig = dynamicWaterConfig;
 //步骤3:调用播放视频方法
 mSuperPlayerView.playWithModelNeedLicence(mode);

 方法二:
 //步骤1:创建水印信息 mode
 DynamicWaterConfig dynamicWaterConfig = new DynamicWaterConfig("shipinyun", 30, Color.parseColor("#80FFFFFF"));
  //步骤2:调用设置动态水印功能方法
 mSuperPlayerView.setDynamicWatermarkConfig(dynamicWaterConfig);

public DynamicWaterConfig(String dynamicWatermarkTip, int tipTextSize, int tipTextColor)

接口参数说明

参数名 类型 描述
dynamicWatermarkTip String 水印文本信息
tipTextSize int 文字大小
tipTextColor int 文字颜色

7、视频下载

支持用户在有网络的条件下缓存视频,随后在无网络的环境下观看;同时离线缓存的视频仅可在客户端内观看,不可被下载至本地,可有效防止下载视频的非法传播,保护视频安全。
你可在 腾讯云视立方 App > 播放器 > 播放器组件 > 离线缓存(全屏)演示视频中,使用全屏观看模式后体验。

DownloadMenuListView( 缓存选择列表视图),用于选择下载对应清晰度的视频。左上角选择清晰度后,再点击要下载的视频选项,出现对勾后,代表开始了下载。点击下方的 video download list 按钮后会跳转到 VideoDownloadListView 所在的 Activity。

// 步骤1:初始化下载数据 参数见下方列表
DownloadMenuListView mDownloadMenuView = findViewById(R.id.superplayer_cml_cache_menu);
mDownloadMenuView.initDownloadData(superPlayerModelList, mVideoQualityList, mDefaultVideoQuality, "default");

// 步骤2:设置正在播放的视频选项
mDownloadMenuView.setCurrentPlayVideo(mSuperplayerModel);

// 步骤3:设置 video download list 按钮的点击事件
mDownloadMenuView.setOnCacheListClick(new OnClickListener() {
     @Override
     public void onClick(View v) {
       // 跳转到 VideoDownloadListView 所在的 Activity
       startActivity(DownloadMeduListActivity.this,VideoDownloadListActivity.class);
     }
});

// 步骤4:通过动画展示 view
mDownloadMenuView.show();

public void initDownloadData(List<SuperPlayerModel> superPlayerModelList,
                             List<VideoQuality> qualityList,
                             VideoQuality currentQuality,
                             String userName)

接口参数说明

参数名 类型 描述
superPlayerModelList List 下载的视频数据
qualityList List 视频清晰度数据
currentQuality VideoQuality 当前的视频清晰度
userName String 用户名

VideoDownloadListView(视频下载列表),显示所有正在下载的和下载完成视频的列表 View。点击时,如果正在下载,会暂停下载;如果暂时下载,会继续下载;如果下载完成,会跳转播放。

// 步骤1:绑定控件
VideoDownloadListView mVideoDownloadListView = findViewById(R.id.video_download_list_view);

//步骤2: 添加数据  
mVideoDownloadListView.addCacheVideo(mDataList, true);

接口参数说明

public void addCacheVideo(List<TXVodDownloadMediaInfo> mediaInfoList, boolean isNeedClean)

参数名 类型 描述
mediaInfoList List 添加的视频数据类型
isNeedClean boolean 是否清除之前的数据

8、雪碧图和打点信息

打点信息

支持在进度条关键位置添加文字介绍,用户点击后可显示打点位置的文字信息,以快速了解当前位置的视频信息。点击视频信息后,可以 seek 到打点信息位置。

您可在腾讯云视立方 App > 播放器 > 播放器组件 > 腾讯云 视频中,使用全屏观看模式后体验。

雪碧图

支持用户在拖拽进度条或执行快进操作时查看视频缩略图,以快速了解指定进度的视频内容。缩略图预览基于视频雪碧图实现,您可以在云点播控制台中生成视频文件雪碧图,或直接生成雪碧图文件。
您可在腾讯云视立方 App > 播放器 > 播放器组件 > 腾讯云 视频中,使用全屏观看模式后体验。

// 步骤1:播放视频 superplayerModel的url 变量需要为空,且 videoId 不为空,这样才会通过 PlayWithField 播放,才能在 onPlayEvent 回调中获取到打点信息和雪碧图数据
mSuperplayerView.play(superplayerModel);

// 步骤2: PlayWithFileId 播放时候 在 VOD_PLAY_EVT_GET_PLAYINFO_SUCC 回调事件中取得打点信息和雪碧图信息
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
    switch (event) {
        case TXVodConstants.VOD_PLAY_EVT_GET_PLAYINFO_SUCC:

            // 获取 雪碧图 图片链接 URL
            playImageSpriteInfo.imageUrls = param.getStringArrayList(TXVodConstants.EVT_IMAGESPRIT_IMAGEURL_LIST);
            // 获取 雪碧图 web vtt 描述文件下载 URL
            playImageSpriteInfo.webVttUrl = param.getString(TXVodConstants.EVT_IMAGESPRIT_WEBVTTURL);
            // 获取 打点信息    
           ArrayList<String> keyFrameContentList =
                    param.getStringArrayList(TXVodConstants.EVT_KEY_FRAME_CONTENT_LIST);
            // 获取 打点信息时间信息
            float[] keyFrameTimeArray = param.getFloatArray(TXVodConstants.EVT_KEY_FRAME_TIME_LIST);

            // 构建 打点信息数据列表
            if (keyFrameContentList != null && keyFrameTimeArray != null
                    && keyFrameContentList.size() == keyFrameTimeArray.length) {
                for (int i = 0; i < keyFrameContentList.size(); i++) {
                    PlayKeyFrameDescInfo frameDescInfo = new PlayKeyFrameDescInfo();
                    frameDescInfo.content = keyFrameContentList.get(i);
                    frameDescInfo.time = keyFrameTimeArray[i];
                    mKeyFrameDescInfoList.add(frameDescInfo);
                }
            }
            break;
        default:
            break;
  }
}

// 步骤3: 将拿到的打点信息和雪碧图信息通过 updateVideoImageSpriteAndKeyFrame 方法赋值给对应的 view。 
// 雪碧图的 view 对应 VideoProgressLayout 组件中 mIvThumbnail。
// 打点信息的 view 对应 PointSeekBar 组件中的 TCPointView。
updateVideoImageSpriteAndKeyFrame(playImageSpriteInfo,keyFrameDescInfoList);

Demo 体验

更多完整功能可直接运行工程 Demo,或扫码下载移动端 Demo 腾讯云视立方 App 体验。

运行工程 Demo

  1. 在 Android Studio 的导航栏选择 File > Open,在弹框中选择 Demo 工程目录: $SuperPlayer_Android/Demo,待成功导入 Demo 工程后,单击 Run app,即可成功运行 Demo 。
  2. 成功运行 Demo 后如下图,进入播放器 > 播放器组件,可体验播放器功能。

腾讯云视立方 App

腾讯云视立方 App > 播放器 中可体验更多播放器组件功能。

目录