本文介绍Android端播放器SDK进阶功能使用示例,完整功能说明请参见API接口说明。
播放
短视频列表播放
针对典型的短视频列表播放场景,Android端播放器SDK提供了完善的列表播放功能,结合预加载等机制大幅改善短视频的起播速度。长视频场景不建议使用该功能。
播放带透明度视频
功能简介
阿里云播放器SDK支持渲染Alpha通道,实现播放透明礼物的动态效果。在直播间等场景中,播放透明礼物动效且不会遮挡直播间内容,明显提升用户观看和互动体验。
使用限制
一体化SDK6.8.0及以后版本或播放器SDK6.9.0及以后版本支持透明渲染能力。
功能优势
使用带有透明度信息的MP4视频作为礼物特效可以提供更好的动效质量,较小的文件体积,更高的兼容性和更高的开发效率。这使得礼物特效能够更好地展示给用户,提升用户体验。
更好的动效质量:MP4视频可以保留原始的动效质量,包括细节和颜色等,相比于其他格式,如 APN 或IXD,MP4可以更准确地还原设计师创作的动效效果。
较小的文件体积:MP4视频文件相比于其他格式,如APNG或IXD,可以更有效地压缩文件体积,提升加载速度并降低网络带宽消耗。
更高的兼容性:MP4视频是一种通用的视频格式,在各种设备和浏览器中都得到广泛支持,支持在主流设备上播放和观看礼物特效。
更高的开发效率:使用MP4视频作为礼物特效的技术方案相对简单,不需要开发人员去研究和实现复杂的解析和渲染逻辑,开发人员可以专注于其他功能的实现,提高开发效率。
外挂字幕
Android端播放器SDK支持添加和切换外挂字幕,现已支持SRT、SSA、ASS、VTT这4种格式的字幕。示例如下:
创建显示字幕的View。
根据不同的字幕格式创建不同的View。
//用于显示SRT和VTT字幕 SubtitleView subtitleView = new SubtitleView(getContext()); //用于显示ASS和SSA字幕 AssSubtitleView assSubtitleView = new AssSubtitleView(getContext()); //将字幕View添加到布局视图中 viewGroup.addView(assSubtitleView);
设置字幕相关监听。
添加字幕。
mAliPlayer.addExtSubtitle(url);
切换字幕。
//trackIndex:传入字幕索引;true:表示显示传入的字幕;false:表示隐藏传入的字幕 mAliPlayer.selectExtSubtitle(trackIndex, true);
纯音频播放
通过禁用视频播放,达到纯音频播放的效果。在prepare之前配置PlayerConfig。
PlayerConfig config = mAliPlayer.getConfig();
config.mDisableVideo = true; //设置开启纯音频播放
mAliPlayer.setConfig(config);
软硬解切换
解码方式需要在播放前切换,播放中切换解码方式将不会生效。
Android端播放器SDK提供了H.264、H.265的硬解码能力,同时提供了enableHardwareDecoder
提供开关。默认开,并且在硬解初始化失败时,自动切换为软解,保证视频的正常播放。示例如下:
//开启硬解。默认开启
mAliyunVodPlayer.enableHardwareDecoder(true);
如果从硬解自动切换为软解,将会通过onInfo
回调,示例如下:
mApsaraPlayerActivity.setOnInfoListener(new IPlayer.OnInfoListener() {
@Override
public void onInfo(InfoBean infoBean) {
if (infoBean.getCode() == InfoCode.SwitchToSoftwareVideoDecoder) {
//切换到软解
}
}
});
网络自适应切换视频清晰度
HLS的多码率自适应视频流可以在视频点播中经过视频打包转码模板组进行转码处理后生成,详细操作请参见点播多码率自适应配置。
经过视频点播转码生成的自适应流,如果使用Vid方式播放,则需要指定默认播放清晰度列表为
DEFINITION_AUTO
,才会获取并播放自适应的视频流;否则将按照默认逻辑选择低清晰度的视频流进行播放,默认清晰播放顺序请参见清晰度相关问题。以VidAuth播放方式为例,指定清晰度列表的示例如下:VidAuth vidAuth = new VidAuth(); List<Definition> list = new ArrayList<>(); list.add(Definition.DEFINITION_AUTO); vidAuth.setDefinition(list);
Android端播放器SDK支持多码率自适应HLS、DASH视频流。在prepare
成功之后,通过getMediaInfo
可以获取到各个码流的信息,即TrackInfo
。示例如下:
List<TrackInfo> trackInfos = aliyunVodPlayer.getMediaInfo().getTrackInfos();
在播放过程中,可以通过调用播放器的selectTrack
方法切换播放的码流,取值为AUTO_SELECT_INDEX时,为多码率自适应。示例如下:
int index = trackInfo.getIndex();
//多码率切换
aliyunVodPlayer.selectTrack(index);
//多码率切换并自适应
aliyunVodPlayer.selectTrack(TrackInfo.AUTO_SELECT_INDEX);
切换的结果会在OnTrackChangedListener
监听之后会回调(在调用selectTrack
之前设置)。示例如下:
aliyunVodPlayer.setOnTrackChangedListener(new IPlayer.OnTrackChangedListener() {
@Override
public void onChangedSuccess(TrackInfo trackInfo) {
//切换成功
}
@Override
public void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo) {
//切换失败。失败原因通过errorInfo.getMsg()获取
}
});
截图
Android端播放器SDK提供了对当前视频截图的功能,由snapshot
接口实现。截取的是原始的数据,并转为bitmap
返回。回调接口为OnSnapShotListener
。示例如下:
//设置截图回调
aliyunVodPlayer.setOnSnapShotListener(new OnSnapShotListener(){
@Override
public void onSnapShot(Bitmap bm, int with, int height){
//获取到的bitmap以及图片的宽高。
}
});
//截取当前播放的画面
aliyunVodPlayer.snapshot();
试看
Android端播放器SDK通过配合点播服务配置,可以实现试看功能,支持VidSts和VidAuth(视频点播推荐使用此方式)两种播放方式。如何配置和使用试看功能,请参见试看视频。
配置试看功能之后,通过VidPlayerConfigGen.setPreviewTime()
方法设置播放器的试看时长。以VidSts播放方式为例,示例如下:
VidSts vidSts = new VidSts;
....
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
configGen.setPreviewTime(20);//20秒试看
vidSts.setPlayConfig(configGen);//设置给播放源
...
当设置试看的时长,通过Android端播放器SDK播放视频时,服务端将不会返回完整的视频内容,而是返回试看时间段的内容。
VidPlayerConfigGen支持设置服务端支持的请求参数。请参见请求参数说明。
FLV和MP3格式视频暂时不支持试看。
设置黑名单
Android端播放器SDK提供了硬解的黑名单机制。对于明确不能使用硬解播放的机器,可以直接使用软解,避免了无效的操作。示例如下:
DeviceInfo deviceInfo = new DeviceInfo();
deviceInfo.model="Lenovo K320t";
AliPlayerFactory.addBlackDevice(BlackType.HW_Decode_H264 ,deviceInfo );
退出App之后,黑名单自动失效。
设置Referer
Android端播放器SDK支持设置Referer,配合控制台的黑白名单Referer,可以控制访问权限,由PlayerConfig
方法设置请求Referer。播放器SDK的设置示例如下:
//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//设置referer,示例:http://example.aliyundoc.com。(注意:设置referer时,需要加上前面的协议部分。)
config.mReferrer = referrer;
....//其他设置
//设置配置给播放器
mAliyunVodPlayer.setConfig(config);
设置UserAgent
Android端播放器SDK提供了PlayerConfig
用来设置请求UA。设置之后,播放器请求的过程中将会带上UA信息。示例如下:
//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//设置UA
config.mUserAgent = "需要设置的UserAgent";
....//其他设置
//设置配置给播放器
mAliyunVodPlayer.setConfig(config);
配置网络重试时间和次数
支持设置Android端播放器SDK的网络超时的时间和重试次数,由PlayerConfig
方法实现。示例如下:
//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//设置网络超时时间,单位:毫秒
config.mNetworkTimeout = 5000;
//设置超时重试次数。每次重试间隔为networkTimeout。networkRetryCount=0则表示不重试,重试策略app决定,默认值为2
config.mNetworkRetryCount=2;
....//其他设置
//设置配置给播放器
mAliyunVodPlayer.setConfig(config);
如果设置了NetworkRetryCount,若此时发生网络问题,导致出现loading后,那么将会重试NetworkRetryCount次,每次的间隔时间为mNetworkTimeout。
如果重试多次之后,还是loading的状态,那么就会回调
onError
事件,此时,ErrorInfo.getCode()=ErrorCode.ERROR_LOADING_TIMEOUT。如果NetworkRetryCount设置为0,当网络重试超时的时候,播放器就会回调
onInfo
事件,事件的InfoBean.getCode()=InfoCode.NetworkRetry。 此时,可以调用播放器的reload
方法进行重新加载网络,或者进行其他的处理。
配置缓存和延迟控制
Android端播放器SDK通过PlayerConfig
提供了设置缓存和延迟的控制接口。示例如下:
三个缓冲区时长的大小关系必须为:mStartBufferDuration ≤ mHighBufferDuration ≤ mMaxBufferDuration。
当最大缓冲区时长(mMaxBufferDuration)大于5分钟时,为防止因为缓冲区过大导致的内存异常,系统将默认按5分钟生效。当mMaxBufferDuration设置超过50000 ms(即50s)时,可以启用大缓存,来降低内存占用,进一步提高播放性能,如有需要,请参见大缓存。
设置HTTP Header
通过PlayerConfig
方法,可以给播放器中的请求加上HTTP的header参数。示例如下:
RTS降级播放
在使用超低延时直播RTS地址播放的场景下,通过设置RTS的降级地址(如HLS地址或FLV地址),当RTS拉流失败时,会自动降级到该地址播放。示例如下:
PlayerConfig config = player.getConfig();
//可选,配置config其他项
UrlSource urlSource = new UrlSource();
urlSource.setUri(downgradeUrl);
//设置降级URL
player.enableDowngrade(urlSource, config);
设置视频背景色
Android播放器SDK支持设置播放器渲染的背景色。接口和用法说明如下:
接口示例
/**
@brief 设置视频的背景色
@param color the color
*/
/****
@brief Set video background color
@param color the color
*/
-(void) setVideoBackgroundColor:(UIColor *)color;
用法说明
//参数为8位16进制数据,8位数据两两为一组,按照顺序分别表示R(red) G(green) B(blue) A(alpha 透明度)
//例如0x00ff00ff,表示绿色
[aliPlayer setVideoBackgroundColor:0x00ff00ff]
vidAuth设置指定播放域名
通过vidAuth方式可以指定vid对应的域名等字段,支持的字段详情请参见GetPlayInfo请求参数。接口及用法说明如下:
接口示例
/**
* 设置播放参数
*
* @param playConfig 播放参数
*/
public void setPlayConfig(VidPlayerConfigGen playConfig);
用法说明
通过其中的VidPlayerConfigGen接口的addPlayerConfig添加playDomain字段。
vidAuth = new VidAuth();
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
//增加playDomain字段,可以添加的字段参考
//https://help.aliyun.com/zh/vod/developer-reference/api-vod-2017-03-21-getplayinfo?spm=a2c4g.11186623.0.0.2bec2e44eqeDgx#api-detail-35
configGen.addPlayerConfig("playDomain", "com.xxx.xxx");
vidAuth.setPlayConfig(configGen);
性能
本地缓存
Android端播放器SDK提供了本地缓存的功能,能够让用户重复播放视频时,提高起播速度、提高seek速度、减少卡顿,也能达到节省流量的目的。
开启本地缓存
本地缓存功能默认关闭,如需使用,需要手动开启。通过AliPlayerGlobalSettings
中的enableLocalCache
控制。示例如下:
如果视频播放URL带有鉴权参数,本地缓存和播放时鉴权参数会变化,可以将URL的鉴权参数去掉后再计算md5值。例如:带有鉴权参数的视频播放URL为
http://****.mp4?aaa
,则加载时使用http://****.mp4
计算md5值。如果服务器同时支持HTTP和HTTPS协议,但是不同的协议指向的媒体文件是同一个,则可以将请求头去掉或者统一后再计算md5值。例如:
视频播放URL为
https://****.mp4
和http://****.mp4
,则加载时使用****.mp4
计算md5值。视频播放URL为
https://****.mp4
,加载时统一为http://****.mp4
后再计算md5值。
针对5.5.4.0及以后版本的播放器SDK,如果视频播放URL带有鉴权参数且播放协议为HLS,可以通过设置
PlayerConfig.mEnableStrictAuthMode
字段,进行不同鉴权模式的选择(默认值为false):非严格鉴权(false):鉴权也缓存,若上一次只缓存了部分媒体,下次播放至非缓存部分时,播放器会用缓存的鉴权发起请求,如果URL鉴权设置的有效期很短,会导致播放异常。
严格鉴权(true):鉴权不缓存,每次起播都进行鉴权,无网络下会导致起播失败。
开启或关闭单个URL的本地缓存
如果想要针对单个URL开启或关闭本地缓存功能,可以在player config
中设置。
//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//是否针对播放的URL开启本地缓存,默认值为true。当AliPlayerGlobalSettings处的本地缓开启时,且同时开启此处的本地缓存,即设置为true,该URL的本地缓存才会生效;若此处设置为false,则关闭该URL的本地缓存。
config.mEnableLocalCache = false;
....//其他设置
//设置配置给播放器
mAliyunVodPlayer.setConfig(config);
大缓存
通过设置数据的最大缓冲区时长可以在播放视频时通过缓存视频数据到内存中,从而提高播放性能和观看体验。当最大缓冲区时长设置过大时,会造成缓冲区对内存的消耗。通过启用大缓存,可以将视频数据缓存到文件中,从而降低内存的占用,进一步提高播放器性能。
当mMaxBufferDuration设置超过50000 ms时,通过开启本地缓存触发大缓存功能自动启用。操作流程如下:
开启全局本地缓存。
本地缓存功能默认关闭,如需使用,需要手动开启。通过
AliPlayerGlobalSettings
中的enableLocalCache
控制。代码示例请参见本地缓存中的开启本地缓存。开启URL的本地缓存。
代码示例请参见本地缓存中的开启或关闭单个URL的本地缓存。
预加载
Android端播放器SDK提供预加载功能,是对本地缓存功能的升级,通过设置视频缓存的内存占用大小,更能提升视频的起播速度。
预加载功能的使用限制如下:
目前支持MP4、MP3、FLV、HLS(单码率视频流)等单个媒体文件的加载。
仅支持UrlSource播放方式播放视频的预加载,暂不支持VidAuth、VidSts方式播放视频的预加载。
Android端播放器SDK默认提供预加载时网络资源自动调度能力,以减少预加载的网络请求对正在播放视频的网络请求的影响。自动调度的策略是:仅当正在播放的视频缓冲到达一定阈值后,才会允许预加载进行请求。若您需要自行控制预加载的实时请求,可以通过以下方法将此策略关闭:
AliPlayerGlobalSettings.enableNetworkBalance(false);
开启本地缓存功能,详细操作请参见本地缓存。
获取AliMediaLoader实例。
AliMediaLoader实例为单例,即无论获取多少次,创建的都是同一个实例。
MediaLoader mediaLoader = MediaLoader.getInstance();
配置AliMediaLoader。
配置回调,并开始加载。
可选:删除加载文件。
可按需删除加载文件,以节省空间。Android端播放器SDK不提供删除接口,需要在App删除加载目录下的文件。
动态预加载
动态预加载策略,支持集成方既可以控制当前正在播放视频的缓存,又可以控制预加载的个数和缓存,满足业务方对播放体验与成本开销之间取得平衡的诉求。
获取下载速度
获取当前播放视频的下载速度,在onInfo回调中获取,由getExtraValue
接口实现。
网络特性
HTTPDNS
HTTPDNS是通过DNS解析技术将域名解析请求发送到特定的HTTPDNS服务器,以获取更快、更稳定的域名解析结果,降低DNS劫持风险。
阿里云播放器SDK提供以下2种类型的HTTPDNS功能,您可以按需选用:
类型 | 描述 |
标准型HTTPDNS | 能够为各种域名提供HTTPDNS服务。 |
增强型HTTPDNS | 专为阿里云CDN域名提供HTTPDNS服务,支持阿里云CDN网络精准调度、实时解析生效,有效提高网络性能。 说明 如需使用增强型HTTPDNS,请先提交Android和iOS播放器SDK增值服务申请表单或联系阿里云商务经理申请开通。 |
标准型HTTPDNS使用示例
//打开标准型httpdns
AliPlayerGlobalSettings.enableHttpDns(true);
//可选,增加httpdns预解析域名
DomainProcessor.getInstance().addPreResolveDomain("player.***cdn.com");
增强型HTTPDNS使用示例
增强型HTTPDNS仅为阿里云CDN域名提供HTTPDNS服务,请确保您配置的域名为阿里云CDN域名且已完成域名配置可正常使用。视频点播中添加和配置CDN域名请参见添加加速域名。更多有关CDN域名的信息请参见阿里云CDN。
//打开增强型httpdns
AliPlayerGlobalSettings.enableEnhancedHttpDns(true);
//必选,添加增强型httpdns域名,请确保该域名为阿里云CDN域名并完成域名配置可以正常可提供线上服务。
DomainProcessor.getInstance().addEnhancedHttpDnsDomain("player.***alicdn.com");
//可选,增加httpdns预解析域名
DomainProcessor.getInstance().addPreResolveDomain("player.***alicdn.com");
配置HTTPDNS优先级
该功能适用于标准型HTTPDNS和增强型HTTPDNS,可以设置HTTPDNS和Local DNS的优先级。
// AliPlayerGlobalSettings.SET_DNS_PRIORITY_LOCAL_FIRST表示设置httpdns的优先级
// true表示local dns优先,false 表示httpdns优先,默认为httpdns优先
AliPlayerGlobalSettings.setOption(AliPlayerGlobalSettings.SET_DNS_PRIORITY_LOCAL_FIRST, false);
HTTP/2
Android端播放器SDK自5.5.0.0版本开始默认开启使用HTTP/2。
Android端播放器SDK支持使用HTTP/2协议,该协议通过多路复用,避免队头阻塞,以改善播放性能。示例如下:
AliPlayerGlobalSettings.setUseHttp2(true);
视频下载
Android端播放器SDK提供了点播服务视频的下载功能,允许用户通过阿里云播放器将视频缓存至本地观看。同时,提供了普通下载和安全下载两种下载方式。
普通下载
下载后的视频数据未经过阿里云加密,用户可以用第三方播放器播放。
安全下载
下载后的视频数据经过阿里云加密。第三方播放器无法播放。仅支持使用阿里云的播放器进行播放。
使用说明
仅VidSts和VidAuth方式支持视频下载功能。
使用播放器的视频下载功能,需要在点播控制台开启并配置下载模式,详细操作请参见下载设置。
视频下载支持断点续传。
操作步骤
可选:配置安全下载的加密校验文件。仅安全下载需要配置,普通下载无需配置。
说明请确保配置的加密校验文件与App信息一致,否则会导致视频下载失败。
如果设置为安全下载方式,则需要将在点播控制台生成的密钥文件配置到播放器SDK中,用于视频下载和播放的解密验证,密钥文件的生成请参见安全下载。
建议在Application中配置一次即可,示例如下:
PrivateService.initService(getApplicationContext(), "encryptedApp.dat所在的文件路径"); //建议将encryptedApp.dat加密校验文件存放到手机中后,此处设置加密校验文件的手机本地文件路径
创建并设置下载器。
创建下载器,通过AliDownloaderFactory创建。示例如下:
AliMediaDownloader mAliDownloader = null; ...... //创建下载器 mAliDownloader = AliDownloaderFactory.create(getApplicationContext()); //配置下载保存的路径 mAliDownloader.setSaveDir("保存的文件夹地址");
设置监听事件。
下载器提供了多个事件监听。示例如下:
准备下载源。
通过
prepare
方法准备下载源。下载源支持VidSts和VidAuth两种方式。示例如下:VidSts
//创建VidSts VidSts aliyunVidSts = new VidSts(); aliyunVidSts.setVid("Vid信息");//视频ID(VideoId) aliyunVidSts.setAccessKeyId("<yourAccessKeyId>");//鉴权ID aliyunVidSts.setAccessKeySecret"<yourAccessKeySecret>");//鉴权密钥 aliyunVidSts.setSecurityToken("<yourSecurityToken>");//安全token aliyunVidSts.setRegion("接入地域");//点播服务的接入地域,默认为cn-shanghai //准备下载源 mAliDownloader.prepare(aliyunVidSts)
VidAuth
//创建VidAuth VidAuth vidAuth = new VidAuth(); vidAuth.setVid("Vid信息");//视频ID(VideoId) vidAuth.setPlayAuth("<yourPlayAuth>");//播放凭证 vidAuth.setRegion("接入地域");//点播服务的接入地域,默认为cn-shanghai //准备下载源 mAliDownloader.prepare(vidAuth);
说明源文件格式与输出的下载文件格式保持一致,不支持更改。
准备成功后,选择下载项并开始下载。
准备成功后,会回调
OnPreparedListener
方法。返回的TrackInfo中会包含各视频流的清晰度等信息,请选择一个Track进行下载,示例如下:public void onPrepared(MediaInfo mediaInfo) { //准备下载项成功 List<TrackInfo> trackInfos = mediaInfo.getTrackInfos(); //比如:下载第一个TrackInfo mAliDownloader.selectItem(trackInfos.get(0).getIndex()); //开始下载 mAliDownloader.start(); }
(可选)更新下载源。
为了防止VidSts和VidAuth过期,您也可以更新下载源的信息后开始下载。示例如下:
//更新下载源 mAliDownloader.updateSource(VidSts); //开始下载 mAliDownloader.start();
下载成功或失败后,释放下载器。
下载成功后,在
onCompletion
或者onError
回调中调用release
释放下载器。示例如下:mAliDownloader.stop(); mAliDownloader.release();
可选:删除下载的文件。
下载过程中,或者下载完成后,可以删除下载的文件。示例如下:
//通过对象删除文件 mAliDownloader.deleteFile(); //通过静态方法删除,若删除成功则返回0 AliDownloaderFactory.deleteFile("待删除的下载文件夹路径","视频ID","视频格式","下载的视频索引");
后续操作
下载的视频可以使用阿里云播放器进行播放。具体方法如下:
下载完成后获取视频文件的绝对路径。
String path = mAliDownloader.getFilePath();
通过点播UrlSource方式设置绝对路径进行播放。
UrlSource urlSource = new UrlSource(); urlSource.setUri("播放地址");//设置下载视频的绝对路径。 aliPlayer.setDataSource(urlSource);
视频加密播放
点播视频支持HLS标准加密、阿里云私有加密和DRM加密,直播视频仅支持DRM加密。加密播放请参见如何播放加密视频。
Native RTS播放
Android端播放器SDK集成Native RTS SDK实现Native端低延时直播功能,详情请参见基于阿里云播放器实现RTS拉流。
异常处理
使用阿里云播放器播放视频发生异常时,可借助单点探查功能快速定位问题,详细内容,请参见单点追查。
相关文档
- 本页导读 (1)