ApsaraVideo VOD：進階功能

播放帶透明度視頻

/**
 * 設定Alpha渲染模式
 *
 * @param alphaRenderMode 鏡像模式。見{@link AlphaRenderMode}。
 */
/****
 * Set a alpha render mode
 *
 * @param alphaRenderMode The specified alpha render mode. See {@link AlphaRenderMode}.
 */
abstract public void setAlphaRenderMode(AlphaRenderMode alphaRenderMode);

//--------------View用法-------------
// 對於View需要設定透明
//TextureView
TextureView aliplayerView; //用於播放的 view
aliplayerView.setOpaque(false);

//SurfaceView
SurfaceView aliplayerView; //用於播放的 view
aliplayerView.getHolder().setFormat(PixelFormat.TRANSLUCENT);
aliplayerView.setZOrderOnTop(true); //把SurfaceView置於顯示視窗的最頂層

//-----------AliPlayer用法-----------
//設定alpha模式
aliPlayer.setAlphaRenderMode(IPlayer.AlphaRenderMode.RENDER_MODE_ALPHA_AT_RIGHT);
//設定alpha模式對應的素材
UrlSource urlSource = new UrlSource();
urlSource.setUri("https://alivc-player.oss-cn-shanghai.aliyuncs.com/video/%E4%B8%9A%E5%8A%A1%E9%9C%80%E6%B1%82%E6%A0%B7%E6%9C%AC/alpha%E9%80%9A%E9%81%93/alpha_right.mp4");
aliPlayer.setDataSource(urlSource);
aliPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
    @Override
    public void onCompletion() {
        //可選：單一實例播放完成後如果有銜接問題，可以清屏
        aliPlayer.clearScreen();
    }
}
aliPlayer.setAutoPlay(true);
aliPlayer.prepare();

Android播放器SDK支援添加和切換外掛字幕，現已支援SRT、SSA、ASS、VTT這4種格式的字幕。

樣本如下：

1. 建立顯示字幕的View。

   根據不同的字幕格式建立不同的View。

   展開查看代碼

   //用於顯示SRT和VTT字幕
   SubtitleView subtitleView = new SubtitleView(getContext());
   //對於播放器V7.6.0及以上版本，建議使用VttSubtitleView顯示SRT和VTT字幕
   VttSubtitleView vttSubtitleView = new VttSubtitleView(getContext());
   //用於顯示ASS和SSA字幕
   AssSubtitleView assSubtitleView = new AssSubtitleView(getContext());
   //將字幕View添加到布局視圖中
   viewGroup.addView(assSubtitleView);

   當整合播放器V7.6.0及以上版本且使用VttSubtitleView顯示SRT和VTT字幕時，需設定以下監聽：

   //播放器7.6.0及以上版本必須
   mAliPlayer.setOnVideoSizeChangedListener(new IPlayer.OnVideoSizeChangedListener() {
       @Override
       public void onVideoSizeChanged(int width, int height) {
           int viewWidth = getWidth();
           int viewHeight = getHeight();
           IPlayer.ScaleMode mode = mVideoListPlayer.getScaleMode();
           SubTitleBase.VideoDimensions videoDimensions = SubTitleBase.getVideoDimensionsWhenRenderChanged(width, height, viewWidth, viewHeight, mode);
           vttSubtitleView.setVideoRenderSize(videoDimensions.videoDisplayWidth, videoDimensions.videoDisplayHeight);
       }
   });

2. 添加字幕。

   重要

   字幕檔案需要在onPrepared中進行設定。

   mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
       @Override
       public void onPrepared() {
           // 字幕設定（需要在 onPrepared 中進行設定）
           mAliPlayer.addExtSubtitle(EXT_SUBTITLE_URL);
       }
   });

3. 設定字幕相關監聽。

   展開查看代碼

   mAliPlayer.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
               @Override
               public void onSubtitleExtAdded(int trackIndex, String url) {
                   //trackIndex：傳入字幕索引；true：表示顯示傳入的字幕；false：表示隱藏傳入的字幕
                   mAliPlayer.selectExtSubtitle(trackIndex, true);
               }
   
               @Override
               public void onSubtitleShow(int trackIndex, long id, String data) {
                   // 字幕
                   SubtitleView.Subtitle subtitle = new SubtitleView.Subtitle();
                   subtitle.id = String.valueOf(id);
                   subtitle.content = data;
                   // 顯示字幕
                   mSubtitleView.show(subtitle);
               }
   
               @Override
               public void onSubtitleHide(int trackIndex, long id) {
                   // 去除字幕
                   mSubtitleView.dismiss(String.valueOf(id));
               }
   
               @Override
               public void onSubtitleHeader(int trackIndex, String header) {
               }
           }
       );

當前機型包含在雲端H265黑名單機型庫或者播放H265流硬解失敗時，觸發自適應降級。具體的降級流程為：若已設定H264備流，自動播放H264備流；若未設定H264備流，則自動降級為H265軟解播放。

設定備流樣本如下：

// 應用程式層維護一個Map，儲存所有原URL-備URL的索引值對，切換時根據原URL在Map中查詢備URL
 AliPlayerGlobalSettings.setAdaptiveDecoderGetBackupURLCallback(new AliPlayerGlobalSettings.OnGetBackupUrlCallback() {
    @Override
    public String getBackupUrlCallback(int oriBizScene, int oriCodecType, String original_url) {
        String kurl = original_url;
        if (!H265toH264Map.get(kurl).isEmpty()) {
            return H265toH264Map.get(kurl);
        } else {
            return "";
        }
    }
});

Android播放器SDK通過配合點播服務配置，可以實現試看功能，支援VidSts和VidAuth（ApsaraVideo for VOD推薦使用此方式）兩種播放方式。如何配置和使用試看功能，請參見試看視頻。

VidSts vidSts = new VidSts;
....
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
configGen.setPreviewTime(20);//20秒試看
vidSts.setPlayConfig(configGen);//設定給播放源
...

Android播放器SDK通過PlayerConfig提供了設定緩衝和延遲的控制介面。樣本如下：

//先擷取配置
PlayerConfig config = aliPlayer.getConfig();
//最大延遲。注意：直播有效。當延時比較大時，播放器sdk內部會追幀等，保證播放器的延時在這個範圍內。
config.mMaxDelayTime = 5000;
// 最大緩衝區時間長度。單位ms。播放器每次最多載入這麼長時間的緩衝資料。
config.mMaxBufferDuration = 50000;
//高緩衝時間長度。單位ms。當網路不好導致載入資料時，如果載入的緩衝時間長度到達這個值，結束載入狀態。
config.mHighBufferDuration = 3000;
// 起播緩衝區時間長度。單位ms。這個時間設定越短，起播越快。也可能會導致播放之後很快就會進入載入狀態。
config.mStartBufferDuration = 500;
....//其他設定
//往前緩衝的最大時間長度。單位ms。預設為0。
config.mMaxBackwardBufferDurationMs = 0;

//設定配置給播放器
aliPlayer.setConfig(config);

畫中畫

操作流程如下：

1. 在AndroidManifest.xml檔案中,聲明畫中畫許可權。

   <activity
     android:name=".PictureInPictureActivity"
     android:exported="true"
     android:supportsPictureInPicture="true"
     android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation" />

2. 將目標Activity切換到畫中畫模式。

   Rational aspectRatio = new Rational(16, 9); // 畫中畫的寬高比，根據自身業務可調整
   PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
   pipBuilder.setAspectRatio(aspectRatio);
   enterPictureInPictureMode(pipBuilder.build());

   可以選擇從 OnClick（點擊事件）、離開應用或者返回應用時觸發畫中畫模式，實現方式如下：

   OnClick（點擊事件）觸發

   button.setOnClickListener(new View.OnClickListener() {
       @Override
       public void onClick(View v) {
           Rational aspectRatio = new Rational(16, 9); // 畫中畫的寬高比
           PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
           pipBuilder.setAspectRatio(aspectRatio);
           enterPictureInPictureMode(pipBuilder.build());
       }
   });

   離開應用觸發

   @Override
   protected void onUserLeaveHint() {
       super.onUserLeaveHint();
       Rational aspectRatio = new Rational(16, 9); // 畫中畫的寬高比
       PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
       pipBuilder.setAspectRatio(aspectRatio);
       enterPictureInPictureMode(pipBuilder.build());
   
       Log.e(TAG, "畫中畫 onUserLeaveHint");
   }

   返回應用觸發

   @Override
   public void onBackPressed() {
       super.onBackPressed();
       // 從返回觸發
       enterPictureInPictureMode();
   }

3. 處理畫中畫顯示/消失的UI。

   @Override
   public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode, Configuration newConfig) {
       super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig);
       if (isInPictureInPictureMode) {
           // 進入畫中畫模式時的處理
           // hide UI
           Log.e(TAG, "進入畫中畫模式");
       } else {
           // 退出畫中畫模式時的處理
           // show UI 
           Log.e(TAG, "退出畫中畫模式");
       }
   }

直播RTS降級

詳情請參見RTS直播播放。

Android播放器SDK通過setOutputAudioChannel方法設定輸出聲道，如果輸入源是雙聲道，則支援通過下述方法切換為左聲道或右聲道；如果輸入源是單聲道，則設定無效。

/*
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_LEFT 切換到左聲道播放,
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_RIGHT 切換到右聲道播放,
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_NONE 不切換聲道，保持輸入源聲道播放
*/
aliPlayer.setOutputAudioChannel();

設定監聽，可擷取音視頻流資料。音視頻不能是加密流，加密流無法解析。

//可選配置1：是否返回底層資料的地址
IPlayer.RenderFrameCallbackConfig config = new IPlayer.RenderFrameCallbackConfig();
config.mVideoDataAddr = true;//是否只返回底層視頻資料地址
config.mAudioDataAddr = true;//是否只返回底層音頻資料地址
aliPlayer.setRenderFrameCallbackConfig(config);

//可選配置2：硬解時，RenderFrame返回 texture_oes_id，軟解時，RenderFrame返回來源資料
aliPlayer.enableHardwareDecoder(true);
//設定監聽，擷取音視頻資料
aliPlayer.setOnRenderFrameCallback(frameInfo -> {
    if (frameInfo.frameType == FrameInfo.FrameType_video) {
        //視頻資料
    } else {
        //音頻資料
    }
    return false;
});

Android播放器SDK支援設定播放器渲染的背景色。介面和用法說明如下：

介面樣本

/**
 * 設定視頻的背景色
 *
 * @param color  ARGB
 *
 */
/****
 * Set video background color
 * @param color  ARGB
 */
abstract public void setVideoBackgroundColor(int color);

用法說明

//參數為8位16進位資料，8位元據兩兩為一組，按照順序分別表示A(alpha 透明度) R(red) G(green) B(blue)
//例如0x0000ff00，表示綠色
aliPlayer.setVideoBackgroundColor(0x0000ff00);

vidAuth設定指定播放網域名稱

通過vidAuth方式可以指定vid對應的網域名稱等欄位，支援的欄位詳情請參見GetPlayInfo請求參數。介面及用法說明如下：

介面樣本

/**
 * 設定播放參數
 *
 * @param playConfig 播放參數
 */
public void setPlayConfig(VidPlayerConfigGen playConfig);

用法說明

通過其中的VidPlayerConfigGen介面的addPlayerConfig添加playDomain欄位。

vidAuth = new VidAuth();
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
//增加playDomain欄位，可以添加的欄位參考
//https://www.alibabacloud.com/help/zh/vod/developer-reference/api-vod-2017-03-21-getplayinfo
configGen.addPlayerConfig("playDomain", "com.xxx.xxx");
vidAuth.setPlayConfig(configGen);

H.266解碼外掛程式

H.266（VVC/Versatile Video Coding）作為新一代視頻編碼通訊協定，能在同等畫質下大幅節省碼率。為最佳化效能並控制主SDK體積，H.266增值解碼能力以外掛程式形式獨立封裝，支援按需整合。

前提條件

1. 播放器/一體化SDK為V7.6.0及以上版本。

2. 已完成專業版License授權，詳情請參見擷取播放器SDK License。

3. 阿里雲播放器搭配H.266解碼外掛程式僅支援播放阿里雲轉碼的H.266視頻。

整合外掛程式

// x.x.x與播放器SDK版本號碼保持一致
com.aliyun.sdk.android:AlivcVVCCodec:x.x.x

// x.x.x與所用一體化SDK版本號碼保持一致
com.aliyun.sdk.android:AlivcVVCCodec:x.x.x-aio

啟用外掛程式

AliPlayerGlobalSettings.enableCodecPlugin("vvc", true);

相關錯誤碼

H.266解碼外掛程式相關錯誤碼請參見各端播放器公用常見問題。

自動重新整理播放源

啟用播放源自動重新整理功能可防止鑒權機制下到期導致的播放中斷，此功能會在源失效時觸發監聽並擷取新地址，確保視頻持續流暢播放。

前提條件

1. 播放器/一體化SDK為V7.9.0及以上版本。

2. 使用VidAuth源進行播放或業務配置了URL鑒權。

/**
 * 設定 VidAuth 源到期監聽器。
 *
 * 此功能用於啟用 VidAuth 源到期重新整理機制，防止 VidAuth 源鑒權到期導致的視頻播放中斷。
 * 當監聽器被觸發時，您可以重新整理 VidAuth 源，並通過 {@link SourceRefreshCallback#onSuccess} 提交新的 VidAuth 源，
 * 以確保視頻播放穩定和流暢。
 *
 * @param listener 監聽 VidAuth 源到期事件的介面。見 {@link OnVidAuthExpiredListener}。
 */
/****
 * Sets the listener for VidAuth source expiration events.
 *
 * This feature enables automated VidAuth source refresh to avoid playback interruptions
 * caused by expiration. When the listener is triggered, you can refresh the VidAuth source
 * and return the updated VidAuth using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener The interface for listening to VidAuth source expiration events. See {@link OnVidAuthExpiredListener}.
 *
 */
abstract public void setOnVidAuthExpiredListener(OnVidAuthExpiredListener listener);

/**
 * VidAuth 源到期通知監聽器，用於處理 VidAuth 源的到期事件。
 */
/****
 * Listener for VidAuth source expiration notifications.
 * Handles events when a VidAuth source expires.
 */
public interface OnVidAuthExpiredListener {

    /**
     * 當播放器檢測到 VidAuth 源到期時觸發回調。VidAuth 源到期包含PlayAuth到期與播放地址到期。
     *
     * 您可以在此回調中重新整理 VidAuth 源，並通過 {@link SourceRefreshCallback#onSuccess} 返回新的 VidAuth 源。
     *
     * @param expiredSource 已到期的 VidAuth 來源物件。見 {@link VidAuth}。
     * @param callback 提供新的 VidAuth 源給播放器的回調介面。見 {@link SourceRefreshCallback}。
     */
    /****
     * Called when the player detects that the VidAuth source has expired.
     *
     * You can refresh the VidAuth source in this callback and return the new VidAuth
     * using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired VidAuth source object. See {@link VidAuth}.
     * @param callback The callback used to provide the updated VidAuth source to the player. See {@link SourceRefreshCallback}.
     */
    void onVidAuthExpired(VidAuth expiredSource, SourceRefreshCallback<VidAuth> callback);
}

/**
 * 播放源重新整理回調介面，用於處理播放源重新整理結果。
 *
 * 此介面適用於需要動態更新的播放源類型，例如 URL 源或 VidAuth 源。
 * 當播放器觸發重新整理請求後，您可以通過此介面返回重新整理結果。
 * 選擇調用 `onSuccess` 或 `onError` 方法。
 */
/****
 * A callback interface for handling playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as URL source or VidAuth source. When the player triggers a refresh request,
 * the refresh result can be returned via this interface by invoking either the `onSuccess` or `onError` method.
 */
public interface SourceRefreshCallback<T extends SourceBase> {
    /**
     * 當重新整理操作成功時由播放器調用。
     *
     * @param newSource 包含更新資訊的新播放來源物件。見 {@link SourceBase}。
     *
     * 此方法表示重新整理操作已成功完成，開發人員需要在此方法中提供新的播放源，
     * 以使播放器能夠載入最新的資源。
     */
    /****
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object containing the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. Developers should provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    void onSuccess(T newSource);

    /**
     * 當重新整理操作失敗時由播放器調用。
     *
     * @param errorMsg 描述失敗原因的錯誤資訊。
     *
     * 此方法表示重新整理操作失敗，開發人員可以使用 `errorMsg` 提供的失敗資訊，
     * 捕獲錯誤原因並進行後續處理。
     */
    /****
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string describing the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. Developers can use the `errorMsg`
     * to capture details of the failure and proceed with subsequent handling.
     */
    void onError(String errorMsg);
}

// 設定VID播放憑證到期監聽器
aliPlayer.setOnVidAuthExpiredListener(new AliPlayer.OnVidAuthExpiredListener() {
    @Override
    public void onVidAuthExpired(VidAuth vidAuth, UrlPlayer.SourceRefreshCallback<VidAuth> sourceRefreshCallback) {
        
        String vid = vidAuth.getVid();

        // ------------------- 使用者實現部分開始 -------------------
        // 調用您自己實現的、從App伺服器擷取新PlayAuth的函數。
        // clinetGetPlayAuthFunction 是一個樣本函數名，您需要替換為您自己的實現。
        clinetGetPlayAuthFunction(vid, new PlayAuthCallback() {
            
            /**
             * 成功擷取到新憑證的回調。
             * @param newPlayAuth 從您的伺服器擷取到的新播放憑證字串。
             */
            @Override
            public void onAuthSuccess(String newPlayAuth) {                
                // 1. 使用新的PlayAuth更新舊的vidAuth對象
                vidAuth.setPlayAuth(newPlayAuth);
                
                // 2. 將更新後的對象通過SDK的回調傳回給播放器
                sourceRefreshCallback.onSuccess(vidAuth);
            }

            /**
             * 擷取新憑證失敗的回調。
             * @param errorMessage 詳細的錯誤資訊。
             */
            @Override
            public void onAuthError(String errorMessage) {                
                // 將錯誤資訊通過SDK的回調傳回給播放器
                sourceRefreshCallback.onError(errorMessage);
            }
        });
        // ------------------- 使用者實現部分結束 -------------------
    }
});

/**
 * 設定 URL 源到期監聽器。
 *
 * 此功能用於啟用 URL 源到期重新整理機制，避免由於鑒權等導致的 URL 源到期情況，引發播放中斷。
 * 當監聽器觸發時，您可以重新整理 URL 源並通過 {@link SourceRefreshCallback#onSuccess} 提交新的 URL 源，
 * 以確保視頻播放持續流暢。
 *
 * @param listener 用於處理 URL 源到期事件的監聽器。見 {@link OnURLSourceExpiredListener}。
 *
 * <p>關於 URL 鑒權機制的配置，請參考：<a href="https://www.alibabacloud.com/help/zh/vod/user-guide/configure-url-signing?spm=a2c4g.11186623.0.0.560c4140fGh8MW">URL 鑒權文檔</a></p>
 */
/****
 * Sets the listener for URL source expiration events.
 *
 * This feature enables URL refresh to avoid playback interruptions caused by
 * URL expiration due to authentication. When the listener is triggered,
 * you can refresh the URL source and return the updated URL source using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener Listener for handling URL source expiration events. See {@link OnURLSourceExpiredListener}.
 *
 * <p>For more information on configuring URL authentication, see
 * <a href="https://www.alibabacloud.com/help/zh/vod/user-guide/configure-url-signing?spm=a2c4g.11186623.0.0.560c4140fGh8MW">URL authentication documentation</a>.</p>
 */
abstract public void setOnURLSourceExpiredListener(OnURLSourceExpiredListener listener);

/**
 * 播放源重新整理回調介面，用於處理播放源重新整理結果。
 *
 * 此介面適用於需要動態更新的播放源類型，例如 URL 源或 VidAuth 源。
 * 當播放器觸發重新整理請求後，您可以通過此介面返回重新整理結果。
 * 選擇調用 `onSuccess` 或 `onError` 方法。
 */
/****
 * A callback interface for handling playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as URL source or VidAuth source. When the player triggers a refresh request,
 * the refresh result can be returned via this interface by invoking either the `onSuccess` or `onError` method.
 */
public interface SourceRefreshCallback<T extends SourceBase> {
    /**
     * 當重新整理操作成功時由播放器調用。
     *
     * @param newSource 包含更新資訊的新播放來源物件。見 {@link SourceBase}。
     *
     * 此方法表示重新整理操作已成功完成，開發人員需要在此方法中提供新的播放源，
     * 以使播放器能夠載入最新的資源。
     */
    /****
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object containing the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. Developers should provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    void onSuccess(T newSource);

    /**
     * 當重新整理操作失敗時由播放器調用。
     *
     * @param errorMsg 描述失敗原因的錯誤資訊。
     *
     * 此方法表示重新整理操作失敗，開發人員可以使用 `errorMsg` 提供的失敗資訊，
     * 捕獲錯誤原因並進行後續處理。
     */
    /****
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string describing the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. Developers can use the `errorMsg`
     * to capture details of the failure and proceed with subsequent handling.
     */
    void onError(String errorMsg);
}

/**
 * URL源到期通知監聽器，用於處理資源到期並防止播放中斷。
 */
/****
 * Listener for URL source expiration notifications.
 * This helps process expired sources and prevents playback interruptions.
 */
public interface OnURLSourceExpiredListener {

    /**
     * 當播放器檢測到 URL 源 (UrlSource) 到期時觸發回調。
     *
     * 您可在此回調中重新整理 URL 源，並通過 {@link SourceRefreshCallback#onSuccess} 返回新的 URL 源。
     *
     * @param expiredSource 已到期的 UrlSource 對象。見 {@link UrlSource}。
     * @param callback 重新整理的回調，用於將新的 UrlSource 返回給播放器。見 {@link SourceRefreshCallback}。
     */
    /****
     * Called when the player detects that the URL source (UrlSource) has expired.
     *
     * You can refresh the URL source in this callback and return the new UrlSource
     * using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired UrlSource object. See {@link UrlSource}.
     * @param callback The refresh callback used to return the updated UrlSource to the player. See {@link SourceRefreshCallback}.
     */
    void onUrlSourceExpired(UrlSource expiredSource, SourceRefreshCallback<UrlSource> callback);
}

// 設定播放器的URL到期監聽器
mAliyunVodPlayer.setOnURLSourceExpiredListener(new UrlPlayer.OnURLSourceExpiredListener() {
    @Override
    public void onUrlSourceExpired(UrlSource urlSource, UrlPlayer.SourceRefreshCallback<UrlSource> sourceRefreshCallback) {
        String expiredUrl = urlSource.getUri();
        Log.d(TAG, "[onUrlSourceExpired] Received expired URL: " + expiredUrl);

        // 1. 檢查鑒權密鑰是否有效 (假設 authenticationKey 是類的成員變數)
        if (authenticationKey == null || authenticationKey.trim().isEmpty()) {
            Log.e(TAG, "Refresh failed: Authentication key is empty.");
            sourceRefreshCallback.onError("REFRESH_ERROR: Authentication key is missing.");
            return; // 密鑰無效，提前退出
        }

        // 2. 計算播放地址的逾時時間（有效期間）
        // 如果類成員 validTime 有效，則使用它，否則預設使用 3600 秒（1小時）
        long validityDuration = (AliyunVodPlayerView.this.validTime > 0) ? validTime : 3600;
        long newExpireTime = (System.currentTimeMillis() / 1000) + validityDuration;

        // 3. 從到期的URL中提取原始URL (以鑒權方式A為例)
        // 通過移除URL參數部分 (如 "?auth_key=") 恢複原始資源地址
        int authKeyIndex = expiredUrl.indexOf("?auth_key=");
        if (authKeyIndex == -1) {
            authKeyIndex = expiredUrl.indexOf("&auth_key=");
        }
        // 確保即使找不到 auth_key 也能安全處理
        String originalUrl = (authKeyIndex != -1) ? expiredUrl.substring(0, authKeyIndex) : expiredUrl;

        // 4. 使用工具類產生新的鑒權URL
        String newAuthUrl = CdnAuthUtil.aAuth(originalUrl, authenticationKey, newExpireTime);

        // 5. 檢查產生的鑒權URL並通過回調返回結果
        if (newAuthUrl != null && !newAuthUrl.isEmpty()) {
            Log.i(TAG, "Refresh success, new URL: " + newAuthUrl);
            // 根據SDK要求，建立 UrlSource 對象並設定新的URL
            UrlSource resultSource = new UrlSource();
            resultSource.setUri(newAuthUrl);
            sourceRefreshCallback.onSuccess(resultSource);
        } else {
            Log.e(TAG, "Refresh failed: Failed to generate new authorized URL.");
            sourceRefreshCallback.onError("REFRESH_ERROR: Failed to generate new URL.");
        }
    }
});

工具函數補充

以鑒權方式A為例。

// 鑒權URL產生函數
private String generateAuthUrl(String uri, String key, long exp) {
    Pattern uriPattern = Pattern.compile("^(https?://)?([^/?]+)(/[^?]*)?(\\?.*)?$");
    Matcher m = uriPattern.matcher(uri);

    if (!m.matches()) {
        return null;
    }

    String scheme = (m.group(1) != null) ? m.group(1) : "http://";
    String host = m.group(2);
    String path = (m.group(3) != null) ? m.group(3) : "/";
    String args = (m.group(4) != null) ? m.group(4) : "";

    String rand = "0";
    String uid = "0";

    String sstring = String.format("%s-%d-%s-%s-%s", path, exp, rand, uid, key);
    String hashvalue = md5sum(sstring);
    String authKey = String.format("%d-%s-%s-%s", exp, rand, uid, hashvalue);

    if (!args.isEmpty()) {
        return String.format("%s%s%s%s&auth_key=%s", scheme, host, path, args, authKey);
    } else {
        return String.format("%s%s%s%s?auth_key=%s", scheme, host, path, args, authKey);
    }
}

// 計算 MD5 的工具函數
private String md5sum(String src) {
    try {
        MessageDigest md = MessageDigest.getInstance("MD5");
        md.update(src.getBytes(StandardCharsets.UTF_8));
        byte[] digest = md.digest();

        StringBuilder hexString = new StringBuilder();
        for (byte b : digest) {
            hexString.append(String.format("%02x", b));
        }
        return hexString.toString();
    } catch (NoSuchAlgorithmException e) {
        throw new RuntimeException("MD5 algorithm not found", e);
    }
}

Android播放器SDK支援在起播之前快速渲染第一幀，可以提高起播速度。

樣本如下：

aliPlayer.setOption(ALLOW_PRE_RENDER, 1);

Android播放器SDK提供了本機快取的功能，能夠讓使用者重複播放視頻時，提高起播速度、提高seek速度、減少卡頓，也能達到節省流量的目的。

開啟本機快取

// 開啟本機快取（預設路徑）
AliPlayerGlobalSettings.enableLocalCache(true, this);

/**
 *  也可以使用下方代碼進行緩衝設定
 *  開啟本機快取，開啟之後，就會緩衝到本地檔案中。
 *  @param enable：本機快取功能開關。true：開啟，false：關閉，預設關閉。
 *  @param maxBufferMemoryKB：5.4.7.1及以後版本已廢棄，暫無作用。
 *  @param localCacheDir：必須設定，本機快取的檔案目錄，為絕對路徑。
 *  AliPlayerGlobalSettings.enableLocalCache(enable, maxBufferMemoryKB, 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的本機快取

//先擷取配置
PlayerConfig config = aliPlayer.getConfig();
//是否針對播放的URL開啟本機快取，預設值為true。當AliPlayerGlobalSettings處的本地緩開啟時，且同時開啟此處的本機快取，即設定為true，該URL的本機快取才會生效；若此處設定為false，則關閉該URL的本機快取。
config.mEnableLocalCache = false;
....//其他設定

//設定配置給播放器
aliPlayer.setConfig(config);

Android播放器SDK提供預先載入功能，是對本機快取功能的升級，通過設定視頻緩衝的記憶體佔用大小，更能提升視頻的起播速度。

AliPlayerGlobalSettings.enableNetworkBalance(false);

1. 開啟本機快取功能，詳細操作請參見本機快取。

2. 設定資料來源。

   VidAuth（推薦）

   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.setQuality("選擇的清晰度") //"AUTO"代表自適應碼率

   VidSts

   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.setQuality("選擇的清晰度") //"AUTO"代表自適應碼率

   UrlSource

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

3. 設定任務參數。

   說明

   僅適用於多碼率視頻，setDefaultBandWidth、setDefaultResolution、setDefaultQuality三者任選其一即可。

   PreloadConfig preloadConfig = new PreloadConfig();
   // 多碼率流下設定預先載入碼率
   preloadConfig.setDefaultBandWidth(400000);
   // 多碼率流下設定預先載入解析度
   preloadConfig.setDefaultResolution(640 * 480);
   // 多碼率流下設定預先載入品質
   preloadConfig.setDefaultQuality(“FD”);
   // 設定預先載入時間長度
   preloadConfig.setDuration(1000);

4. 新增工作監聽器。

   展開查看代碼

   /**
    * 預先載入監聽器實現
    */
   private static class PreloadListenerImpl extends OnPreloadListener {
   
       @Override
       public void onError(@NonNull String taskId, @NonNull String urlOrVid, @NonNull ErrorInfo errorInfo) {
           //載入出錯
       }
   
       @Override
       public void onCompleted(@NonNull String taskId, @NonNull String urlOrVid) {
           //載入完成
       }
   
       @Override
       public void onCanceled(@NonNull String taskId, @NonNull String urlOrVid) {
          //載入取消
       }
   }

5. 構建任務並添加到MediaLoaderV2執行個體，開始預先載入。

   VidAuth（推薦）

   //構建預先載入
   PreloadTask mPreloadTask = new PreloadTask(vidAuth, preloadConfig);
   //擷取MediaLoaderV2執行個體
   MediaLoaderV2 mediaLoaderV2 = MediaLoaderV2.getInstance();
   //新增工作並開始預先載入
   String taskId = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

   VidSts

   //構建預先載入
   PreloadTask mPreloadTask = new PreloadTask(vidSts, preloadConfig);
   //擷取MediaLoaderV2執行個體
   MediaLoaderV2 mediaLoaderV2 = MediaLoaderV2.getInstance();
   //新增工作並開始預先載入
   String taskId = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl);

   UrlSource

   //構建預先載入
   PreloadTask mPreloadTask = new PreloadTask(urlSource, preloadConfig);
   //擷取MediaLoaderV2執行個體
   MediaLoaderV2 mediaLoaderV2 = MediaLoaderV2.getInstance();
   //新增工作並開始預先載入
   String taskId = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

6. 可選：管理工作。

   mediaLoaderV2.cancelTask(taskId);//取消指定任務ID預先載入任務
   mediaLoaderV2.pauseTask(taskId);//暫停指定任務ID預先載入任務
   mediaLoaderV2.resumeTask(taskId);//恢複指定任務ID預先載入任務

7. 可選：刪除負載檔案。

   可按需刪除負載檔案，以節省空間的。Android播放器SDK不提供刪除介面，需要在App刪除載入目錄下的檔案。

動態預先載入策略，支援整合方既可以控制當前現正播放視頻的緩衝，又可以控制預先載入的個數和緩衝，滿足業務方對播放體驗與成本開銷之間取得平衡的訴求。

// 開啟推薦配置和動態預先載入
aliListPlayer.setPreloadScene(IListPlayer.SceneType.SCENE_SHORT);

// 配置基準預先載入時間長度
// 設定預先載入時間長度為1000ms
PreloadConfig config = new PreloadConfig();
config.mPreloadDuration = 1000;
aliListPlayer.updatePreloadConfig(config);

// 配置預先載入的數量，支援雙向
// 1為向前預先載入的數量，3為向後預先載入的數量
aliListPlayer.setPreloadCount(1, 3);

// 配置動態預先載入的遞減的offset
aliListPlayer.enablePreloadStrategy(IListPlayer.StrategyType.STRATEGY_DYNAMIC_PRELOAD_DURATION, true);
aliListPlayer.setPreloadStrategy(IListPlayer.StrategyType.STRATEGY_DYNAMIC_PRELOAD_DURATION, "{\"algorithm\": \"sub\",\"offset\": \"200\"}");

多碼率HLS視頻預先載入

在listPlayer+多碼率HLS視頻播放情境下，支援整合方預先載入與當前播放清晰度一致的流，並且可以根據業務情況選擇預先載入模式。

  /**
   * 預設配置，播放和預先載入預設碼率
   */
  /****
   * default mode, play and preload default bitrate of a stream
   */
  MultiBitratesMode_Default(0),

  /**
   * 首幀優先配置，起播視頻預設播放已完成預先載入的碼率
   */
  /****
   * First frame cost (FC) priority, decrease first frame cost. only play bitrate of the hls stream which has been preloaded.
   */
  MultiBitratesMode_FCPrio(1),

  /**
   * 兼顧首幀和播放平滑，切換前後（moveToNext）的視頻碼率一致，且兼顧首幀效能
   */
  /****
   * First frame and play smooth, play the same bitrate before and after moveToNext
   */
  MultiBitratesMode_FC_AND_SMOOTH(2),

  /**
   * 播放平滑優先配置，起播視頻預設播放前一個視頻的碼率
   */
  /****
   * Play Smooth priority, play the same bitrate before and after moveToNext.
   */
  MultiBitratesMode_SmoothPrio(3);

//選擇多碼率載入模式
aliListPlayer.SetMultiBitratesMode(preLoadMode);


//（可選）選擇起播碼率
aliListPlayer.setDefaultBandWidth(defaultBandWidth)


//（可選）在onPrepared回調中，選擇abr模式
aliListPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        //abr only effect on multiBitrate m3u8
        aliListPlayer.selectTrack(-1);
    }
});

HTTPDNS

//開啟增強型httpdns
AliPlayerGlobalSettings.enableEnhancedHttpDns(true);
//可選，增加httpdns預解析網域名稱
DomainProcessor.getInstance().addPreResolveDomain("player.***alicdn.com");

HTTP/2

AliPlayerGlobalSettings.setUseHttp2(true);

HTTP預建連TCP

針對HTTP的視頻播放請求（非HTTPS），通過提前建立TCP串連能夠顯著改善使用者體驗，降低網路連接耗時，確保播放的即時性與連續性，同時最佳化網路和系統資源的使用效率。使用方式如下：

// domain格式為host[:port]，port可選，用分號（;）隔開多個網域名稱
// 全域設定
// 全量介面每次設定後使用當前的字串為準（多-新增，少-刪除），字串空為停止預建連
AliPlayerGlobalSettings.setOption(AliPlayerGlobalSettings.SET_PRE_CONNECT_DOMAIN, "domain1;domain2");

Android播放器SDK提供了點播服務視頻的下載功能，允許使用者通過阿里雲播放器將視頻緩衝至本地觀看。同時，提供了普通下載和安全下載兩種下載方式。

• 普通下載

  下載後的視頻資料未經過阿里雲加密，使用者可以用第三方播放器播放。

• 安全下載

  下載後的視頻資料經過阿里雲加密。第三方播放器無法播放。僅支援使用阿里雲的播放器進行播放。

使用說明

• 僅VidSts和VidAuth方式可使用視訊下載功能。

• 使用播放器的視頻下載功能，需要在點播控制台開啟並配置下載模式，詳細操作請參見離線下載。

• 視頻下載支援斷點續傳。

操作步驟

1. 可選：配置安全下載的加密校正檔案。僅安全下載需要配置，普通下載無需配置。

   說明

   請確保配置的加密校正檔案與App資訊一致，否則會導致視頻下載失敗。

   如果設定為安全下載方式，則需要將在點播控制台產生的密鑰檔案配置到播放器SDK中，用於視頻下載和播放的解密驗證，密鑰檔案的產生請參見開啟安全下載。

   建議在Application中配置一次即可，樣本如下：

   PrivateService.initService(getApplicationContext(),  "encryptedApp.dat所在的檔案路徑"); //建議將encryptedApp.dat加密校正檔案存放到手機中後，此處設定加密校正檔案的手機本地檔案路徑

2. 建立並設定下載器。

   建立下載器，通過AliDownloaderFactory建立。樣本如下：

   AliMediaDownloader mAliDownloader = null;
   ......
   //建立下載器
   mAliDownloader = AliDownloaderFactory.create(getApplicationContext());
   //配置下載儲存的路徑
   mAliDownloader.setSaveDir("儲存的檔案夾地址");

3. 設定監聽事件。

   下載器提供了多個事件監聽。樣本如下：

   展開查看代碼

   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() {
          //下載成功
      }
   });

4. 準備下載源。

   通過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。
      //若您在VOD控制台開啟了HLS標準加密參數透傳，且預設的參數名為MtsHlsUriToken，那麼需要設定config，並將其傳入vid中，參考下述
      //若您未在VOD控制台開啟了HLS標準加密參數透傳，那麼則不需要整合下述代碼
      VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
      vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
      aliyunVidSts.setPlayerConfig(config);
             
     
     //準備下載源
     mAliDownloader.prepare(aliyunVidSts)

   • VidAuth

     //建立VidAuth
     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。
     //若您在VOD控制台開啟了HLS標準加密參數透傳，且預設的參數名為MtsHlsUriToken，那麼需要設定config，並將其傳入vid中，參考下述
     VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
     vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     vidAuth.setPlayerConfig(config);
     //準備下載源
     mAliDownloader.prepare(vidAuth);

   說明

   • 源檔案格式與輸出的下載檔案格式保持一致，不支援更改。

   • 若您在VOD控制台開啟HLS標準加密參數透傳，預設的參數名為MtsHIsUriToken，詳情見HLS標準加密參數透傳，那麼請按照上述代碼，將MtsHIsUriToken值設入點播源中。

5. 準備成功後，選擇下載項並開始下載。

   準備成功後，會回調OnPreparedListener方法。返回的TrackInfo中會包含各視頻流的清晰度等資訊，請選擇一個Track進行下載，樣本如下：

   public void onPrepared(MediaInfo mediaInfo) {
       //準備下載項成功
       List<TrackInfo> trackInfos = mediaInfo.getTrackInfos();
       //比如：下載第一個TrackInfo
       mAliDownloader.selectItem(trackInfos.get(0).getIndex());
       //開始下載
       mAliDownloader.start();
   }

6. （可選）更新下載源。

   為了防止VidSts和VidAuth到期，您也可以更新下載源的資訊後開始下載。樣本如下：

   //更新下載源
   mAliDownloader.updateSource(VidSts);
   //開始下載
   mAliDownloader.start();

7. 下載成功或失敗後，釋放下載器。

   下載成功後，在onCompletion或者onError回調中調用release釋放下載器。樣本如下：

   mAliDownloader.stop();
   mAliDownloader.release();

8. 可選：刪除下載的檔案。

   下載過程中，或者下載完成後，可以刪除下載的檔案。樣本如下：

   //通過對象刪除檔案
   mAliDownloader.deleteFile();
   //通過靜態方法刪除，若刪除成功則返回0
   AliDownloaderFactory.deleteFile("待刪除的下載檔案夾路徑","視頻ID","視頻格式","下載的視頻索引");

後續操作

下載的視頻可以使用阿里雲播放器進行播放。具體方法如下：

1. 下載完成後擷取視頻檔案的絕對路徑。

   String path = mAliDownloader.getFilePath();

2. 通過點播UrlSource方式設定絕對路徑進行播放。

    UrlSource urlSource = new UrlSource();
           urlSource.setUri("播放地址");//設定下載視頻的絕對路徑。
           aliPlayer.setDataSource(urlSource);