基础功能

创建播放器

本节介绍如何用简单的方式通过Android播放器SDK播放视频，按照播放方式的不同可以分为手动播放和自动播放。

1. 创建播放器。

   通过AliPlayerFactory类创建AliPlayer播放器。

   // 创建播放器
   AliPlayer aliPlayer = AliPlayerFactory.createAliPlayer(context);
   // 埋点日志上报功能默认开启，当traceId设置为DisableAnalytics时，则关闭埋点日志上报。当traceId设置为其他参数时，则开启埋点日志上报。
   // 建议传递traceId，便于跟踪日志。traceId为设备或用户的唯一标识符，通常为imei或idfa。
   aliPlayer.setTraceId("traceId");  

   说明

   创建播放器时，将用户或设备标识符透传至traceId参数，可便于后续播放异常时的快速定位问题，详细内容请参见单点追查。

2. 设置监听器。

   播放器支持设置多个监听器。

   • 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() {
           //结束加载。画面和声音可以播放。
           //一般在此处隐藏圆形加载。
       }
   });

3. 创建DataSource。

   • Android播放器SDK支持5种点播播放方式，包括：UrlSource播放、VidAuth播放（视频点播用户推荐使用）、VidSts播放、VidMps播放、加密播放。

   • Android播放器SDK支持2种直播播放方式，UrlSource播放和加密播放。

   说明

   • UrlSource是直接通过URL播放，其余的三种是通过vid进行播放：VidSts，VidAuth（推荐）限点播用户使用；VidMps仅限媒体处理（MPS）用户使用。

   • 接入地域Region的设置，请参见点播地域标识。

   • MPS视频播放的流程与概念，请参见视频播放。

   点播视频播放

   点播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("接入地域");// 必选参数，点播服务的接入地域，默认为cn-shanghai。
           aliPlayer.setDataSource(vidAuth);

   点播VidSts播放

   使用点播VidSts播放方式播放点播视频是指用STS临时凭证而非点播音视频播放凭证播放。STS安全令牌和STS临时AK对（AccessKeyId和AccessKeySecret）需要提前获取，获取方式请参见创建RAM角色并进行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。
           aliPlayer.setDataSource(vidSts);

   VidMps播放

   VidMps播放方式是播放器为媒体处理用户（MPS用户）提供的播放方式。VidMps播放需要提前获取以下信息：

   • vid：媒体处理系统中的媒资ID。

   • AccessKeyId和AccessKeySecret：随STS安全令牌下发的STS临时AK对。

   • SecurityToken：STS安全令牌。

   • domainRegion：媒体资源所在的地域。

   • authInfo：鉴权信息。

   获取MPS媒体相关信息请参见视频播放。

   VidMps vidMps = new VidMps();
           vidMps.setRegion("接入地域");// 必选参数，媒体资源所在的地域，例如cn-shanghai
           vidMps.setMediaId("媒体ID");// 必选参数，媒体ID，也是视频ID（VideoId）。
           vidMps.setAuthInfo("鉴权信息");// 必选参数，设置鉴权信息。
           vidMps.setAccessKeyId("<yourAccessKeyId>");// 必选参数，STS临时AK对的访问密钥ID，需要调用STS服务的AssumeRole接口生成。
           vidMps.setSecurityToken("<yourSecurityToken>");// STS安全令牌，需要调用STS服务的AssumeRole接口生成。
           vidMps.setPlayDomain("播放Domain信息");// 必选参数，设置播放Domain。
           vidMps.setHlsUriToken("用户令牌信息");// 可选参数，如需校验MtsHlsUriToken（用户令牌），可使用此参数传递。
           vidMps.setAccessKeySecret("<yourAccessKeySecret>");// 必选参数，STS临时AK对的访问密钥，需要调用STS服务的AssumeRole接口生成。
           aliPlayer.setDataSource(vidMps);

   点播加密播放

   点播视频支持HLS标准加密、阿里云私有加密和DRM加密。加密播放请参见播放加密视频。

   直播视频播放

   直播UrlSource播放

   使用UrlSource播放方式播放直播视频，需要将播放器的setUrl属性设置为直播拉流地址。播放地址可以是第三方直播地址或阿里云直播服务中的拉流地址。

   阿里云直播拉流地址可以通过直播控制台的地址生成器生成。详情请参见直播地址生成器。

   UrlSource urlSource = new UrlSource();
           urlSource.setUri("播放地址");// 播放地址，可以是第三方直播地址，或阿里云直播服务中的拉流地址。
           aliPlayer.setDataSource(urlSource);

   直播DRM加密播放

   直播DRM加密播放请参见播放DRM加密视频。

4. 设置显示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) {
     
         }
     });

5. 可选：开启自动播放，默认为关闭状态。

   aliPlayer.setAutoPlay(true);

6. 准备播放。

   调用aliPlayer.prepare()开始读取并解析数据。

   aliPlayer.prepare();

7. 开始播放。

   • 如果未开启自动播放，需要在OnPrepard回调中调用aliPlayer.start()开始播放视频。

   • 如果开启了自动播放，则不需要调用aliPlayer.start()，数据解析完成后将开始自动播放视频。

   aliPlayer.start();// 开始之后可以调用pause()暂停播放视频。

控制播放

Android播放器SDK支持从指定时间点播放、开始、暂停、停止播放等操作。

开始播放

aliyunVodPlayer.start();

从指定时间开始播放

// posotion为指定的时间，单位：毫秒。
aliyunVodPlayer.seekTo(long position);

暂停播放

aliyunVodPlayer.pause();

停止播放

aliyunVodPlayer.stop();

设置显示模式

Android播放器SDK支持填充、旋转、镜像等显示设置。

填充

// 设置宽高比适应（将按照视频宽高比等比缩小到view内部，不会有画面变形）
aliyunVodPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FIT);
// 设置宽高比填充（将按照视频宽高比等比放大，充满view，不会有画面变形）
aliyunVodPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FILL);
// 设置拉伸填充（如果视频宽高比例与view比例不一致，会导致画面变形）
aliyunVodPlayer.setScaleMode(ScaleMode.SCALE_TO_FILL);

旋转

// 设置画面顺时针旋转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();

镜像

// 设置无镜像
aliyunVodPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_NONE);
// 设置水平镜像
aliyunVodPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_HORIZONTAL);
// 设置垂直镜像
aliyunVodPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_VERTICAL);

获取播放信息

Android播放器SDK支持获取当前的播放进度、播放时长和缓冲进度等信息。

获取当前播放进度

mAliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.CurrentPosition){
            // extraValue为当前播放进度，单位为毫秒
            long extraValue = infoBean.getExtraValue();
        }
    }
});

获取播放时长

long duration = mAliPlayer.getDuration();

获取缓冲进度

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);

监听播放状态

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;
      */
    }
});

设置音量

设置音量包括音量调节和静音设置。

音量调节

// volume的值为0～2之间的实数。
aliyunVodPlayer.setVolume(1f);
// 获取音量信息。
aliyunVodPlayer.getVolume();

静音设置

aliyunVodPlayer.setMute(true);

倍速播放

// 设置倍速播放：支持0.5～5倍速的播放，通常按0.5的倍数来设置，例如0.5倍、1倍、1.5倍等
aliyunVodPlayer.setSpeed(1.0f);

多清晰度设置

如果使用VID方式（VidAuth及VidSts）播放，无需额外设置。Android播放器SDK会从点播服务获取清晰度列表。Android播放器SDK支持获取和切换清晰度，UrlSource方式暂不支持此设置。

获取清晰度

当视频加载完成后，可以获取视频的清晰度。

//获取媒体所有的流信息
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) { }
});

循环播放

aliyunVodPlayer.setLoop(true);

aliyunVodPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if (infoBean.getCode() == InfoCode.LoopingStart){
            //循环播放开始事件。
        }
    }
});

相关文档

• 详细的接口描述，请参见接口说明。

• 更多进阶功能的使用方法，请参见进阶功能。

• 播放异常时，常见问题及解决方案，请参见播放异常自主排查、Android播放器常见问题、错误码查询。