投屏

使用说明

• 在集成投屏插件SDK之前，您需要先开通投屏增值服务。开通地址请参见播放器SDK开通申请。

• 投屏功能是阿里云播放器SDK中的一个独立功能，使用投屏前需要先集成阿里云播放器SDK，再集成投屏插件SDK。播放器SDK集成请参见播放器SDK简介。

• 投屏功能支持在AliPlayer的URL、 VidAuth或VidSts三种播放方式下使用。

  说明

  • 低延时直播流（ARTC协议）、加密视频源和本地视频源不支持投屏。

  • 其他非常见协议与格式，例如：DASH、H266、HDR、杜比音效、特殊声道、高码率、高FPS等，能否投屏需要看大屏端的设备支持情况。

Android端集成投屏插件SDK

步骤一：集成投屏插件

1. 在项目级build.gradle项目文件中添加阿里云Maven仓库。

   maven { url "http://maven.aliyun.com/nexus/content/repositories/releases" }

2. 在应用级build.gradle项目文件下，添加投屏插件SDK和播放器SDK的依赖。

   投屏插件SDK版本号无需修改，播放器SDK版本号请根据实际情况进行修改，播放器的版本号请参见Android播放器SDK。

   //投屏插件SDK
   implementation 'com.aliyun.sdk.android:AliyunPlayerScreenProjection:1.0.2'
   //投屏插件SDK依赖的子SDK
   implementation 'com.alibaba:fastjson:1.2.62'
   
   //播放器SDK版本必须为5.5.6.0及以上
   implementation 'com.aliyun.sdk.android:AliyunPlayer:5.5.6.0-full'

3. 混淆配置。

   -keepclasseswithmembers class com.youku.multiscreen.MultiScreen{*;}
   -keepclasseswithmembers class com.yunos.tvhelper.support.biz.ut.Ut.** {*;}
   -keepclasseswithmembers class com.youku.multiscreen.Client{*;}
   -keepclasseswithmembers class com.youku.multiscreen.callback.** {*;}
   -keepclasseswithmembers class com.yunos.** {*;}
   -keepclasseswithmembers class com.tmalltv.** {*;}
   -keep class * extends com.yunos.lego.LegoBundle
   -keep class * extends com.yunos.tvhelper.youku.dlna.biz.cb.DlnaCb
   -keep class * extends com.yunos.tvhelper.youku.remotechannel.api.RchannelPublic$IRchannel
   
   -keepclasseswithmembers class com.ta.utdid2.** { *;}
   -keepclasseswithmembers class com.ta.audid.** {*;}
   -keepclasseswithmembers class com.ut.device.** { *;}
   -keepclasseswithmembers class com.ut.mini.** {*;}
   -keep public class com.alibaba.mtl.log.model.LogField {public *;}
   -keepclasseswithmembers public class com.alibaba.analytics.core.model.LogField{*;}
   -keepclasseswithmembers class com.ut.mini.exposure.TrackerFrameLayout$ExposureEntity{*;}
   
   -keep class com.alibaba.fastjson.** {*;}
   -keep class com.aliyun.player.aliplayerscreenprojection.** {*;}

步骤二：设置播放器

1. 设置UserData。

   说明

   UserData必须设置。当创建多个播放器时，投屏插件SDK会根据不同的UserData区分对应的播放器及视频资源。

   //创建播放器
   AliPlayer aliPlayer = AliPlayerFactory.createAliPlayer(context);
   //设置 UserData
   String userData = "自定义UserData";
   aliPlayer.setUserData(userData);

2. 打开投屏开关。

   PlayerConfig playConfig = aliPlayer.getPlayConfig();
   //默认是关闭的
   playConfig.mEnableProjection = true;
   aliPlayer.setConfig(playConfig);

3. 设置播放源并prepare。

   //设置播放器prepare，完成监听
   aliPlayer.setOnPreparedListener(() -> {
   	 //收到prepare完成的回调后，可以执行投屏相关的操作           
   });
   //设置播放源，可以设置URL、VidSts、VidAuth
   aliPlayer.setDataSource();
   aliPlayer.prepare();

步骤三：使用投屏

1. 初始化。

   1. 投屏日志开关设置。

      默认为关闭状态，如果遇见投屏插件SDK的问题，可以使用该接口打开投屏插件SDK的日志，方便问题排查。

      AliPlayerScreenProjectionHelper.enableLog(true);

   2. 创建投屏相关对象。

      //投屏设备相关对象
      Device deviceDelegate = AliPlayerScreenProjectionHelper.createDeviceDelegate(context);
      //投屏操作相关对象
      Projection projectDelegate = AliPlayerScreenProjectionHelper.createProjectDelegate(context);

2. 投屏设备对象的使用。

   1. 注册/反注册监听。

      //注册监听
      deviceDelegate.registerDeviceListener(new AliPlayerScreenProjectDevListener() {
      	//开始搜索投屏设备回调
      	@Override
      	public void onDevSearchStart() {}
      	//搜索投屏设备完成回调
      	@Override
      	public void onDevSearchStop() {}
      });
      //反注册监听
      deviceDelegate.unRegisterDeviceListener();

   2. 搜索设备。

      deviceDelegate.searchDevices();

   3. 获取设备列表。可以在搜索完成的回调里调用。

      deviceDelegate.getDevicesList();

   4. 选择设备。

      deviceDelegate.selectDevice(dev);

3. 投屏控制对象的使用。

   1. 注册/反注册监听。

      //注册监听
      projectDelegate.registerProListener(new AliPlayerScreenProjectProListener() {
      	//当前播放进度回调
      	@Override
      	public void onProgressUpdate(int i) {}
      	//投屏状态改变回调
      	@Override
      	public void onStateChanged(AliPlayerScreenProjectProState aliPlayerScreenProjectProState) {}
      });
      //反注册监听
      projectDelegate.unRegisterProListener();

   2. 设置时长。

      Android投屏插件SDK必须要设置duration，否则会导致播放进度回调异常。

      //时长可以通过播放器接口获取，在播放器准备完成后，调用 player.getDuration() 获取视频时长。
      projectDelegate.setDuration((int) mDuration);

   3. 开始投屏。

      说明

      在执行开始投屏前，需检查以下设置项是否配置正常：

      • 入参UserData有在播放器SDK设置UserData对应。

      • 播放器SDK的License需要有投屏服务权限，并打开投屏开关。

      • 必须在对应UserData的播放器SDK监听的setOnPreparedListener事件回调后才能进行。

      projectDelegate.start(userData);

   4. 退出投屏。

      projectDelegate.stop();

   5. 投屏相关操作。

      //暂停投屏
      projectDelegate.pause();
      //恢复投屏
      projectDelegate.play();
      //seek
      projectDelegate.seek(progress);
      //获取音量
      projectDelegate.getVolume();
      //设置音量[0,100]
      projectDelegate.setVolume(int volume);

iOS端集成投屏插件SDK

步骤一：集成投屏插件

1. 采用pod方式集成投屏插件SDK。

   pod 'AliPlayerScreenProjectionSDK_iOS', '1.0.0'

2. 集成播放器SDK。

   集成投屏插件SDK时，必须同时集成5.5.6.0及以上版本的播放器SDK，投屏插件SDK不能独立进行投屏系列操作。播放器SDK版本号说明请参见iOS播放器SDK。

   播放器SDK可以使用pod方式集成，也可以本地集成，具体集成方式说明请参见快速集成。下文以pod方式集成为例进行说明。

   pod 'AliPlayerSDK_iOS', '<版本号>'

步骤二：设置播放器

1. 设置UserData。

   说明

   UserData必须设置。当创建多个播放器时，投屏插件SDK会根据不同的UserData区分对应的播放器以及视频资源。UserData没有格式要求，建议设置能区分的唯一标识字符串。

   //创建播放器
   AliPlayer *aliPlayer = [[AliPlayer alloc] init];
   //设置UserData
   [aliPlayer setUserData:@"<UserData>"];

2. 打开投屏开关。

   AVPConfig *playerConfig = [aliPlayer getConfig];
   //默认是关闭的
   playerConfig.enableProjection = YES;
   [aliPlayer setConfig:playerConfig];

3. 设置播放源并prepare。

   //设置播放源，可以设置Url、VidSts、VidAuth。以Url为例：
   AVPUrlSource *urlSource = [[AVPUrlSource alloc] urlWithString:<url>];
   [aliPlayer setUrlSource:urlSource];
   // 设置播放器
   aliPlayer.delegate = self;
   // 调用准备播放
   aliPlayer.prepare();
   
   // 监听播放器事件回调，prepare完成时可以进行投屏操作
   -(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
       switch (eventType) {
           case AVPEventPrepareDone:
   		{
   			// 投屏相关操作
   		}
    			break;
   	}
   }

步骤三：使用投屏

1. 初始化。

   1. 打开/关闭投屏SDK的log日志，默认为关闭。如果遇见投屏插件SDK的问题，可以使用该接口打开投屏SDK的日志，方便问题排查。

      [AliPlayerScreenProjectionHelper enableLog:YES];

   2. 创建投屏相关对象。

      // 调用create方法，自动创建好投屏设备对象实例helper.device、投屏控制对象实例helper.projection
      AliPlayerScreenProjectionHelper *helper = [AliPlayerScreenProjectionHelper create];

2. 投屏设备对象的使用。

   1. 注册监听。

      // 设置监听。同时会注册设备状态监听相关回调(AliPlayerScreenProjectDevListener)、错误相关回调(AliPlayerScreenProjectErrorListener)。
      [helper.device setDelegate:self];
      
      // 实现监听设备状态监听相关回调
      /**
       @brief 设备添加回调
       @param dev 新添加的设备
       */
      - (void)onAdded:(AliPlayerScreenProjectDev *)dev {}
      /**
       @brief 设备移除回调
       @param dev 被移除的设备
       */
      - (void)onRemoved:(AliPlayerScreenProjectDev *)dev {}
      /**
       @brief 开始搜索回调
       */
      - (void)onSearchStart {}
      /**
       @brief 停止搜索
       */
      - (void)onSearchStop {}

   2. 搜索设备。

      [helper.device searchDevices];

   3. 刷新搜索列表。

      在执行开始搜索后，监听设备添加回调onAdded:，有设备回调回来，即可将此设备放到保存的设备列表中进行刷新UI。

      // 保存的设备列表
      NSMutableArray<AliPlayerScreenProjectDev *> devLists = [NSMutableArray array];
      
      - (void)onAdded:(AliPlayerScreenProjectDev *)dev {
      	[devLists addObject:dev];
      	// 刷新UITableView等搜索设备列表UI。以UITableView为例：
      	[tableView reloadData]
      } 

   4. 选择设备。

      AliPlayerScreenProjectDev *dev = xxxx; // xxxx 获取到的某个搜索的设备
      [helper.device selectDevice:dev]

   5. 停止搜索设备。

      退出投屏相关页面。不使用搜索的相关逻辑后，建议调用停止搜索设备。

      [helper.device stopSearchDevices];

   6. 获取设备列表。

      可以直接获取当前时间点的搜索到的设备列表。

      NSArray<AliPlayerScreenProjectDev *> *devicesList = [helper.device getDevicesList];

3. 投屏控制对象的使用。

   1. 注册监听。

      //设置监听。同时会注册投屏状态相关回调(AliPlayerScreenProjectProListener)、错误相关回调(AliPlayerScreenProjectErrorListener)。
      [helper.projection setDelegate:self];
      
      // 实现监听投屏状态相关回调
      /**
       @brief 投屏进度更新回调
       @param position 投屏当前进度
       @param duration 投屏总时长
       */
      - (void)onProgressUpdate:(NSInteger)position duration:(NSInteger)duration {}
      /**
       @brief 投屏状态改变回调
       @param state 投屏当前状态
       */
      - (void)onStateChanged:(AliPlayerScreenProjectProState)state {}

   2. 开始投屏。

      说明

      在执行开始投屏前，需检查以下设置项是否配置正常：

      • 入参UserData有在播放器SDK设置UserData对应。

      • 播放器SDK的License需要有投屏服务权限，并打开投屏开关。

      • 必须在对应UserData的播放器SDK监听的AVPEventPrepareDone事件回调后才能进行。

      [helper.projection start:"<UserData>"];

   3. 退出投屏。

      [helper.projection stop];

   4. 投屏相关操作。

      // 暂停投屏
      [helper.projection pause];
      // 继续投屏
      [helper.projection play];
      // seek
      NSInteger progress = 10; // 10代表指定的投屏seek位置是10秒的位置
      [helper.projection seek:progress];
      // 获取当前音量
      NSInteger currentVolume = [helper.projection getVolume];
      //设置音量，范围[0 ~ 100]
      NSInteger volume = 50;
      [helper.projection setVolume:volume];

错误相关

错误回调

Android

//设置设备错误监听
deviceDelegate.setErrorListener(aliPlayerScreenProjectErrorEnum -> {});
//设置投屏错误监听
projectDelegate.setErrorListener(aliPlayerScreenProjectErrorEnum -> {});

iOS

参考上文的投屏设备对象的使用和投屏控制对象的使用中的注册回调方法实现，示例如下：

/**
 @brief 报错监听回调
 @param error 报错信息
 */
- (void)onError:(AliPlayerScreenProjectError *)error {}

错误码说明