Flutter架構播放器SDK基礎功能的使用樣本 - ApsaraVideo VOD

本文提供Flutter架構播放器SDK基礎功能的使用樣本，更多功能使用說明請參見進階功能、API說明。

設定播放源（DataSource）

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

點播視訊播放

點播VidAuth播放（推薦）

使用VidAuth播放方式播放點播視訊，需要將播放器的vid屬性設定為音視頻ID，將playauth屬性設定為音視頻播放憑證。

音視頻ID可以在音視頻上傳完成後通過控制台（路徑：媒資庫>音/視頻。）或服務端介面（SearchMedia）擷取。
音視頻播放憑證可以調用GetVideoPlayAuth介面擷取。建議您通過SDK方式來擷取音視頻播放憑證，免去自簽名的麻煩。調用介面擷取音視頻播放憑證的樣本請參見開發人員門戶。

推薦ApsaraVideo for VOD使用者採用此播放方式。相比STS播放方式，PlayAuth播放方式在易用性和安全性上更有優勢，對比詳情請參見憑證方式與STS方式對比。

void onViewPlayerCreated(viewId) async {
  // 將渲染的View設定給播放器
  fAliplayer.setPlayerView(viewId);
  //請注意 generatePlayerConfig 之前必須調用 createVidPlayerConfigGenerator()和setPreviewTime()
  FlutterAliplayer.createVidPlayerConfigGenerator();
  FlutterAliplayer.setPreviewTime(0);
  // 設定播放源
  FlutterAliplayer.generatePlayerConfig().then((value) {
      fAliplayer.setVidAuth(
          vid: "Vid資訊",// 必選參數，視頻ID（VideoId）。
          region: "接入地區",// 必選參數，點播服務的接入地區，預設為cn-shanghai。
          playAuth: "<yourPlayAuth>",// 必選參數，播放憑證，需要調用點播服務的GetVideoPlayAuth介面產生。
          playConfig: value);
        });    
  }
}

點播VidSts播放

使用點播VidSts播放方式播放點播視訊是指用STS臨時憑證而非點播音視頻播放憑證播放。STS安全性權杖和STS臨時AK對（AccessKeyId和AccessKeySecret）需要提前擷取，擷取方式請參見擷取STS Token。

void onViewPlayerCreated(viewId) async {
  // 將渲染的View設定給播放器
  fAliplayer.setPlayerView(viewId);
  //請注意 generatePlayerConfig 之前必須調用 createVidPlayerConfigGenerator()和setPreviewTime()
  FlutterAliplayer.createVidPlayerConfigGenerator();
  FlutterAliplayer.setPreviewTime(0);
  // VidSts播放方式
  FlutterAliplayer.generatePlayerConfig().then((value) {
     fAliplayer.setVidSts(
          vid: "Vid資訊",// 必選參數，視頻ID（VideoId）。
          region: "接入地區",// 必選參數，點播服務的接入地區，預設為cn-shanghai。
          accessKeyId: "<yourAccessKeyId>",// 必選參數，STS臨時AK對的存取金鑰ID，需要調用STS服務的AssumeRole介面產生。
          accessKeySecret: "<yourAccessKeySecret>",// 必選參數，STS臨時AK對的存取金鑰，需要調用STS服務的AssumeRole介面產生。
          securityToken: "<yourSecurityToken>",// 必選參數，STS安全性權杖，需要調用STS服務的AssumeRole介面產生。
      	  playConfig: value);
    	});
       
}

點播UrlSource播放

使用點播UrlSource播放方式播放點播視訊，需要將播放器的setUrl屬性設定為播放地址。播放地址可以是第三方點播地址或阿里雲點播服務中的播放地址。

阿里雲播放地址可以調用GetPlayInfo介面擷取。建議您通過SDK方式來擷取音視頻播放地址，免去自簽名的麻煩。調用介面擷取音視頻播放地址的樣本請參見開發人員門戶。

void onViewPlayerCreated(viewId) async {
  // 將渲染的View設定給播放器
  fAliplayer.setPlayerView(viewId);
  // 設定播放源
  switch (_playMode) {
      // UrlSource播放方式
    case ModeType.URL:
      this.fAliplayer.setUrl("播放地址"); // 必選參數，播放地址，可以是第三方點播地址，或阿里雲點播服務中的播放地址。
      break;
    default:
  }
}

點播加密播放

點播視訊支援HLS標準加密、阿里雲私人加密和DRM加密。加密播放請參見Flutter端播放加密視頻。

直播視頻播放

詳情請參見Flutter播放器。

說明

UrlSource是直接通過URL播放，VidSts，VidAuth是通過Vid進行播放。
接入地區Region的設定，請參見點播地區標識。

控制播放

Flutter架構播放器SDK支援開始、暫停、從指定時間點播放等主流操作。

自動播放

自動播放視頻，由setAutoPlay介面實現（預設為關閉狀態）。樣本如下：

fAliplayer.setAutoPlay(true);

準備播放

準備播放視頻，調用prepare介面開始讀取並解析資料。若開啟自動播放，資料解析完成後將開始自動播放視頻。樣本如下：

fAliplayer.prepare();

開始播放

開始播放視頻，由play介面實現。樣本如下：

 fAliplayer.play();

從指定時間開始播放

跳轉到某個時刻進行播放，由seek介面實現。適用於使用者拖拽進度條，或續播等需要從指定時間點開始播放的情境。樣本如下：

////posotion為指定的時間，單位：毫秒。seekMode取值：FlutterAvpdef.ACCURATE（精準seek）和FlutterAvpdef.INACCURATE（非精準seek）
fAliplayer.seek(position,seekMode);

以指定位置起播，適用於使用者從指定時間點開始播放的情境。需在每次prepare前調用一次該介面生效，樣本如下：

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

暫停播放

暫停播放視頻，由pause介面實現。樣本如下：

fAliplayer.pause();

恢複播放

恢複播放視頻，由play介面實現。樣本如下：

fAliplayer.play();

停止播放

停止播放視頻，由stop介面實現。樣本如下：

fAliplayer.stop();

銷毀播放器

銷毀播放器執行個體，有同步和非同步兩種銷毀方式，樣本如下：

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

說明

調用同步銷毀介面需等待播放器資源完全釋放後才返回。如果您對介面的響應速度有較高要求，建議使用非同步銷毀介面，並注意以下幾點：

避免在非同步銷毀過程中對播放器對象執行任何其他動作。
無需在調用非同步銷毀之前手動停止播放器，因為該過程內部已經包含了非同步化的停止流程。

播放器狀態監聽

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

設定播放器監聽

播放器支援設定多個監聽器。

建立手動播放時，OnPrepard必須設定，因為手動播放需要在OnPrepard回調中調用play開始播放。
OnTrackReady、OnError較為重要，建議您設定。

以下樣本僅展示部分介面，如下所示：

// 準備成功
fAliplayer.setOnPrepard((playerId) {});
// 首幀顯示
fAliplayer.setOnRenderingStart((playerId) {});
// 視頻寬高變化
fAliplayer.setOnVideoSizeChanged((width, height,playerId) {});
// 播放器狀態變化
fAliplayer.setOnStateChanged((newState,playerId) {});
// 載入狀態
fAliplayer.setOnLoadingStatusListener(
    loadingBegin: (playerId) {},
    loadingProgress: (percent, netSpeed,playerId) {},
    loadingEnd: (playerId) {});
// 拖動完成
fAliplayer.setOnSeekComplete((playerId) {});
// 播放器事件資訊回調，包括buffer、當前播放進度等等資訊，根據infoCode來判斷，對應FlutterAvpdef.infoCode
fAliplayer.setOnInfo((infoCode, extraValue, extraMsg,playerId) {});
// 播放完成
fAliplayer.setOnCompletion((playerId) {});
// 設定流準備完成
fAliplayer.setOnTrackReady((playerId) {});
// 截圖結果
fAliplayer.setOnSnapShot((path,playerId) {});
// 錯誤結果
fAliplayer.setOnError((errorCode, errorExtra, errorMsg,playerId) {});
// 切換流變化
fAliplayer.setOnTrackChanged((value,playerId) {});

監聽播放狀態

監聽播放器的狀態，onStateChanged 回調參數為當前播放器狀態。樣本如下：

fAliplayer.setOnStateChanged((newState, playerId) {
  //newState為播放狀態
  switch (newState) {
    case FlutterAvpdef.AVPStatus_AVPStatusIdle: // 空轉、閑時、靜態
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusInitialzed: // 初始化完成
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusPrepared: // 準備完成
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusStarted: // 現正播放
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusPaused: // 播放暫停
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusStopped: // 播放停止
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusCompletion: // 播放完成
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusError: // 播放錯誤
      break;
    default:
  }
});

設定顯示模式

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

填充

支援設定寬高比適應、寬高比填充和展開填充這3種畫面填充模式，由setScalingMode介面實現。樣本如下：

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

旋轉

畫面按指定角度旋轉，由setRotateMode介面實現。設定後還可查詢旋轉角度。樣本如下：

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

鏡像

支援水平鏡像、垂直鏡像和無鏡像，由setMirrorMode介面實現。樣本如下：

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

擷取播放資訊

Flutter架構播放器SDK支援擷取當前的播放進度和播放時間長度。

擷取當前播放進度

擷取當前的播放時刻，在onInfo回調中擷取，單位毫秒。樣本如下：

fAliplayer.setOnInfo((infoCode,extraValue,extraMsg,playerId){
 if(infoCode==FlutterAvpdef.CURRENTPOSITION){
 //extraValue為當前播放進度
}
});

擷取播放時間長度

擷取視頻總時間長度。需要在視頻載入完成以後才可以擷取到，可以在AVPEventPrepareDone事件後擷取duration。樣本如下：

fAliplayer.getMediaInfo().then((value){
 _videoDuration=value['duration'];
});

設定音量

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

音量大小

調節音量大小，支援0～2倍，當音量大於1時，可能出現噪音，不推薦使用。由setVolume介面實現。設定後還可擷取音量資訊。樣本如下：

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

靜音設定

將播放中的視頻設定為靜音狀態，由setMute介面實現。樣本如下：

fAliplayer.setMute(true);

倍速播放

Flutter架構播放器SDK提供了倍速播放視頻的功能，通過設定setSpeed方法，能夠以0.5倍~5倍速播放視頻。同時保持變聲不變調。樣本如下：

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

多清晰度設定

如果使用VID方式（VidAuth（推薦）及VidSts）播放，無需額外設定。Flutter架構播放器SDK會從點播服務擷取清晰度列表。Flutter架構播放器SDK支援擷取和切換清晰度，UrlSource播放方式暫不支援此設定。

擷取清晰度

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

fAliplayer.setOnPrepared((playerId) {
  fAliplayer.getMediaInfo().then((value){
        AVPMediaInfoinfo info=AVPMediaInfo.fromJson(value);
        info.tracks.forEach((element){
          if(element.trackType==3){
            // 清晰度
            String definition=element.trackDefinition;
            // 流索引
            int index=element.trackIndex;
          }
        });
      });    
});

切換清晰度

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

fAliplayer.selectTrack(trackIdx);

清晰度切換通知

清晰度切換成功回調。

fAliplayer.setOnTrackChanged((value,playerId){
 //有回調錶示切換成功，切換失敗介面暫未提供
});

迴圈播放

Flutter架構播放器SDK提供了迴圈播放視頻的功能。調用setLoop開啟迴圈播放，播放完成後，將會自動從頭開始播放視頻。樣本如下：

fAliplayer.setLoop(true);

同時迴圈開始的回調將會使用onInfo通知。樣本如下：

fAliplayer.setOnInfo((infoCode, extraValue, extraMsg, playerId) {
 if(infoCode == FlutterAvpdef.LOOPINGSTART){
 //迴圈播放開始通知
 }
});

擷取播放日誌

Flutter架構播放器SDK提供了擷取播放日誌的功能。調用enableConsoleLog開啟日誌列印。樣本如下：

//開啟日誌列印功能
FlutterAliplayer.enableConsoleLog(true);
//設定記錄層級，預設為AF_LOG_LEVEL_INFO，如需排查問題，可設定為AF_LOG_LEVEL_TRACE
FlutterAliplayer.setLogLevel(FlutterAvpdef.AF_LOG_LEVEL_INFO);

Flutter架構播放器SDK提供了擷取幀層級日誌的功能。調用setLogOption設定幀層級日誌的列印。樣本如下：

/// 設定日誌等級，排查問題請設定記錄層級為 AF_LOG_LEVEL_TRACE
FlutterAliplayer.setLogLevel(LogLevel.AF_LOG_LEVEL_INFO);
/// 開啟/關閉 日誌
FlutterAliplayer.enableConsoleLog(true);
/// 日誌回調資訊
FlutterAliplayer.setLogInfoCallBack((level, msg) {
   print("[LOG][LEVEL][$level] $msg");
});
/// 開啟幀日誌回調，一般在排查問題時開啟
/// 選項value 0代表關閉 1代表開啟
FlutterAliplayer.setLogOption(value);

說明

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