ApsaraVideo VOD：多視頻源支援

什麼是視頻源？

視頻源 (Video Source) 是播放器播放視頻的資料來源，定義了視頻資源的擷取方式和授權機制。

AliPlayerKit 支援 3 種視頻源類型：

如何選擇視頻源類型？

根據業務情境和安全需求選擇合適的視頻源類型：

解決問題

• 不同視頻源類型配置方式不統一。

• 授權憑證管理複雜。

• 缺乏統一的視頻源驗證機制。

• 難以區分不同類型的視頻資源。

核心價值

核心能力

VidAuth 模式（推薦）

通過視頻 ID (VID) 和播放憑證 (PlayAuth) 進行授權播放。

適用情境：

• 需要授權驗證的視頻資源。

• 大多數生產環境的視頻播放。

• 需要簡單且安全的授權方式。

特點：

• 授權機制簡單，易於整合。

• 提供基本的安全保障。

• 推薦用於大多數業務情境。

參數說明：

使用樣本：

// 建立 VidAuth 類型的視頻源
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
    "your_video_id",      // 視頻 ID
    "your_play_auth"      // 播放憑證
);

// 建立播放資料
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .build(); 

VidSts 模式

通過視頻 ID (VID) 和阿里雲 STS (Security Token Service) 令牌進行播放，提供更高的安全性和存取控制。

適用情境：

• 需要臨時訪問憑證的情境。

• 高安全性要求的視頻資源。

• 需要精細存取控制的情境。

特點：

• 使用臨時訪問憑證，安全性高。

• 支援存取權限的精細控制。

• 適合高安全性要求的情境。

參數說明：

使用樣本：

// 建立 VidSts 類型的視頻源
VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
    "your_video_id",              // 視頻 ID
    "your_access_key_id",         // 存取金鑰 ID
    "your_access_key_secret",     // 存取金鑰密文
    "your_security_token",        // 安全性權杖
    "cn-shanghai"                 // 地區資訊（可選）
);

// 建立播放資料
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .build();   

URL 模式

通過直接提供視頻 URL 進行播放，適用於公開訪問的視頻資源。

適用情境：

• 公開的視頻資源，無需授權驗證。

• 測試和示範情境。

• 簡單的視頻播放需求。

特點：

• 使用簡單，只需提供視頻 URL。

• 無需額外的授權配置。

• 安全性較低，不適合敏感內容。

參數說明：

使用樣本：

// 建立 URL 類型的視頻源
VideoSource.UrlSource videoSource = VideoSourceFactory.createUrlSource(
    "https://example.com/video.mp4"
);

// 建立播放資料
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .build();

基本播放流程

// 1. 建立視頻源（推薦使用 VidAuth 模式）
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
    "your_video_id",
    "your_play_auth"
);

// 2. 建立播放資料
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .coverUrl("https://example.com/cover.jpg")
    .videoTitle("Sample Video")
    .sceneType(SceneType.VOD)
    .autoPlay(true)
    .build();

// 3. 建立控制器
AliPlayerController controller = new AliPlayerController(this);

// 4. 綁定到播放器視圖
controller.configure(model);
playerView.attach(controller);   

切換視訊源

// 切換視訊時，先解除綁定並釋放舊控制器
playerView.detach();
controller.destroy();

// 建立新的視頻源
VideoSource.VidAuthSource newSource = VideoSourceFactory.createVidAuthSource(
    "new_video_id",
    "new_play_auth"
);

// 建立新的播放資料
AliPlayerModel newModel = new AliPlayerModel.Builder()
    .videoSource(newSource)
    .build();

// 建立新的控制器並綁定
AliPlayerController newController = new AliPlayerController(this);
newController.configure(newModel);
playerView.attach(newController); 

如何驗證視頻源有效性？

在配置播放器之前，可以調用 isValid() 方法驗證視頻源配置：

VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);

if (videoSource.isValid()) {
    // 配置有效，可以使用
    AliPlayerModel model = new AliPlayerModel.Builder()
        .videoSource(videoSource)
        .build();
    controller.configure(model);
    playerView.attach(controller);
} else {
    // 配置無效，檢查參數
    Log.e(TAG, "Invalid video source configuration");
}

如何從伺服器擷取授權資訊？

推薦通過伺服器端擷取授權資訊，避免在用戶端寫入程式碼敏感性資料：

// 推薦：從伺服器擷取
public void playVideo(String videoId) {
    // 請求伺服器擷取 playAuth
    apiService.getPlayAuth(videoId, new Callback<PlayAuthResponse>() {
        @Override
        public void onSuccess(PlayAuthResponse response) {
            VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
                videoId,
                response.getPlayAuth()
            );
            // 開始播放...
        }

        @Override
        public void onError(Exception e) {
            Log.e(TAG, "Failed to get playAuth", e);
        }
    });
}   

如何處理 STS 令牌到期？

對於 VidSts 模式，需要注意安全性權杖的到期時間：

// 檢查令牌是否即將到期if (isTokenExpiringSoon(securityToken)) {
    // 重新整理權杖
    refreshSecurityToken(new TokenCallback() {
        @Overridepublic void onTokenRefreshed(String newToken) {
            // 使用新令牌重新建立視頻源
            VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
                vid, accessKeyId, accessKeySecret, newToken, region
            );
            // 繼續播放...
        }
    });
}

視頻源類型選擇

安全性建議

錯誤處理

建立視頻源時建議進行錯誤處理：

try {
    VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);

    if (!videoSource.isValid()) {
        // 處理無效配置
        showError("視頻源配置無效");
        return;
    }

    // 使用視頻源
    playVideo(videoSource);

} catch (IllegalArgumentException e) {
    // 處理參數錯誤
    Log.e(TAG, "Invalid video source parameters", e);
    showError("參數錯誤: " + e.getMessage());
}   

樣本功能

運行樣本

在 Demo App 中選擇 Video Source 樣本查看效果。

VideoSourceFactory 方法

VideoSource 方法

SourceType 常量

MediaId 建置規則

MediaId 用於播放器生命週期策略中的執行個體複用，相同 MediaId 的視頻源會複用同一個播放器執行個體。

如何選擇視頻源類型？

• 需要授權且安全性要求一般：使用 VidAuth 模式（推薦）。

• 需要高安全性和臨時訪問憑證：使用 VidSts 模式。

• 視頻是公開的：使用 URL 模式。

VidAuth 和 VidSts 有什麼區別？

視頻源建立失敗怎麼辦？

檢查以下幾點：

1. 參數是否為空白或無效。

2. URL 格式是否正確（URL 模式）。

3. 授權資訊是否有效（VidAuth 和 VidSts）。

4. 網路連接是否正常。

高頻錯誤錯例

// 不要在用戶端寫入程式碼敏感資訊
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
    "video_id",
    "hardcoded_play_auth_value"  // 安全風險！
);

// 從伺服器擷取授權資訊
String playAuth = fetchPlayAuthFromServer(videoId);
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(videoId, playAuth);

//  未驗證就使用
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);
controller.configure(createModel(videoSource));  // 可能為無效配置
playerView.attach(controller);

//  先驗證再使用
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);

if (videoSource.isValid()) {
    controller.configure(createModel(videoSource));
    playerView.attach(controller);
} else {
    showError("視頻源配置無效");
}

// 未處理令牌到期
VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
    vid, accessKeyId, accessKeySecret, expiredToken, region
);
// 播放失敗！令牌已到期

// 檢查令牌有效期間，及時重新整理if (isTokenExpired(securityToken)) {
    securityToken = refreshToken();
}
VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
    vid, accessKeyId, accessKeySecret, securityToken, region
);

如何調試？

1. 檢查日誌：使用 tag:AliPlayerKit 過濾 Logcat。

2. 調用 toString()：視頻源的 toString() 方法會輸出脫敏後的配置資訊。

3. 驗證參數：使用 isValid() 方法驗證配置。

4. 檢查網路：確保能正常訪問視頻資源。