Android播放器的使用示例_视频点播-阿里云帮助中心

本文提供Android播放器进阶功能的使用示例。

说明

本文档仅提供常用进阶功能的使用示例，更多功能的支持和使用请参见接口说明。

播放

短视频列表播放

针对典型的短视频列表播放场景，Android播放器SDK提供了完善的列表播放功能，结合预加载等机制大幅改善短视频的起播速度。长视频场景不建议使用该功能。

使用限制

AliListPlayer存在以下限制，推荐使用多个AliPlayer的方式来实现短视频列表播放，详细内容请参见沉浸式短视频。

AliListPlayer不支持多实例，要保持全局单实例，使用多个AliListPlayer会出现视频源混乱的问题。
5.4.5.0以前版本的Android播放器SDK中，AliListPlayer不支持m3u8格式的视频；5.4.5.0及以后版本的Android播放器SDK才支持m3u8格式的视频（需要打开本地缓存功能）。

操作步骤

创建播放器。

通过AliPlayerFactory类创建AliListPlayer播放器。示例如下：

AliListPlayer aliyunListPlayer;
.....
aliyunListPlayer = AliPlayerFactory.createAliListPlayer(getApplicationContext());
aliyunListPlayer.setTraceId("traceId");  //traceId为设备或用户的唯一标识符，通常为imei或idfa

可选：设置监听器。

创建列表播放时，监听器为非必须配置，但如果不设置，将无法收到播放器的播放失败、播放进度等事件通知，因此，建议您设置。其中OnPreparedListener、OnErrorListener、OnCompletionListener、OnLoadingStatusListener、OnInfoListener较为重要，建议您设置。

aliyunListPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
    @Override
    public void onCompletion() {
        //播放完成事件
    }
});
aliyunListPlayer.setOnErrorListener(new IPlayer.OnErrorListener() {
    @Override
    public void onError(ErrorInfo errorInfo) {
        //出错事件
    }
});
aliyunListPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        //准备成功事件
    }
});
aliyunListPlayer.setOnVideoSizeChangedListener(new IPlayer.OnVideoSizeChangedListener() {
    @Override
    public void onVideoSizeChanged(int width, int height) {
        //视频分辨率变化回调
    }
});
aliyunListPlayer.setOnRenderingStartListener(new IPlayer.OnRenderingStartListener() {
    @Override
    public void onRenderingStart() {
        //首帧渲染显示事件
    }
});
aliyunListPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(int type, long extra) {
        //其他信息的事件，type包括了：循环播放开始，缓冲位置，当前播放位置，自动播放开始等
    }
});
aliyunListPlayer.setOnLoadingStatusListener(new IPlayer.OnLoadingStatusListener() {
    @Override
    public void onLoadingBegin() {
        //缓冲开始。
    }
    @Override
    public void onLoadingProgress(int percent, float kbps) {
        //缓冲进度
    }
    @Override
    public void onLoadingEnd() {
        //缓冲结束
    }
});
aliyunListPlayer.setOnSeekCompleteListener(new IPlayer.OnSeekCompleteListener() {
    @Override
    public void onSeekComplete() {
        //拖动结束
    }
});
aliyunListPlayer.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
    @Override
    public void onSubtitleShow(long id, String data) {
        //显示字幕
    }
    @Override
    public void onSubtitleHide(long id) {
        //隐藏字幕
    }
});
aliyunListPlayer.setOnTrackChangedListener(new IPlayer.OnTrackChangedListener() {
    @Override
    public void onChangedSuccess(TrackInfo trackInfo) {
        //切换音视频流或者清晰度成功
    }
    @Override
    public void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo) {
        //切换音视频流或者清晰度失败
    }
});
aliyunListPlayer.setOnStateChangedListener(new IPlayer.OnStateChangedListener() {
    @Override
    public void onStateChanged(int newState) {
        //播放器状态改变事件
    }
});
aliyunListPlayer.setOnSnapShotListener(new IPlayer.OnSnapShotListener() {
    @Override
    public void onSnapShot(Bitmap bm, int with, int height) {
        //截图事件
    }
});

设置预加载个数。

合理设置预加载个数，能够有效的提高起播的速度。示例如下：

//设置预加载个数。总共加载的个数为： 1 + count*2。
aliyunListPlayer.setPreloadCount(int count);

添加或移除多个播放源。
列表播放支持两种播放源：Vid播放（包括VidSts及VidPlayAuth）和UrlSource播放。Url为视频的播放地址。示例如下
- Url：播放地址可以是第三方点播地址或阿里云点播服务中的播放地址。阿里云播放地址可以调用获取音视频播放地址接口获取。建议您集成点播服务端SDK来获取音视频播放地址，免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户。
- Vid：音视频ID，可以在音视频上传完成后通过控制台（路径：媒资库 > 音/视频。）或服务端接口（搜索媒体信息）获取。
```
//添加Vid播放源
aliyunListPlayer.addVid(String videoId, String uid);
//添加UrlSource播放源
aliyunListPlayer.addUrl(String url, String uid);
//移除某个源
aliyunListPlayer.removeSource(String uid);
```
说明
- 不支持VidMps播放方式。
- uid是视频的唯一标志。用于区分视频是否一样。如果uid一样，则认为视频是一样的。如果播放出现串流的情况，请注意查看是不是在不同的界面设置了同一个uid。uid没有格式限制，可以是任意的字符串。

设置显示View。

播放器支持SurfaceView和TextureView，任选其中一种即可。

设置SurfaceView，示例如下：

SurfaceView surfaceView = findViewById(R.id.surface_view);
surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() {
    @Override
    public void surfaceCreated(SurfaceHolder holder) {
        aliyunListPlayer.setSurface(holder.getSurface());
    }

    @Override
    public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
        aliyunListPlayer.surfaceChanged();
    }

    @Override
    public void surfaceDestroyed(SurfaceHolder holder) {
        aliyunListPlayer.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) {
        aliyunListPlayer.setSurface(new Surface(surface));
    }

    @Override
    public void onSurfaceTextureSizeChanged(SurfaceTexture surface, int width, int height) {
        aliyunListPlayer.surfaceChanged();
    }

    @Override
    public boolean onSurfaceTextureDestroyed(SurfaceTexture surface) {
        aliyunListPlayer.setSurface(null);
        return false;
    }

    @Override
    public void onSurfaceTextureUpdated(SurfaceTexture surface) {

    }
});

播放视频源。

添加了一个或多个播放源之后并设置自动播放，调用moveTo便可以自动播放某个视频源。示例如下：

//开启自动播放
aliyunListPlayer.setAutoPlay(true);

//url时使用此接口
aliyunVodPlayer.moveTo(String uid);
//vid的时候使用此接口，需要传递stsInfo即STS临时凭证和临时AK对，需要提前获取，获取方式请参见创建RAM角色并进行STS临时授权。
aliyunVodPlayer.moveTo(String uid, StsInfo info);
//vid的时候使用此接口，需要传递PlayAuthInfo,在此之前要针对每个视频获取PlayAuth信息。
aliyunVodPlayer.moveTo(String uid, PlayAuthInfo info);

播放上一个、下一个视频。

播放器提供了moveToPrev，moveToNext接口用于播放上一个，下一个视频。示例如下：

//开启自动播放
aliyunListPlayer.setAutoPlay(true);

//移动到下一个视频。 注意：只能用于url的源。这个方法不适用于vid的播放。
aliyunVodPlayer.moveToNext();
//移动到上一个视频。注意：只能用于url的源。这个方法不适用于vid的播放。
aliyunVodPlayer.moveToPrev();
//移动到下一个视频。注意：只能用于vid的播放。
aliyunVodPlayer.moveToNext(StsInfo info);
// 移动到上一个视频。注意：只能用于vid的播放。
aliyunVodPlayer.moveToPrev(StsInfo info);
//移动到下一个视频。注意：只能用于vid且使用PlayAuth的播放。
aliyunVodPlayer.moveToNext(PlayAuthInfo info);
// 移动到上一个视频。注意：只能用于vid且使用PlayAuth的播放。
aliyunVodPlayer.moveToPrev(PlayAuthInfo info);

根据vid申请PlayAuth信息，申请成功后再进行MoveTo或MoveToNext等。

说明

只有VidPlayAuth播放才需要根据vid申请PlayAuth信息。

requestAuth(source.getVideoId(), new OnRequestAuthResultListener() {
    @Override
    public void onResult(VidAuth vidAuth) {
        mVideoListPlayer.moveToNext(createVidAuth(vidAuth));
    }
});

private PlayAuthInfo createVidAuth(VidAuth vidAuth) {
    if (vidAuth == null) {
        return new PlayAuthInfo();
    }
    PlayAuthInfo playAuthInfo = new PlayAuthInfo();
    playAuthInfo.setPlayAuth(vidAuth.getPlayAuth());
    return playAuthInfo;
}

可选：使用预渲染实例提升视频切换的顺畅度。

说明

Android播放器SDK 5.5.2.0及以上版本才支持本功能，并且需要开启本地缓存，开启方法请参见本地缓存。

Android播放器SDK从5.5.2.0版本开始提供getPreRenderPlayer和moveToNextWithPrerendered接口，用于提升滑动切换到下一个视频播放时的顺畅度，根据您的SDK集成场景不同，其使用方法有所差异，具体如下：

全新集成5.5.2.0及以后版本

使用PreRenderPlayer来实现。示例代码如下：

//preRenderPlayer只能在moveToNext时使用，并且需要开启本地缓存。
IPlayer preRenderPlayer = listPlayer.getPreRenderPlayer();
if (preRenderPlayer != null) {
    //设置surface
    preRenderPlayer.setSurface(surface);
  preRenderPlayer.start();
  listPlayer.setSurface(null);
  //STS播放方式，将moveToNext接口替换成moveToNextWithPrerendered
  listPlayer.moveToNextWithPrerendered(createStsInfo(source));
}

从低版本升级至5.5.2.0及以后版本

您需要修改低版本SDK的代码实现，具体如下：

修改渲染View。

低版本的Android播放器SDK全局使用一个渲染View，在每次切换播放源时，先从布局中remove前一个View，再添加下一个View到当前界面上。从5.5.2.0版本开始，支持使用多个渲染View，在RecyclerView.ViewHolder的布局中添加多个View，在切换播放源时，可以预加载下一个播放源，以提升切换的顺畅度。您需要删除低版本的渲染View的代码，并添加新版本添加多个渲染View的代码，示例代码如下：

/*
删除如下代码
    如下几行代码为低版本添加渲染View的代码。会将渲染View添加到FrameLayout中，然后在切换播放源时，会将mPlayerViewContainer移除、添加。
*/
private void initPlayer() {
    //...
    mPlayerViewContainer = View.inflate(getContext(), R.layout.layout_player_view, null);
    FrameLayout frameLayout = mPlayerViewContainer.findViewById(R.id.framelayout);
    FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT,
    FrameLayout.LayoutParams.MATCH_PARENT);
    View renderView = createRenderView(Common.RENDER_VIEW_NAME);
    frameLayout.addView(renderView, 0, params);
    //...
}

/*
添加或修改如下代码以添加多个渲染View
    修改RecyclerView的item布局，以及对应的ViewHolder
*/

public final class MyHolder extends RecyclerView.ViewHolder {
    //...
    private Surface mSurface;
    MyHolder(@NonNull View itemView) {
        super(itemView);
        //...
        TextureView mTextureView = itemView.findViewById(R.id.texture_view);
        mTextureView.setSurfaceTextureListener(new TextureView.SurfaceTextureListener() {
            @Override
            public void onSurfaceTextureAvailable(SurfaceTexture surface, int width, int height) {
                mSurface = new Surface(surface);
            }

            @Override
            public void onSurfaceTextureSizeChanged(SurfaceTexture surface, int width, int height) {}

            @Override
            public boolean onSurfaceTextureDestroyed(SurfaceTexture surface) {
                mSurface = null;
                return false;
            }

            @Override
            public void onSurfaceTextureUpdated(SurfaceTexture surface) {}
        });
    }
    //...

    //对外呈现获取Surface的接口
    public Surface getSurface() {
        return mSurface;
    }
}

修改RecyclerView中的item布局的示例代码如下：

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/root_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@android:color/black">

    <TextureView
        android:id="@+id/texture_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

<!-- 删除封面图片，如果效果不好，可以保留封面图片的相关逻辑。 -->
<!--    <FrameLayout-->
<!--        android:id="@+id/player_view"-->
<!--        android:layout_width="match_parent"-->
<!--        android:layout_height="match_parent"-->
<!--        android:clickable="false"-->
<!--        android:clipChildren="false"-->
<!--        android:focusable="false">-->

<!--        <ImageView-->
<!--            android:id="@+id/img_thumb"-->
<!--            android:layout_width="match_parent"-->
<!--            android:layout_height="match_parent"-->
<!--            android:layout_gravity="center"-->
<!--            android:adjustViewBounds="true"-->
<!--            android:clickable="false"-->
<!--            android:focusable="false"-->
<!--            android:scaleType="fitXY" />-->

<!--    </FrameLayout>-->

</FrameLayout>

修改切换播放源的逻辑。

从Android播放器SDK 5.5.2.0版本开始，在调用moveToNext时，会增加对preRenderPlayer的调用，因此需要单独对渲染View（Surface）进行设置。其中，moveToNext、moveToPre、moveTo的逻辑有所差异。示例代码如下：

/*
    说明：mQuickPlayer是AlivcQuickPlayer类的实例对象，封装了ListPlayer的接口。
*/
private void startPlay(int position, boolean isInitComplete) {
    //...
    //根据position获取ViewHolder实例对象
    LittleVideoListAdapter.MyHolder holder = (LittleVideoListAdapter.MyHolder) recycler.findViewHolderForLayoutPosition(position);

    //...

    //1.moveToPre时，先设置Surface，再调用moveToPre
    if (holder != null) {
        mQuickPlayer.setSurface(holder.getSurface());
    }
    mQuickPlayer.moveToPrev(video, position, mVideoSourceType);

    //2.moveTo时，先设置Surface，再调用moveTo
    if (holder != null) {
        mQuickPlayer.setSurface(holder.getSurface());
    }
    //mQuickPlayer.startPlay()内部最终会调用moveTo()接口
    mQuickPlayer.startPlay(video, position, mVideoSourceType);

    //3.moveToPre时，需要增加一个参数，将Surface传递进去
    mQuickPlayer.moveToNext(video, position, mVideoSourceType, holder.getSurface());

    //...
}

修改AlivcQuickPlayer类的示例代码如下：

//修改moveToPre方法
public void moveToPrev(AlivcVideoInfo.Video source, final int position, VideoSourceType videoSourceType) {
    //...
    //增加如下代码
    mVideoListPlayer.clearScreen();
    if (videoSourceType == VideoSourceType.TYPE_STS) {
        mVideoListPlayer.moveToPrev(createStsInfo(source));
    } else {
        mVideoListPlayer.moveToPrev();
    }
}

//增加moveToNext的重载方法
public void moveToNext(AlivcVideoInfo.Video source, int position, VideoSourceType videoSourceType, Surface surface) {
    //...
    //moveToNext时，可以获取preRenderPlayer对象，并使用该Player播放
    IPlayer preRenderPlayer = mVideoListPlayer.getPreRenderPlayer();
    if (preRenderPlayer != null) {
        preRenderPlayer.clearScreen();
        preRenderPlayer.setSurface(surface);
        preRenderPlayer.start();
        mVideoListPlayer.setSurface(null);
    } else {
        mVideoListPlayer.clearScreen();
        mVideoListPlayer.setSurface(surface);
    }

    //STS播放方式
    if (videoSourceType == VideoSourceType.TYPE_STS) {
        //当preRenderPlayer不为null时候，调用moveToNextWithPrerendered进行播放
        if (preRenderPlayer != null) {
            mVideoListPlayer.moveToNextWithPrerendered(createStsInfo(source));
        } else {
            mVideoListPlayer.moveToNext(createStsInfo(source));
        }
    } else {
        //URL播放方式
        if (preRenderPlayer != null) {
            mVideoListPlayer.moveToNextWithPrerendered();
        } else {
            mVideoListPlayer.moveToNext();
        }
    }
}

可选：修改滑动播放的逻辑。

支持通过修改滑动播放的逻辑，实现在滑动切换视频时，当滑动到下一个视频的一半画面出现时，开始播放下一个视频。通过修改PagerLayoutManager类中的代码实现，即当RecyclerView的item出现在屏幕一半时，切换播放源，示例代码如下：

recyclerView.addOnScrollListener(new OnScrollListener() {
    private int measuredHeight;
    private int mScrollDiff;
    @Override
    public void onScrollStateChanged(RecyclerView recyclerView, int newState) {
        super.onScrollStateChanged(recyclerView, newState);

        if (newState == RecyclerView.SCROLL_STATE_DRAGGING) {
            measuredHeight = recyclerView.getMeasuredHeight();
            mScrollDiff = 0;
        }

        if (newState == RecyclerView.SCROLL_STATE_IDLE) {
            mScrollDiff = 0;
            View viewIdle = mPagerSnapHelper.findSnapView(PagerLayoutManager.this);
            if (viewIdle == null) {
                return;
            }
            int positionIdle = getPosition(viewIdle);
            if (mOnViewPagerListener != null && getChildCount() == 1 && mOldPosition != positionIdle) {
                mOnViewPagerListener.onPageSelected(positionIdle, positionIdle == getItemCount() - 1, viewIdle);
                mOldPosition = positionIdle;
            }
        }
    }

    @Override
    public void onScrolled(RecyclerView recyclerView, int dx, int dy) {
        super.onScrolled(recyclerView, dx, dy);
        if (measuredHeight > 0 && mOnViewPagerListener != null) {
            mScrollDiff += dy;
            changeVideoAfterScrolled(recyclerView, dy >= 0);
        }
    }

    private void changeVideoAfterScrolled(RecyclerView recyclerView, boolean isNext) {
        if (Math.abs(mScrollDiff) >= measuredHeight / 2) {
            View snapView = mPagerSnapHelper.findSnapView(PagerLayoutManager.this);
            if (snapView != null) {
                int position = getPosition(snapView);
                if (mOldPosition != position) {
                    if (isNext) {
                        mOnViewPagerListener.onPageHideHalf(position - 1);
                    } else {
                        mOnViewPagerListener.onPageHideHalf(position + 1);
                    }
                    mOnViewPagerListener.onPageSelected(position, false, snapView);
                    mOldPosition = position;
                    recyclerView.smoothScrollToPosition(position);
                    mScrollDiff = 0;
                }
            }
        }
    }
});

外挂字幕

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.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
    @Override
    public void onSubtitleExtAdded(int trackIndex, String url) { }

    @Override
    public void onSubtitleShow(int trackIndex, long id, String data) {
            // ass 字幕
        assSubtitleView.show(id,data);

        // srt 字幕
        SubtitleView.Subtitle subtitle = new SubtitleView.Subtitle();
        subtitle.id = id + "";
        subtitle.content = data;
        subtitleView.show(subtitle);

    }

    @Override
    public void onSubtitleHide(int trackIndex, long id) {
            // ass 字幕
            assSubtitleView.dismiss(id);

        // srt 字幕
        subtitleView.dismiss(id + "");
    }

    @Override
    public void onSubtitleHeader(int trackIndex, String header) { }
});

添加字幕。
```
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提供了设置缓存和延迟的控制接口。示例如下：

//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//最大延迟。注意：直播有效。当延时比较大时，播放器sdk内部会追帧等，保证播放器的延时在这个范围内。
config.mMaxDelayTime = 5000;
// 最大缓冲区时长。单位ms。播放器每次最多加载这么长时间的缓冲数据。
config.mMaxBufferDuration = 50000;
//高缓冲时长。单位ms。当网络不好导致加载数据时，如果加载的缓冲时长到达这个值，结束加载状态。
config.mHighBufferDuration = 3000;
// 起播缓冲区时长。单位ms。这个时间设置越短，起播越快。也可能会导致播放之后很快就会进入加载状态。
config.mStartBufferDuration = 500;
....//其他设置
//往前缓存的最大时长。单位ms。默认为0。
config.mMaxBackwardBufferDurationMs = 0;

//设置配置给播放器
mAliyunVodPlayer.setConfig(config);

重要

三个缓冲区时长的大小关系必须为：mStartBufferDuration ≤ mHighBufferDuration ≤ mMaxBufferDuration。
当最大缓冲区时长（mMaxBufferDuration）大于5分钟时，为防止因为缓冲区过大导致的内存异常，系统将默认按5分钟生效。当mMaxBufferDuration设置超过50000 ms（即50s）时，可以启用大缓存，来降低内存占用，进一步提高播放性能，如有需要，请参见大缓存。

设置HTTP Header

通过PlayerConfig方法，可以给播放器中的请求加上HTTP的header参数。示例如下：

//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//定义header
String[] headers = new String[1];
headers[0]="Host:example.com";//比如需要设置Host到header中。
//设置header
config.setCustomHeaders(headers);
....//其他设置
  //设置配置给播放器
mAliyunVodPlayer.setConfig(config);

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通过player.setOutputAudioChannel方法设置输出声道，如果输入源是双声道，则支持通过下述方法切换为左声道或右声道；如果输入源是单声道，则设置无效。

说明

下述输出声道的设置会同时影响音频渲染及PCM数据回调。

/*
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_LEFT 切换到左声道播放,
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_RIGHT 切换到右声道播放,
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_NONE 不切换声道，保持输入源声道播放
*/
player.setOutputAudioChannel();

解析音频流

设置监听，可获取音视频流数据。音视频不能是加密流，加密流无法解析。

//可选配置1：是否返回底层数据的地址
IPlayer.RenderFrameCallbackConfig config = new IPlayer.RenderFrameCallbackConfig();
config.mVideoDataAddr = true;//是否只返回底层视频数据地址
config.mAudioDataAddr = true;//是否只返回底层音频数据地址
player.setRenderFrameCallbackConfig(config);

//可选配置2：硬解时，RenderFrame返回 texture_oes_id，软解时，RenderFrame返回源数据
player.enableHardwareDecoder(true);
//设置监听，获取音视频数据
player.setOnRenderFrameCallback(frameInfo -> {
    if (frameInfo.frameType == FrameInfo.FrameType_video) {
        //视频数据
    } else {
        //音频数据
    }
    return false;
});

性能

本地缓存

Android播放器SDK提供了本地缓存的功能，能够让用户重复播放视频时，提高起播速度、提高seek速度、减少卡顿，也能达到节省流量的目的。

开启本地缓存

本地缓存功能默认关闭，如需使用，需要手动开启。通过AliPlayerGlobalSettings中的enableLocalCache控制。示例如下：

/**
 *  开启本地缓存，开启之后，会缓存到本地文件中。
 *
 *  @param enable - 本地缓存功能开关。true：开启本地缓存，false：关闭，默认关闭。
 *  @param maxBufferMemoryKB - 5.4.7.1及以后版本已废弃，暂无作用
 *  @param localCacheDir - 本地缓存的文件目录，为绝对路径。
 */
public static void enableLocalCache(boolean enable,
                                    int maxBufferMemoryKB,
                                    java.lang.String localCacheDir)

 /**
  * 本地缓存文件清理相关配置。
  *
  * @param expireMin - 5.4.7.1及以后版本已废弃，暂无作用。
  * @param maxCapacityMB - 最大缓存容量。单位：兆，默认值20GB，在清理时，如果缓存总容量超过此大小，则会以cacheItem为粒度，按缓存的最后时间排序，一个一个的删除最旧的缓存文件，直到小于等于最大缓存容量。
  * @param freeStorageMB - 磁盘最小空余容量。单位：兆，默认值0，在清理时，同最大缓存容量，如果当前磁盘容量小于该值，也会按规则一个一个的删除缓存文件，直到freeStorage大于等于该值或者所有缓存都被清理掉。
  */
 public static void setCacheFileClearConfig(long expireMin,
                                           long maxCapacityMB,
                                           long freeStorageMB)

  /**
   * 设置加载url的hash值回调。如果不设置，SDK使用md5算法。
   */
  public static void setCacheUrlHashCallback(AliPlayerGlobalSettings.OnGetUrlHashCallback cb)

说明

如果视频播放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。

配置回调，并开始加载。

/**
 * 设置加载状态回调
 */
mediaLoader.setOnLoadStatusListener(new MediaLoader.OnLoadStatusListener() {
    @Override
    public void onError(String url, int code, String msg) {
        //加载出错
    }

    @Override
    public void onCompleted(String s) {
        //加载完成
    }

    @Override
    public void onCanceled(String s) {
        //加载取消
    }
});
/**
 * 开始加载文件。异步加载。可以同时加载多个视频文件。
 * @param url - 视频文件地址。
 * @param duration - 加载的时长大小，单位：毫秒。
 */
mediaLoader.load("url","duration");

可选：删除加载文件。
可按需删除加载文件，以节省空间。Android播放器SDK不提供删除接口，需要在App删除加载目录下的文件。

获取下载速度

指获取当前播放视频的下载速度，在onInfo回调中获取，由getExtraValue接口实现。示例如下：

mAliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.CurrentDownloadSpeed){
            //当前下载速度
            long extraValue = infoBean.getExtraValue();
        }
    }
});

网络特性

使用HTTP/2

说明

Android播放器SDK自5.5.0.0版本开始默认开启使用HTTP/2。

Android播放器SDK支持使用HTTP/2协议，该协议通过多路复用，避免队头阻塞，以改善播放性能。示例如下：

AliPlayerGlobalSettings.setUseHttp2(true);

使用HTTP/3

说明

IETF QUIC已于2022年成为正式标准，Android播放器SDK仅支持IETF QUIC h3-v1版本，不支持Google QUIC。
开启使用HTTP/3协议后若播放连接超时或失败，会自动降级至使用HTTP/2协议进行请求。

Android播放器SDK支持使用HTTP/3协议，您需要填写表单申请给域名开通HTTP/3，使存储在视频点播中经过该域名加速的视频支持使用HTTP/3协议观看，再通过下述配置使播放器以HTTP/3协议进行请求播放，以达到更好的抗弱网体验。示例如下：

//先获取配置
PlayerConfig config = mAliyunVodPlayer.getConfig();
//以HTTP/3协议进行请求
config.mEnableHttp3 = true;
....//其他设置
//设置配置给当前播放器实例
mAliyunVodPlayer.setConfig(config);

视频下载

Android播放器SDK提供了点播服务视频的下载功能，允许用户通过阿里云播放器将视频缓存至本地观看。同时，提供了普通下载和安全下载两种下载方式。

普通下载
下载后的视频数据未经过阿里云加密，用户可以用第三方播放器播放。
安全下载
下载后的视频数据经过阿里云加密。第三方播放器无法播放。仅支持使用阿里云的播放器进行播放。

使用说明

仅VidSts和VidAuth方式支持视频下载功能。
使用播放器的视频下载功能，需要在点播控制台开启并配置下载模式，详细操作请参见下载设置。
视频下载支持断点续传。

操作步骤

可选：配置安全下载的加密校验文件。仅安全下载需要配置，普通下载无需配置。
说明
请确保配置的加密校验文件与App信息一致，否则会导致视频下载失败。
如果设置为安全下载方式，则需要将在点播控制台生成的密钥文件配置到播放器SDK中，用于视频下载和播放的解密验证，密钥文件的生成请参见安全下载。
建议在Application中配置一次即可，示例如下：
```
PrivateService.initService(getApplicationContext(),  "encryptedApp.dat所在的文件路径"); //建议将encryptedApp.dat加密校验文件存放到手机中后，此处设置加密校验文件的手机本地文件路径
```

创建并设置下载器。

创建下载器，通过AliDownloaderFactory创建。示例如下：

AliMediaDownloader mAliDownloader = null;
......
//创建下载器
mAliDownloader = AliDownloaderFactory.create(getApplicationContext());
//配置下载保存的路径
mAliDownloader.setSaveDir("保存的文件夹地址");

设置监听事件。

下载器提供了多个事件监听。示例如下：

mAliDownloader.setOnPreparedListener(new AliMediaDownloader.OnPreparedListener() {
   @Override
   public void onPrepared(MediaInfo mediaInfo) {
       //准备下载项成功
   }
});
mAliDownloader.setOnProgressListener(new AliMediaDownloader.OnProgressListener() {
   @Override
   public void onDownloadingProgress(int percent) {
       //下载进度百分比
   }
   @Override
   public void onProcessingProgress(int percent) {
       //处理进度百分比
   }
});
mAliDownloader.setOnErrorListener(new AliMediaDownloader.OnErrorListener() {
   @Override
   public void onError(ErrorInfo errorInfo) {
       //下载出错
   }
});
mAliDownloader.setOnCompletionListener(new AliMediaDownloader.OnCompletionListener() {
   @Override
   public void onCompletion() {
       //下载成功
   }
});

准备下载源。

通过prepare方法准备下载源。下载源支持VidSts和VidAuth两种方式。示例如下：

VidSts

//创建VidSts
VidSts aliyunVidSts = new VidSts();
aliyunVidSts.setVid("Vid信息");//视频ID（VideoId）。
aliyunVidSts.setAccessKeyId("<yourAccessKeyId>");//STS临时AK对的访问密钥ID，需要调用STS服务的AssumeRole接口生成。
aliyunVidSts.setAccessKeySecret"<yourAccessKeySecret>");//STS临时AK对的访问密钥，需要调用STS服务的AssumeRole接口生成。
aliyunVidSts.setSecurityToken("<yourSecurityToken>");//STS安全令牌，需要调用STS服务的AssumeRole接口生成。
aliyunVidSts.setRegion("接入地域");//点播服务的接入地域，默认为cn-shanghai。
//准备下载源
mAliDownloader.prepare(aliyunVidSts)

VidAuth

//创建VidAuth
VidAuth vidAuth = new VidAuth();
vidAuth.setVid("Vid信息");//视频ID（VideoId）。
vidAuth.setPlayAuth("<yourPlayAuth>");//播放凭证，需要调用点播服务的GetVideoPlayAuth接口生成。
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端低延时直播功能，详情请参见阿里云播放器SDK集成Native RTS SDK实现说明（Android端）。

异常处理

使用阿里云播放器播放视频发生异常时，可借助单点探查功能快速定位问题，详细内容，请参见单点追查。

播放

短视频列表播放

使用限制

操作步骤

外挂字幕

纯音频播放

软硬解切换

网络自适应切换视频清晰度

截图

试看

设置黑名单

设置Referer

设置UserAgent

配置网络重试时间和次数

配置缓存和延迟控制

设置HTTP Header

RTS降级播放

切换左右声道

解析音频流

性能

本地缓存

大缓存

预加载

获取下载速度

网络特性

使用HTTP/2

使用HTTP/3

视频下载

使用说明

操作步骤

后续操作

视频加密播放

Native RTS播放

异常处理

相关文档