基础功能 - 视频点播

创建播放器

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

创建播放器。

通过AliPlayerFactory类创建AliPlayer播放器。

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

说明创建播放器时，将用户或设备标识符透传至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(); //错误描述。
        //出错后需要停止掉播放器。
        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支持5种点播播放方式，包括：UrlSource播放、VidAuth播放（视频点播用户推荐使用）、VidSts播放、VidMps播放、加密播放。
- Android播放器SDK支持2种直播播放方式，UrlSource播放和加密播放。
说明

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

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

MPS视频播放的流程与概念，请参见视频播放。
点播视频播放
点播UrlSource播放 VidAuth播放点播VidSts播放 VidMps播放点播加密播放
使用UrlSource播放方式播放点播视频，需要将播放器的source属性设置为播放地址。播放地址可以是第三方点播地址或阿里云点播服务中的播放地址，也可以是本地视频地址。阿里云播放地址可以调用获取音视频播放地址接口获取。建议您集成点播服务端SDK来获取音视频播放地址，免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户。本地视频请确保有访问权限，播放地址为将本地视频文件转换成URL，例如：/sdcard/xxx/xxx/xxx.mp4或content://xxx/xxx/xx.mp4。

点播URLSource播放示例
```
 UrlSource urlSource = new UrlSource();
        urlSource.setUri("播放地址");//播放地址，可以是第三方点播地址，或阿里云点播服务中的播放地址，也可以是本地视频地址。
        aliPlayer.setDataSource(urlSource);
```
使用VidAuth播放方式播放点播视频，需要将播放器的vid属性设置为音视频ID，将playauth属性设置为音视频播放凭证。音视频ID可以在音视频上传完成后通过控制台（路径：媒资库 > 音/视频。）或服务端接口（SearchMedia ）获取。音视频播放凭证可以调用获取音视频播放凭证接口获取。建议您集成点播服务端SDK来获取音视频播放凭证，免去自签名的麻烦。调用接口获取音视频播放凭证的示例请参见开发者门户。

推荐视频点播用户采用此播放方式。相比STS播放方式，PlayAuth播放方式在易用性和安全性上更有优势，对比详情请参见凭证方式与STS方式对比。

VidAuth播放示例
```
VidAuth vidAuth = new VidAuth();
        vidAuth.setVid("Vid信息");//视频ID（VideoId）
        vidAuth.setPlayAuth("playAuth信息");//播放凭证
        vidAuth.setRegion("接入地域");//点播服务的接入地域，默认为cn-shanghai
        aliPlayer.setDataSource(vidAuth);
```
使用VidSts播放方式播放点播视频是指用STS临时凭证而非点播音视频播放凭证播放。STS临时Token需要提前获取，获取方式请参见获取STS临时Token。播放时需要将播放器的securityToken属性设置为STS临时Token，同时设置为STS临时Token生成的临时AK对（accessKeyId和accessKeySecret）。

VidSts播放示例
```
VidSts vidSts = new VidSts();
        vidSts.setVid("Vid信息");//视频ID（VideoId）
        vidSts.setAccessKeyId("<yourAccessKeyId>");//鉴权ID
        vidSts.setAccessKeySecret("<yourAccessKeySecret>");//鉴权密钥
        vidSts.setSecurityToken("<yourSecurityToken>");//安全token
        vidSts.setRegion("接入地域");//点播服务的接入地域，默认为cn-shanghai
        aliPlayer.setDataSource(vidSts);
```
VidMps播放方式是播放器为媒体处理用户（MPS用户）提供的播放方式。VidMps播放既需要提前获取以下信息：
- vid：媒体处理系统中的媒资ID。
- AcessKeyId和AccessKeySecret：随STS临时Token下发的临时AK对。
- SecurityToken：STS临时Token。
- domainRegion：媒体资源所在的地域。
- authInfo：授权信息。
获取MPS媒体相关信息请参见媒体处理视频播放。

VidMps播放示例
```
VidMps vidMps = new VidMps();
        vidMps.setRegion("接入地域");//点播服务的接入地域，默认为cn-shanghai
        vidMps.setMediaId("媒体ID");//媒体ID，也是视频ID（VideoId）
        vidMps.setAuthInfo("认证信息");//设置认证信息
        vidMps.setAccessKeyId("<yourAccessKeyId>");//鉴权ID
        vidMps.setSecurityToken("<yourSecurityToken>");//安全token
        vidMps.setPlayDomain("播放Domain信息");//设置播放Domain
        vidMps.setHlsUriToken("HlsUriToken信息");//设置HlsUriToken
        vidMps.setAccessKeySecret("<yourAccessKeySecret>");//鉴权密钥
        aliPlayer.setDataSource(vidMps);
```
点播视频支持HLS标准加密、阿里云私有加密和DRM加密。加密播放请参见Android播放器加密播放。
直播视频播放
直播UrlSource播放直播DRM加密播放
使用URL播放方式播放直播视频，需要将播放器的urlSource属性设置为直播拉流地址。播放地址可以是第三方直播地址或阿里云直播服务中的拉流地址。阿里云直播拉流地址可以通过直播控制台的地址生成器生成。详情请参见地址生成器。

直播URL播放示例
```
UrlSource urlSource = new UrlSource();
        urlSource.setUri("播放地址");//播放地址，可以是第三方直播地址，或阿里云直播服务中的拉流地址。
        aliPlayer.setDataSource(urlSource);
```
直播DRM加密播放请参见Android播放器加密播放。

设置显示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);

暂停播放

指暂停播放视频，由pause接口实现。示例如下：

aliyunVodPlayer.pause();

停止播放

指停止播放视频，由stop接口实现。示例如下：

aliyunVodPlayer.stop();

设置显示模式

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

设置音量

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

音量调节

指调节音量大小，支持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);

多清晰度设置

如果使用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) { }
});

循环播放

Android播放器SDK提供了循环播放视频的功能。调用setLoop开启循环播放，播放完成后，将会自动从头开始播放视频。示例如下：

aliyunVodPlayer.setLoop(true);

同时循环开始的回调将会使用onInfo中通知。示例如下：

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