Apsara Video SDK：基礎功能

建立播放器

本節介紹如何用更簡單的方式讓Flutter架構播放器SDK播放視頻，按照播放方式的不同可以分為手動播放和自動播放。

1. 建立播放器。

   建立單一實例播放器。

   //建立播放器執行個體
   FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();
   //建議傳入TraceID 
   fAliplayer.setTraceID("traceID");

   建立多執行個體播放器。

   需要在Flutter層管理playerId，在播放器的回調中會返回對應的playerId，用來通知Flutter層。

   FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer(playerId: playerId);

2. 設定監聽器。

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

   • 建立手動播放時，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) {});

3. 建立播放源。

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

   • Flutter播放器SDK僅支援1種直播播放方式，為UrlSource播放。

   點播視訊播放

   點播UrlSource播放

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

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

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

   點播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()
     FlutterAliplayer.createVidPlayerConfigGenerator();
     // 設定播放源
     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臨時授權方案上傳視頻。

   void onViewPlayerCreated(viewId) async {
     // 將渲染的View設定給播放器
     fAliplayer.setPlayerView(viewId);
     //請注意 generatePlayerConfig 之前必須調用 createVidPlayerConfigGenerator()
     FlutterAliplayer.createVidPlayerConfigGenerator();
     // 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);
       	});
          
   }

   點播加密播放

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

   直播視頻UrlSource播放

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

   阿里雲直播拉流地址可以通過直播控制台的地址產生器產生。詳情請參見阿里雲直播地址產生器 。

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

4. 設定顯示View。

   如果播放源有畫面，那麼需要設定顯示的view到播放器中，用來顯示畫面。樣本如下：

   @override
   Widget build(BuildContext context) {
     var x = 0.0;
     var y = 0.0;
     Orientation orientation = MediaQuery.of(context).orientation;
     var width = MediaQuery.of(context).size.width;
   
     var height;
     if (orientation == Orientation.portrait) {
       height = width * 9.0 / 16.0;
     } else {
       height = MediaQuery.of(context).size.height;
     }
     AliPlayerView aliPlayerView = AliPlayerView(
         onCreated: onViewPlayerCreated,
         x: x,
         y: y,
         width: width,
         height: height);
     return OrientationBuilder(
       builder: (BuildContext context, Orientation orientation) {
         return Scaffold(
           body: Column(
             children: [
               Container(
                   color: Colors.black,
                   child: aliPlayerView,
                   width: width,
                   height: height),
             ],
           ),
         );
       },
     );

5. 可選：開啟自動播放，預設為關閉狀態。

   fAliplayer.setAutoPlay(true);

6. 準備播放。

   調用prepare()方法準備播放。

   fAliplayer.prepare();

7. 開始播放。

   • 如果未開啟自動播放，需要在OnPrepard回調中調用fAliplayer.play();開始播放視頻。

   • 如果開啟了自動播放，則不需要調用fAliplayer.play();，資料解析完成後將開始自動播放視頻。

   fAliplayer.play();

控制播放

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

開始播放

 fAliplayer.play();

從指定時間開始播放

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

暫停播放

fAliplayer.pause();

停止播放

fAliplayer.stop();

設定顯示模式

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

填充

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

旋轉

//設定畫面順時針旋轉0度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_0);
//設定畫面順時針旋轉90度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_90);
//設定畫面順時針旋轉180度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_180);
//設定畫面順時針旋轉270度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_270);
//擷取旋轉角度
fAliplayer.getRotateMode();

鏡像

//設定無鏡像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_NONE);
//設定水平鏡像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_HORIZONTAL);
//設定垂直鏡像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_VERTICAL); 

擷取播放資訊

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

擷取當前播放進度

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

擷取播放時間長度

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

監聽播放狀態

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:
  }
});

設定音量

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

音量大小

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

靜音設定

fAliplayer.setMute(true);

倍速播放

//設定倍速播放：支援0.5～5倍速的播放，通常按0.5的倍數來設定，例如0.5倍、1倍、1.5倍等
fAliplayer.setRate(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;
          }
        });
      });    
});

切換清晰度

fAliplayer.selectTrack(trackIdx);

清晰度切換通知

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

迴圈播放

fAliplayer.setLoop(true);

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

擷取播放日誌

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