ApsaraVideo VOD：基礎功能

設定播放源（DataSource）

• Android播放器SDK支援4種點播播放方式，包括：VidAuth播放（ApsaraVideo for VOD使用者推薦使用）、VidSts播放、UrlSource播放、加密播放。

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

點播視訊播放

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);// 播放地址的有效時間長度，單位：秒。該時間長度會覆蓋在ApsaraVideo for VOD控制台設定的URL鑒權的有效時間長度。如果不傳，則取預設值3600。如需設定此參數，請確保該時間大於視頻的實際時間長度，防止播放地址在播放完成前到期。
        
   //若您在VOD控制台開啟了HLS標準加密參數透傳，且預設的參數名為MtsHlsUriToken，那麼需要設定config，並將其傳入vid中，參考下述
   VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
   vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
   vidAuth.setPlayerConfig(config);
   aliPlayer.setDataSource(vidAuth);

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);// 播放地址的有效時間長度，單位：秒。該時間長度會覆蓋在ApsaraVideo for VOD控制台設定的URL鑒權的有效時間長度。如果不傳，則取預設值3600。如需設定此參數，請確保該時間大於視頻的實際時間長度，防止播放地址在播放完成前到期。
        
       //若您在VOD控制台開啟了HLS標準加密參數透傳，且預設的參數名為MtsHlsUriToken，那麼需要設定config，並將其傳入vid中，參考下述
       //若您未在VOD控制台開啟了HLS標準加密參數透傳，那麼則不需要整合下述代碼
       VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
       vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
       vidSts.setPlayerConfig(config);
       aliPlayer.setDataSource(vidSts);

 UrlSource urlSource = new UrlSource();
        urlSource.setUri("播放地址");// 必選參數，播放地址，可以是第三方點播地址，或阿里雲ApsaraVideo for VOD服務中的播放地址，也可以是本地視頻地址。
        aliPlayer.setDataSource(urlSource);

直播視頻播放

詳情請參見標準直播播放。

控制播放

Android播放器SDK支援從指定時間點播放、開始、暫停、停止播放等操作。

準備播放

aliPlayer.prepare();

開始播放

aliPlayer.start();

從指定時間開始播放

// posotion為指定的時間，單位：毫秒。
aliPlayer.seekTo(long position);

// 設定下次播放器prepare時的起播時間（毫秒），僅對緊接著的一次prepare生效。
// 調用prepare後，該值會被內部自動清零；若再次prepare前未重新調用此方法，則按普通方式起播。
// seekMode可指定為精準或非精準模式。
aliPlayer.setStartTime(time, seekMode);

暫停播放

aliPlayer.pause();

恢複播放

aliPlayer.start();

停止播放

aliPlayer.stop();

銷毀播放器

//同步銷毀，內部會自動調用stop介面
aliPlayer.release();
//非同步銷毀，內部會自動調用stop介面
aliPlayer.releaseAsync();	

播放器狀態監聽

Android播放器SDK支援設定播放器監聽和監聽播放狀態。

設定播放器監聽

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() {
        // 準備完成
    }
});
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) {
        //載入進度。百分比和網速。
        //網速為預留欄位，暫時為0
    }

    @Override
    public void onLoadingEnd() {
        //結束載入。畫面和聲音可以播放。
        //一般在此處隱藏圓形載入。
    }
});

監聽播放狀態

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

設定顯示模式

Android播放器SDK支援填充、旋轉、鏡像等顯示設定。

填充

// 設定寬高比適應（將按照視頻寬高比等比縮小到view內部，不會有畫面變形）
aliPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FIT);
// 設定寬高比填充（將按照視頻寬高比等比放大，充滿view，不會有畫面變形）
aliPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FILL);
// 設定展開填充（如果視頻寬高比例與view比例不一致，會導致畫面變形）
aliPlayer.setScaleMode(ScaleMode.SCALE_TO_FILL);

旋轉

// 設定畫面順時針旋轉0度
aliPlayer.setRotateMode(RotateMode.ROTATE_0);
// 設定畫面順時針旋轉90度
aliPlayer.setRotateMode(RotateMode.ROTATE_90);
// 設定畫面順時針旋轉180度
aliPlayer.setRotateMode(RotateMode.ROTATE_180);
// 設定畫面順時針旋轉270度
aliPlayer.setRotateMode(RotateMode.ROTATE_270);
// 擷取旋轉角度
aliPlayer.getRotateMode();

鏡像

// 設定無鏡像
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_NONE);
// 設定水平鏡像
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_HORIZONTAL);
// 設定垂直鏡像
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_VERTICAL);

擷取播放資訊

Android播放器SDK支援擷取當前的播放進度、播放時間長度和緩衝進度等資訊。

擷取當前播放進度

aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.CurrentPosition){
            // extraValue為當前播放進度，單位為毫秒
            long extraValue = infoBean.getExtraValue();
        }
    }
});

擷取播放時間長度

long duration = aliPlayer.getDuration();

擷取實際播放時間長度

long duration = aliPlayer.getPlayedDuration();

擷取緩衝進度

aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.BufferedPosition){
            // extraValue為當前緩衝進度，單位為毫秒
            long extraValue = infoBean.getExtraValue();
        }
    }
});

擷取即時渲染幀率、音視頻碼率、網路下行碼率

// 擷取當前渲染的幀率，資料類型為Float。
aliPlayer.getOption(IPlayer.Option.RenderFPS);
// 擷取當前播放的視頻碼率，資料類型為Float，單位為bps。
aliPlayer.getOption(IPlayer.Option.VideoBitrate);
// 擷取當前播放的音頻碼率，資料類型為Float，單位為bps。
aliPlayer.getOption(IPlayer.Option.AudioBitrate);
// 擷取當前的網路下行碼率，資料類型為Float，單位為bps。
aliPlayer.getOption(IPlayer.Option.DownloadBitrate);

音畫不同步回調

aliPlayer.setOnAVNotSyncStatusListener(new IPlayer.OnAVNotSyncStatusListener() {
    @Override
    public void onAVNotSyncStart(int type) {
        if (type == 0) {
            //降低播放倍速
            if (aliPlayer.getSpeed() > 1) {
                aliPlayer.setSpeed(1);
            }
        }
        Toast.makeText(getContext(), "音畫不同步開始" , Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onAVNotSyncEnd() {
        Toast.makeText(getContext(), "音畫不同步結束" , Toast.LENGTH_SHORT).show();
    }
});

設定音量

設定音量包括音量大小和靜音設定。

音量大小

// volume的值為0～2之間的實數。
aliPlayer.setVolume(1f);
// 擷取音量資訊。
aliPlayer.getVolume();

靜音設定

aliPlayer.setMute(true);

倍速播放

// 設定倍速播放：支援0.5～5倍速的播放，通常按0.5的倍數來設定，例如0.5倍、1倍、1.5倍等
aliPlayer.setSpeed(1.0f);

多清晰度設定

直播UrlSource播放方式

詳情請參見標準直播播放。

點播Vid播放方式（VidAuth或VidSts）

如果使用Vid方式（VidAuth或VidSts）播放，無需額外設定。Android播放器SDK會從點播服務擷取清晰度列表。

擷取清晰度

當視頻載入完成後，可以擷取視頻的清晰度。

//擷取媒體所有的流資訊
List<TrackInfo> trackInfos = aliPlayer.getMediaInfo().getTrackInfos();
//遍曆並擷取清晰度
for (TrackInfo trackInfo : trackInfos) {
     if(trackInfo.getType() == TrackInfo.Type.TYPE_VOD){
             //擷取視頻清晰度
        String vodDefinition = trackInfo.getVodDefinition();
     }
}

切換清晰度

通過selectTrack方法切換清晰度，傳遞對應TrackInfo的index即可。

aliPlayer.selectTrack(index);

清晰度切換通知

清晰度切換成功與失敗回調。

aliPlayer.setOnTrackChangedListener(new IPlayer.OnTrackChangedListener() {
    @Override
    public void onChangedSuccess(TrackInfo trackInfo) { }

    @Override
    public void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo) { }
});

快切模式

開啟快切模式後，手動調用selectTrack時，都會快速得到響應。

PlayerConfig config = aliPlayer.getConfig();
config.mSelectTrackBufferMode = 1;
aliPlayer.setConfig(config)

迴圈播放

aliPlayer.setLoop(true);

aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if (infoBean.getCode() == InfoCode.LoopingStart){
            //迴圈播放開始事件。
        }
    }
});

切換音軌

Android播放器SDK提供了切換音軌的功能，適用於使用者觀看多語言配音的視頻時可以自主進行配音語言切換等情境。

使用樣本

1. 設定回調。

   aliPlayer.setOnSubTrackReadyListener(new IPlayer.OnSubTrackReadyListener() {
       @Override
       //onSubTrackReady回調，通常發生在prepare回調之前。
       public void onSubTrackReady(MediaInfo mediaInfo) {
           if (mPlayerTrackFragment != null) {
               //mPlayerTrackFragment.showMediaInfo();
               //通過getSubMediaInfo主動擷取對應的MediaInfo資訊，需要在收到onSubTrackReady回調後才可以調用，否則為空白。
               MediaInfo subMediaInfo = aliPlayer.getSubMediaInfo();
               TrackInfos = subMediaInfo.getTrackInfos();
               //判斷要選擇的Track
               myTrack = myfunc(TrackInfos)
           }
       }
   });

2. 切換音軌。

   index = myTrack.getIndex();
   aliPlayer.selectTrack(index);

縮圖使用

在播放器SDK中使用縮圖前，請確保已為視頻配置縮圖，即視頻已產生雪碧截圖（在ApsaraVideo for VOD控制台建立類型為雪碧圖的截圖模板，通過工作流程將視頻用該雪碧圖的截圖模板處理後，產生雪碧圖資料），詳細內容請參見視頻截圖。播放器SDK中使用縮圖的範例程式碼如下：

mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        //1.擷取縮圖URL。
        List<Thumbnail> thumbnailList = mAliPlayer.getMediaInfo().getThumbnailList();
        //2.建立縮圖協助類。
        ThumbnailHelper mThumbnailHelper = new ThumbnailHelper(thumbnailList.get(0).mURL);
        //3.設定監聽。
        mThumbnailHelper.setOnPrepareListener(new ThumbnailHelper.OnPrepareListener() {
            @Override
            public void onPrepareSuccess() {
                //5.縮圖載入成功後，可以請求擷取指定位置的縮圖。
            }
            @Override
            public void onPrepareFail() {}
        });

        mThumbnailHelper.setOnThumbnailGetListener(new ThumbnailHelper.OnThumbnailGetListener() {
            @Override
            public void onThumbnailGetSuccess(long positionMs, ThumbnailBitmapInfo thumbnailBitmapInfo) {
                //6.擷取指定位置縮圖的Bitmap。
                Bitmap thumbnailBitmap = thumbnailBitmapInfo.getThumbnailBitmap();
            }
            @Override
            public void onThumbnailGetFail(long positionMs, String errorMsg) {}
        });

        //4.載入縮圖。
        mThumbnailHelper.prepare();
    }
});

請注意：如果播放方式為URL的時候，AliPlayer 可能並不能擷取到ThumbnailList，建議使用者直接指定縮圖的URL。

mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        //1.建立縮圖協助類。
        ThumbnailHelper mThumbnailHelper = new ThumbnailHelper(URL);
        //2.設定監聽。
        mThumbnailHelper.setOnPrepareListener(new ThumbnailHelper.OnPrepareListener() {
            @Override
            public void onPrepareSuccess() {
                //4.縮圖載入成功後，可以請求擷取指定位置的縮圖。
            }
            @Override
            public void onPrepareFail() {}
        });

        mThumbnailHelper.setOnThumbnailGetListener(new ThumbnailHelper.OnThumbnailGetListener() {
            @Override
            public void onThumbnailGetSuccess(long positionMs, ThumbnailBitmapInfo thumbnailBitmapInfo) {
                //5.擷取指定位置縮圖的Bitmap。
                Bitmap thumbnailBitmap = thumbnailBitmapInfo.getThumbnailBitmap();
            }
            @Override
            public void onThumbnailGetFail(long positionMs, String errorMsg) {}
        });

        //3.載入縮圖。
        mThumbnailHelper.prepare();
    }
});

擷取SDK日誌

在播放器SDK運行過程中會產生詳細的日誌資訊，包括網路請求的狀態、系統調用的結果、許可權申請情況等各種運行時事件。開發人員可以通過查看這些日誌進行代碼調試或排查問題，提高開發效率。

方式一：通過開發工具的控制台擷取播放器SDK日誌

此方式適用於在您本地可以複現問題並抓取日誌的情境。

1. 開啟日誌並設定記錄層級。

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

2. 設定幀層級日誌。

   //設定幀層級日誌列印
   //選項value 0代表關閉	1代表開啟
   Logger.getInstance(this).setLogOption(Logger.LogOption.FRAME_LEVEL_LOGGING_ENABLED,value);

   說明

   設定幀層級日誌功能主要在排查故障情境下使用。

3. 收集日誌。

   複現問題後，可在您開發工具（例如Logcat）的控制台擷取日誌。

方式二：通過LogCallback監聽播放器SDK的輸出日誌

此方式適用於問題發生在您的使用者側，在您本地無法複現問題並抓取日誌的情境。可以通過LogCallback監聽播放器SDK的輸出日誌，並自動輸出到您App的日誌通道中。

1. 開啟日誌並設定記錄層級。

   // 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){
               // 日誌
           }
   });

2. 收集日誌。

   複現問題後，日誌將通過您App的日誌通道自動輸出到您App的記錄檔。

相關文檔

• 詳細的介面描述，請參見API說明。

• 更多進階功能的使用方法，請參見進階功能。

• 播放異常時，常見問題及解決方案，請參見播放異常自主排查、Android播放器常見問題、移動端錯誤碼。