本文为您介绍如何创建Android播放器实例并提供设置音量、设置拖拽播放、监听播放状态、设置循环播放、设置倍速播放、切换音轨等基础播放功能的使用示例。
创建播放器
本节介绍如何用简单的方式通过Android播放器SDK播放视频，按照播放方式的不同可以分为手动播放和自动播放。
创建播放器。
通过
AliPlayerFactory类创建AliPlayer播放器。说明播放器提供的播放质量监控（可查看播放器整体播放质量相关数据）、单点追查（可定位到具体的用户或设备，分析其播放行为，快速定位播放异常等问题）及视频播放统计功能都依赖埋点日志上报功能而实现。
在创建播放器时，根据
setTraceId参数的设置不同，其后续可实现的功能不同，具体如下：setTraceId参数不传（默认）：埋点日志上报功能开启，后续可以使用播放质量监控和视频播放统计功能，无法使用单点追查功能。setTraceId参数传入traceid：traceid的值由您自行定义，需为您的用户或用户设备的唯一标识符，例如传入您业务的userid或者IMEI、IDFA等您业务用户的设备ID。传入traceid后，埋点日志上报功能开启，后续可以使用播放质量监控、单点追查和视频播放统计功能。setTraceId参数设置为DisableAnalytics：关闭埋点日志上报，后续无法使用播放质量监控、单点追查和视频播放统计功能。
// 创建播放器 AliPlayer aliPlayer = AliPlayerFactory.createAliPlayer(context); // 建议传入traceId aliPlayer.setTraceId("traceId");设置监听器。
播放器支持设置多个监听器。
OnPreparedListener必须设置，因为手动播放需要在OnPreparedListener回调中调用aliPlayer.start()开始播放。OnErrorListener、OnCompletionListener、OnLoadingStatusListener、OnInfoListener较为重要，建议您设置。
aliPlayer.setOnErrorListener(new IPlayer.OnErrorListener() { //此回调会在使用播放器的过程中，出现了任何错误，都会回调此接口。 @Override public void onError(ErrorInfo errorInfo) { ErrorCode errorCode = errorInfo.getCode(); //错误码。 String errorMsg = errorInfo.getMsg(); //错误描述。 //errorExtra为额外错误信息，形式为json字符串，示例如下，需要注意ModuleCode并不完全等同于errorCode //{ "Url": "xxx", // "Module": "NetWork", // "ModuleCode": "-377", // "ModuleMessage": "Redirect to a url that is not a media"} String errorExtra= errorInfo.getExtra(); //出错后需要停止掉播放器。 aliPlayer.stop(); } }); aliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() { // 调用aliPlayer.prepare()方法后，播放器开始读取并解析数据。成功后，会回调此接口。 @Override public void onPrepared() { //一般调用start开始播放视频。 aliPlayer.start(); } }); aliPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() { //播放完成之后，就会回调到此接口。 @Override public void onCompletion() { //一般调用stop停止播放视频。 aliPlayer.stop(); } }); aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() { //播放器中的一些信息，包括：当前进度、缓存位置等等。 @Override public void onInfo(InfoBean infoBean) { InfoCode code = infoBean.getCode(); //信息码。 String msg = infoBean.getExtraMsg();//信息内容。 long value = infoBean.getExtraValue(); //信息值。 //当前进度：InfoCode.CurrentPosition //当前缓存位置：InfoCode.BufferedPosition } }); aliPlayer.setOnLoadingStatusListener(new IPlayer.OnLoadingStatusListener() { //播放器的加载状态, 网络不佳时，用于展示加载画面。 @Override public void onLoadingBegin() { //开始加载。画面和声音不足以播放。 //一般在此处显示圆形加载。 } @Override public void onLoadingProgress(int percent, float netSpeed) { //加载进度。百分比和网速。 } @Override public void onLoadingEnd() { //结束加载。画面和声音可以播放。 //一般在此处隐藏圆形加载。 } });创建DataSource。
Android播放器SDK支持4种点播播放方式，包括：UrlSource播放、VidAuth播放（视频点播用户推荐使用）、VidSts播放、加密播放。
Android播放器SDK支持2种直播播放方式，UrlSource播放和加密播放。
说明UrlSource是直接通过URL播放，VidSts，VidAuth是通过Vid进行播放。
接入地域Region的设置，请参见点播地域标识。
点播视频播放
点播UrlSource播放
使用点播UrlSource播放方式播放点播视频，需要将播放器的setUrl属性设置为播放地址。
阿里云视频点播服务中的播放地址：可以调用GetPlayInfo接口获取。建议您集成点播服务端SDK来获取音视频播放地址，免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户。
本地视频地址：请确保有访问权限，可以通过系统API获取到可访问的本地视频文件完整路径，例如：
/sdcard/xxx/xxx/xxx.mp4或content://xxx/xxx/xx.mp4。
UrlSource urlSource = new UrlSource(); urlSource.setUri("播放地址");// 必选参数，播放地址，可以是第三方点播地址，或阿里云视频点播服务中的播放地址，也可以是本地视频地址。 aliPlayer.setDataSource(urlSource);点播VidAuth播放（推荐）
使用VidAuth播放方式播放点播视频，需要将播放器的vid属性设置为音视频ID，将playauth属性设置为音视频播放凭证。
音视频ID：可以在音视频上传完成后通过控制台（路径：媒资库>音/视频。）或服务端接口（SearchMedia）获取。
音视频播放凭证：可以调用GetVideoPlayAuth接口获取。建议您集成点播服务端SDK来获取音视频播放凭证，免去自签名的麻烦。调用接口获取音视频播放凭证的示例请参见开发者门户。
推荐视频点播用户采用此播放方式。相比STS播放方式，PlayAuth播放方式在易用性和安全性上更有优势，对比详情请参见凭证方式与STS方式对比。
VidAuth vidAuth = new VidAuth(); vidAuth.setVid("Vid信息");// 必选参数，视频ID（VideoId）。 vidAuth.setPlayAuth("<yourPlayAuth>");// 必选参数，播放凭证，需要调用点播服务的GetVideoPlayAuth接口生成。 vidAuth.setRegion("接入地域");// 5.5.5.0及之后版本播放器SDK，本参数已弃用，无需设置region，播放器会自动解析region；5.5.5.0之前版本播放器SDK，本参数必选，点播服务的接入地域，默认为cn-shanghai。 // vidAuth.setAuthTimeout(3600);// 播放地址的有效时长，单位：秒。该时长会覆盖在视频点播控制台设置的URL鉴权的有效时长。如果不传，则取默认值3600。如需设置此参数，请确保该时间大于视频的实际时长，防止播放地址在播放完成前过期。 aliPlayer.setDataSource(vidAuth);点播VidSts播放
使用点播VidSts播放方式播放点播视频是指用STS临时凭证而非点播音视频播放凭证播放。STS安全令牌和STS临时AK对（AccessKeyId和AccessKeySecret）需要提前获取，获取方式请参见使用STS临时授权方案上传视频。
VidSts vidSts = new VidSts(); vidSts.setVid("Vid信息");// 必选参数，视频ID（VideoId）。 vidSts.setAccessKeyId("<yourAccessKeyId>");// 必选参数，STS临时AK对的访问密钥ID，需要调用STS服务的AssumeRole接口生成。 vidSts.setAccessKeySecret("<yourAccessKeySecret>");// 必选参数，STS临时AK对的访问密钥，需要调用STS服务的AssumeRole接口生成。 vidSts.setSecurityToken("<yourSecurityToken>");// 必选参数，STS安全令牌，需要调用STS服务的AssumeRole接口生成。 vidSts.setRegion("接入地域");// 必选参数，点播服务的接入地域，默认为cn-shanghai。 // vidSts.setAuthTimeout(3600);// 播放地址的有效时长，单位：秒。该时长会覆盖在视频点播控制台设置的URL鉴权的有效时长。如果不传，则取默认值3600。如需设置此参数，请确保该时间大于视频的实际时长，防止播放地址在播放完成前过期。 aliPlayer.setDataSource(vidSts);点播加密播放
点播视频支持HLS标准加密、阿里云私有加密和DRM加密。加密播放请参见如何播放加密视频。
直播视频播放
直播UrlSource播放
使用UrlSource播放方式播放直播视频，需要将播放器的setUrl属性设置为直播拉流地址。播放地址可以是第三方直播地址或阿里云直播服务中的拉流地址。
阿里云直播拉流地址可以通过直播控制台的地址生成器生成。详情请参见直播地址生成器。
UrlSource urlSource = new UrlSource(); urlSource.setUri("播放地址");// 播放地址，可以是第三方直播地址，或阿里云直播服务中的拉流地址。 aliPlayer.setDataSource(urlSource);直播DRM加密播放
直播DRM加密播放请参见播放DRM加密视频-Web端。
设置显示View。
播放器支持SurfaceView和TextureView，任选其中一种即可。
设置SurfaceView，示例如下：
SurfaceView surfaceView = findViewById(R.id.surface_view); surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() { @Override public void surfaceCreated(SurfaceHolder holder) { aliPlayer.setSurface(holder.getSurface()); } @Override public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) { aliPlayer.surfaceChanged(); } @Override public void surfaceDestroyed(SurfaceHolder holder) { aliPlayer.setSurface(null); } });设置TextureView，示例如下：
TextureView textureView = findViewById(R.id.texture_view); textureView.setSurfaceTextureListener(new TextureView.SurfaceTextureListener() { @Override public void onSurfaceTextureAvailable(SurfaceTexture surface, int width, int height) { aliPlayer.setSurface(new Surface(surface)); } @Override public void onSurfaceTextureSizeChanged(SurfaceTexture surface, int width, int height) { aliPlayer.surfaceChanged(); } @Override public boolean onSurfaceTextureDestroyed(SurfaceTexture surface) { aliPlayer.setSurface(null); return false; } @Override public void onSurfaceTextureUpdated(SurfaceTexture surface) { } });
可选：开启自动播放，默认为关闭状态。
aliPlayer.setAutoPlay(true);准备播放。
调用
aliPlayer.prepare()开始读取并解析数据。aliPlayer.prepare();开始播放。
如果未开启自动播放，需要在
OnPrepard回调发生之后，择机调用aliPlayer.start()开始播放视频。如果开启了自动播放，则不需要调用
aliPlayer.start()，数据解析完成后将开始自动播放视频。
aliPlayer.start();// 开始之后可以调用pause()暂停播放视频。
控制播放
Android播放器SDK支持从指定时间点播放、开始、暂停、停止播放等操作。
开始播放
指开始播放视频，由start接口实现。示例如下：
aliyunVodPlayer.start();从指定时间开始播放
指跳转到某个时刻进行播放，由seekTo接口实现。适用于用户拖拽进度条，或续播等需要从指定时间点开始播放的场景。示例如下：
// posotion为指定的时间，单位：毫秒。
aliyunVodPlayer.seekTo(long position);以指定位置起播，仅生效一次，适用于用户从指定时间点开始播放的场景。示例如下：
//以指定位置起播，每次prepare前调用，仅生效一次，time为指定的时间(毫秒)，seekMode可设置为精准模式和非精准模式。
aliyunVodPlayer.setStartTime(time, seekMode);暂停播放
指暂停播放视频，由pause接口实现。示例如下：
aliyunVodPlayer.pause();停止播放
指停止播放视频，由stop接口实现。示例如下：
aliyunVodPlayer.stop();销毁播放器
销毁播放器实例，有同步和异步两种销毁方式，示例如下：
//同步销毁，内部会自动调用stop接口
aliyunVodPlayer.release();
//异步销毁，内部会自动调用stop接口
aliyunVodPlayer.releaseAsync(); 调用同步销毁接口需等待播放器资源完全释放后才返回。如果您对界面的响应速度有较高要求，建议使用异步销毁接口，并注意以下几点：
避免在异步销毁过程中对播放器对象执行任何其他操作。
无需在调用异步销毁之前手动停止播放器，因为该过程内部已经包含了异步化的停止流程。
设置显示模式
Android播放器SDK支持填充、旋转、镜像等显示设置。
填充
支持设置宽高比适应、宽高比填充和拉伸填充这3种画面填充模式，由setScaleMode接口实现。示例如下：
// 设置宽高比适应（将按照视频宽高比等比缩小到view内部，不会有画面变形）
aliyunVodPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FIT);
// 设置宽高比填充（将按照视频宽高比等比放大，充满view，不会有画面变形）
aliyunVodPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FILL);
// 设置拉伸填充（如果视频宽高比例与view比例不一致，会导致画面变形）
aliyunVodPlayer.setScaleMode(ScaleMode.SCALE_TO_FILL);旋转
指画面按指定角度旋转，由setRotateMode接口实现。设置后还可查询旋转角度。示例如下：
// 设置画面顺时针旋转0度
aliyunVodPlayer.setRotateMode(RotateMode.ROTATE_0);
// 设置画面顺时针旋转90度
aliyunVodPlayer.setRotateMode(RotateMode.ROTATE_90);
// 设置画面顺时针旋转180度
aliyunVodPlayer.setRotateMode(RotateMode.ROTATE_180);
// 设置画面顺时针旋转270度
aliyunVodPlayer.setRotateMode(RotateMode.ROTATE_270);
// 获取旋转角度
aliyunVodPlayer.getRotateMode();镜像
指画面按不同镜像效果显示，支持水平镜像、垂直镜像和无镜像，由setMirrorMode接口实现。示例如下：
// 设置无镜像
aliyunVodPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_NONE);
// 设置水平镜像
aliyunVodPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_HORIZONTAL);
// 设置垂直镜像
aliyunVodPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_VERTICAL);获取播放信息
Android播放器SDK支持获取当前的播放进度、播放时长和缓冲进度等信息。
获取当前播放进度
指获取当前的播放时刻，需要在onInfo回调中获取，由getExtraValue接口实现。示例如下：
mAliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
@Override
public void onInfo(InfoBean infoBean) {
if(infoBean.getCode() == InfoCode.CurrentPosition){
// extraValue为当前播放进度，单位为毫秒
long extraValue = infoBean.getExtraValue();
}
}
});获取播放时长
指获取视频总时长。需要在视频加载完成以后才可以获取到，可以在onPrepared事件后获取。由getDuration接口实现。示例如下：
long duration = mAliPlayer.getDuration();获取缓冲进度
指获取视频当前的缓冲进度，需要在onInfo回调中获取，由getExtraValue接口实现。示例如下：
mAliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
@Override
public void onInfo(InfoBean infoBean) {
if(infoBean.getCode() == InfoCode.BufferedPosition){
// extraValue为当前缓冲进度，单位为毫秒
long extraValue = infoBean.getExtraValue();
}
}
});获取实时渲染帧率、音视频码率、网络下行码率
示例如下：
// 获取当前渲染的帧率，数据类型为Float。
mAliPlayer.getOption(IPlayer.Option.RenderFPS);
// 获取当前播放的视频码率，数据类型为Float，单位为bps。
mAliPlayer.getOption(IPlayer.Option.VideoBitrate);
// 获取当前播放的音频码率，数据类型为Float，单位为bps。
mAliPlayer.getOption(IPlayer.Option.AudioBitrate);
// 获取当前的网络下行码率，数据类型为Float，单位为bps。
mAliPlayer.getOption(IPlayer.Option.DownloadBitrate);监听播放状态
指监听播放器的状态，onStateChanged回调参数为当前播放器状态。示例如下：
mAliPlayer.setOnStateChangedListener(new IPlayer.OnStateChangedListener() {
@Override
public void onStateChanged(int newState) {
/*
int idle = 0;
int initalized = 1;
int prepared = 2;
int started = 3;
int paused = 4;
int stopped = 5;
int completion = 6;
int error = 7;
*/
}
});音画不同步回调
指极端条件下（软解播放4K或者低端机高倍速播放高清H265流等），解码性能无法跟上播放速度时，会通过回调提示。示例如下：
mAliPlayer.setOnAVNotSyncStatusListener(new IPlayer.OnAVNotSyncStatusListener() {
@Override
public void onAVNotSyncStart(int type) {
if (type == 0) {
//降低播放倍速
if (player.getSpeed() > 1) {
player.setSpeed(1);
}
}
Toast.makeText(getContext(), "音画不同步开始" , Toast.LENGTH_SHORT).show();
}
@Override
public void onAVNotSyncEnd() {
Toast.makeText(getContext(), "音画不同步结束" , Toast.LENGTH_SHORT).show();
}
});设置音量
设置音量包括音量调节和静音设置。
音量调节
指调节音量大小，支持0～2倍，当音量大于1时，可能出现噪音，不推荐使用。由setVolume接口实现。设置后还可获取音量信息。示例如下：
// volume的值为0～2之间的实数。
aliyunVodPlayer.setVolume(1f);
// 获取音量信息。
aliyunVodPlayer.getVolume();静音设置
指将播放中的视频设置为静音状态，由setMute接口实现。示例如下：
aliyunVodPlayer.setMute(true);倍速播放
Android播放器SDK提供了倍速播放视频的功能，通过设置setSpeed方法，能够以0.5倍~5倍速去播放视频。同时保持变声不变调。示例如下：
// 设置倍速播放：支持0.5～5倍速的播放，通常按0.5的倍数来设置，例如0.5倍、1倍、1.5倍等
aliyunVodPlayer.setSpeed(1.0f);多清晰度设置
直播UrlSource播放方式
支持阿里云视频直播的播放地址或经直播转码后（现支持通用转码和自定义转码）的转码流地址，直播转码详情请参见转码管理；地址获取方式请参见生成推流地址和播放地址。
支持ARTC协议和FLV协议的直播流的不同清晰度切换。
推流的gop size需要设置为2s，域名需要配置为时间戳随源。
切换到不符合上述要求的流地址时，会切换失败。
切换清晰度
通过switchStream方法切换清晰度，传递对应新清晰度的URL即可。
mAliPlayer.switchStream(newUrl);清晰度切换通知
清晰度切换成功与失败回调。
mAliPlayer.setOnStreamSwitchedListener(new IPlayer.OnStreamSwitchedListener() {
@Override
public void onSwitchedSuccess(String url) {
Log.i("SwitchStream", "switch success, url = " + url);
}
@Override
public void onSwitchedFail(String url, ErrorInfo errorInfo) {
Log.i("SwitchStream", "switch failed, url = " + url + ", error=" + errorInfo.getMsg());
}
});点播Vid播放方式（VidAuth或VidSts）
如果使用Vid方式（VidAuth或VidSts）播放，无需额外设置。Android播放器SDK会从点播服务获取清晰度列表。
获取清晰度
当视频加载完成后，可以获取视频的清晰度。
//获取媒体所有的流信息
List<TrackInfo> trackInfos = mAliPlayer.getMediaInfo().getTrackInfos();
//遍历并获取清晰度
for (TrackInfo trackInfo : trackInfos) {
if(trackInfo.getType() == TrackInfo.Type.TYPE_VOD){
//获取视频清晰度
String vodDefinition = trackInfo.getVodDefinition();
}
}切换清晰度
通过selectTrack方法切换清晰度，传递对应TrackInfo的index即可。
mAliPlayer.selectTrack(index);清晰度切换通知
清晰度切换成功与失败回调。
mAliPlayer.setOnTrackChangedListener(new IPlayer.OnTrackChangedListener() {
@Override
public void onChangedSuccess(TrackInfo trackInfo) { }
@Override
public void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo) { }
});快切模式
开启快切模式后，手动调用selectTrack时，都会快速得到响应。
playerConfig.mSelectTrackBufferMode = 1;
mAliPlayer.setConfig(playerConfig)循环播放
Android播放器SDK提供了循环播放视频的功能。调用setLoop开启循环播放，播放完成后，将会自动从头开始播放视频。示例如下：
aliyunVodPlayer.setLoop(true);同时循环开始的回调将会使用onInfo中通知。示例如下：
aliyunVodPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
@Override
public void onInfo(InfoBean infoBean) {
if (infoBean.getCode() == InfoCode.LoopingStart){
//循环播放开始事件。
}
}
});切换音轨
Android播放器SDK提供了切换音轨的功能，适用于用户观看多语言配音的视频时可以自主进行配音语言切换等场景。
使用说明
目前仅支持非列表播放流（例如MP4流）、单码率混合HLS流、单码率非混合HLS流的音频流之间的切换以及多码率混合HLS流的子流切换。各类型视频流说明如下：
视频流类型 | 视频流后缀 | 码率数量 | 子m3u8数量 | 子流类型 | 切换说明 |
非列表播放流（例如MP4流） | .mp4 | 1 | - | 一条播放流汇聚了一路视频流、可能多路音频流和多路字幕流。 | 支持多路音频流之间的切换。 |
单码率混合HLS流 | .m3u8 | 1 | 1 | 一条播放流汇聚了一路视频流、可能多路音频流和多路字幕流。 | 支持多路音频流之间的切换。 |
单码率非混合HLS流 | .m3u8 | 1 | n | m3u8，每条子流只能是视频流、音频流或字幕流中的一种。 | 支持多路音频流之间的切换。 |
多码率混合HLS流 | .m3u8 | n | n | m3u8，每条子流汇聚了一路视频流、可能多路音频流和多路字幕流，不同子流之间码率不同。 | 目前仅支持子流之间的切换，不支持子流的多路音频流之间的切换。 |
使用示例
设置回调。
mAliyunVodPlayer.setOnSubTrackReadyListener(new IPlayer.OnSubTrackReadyListener() { @Override //onSubTrackReady回调，通常发生在prepare回调之前。 public void onSubTrackReady(MediaInfo mediaInfo) { if (mPlayerTrackFragment != null) { //mPlayerTrackFragment.showMediaInfo(); //通过getSubMediaInfo主动获取对应的MediaInfo信息，需要在收到onSubTrackReady回调后才可以调用，否则为空。 MediaInfo subMediaInfo = mAliyunVodPlayer.getSubMediaInfo(); TrackInfos = subMediaInfo.getTrackInfos(); //判断要选择的Track myTrack = myfunc(TrackInfos) } } });切换音轨。
index = myTrack.getIndex(); mAliyunVodPlayer.selectTrack(index);
获取SDK日志
在播放器SDK运行过程中会生成详细的日志信息，包括网络请求的状态、系统调用的结果、权限申请情况等各种运行时事件。开发者可以通过查看这些日志进行代码调试或排查问题，提高开发效率。
方式一：通过开发工具的控制台获取播放器SDK日志
此方式适用于在您本地可以复现问题并抓取日志的场景。
打开日志并设置日志级别。
// Logger在com.cicada.player.utils下 // 打开日志开关 Logger.getInstance(context).enableConsoleLog(true); // 设置日志级别，默认为AF_LOG_LEVEL_INFO，如需排查问题，可设置为AF_LOG_LEVEL_TRACE Logger.getInstance(context).setLogLevel(Logger.LogLevel.AF_LOG_LEVEL_INFO);收集日志。
复现问题后，可在您开发工具（例如Logcat）的控制台获取日志。
方式二：通过LogCallback监听播放器SDK的输出日志
此方式适用于问题发生在您的用户侧，在您本地无法复现问题并抓取日志的场景。可以通过LogCallback监听播放器SDK的输出日志，并自动输出到您App的日志通道中。
打开日志并设置日志级别。
// Logger在com.cicada.player.utils下 // 设置日志级别，默认为AF_LOG_LEVEL_INFO，如需排查问题，可设置为AF_LOG_LEVEL_TRACE Logger.getInstance(context).setLogLevel(Logger.LogLevel.AF_LOG_LEVEL_INFO); Logger.getInstance(mContext).setLogCallback(newLogger.OnLogCallback(){ @Override public void onLog(Logger.LogLevel logLevel,Strings){ // 日志 } });收集日志。
复现问题后，日志将通过您App的日志通道自动输出到您App的日志文件。
相关文档
详细的接口描述，请参见API说明。
更多进阶功能的使用方法，请参见进阶功能。
播放异常时，常见问题及解决方案，请参见播放异常自主排查、Android播放器常见问题、错误码查询。