ApsaraVideo VOD:Screen mirroring

Usage notes

• You need to apply to use the screen mirroring feature before you integrate the screen mirroring SDK. To apply to use the screen mirroring feature, submit a request on Yida.

• Screen mirroring is an independent feature of ApsaraVideo Player SDK. You must integrate ApsaraVideo Player SDK and the screen mirroring SDK to use the feature. For more information about how to integrate ApsaraVideo Player SDK, see Overview.

• The screen mirroring feature is supported for playback based on URLs, VidAuth, and VidSts.

  Note

  • The screen mirroring feature is not supported for Real-Time streaming (RTS) streams over the Alibaba Real-Time Communication (ARTC) protocol, encrypted streams, and local video sources.

  • Whether screen mirroring is supported for DASH, H.266, HDR, high-bitrate, or high-fps videos, videos that contain Dolby audio, or videos with special audio channels depends on the support of the device to which the screen is mirrored.

Integrate the screen mirroring SDK for Android

Step 1: Integrate the screen mirroring SDK

1. Add the URL of the Alibaba Cloud Maven repository to the build.gradle file of the project.

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

2. Add the dependencies of the screen mirroring SDK and ApsaraVideo Player SDK to the build.gradle file of the app.

   You do not need to modify the version number of the screen mirroring SDK. You can modify the version number of ApsaraVideo Player SDK based on your business requirements. For more information about the version numbers of ApsaraVideo Player SDK, see Release notes for ApsaraVideo Player SDK for Android.

   // The screen mirroring SDK.
   implementation 'com.aliyun.sdk.android:AliyunPlayerScreenProjection:1.0.2'
   // The dependencies of the screen mirroring SDK.
   implementation 'com.alibaba:fastjson:1.2.62'
   
   // ApsaraVideo Player SDK must be V5.5.6.0 or later.
   implementation 'com.aliyun.sdk.android:AliyunPlayer:5.5.6.0-full'

3. Configure obfuscation rules.

   -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.** {*;}

Step 2: Configure the player

1. Specify UserData.

   Note

   UserData is required. If you create multiple players, the screen mirroring SDK differentiates players and video resources based on UserData.

   // Create a player.
   AliPlayer aliPlayer = AliPlayerFactory.createAliPlayer(context);
   // Specify UserData.
   String userData = "Custom UserData";
   aliPlayer.setUserData(userData);

2. Enable the screen mirroring feature.

   PlayerConfig playConfig = aliPlayer.getPlayConfig();
   // By default, the screen mirroring feature is disabled.
   playConfig.mEnableProjection = true;
   aliPlayer.setConfig(playConfig);

3. Specify a playback source and prepare the player.

   // Listen for the prepare event.
   aliPlayer.setOnPreparedListener(() -> {
   	 // Perform operations related to screen mirroring after the prepare callback is returned.           
   });
   // Specify a playback source. Playback based on URLs, VidSts, and VidAuth are supported.
   aliPlayer.setDataSource();
   aliPlayer.prepare();

Step 3: Use the screen mirroring SDK

1. Initialize the screen mirroring SDK.

   1. Specify whether to enable screen mirroring logging.

      By default, screen mirroring logging is disabled. You can use the following sample code to enable screen mirroring logging for troubleshooting.

      AliPlayerScreenProjectionHelper.enableLog(true);

   2. Create objects related to screen mirroring.

      // The device to which the screen is mirrored.
      Device deviceDelegate = AliPlayerScreenProjectionHelper.createDeviceDelegate(context);
      // The device that controls the screen mirroring.
      Projection projectDelegate = AliPlayerScreenProjectionHelper.createProjectDelegate(context);

2. Configure the device to which the screen is mirrored.

   1. Register or deregister listeners.

      // Register listeners.
      deviceDelegate.registerDeviceListener(new AliPlayerScreenProjectDevListener() {
      	// Configure a callback for the start of device searching.
      	@Override
      	public void onDevSearchStart() {}
      	// Configure a callback for the end of device searching.
      	@Override
      	public void onDevSearchStop() {}
      });
      // Deregister listeners.
      deviceDelegate.unRegisterDeviceListener();

   2. Search for devices.

      deviceDelegate.searchDevices();

   3. Obtain the devices that are available for screen mirroring. You can call the getDevicesList operation after the callback for the end of device searching is returned.

      deviceDelegate.getDevicesList();

   4. Select a device.

      deviceDelegate.selectDevice(dev);

3. Configure the device that controls screen mirroring.

   1. Register or deregister listeners.

      // Register listeners.
      projectDelegate.registerProListener(new AliPlayerScreenProjectProListener() {
      	// Configure a callback for the current playback progress.
      	@Override
      	public void onProgressUpdate(int i) {}
      	// Configure a callback for changes in the screen mirroring status.
      	@Override
      	public void onStateChanged(AliPlayerScreenProjectProState aliPlayerScreenProjectProState) {}
      });
      // Deregister listeners.
      projectDelegate.unRegisterProListener();

   2. Specify the video duration.

      If you use the screen mirroring SDK for Android, you must specify duration. If you do not specify this parameter, the callback for the current playback progress fails.

      // Call player.getDuration() to query the video duration after the player is prepared. 
      projectDelegate.setDuration((int) mDuration);

   3. Start screen mirroring.

      Note

      Before you start screen mirroring, perform the following operations:

      • Check whether the value of the input parameter UserData is consistent with the value of UserData set in ApsaraVideo Player SDK.

      • Check whether the screen mirroring feature is enabled and whether the license of ApsaraVideo Player SDK allows you to perform screen mirroring.

      • Check whether the setOnPreparedListener callback is returned. You can perform screen mirroring only after the setOnPreparedListener callback is fired.

      projectDelegate.start(userData);

   4. Stop screen mirroring.

      projectDelegate.stop();

   5. Perform operations related to screen mirroring.

      // Pause screen mirroring.
      projectDelegate.pause();
      // Resume screen mirroring.
      projectDelegate.play();
      //seek
      projectDelegate.seek(progress);
      // Obtain the volume.
      projectDelegate.getVolume();
      // Specify the volume. Valid values: [0,100].
      projectDelegate.setVolume(int volume);

Integrate the screen mirroring SDK for iOS

Step 1: Integrate the screen mirroring SDK

1. Integrate the screen mirroring SDK in pod mode.

   pod 'AliPlayerScreenProjectionSDK_iOS', '1.0.0'

2. Integrate ApsaraVideo Player SDK for iOS.

   To use the screen mirroring feature, you must integrate the screen mirroring SDK and ApsaraVideo Player SDK V5.5.6.0 or later. You cannot use only the screen mirroring SDK to perform screen mirroring operations. For more information about the version numbers of ApsaraVideo Player SDK for iOS, see Release notes for ApsaraVideo Player SDK for iOS.

   You can integrate ApsaraVideo Player SDK in pod mode or by adding local files. For more information, see Quick integration. The following sample code shows how to integrate ApsaraVideo Player SDK in pod mode:

   pod 'AliPlayerSDK_iOS', '<Version number>'

Step 2: Configure the player

1. Specify UserData.

   Note

   UserData is required. If you create multiple players, the screen mirroring SDK differentiates players and video resources based on UserData. You do not need to specify UserData in a specific format. However, we recommend that you specify a unique string for UserData.

   // Create a player.
   AliPlayer *aliPlayer = [[AliPlayer alloc] init];
   // Specify UserData.
   [aliPlayer setUserData:@"<UserData>"];

2. Enable the screen mirroring feature.

   AVPConfig *playerConfig = [aliPlayer getConfig];
   // By default, the screen mirroring feature is disabled.
   playerConfig.enableProjection = YES;
   [aliPlayer setConfig:playerConfig];

3. Specify a playback source and prepare the player.

   // Specify the playback source. Playback based on URLs, VidSts, and VidAuth are supported. The following sample code uses URL-based playback as an example:
   AVPUrlSource *urlSource = [[AVPUrlSource alloc] urlWithString:<url>];
   [aliPlayer setUrlSource:urlSource];
   // Configure the player.
   aliPlayer.delegate = self;
   // Prepare the player.
   aliPlayer.prepare();
   
   // Listen for the prepare event. You can perform screen mirroring after the player is prepared.
   -(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
       switch (eventType) {
           case AVPEventPrepareDone:
   		{
   			// Perform operations related to screen mirroring.
   		}
    			break;
   	}
   }

Step 3: Use the screen mirroring SDK

1. Initialize the screen mirroring SDK.

   1. Enable or disable screen mirroring logging. By default, screen mirroring logging is disabled. You can use the following sample code to enable screen mirroring logging for troubleshooting.

      [AliPlayerScreenProjectionHelper enableLog:YES];

   2. Create objects related to screen mirroring.

      // Call the create method to create helper.device and helper.projection. helper.device is the device to which the screen is mirrored and helper.projection is the device that controls screen mirroring.
      AliPlayerScreenProjectionHelper *helper = [AliPlayerScreenProjectionHelper create];

2. Configure the device to which the screen is mirrored.

   1. Register listeners.

      // Configure listeners. AliPlayerScreenProjectDevListener and AliPlayerScreenProjectErrorListener are registered. 
      [helper.device setDelegate:self];
      
      // Configure the callback for changes in the status of the device.
      /**
       @ brief The callback for adding a device.
       @ param dev The added device.
       */
      - (void)onAdded:(AliPlayerScreenProjectDev *)dev {}
      /**
       @ brief The callback for removing a device.
       @ param dev The removed device.
       */
      - (void)onRemoved:(AliPlayerScreenProjectDev *)dev {}
      /**
       @ brief The callback for starting device searching.
       */
      - (void)onSearchStart {}
      /**
       @ brief The callback for stopping device searching.
       */
      - (void)onSearchStop {}

   2. Search for devices.

      [helper.device searchDevices];

   3. Refresh the device list.

      After device searching starts, an onAdded: callback is returned when a device is found. Add the device to the device list and refresh the UI elements.

      // Add the device to the device list.
      NSMutableArray<AliPlayerScreenProjectDev *> devLists = [NSMutableArray array];
      
      - (void)onAdded:(AliPlayerScreenProjectDev *)dev {
      	[devLists addObject:dev];
      	// Refresh the UI elements related to device searching, such as UITableView. The following sample code provides an example on how to refresh UITableView:
      	[tableView reloadData]
      } 

   4. Select a device.

      AliPlayerScreenProjectDev *dev = xxxx; // xxxx indicates a found device.
      [helper.device selectDevice:dev]

   5. Stop device searching.

      Exit the screen mirroring page. If you do not need to use search-related logic, we recommend that you use the following sample code to stop the search:

      [helper.device stopSearchDevices];

   6. Obtain the devices that are available for screen mirroring.

      You can obtain the list of found devices.

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

3. Configure the device that controls screen mirroring.

   1. Register listeners.

      // Configure listeners. AliPlayerScreenProjectProListener and AliPlayerScreenProjectErrorListener are registered. 
      [helper.projection setDelegate:self];
      
      // Configure a callback for changes in the status of screen mirroring.
      /**
       @ brief The callback for updating the screen mirroring progress.
       @ param position The current screen mirroring progress.
       @ param duration The total duration of screen mirroring.
       */
      - (void)onProgressUpdate:(NSInteger)position duration:(NSInteger)duration {}
      /**
       @ brief The callback for changes in the status of screen mirroring.
       @ param state The current status of screen mirroring.
       */
      - (void)onStateChanged:(AliPlayerScreenProjectProState)state {}

   2. Start screen mirroring.

      Note

      Before you start screen mirroring, perform the following operations:

      • Check whether the value of the input parameter UserData is consistent with the value of UserData set in ApsaraVideo Player SDK.

      • Check whether the screen mirroring feature is enabled and whether the license of ApsaraVideo Player SDK allows you to perform screen mirroring.

      • Check whether an AVPEventPrepareDone callback is returned. You can perform screen mirroring only after the AVPEventPrepareDone callback is fired.

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

   3. Stop screen mirroring.

      [helper.projection stop];

   4. Perform operations related to screen mirroring.

      // Pause screen mirroring.
      [helper.projection pause];
      // Resume screen mirroring.
      [helper.projection play];
      // seek
      NSInteger progress = 10; // 10 indicates that screen mirroring starts at the 10th second.
      [helper.projection seek:progress];
      // Obtain the current volume.
      NSInteger currentVolume = [helper.projection getVolume];
      // Specify the volume. Valid values: [0,100].
      NSInteger volume = 50;
      [helper.projection setVolume:volume];

Errors

Error-related callbacks

Android

// Listen for device errors.
deviceDelegate.setErrorListener(aliPlayerScreenProjectErrorEnum -> {});
// Listen for screen mirroring errors.
projectDelegate.setErrorListener(aliPlayerScreenProjectErrorEnum -> {});

iOS

For more information, see the "Configure the device to which the screen is mirrored." and "Configure the device that controls the screen mirroring." sections. Sample code:

/**
 @ brief Listen for errors.
 @ param error The error message.
 */
- (void)onError:(AliPlayerScreenProjectError *)error {}

Error codes