ApsaraVideo VOD:Implement floating player

Floating window

A floating window is a type of floating view in the Android system that can be displayed on top of other apps. It can be freely dragged, resized, and closed, and is commonly used for reminders, notifications, and advertisements.

• In the Android system, each window corresponds to a Window object, and a floating window is a special type of Window. Typically, a floating window can be implemented using PopupWindow from the View system.

• PopupWindow is a class that inherits from WindowManager.LayoutParams, which has motion capabilities. Therefore, its position, size, and display mode can be manipulated. You can use PopupWindow to implement a custom floating window without affecting other applications and without requiring an Activity transition.

Follow these steps:

1. Declare the floating window permission in the AndroidManifest.xml file.

   <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

2. In the Activity or Service where the floating window is to be displayed, create a WindowManager and a PopupWindow. Then, set their properties, such as display position, size, and content.

   // Create the layout.
   View layout = View.inflate(this, R.layout.float_window, null);
   // Create the manager.
   WindowManager wm = (WindowManager) this.getSystemService(Context.WINDOW_SERVICE);
   // Create the floating window.
   PopupWindow mPopupWindow = new PopupWindow(layout,
                                              WindowManager.LayoutParams.WRAP_CONTENT,
                                              WindowManager.LayoutParams.WRAP_CONTENT);
   // Set the display position.
   mPopupWindow.showAtLocation(parentView, Gravity.LEFT | Gravity.TOP, x, y);
   // Make it clickable and focusable.
   mPopupWindow.setTouchable(true);
   mPopupWindow.setFocusable(true);
   // Set the background color.
   mPopupWindow.setBackgroundDrawable(new ColorDrawable(Color.TRANSPARENT));

3. Set click events, drag listeners, and other interactions for the controls within the floating window layout.

   mPopupWindow.setOnTouchListener(new View.OnTouchListener() {
       int lastX, lastY;
       int paramX, paramY;
   
       @Override
       public boolean onTouch(View v, MotionEvent event) {
           // Get the current touch point coordinates relative to the screen.
           int x = (int) event.getRawX();
           int y = (int) event.getRawY();
           switch (event.getAction()) {
               case MotionEvent.ACTION_DOWN:
                   lastX = x;
                   lastY = y;
                   paramX = mPopupWindow.getLayoutParams().x;
                   paramY = mPopupWindow.getLayoutParams().y;
                   break;
               case MotionEvent.ACTION_MOVE:
                   int dx = x - lastX;
                   int dy = y - lastY;
                   mPopupWindow.update(paramX + dx, paramY + dy, -1, -1);
                   break;
           }
           return false;
       }
   });

   Important

   On Android 6.0 and later, you need to dynamically request the floating window permission. However, even with the permission, this feature is still not supported on some Android 8.0 devices.

PiP

• Starting from Android 8.0 (API 26), Android introduced the ability to launch an Activity in PiP mode. PiP is a special type of multi-window mode, most commonly used for video playback. In this mode, users can pin a video to a small window in a corner of the screen while navigating between apps or browsing content on the home screen.

• PiP utilizes the multi-window mode APIs available in Android 7.0 to create a fixed video overlay window. To add PiP functionality to your app, you need to register the Activity that supports PiP, switch the Activity to PiP mode as needed, and ensure that UI elements are hidden and video continues to play when the Activity is in PiP mode.

• The PiP window appears at the top of the screen, typically in a corner chosen by the system.

• For information on Android system support for the PiP feature, see Android documentation.

Follow these steps:

1. Declare support for PiP for your Activity in the AndroidManifest.xml file.

   <activity android:name="VideoActivity"
     android:supportsPictureInPicture="true"
     android:configChanges=
     "screenSize|smallestScreenSize|screenLayout|orientation"
     ... />

   • By default, the Android system does not automatically provide PiP support for apps. If you want to support PiP in your app, you can register the video Activity in your AndroidManifest.xml file and set the android:supportsPictureInPicture attribute to true.

   • Additionally, when registering an Activity that supports PiP, you also need to specify that the Activity handles layout configuration changes. This prevents your Activity from restarting during PiP mode transitions if a layout change occurs, providing a smoother user experience.

     Important

     Low-RAM devices may not be able to use PiP mode. Before your app uses PiP, be sure to check for its availability by calling hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE).

2. Switch the Activity to PiP mode.

   The most common ways to enter PiP mode are:

   • Triggered by a button click

     onClicked(View), onOptionsItemSelected(MenuItem), and so on.

     @Override
     public void onActionClicked(Action action) {
         if (action.getId() == R.id.lb_control_picture_in_picture) {
         	// Triggered from a button.
             enterPictureInPictureMode();
             return;
         }
         ...
     }

   • Triggered by intentionally leaving the app, such as by pressing the Home button

     onUserLeaveHint()

     To enter PiP mode, the Activity must call enterPictureInPictureMode(). You can make the app automatically switch to PiP mode when the user presses the Home or Recents button by overriding onUserLeaveHint().

     @Override
     public void onUserLeaveHint () {
         // Triggered by intentionally leaving the app.
         if (iWantToBeInPipModeNow()) {
             enterPictureInPictureMode();
         }
     }

   • Triggered from a back action, such as by pressing a Back button

     onBackPressed()

     @Override
     public void onBackPressed() {
         super.onBackPressed();
         // Triggered from a back action.
         enterPictureInPictureMode();
     }

3. Handle UI elements in PiP mode.

   When an Activity enters or exits PiP mode, the system calls the Activity.onPictureInPictureModeChanged() method or the Fragment.onPictureInPictureModeChanged() method.

   You should override these callbacks to redraw your Activity's UI elements. Note that in PiP mode, the Activity is displayed in a small window, users cannot interact with the app's UI elements, and details in the small window may be difficult to see. A video playback Activity with a minimal UI provides the best user experience.

   1. Support smoother animations when exiting PiP mode.

      When an Activity exits PiP mode, you can add exit animations for UI elements to improve the transition's smoothness and visual appeal.

   2. Add controls.

      In PiP mode, users may not be able to interact with the application's UI elements. Therefore, you might consider adding simple controls to the PiP window to allow users to perform basic actions such as play/pause or next/previous episode.

   3. Disable seamless resizing for non-video content.

      In PiP mode, video content usually needs to maintain its aspect ratio without being stretched or cropped. However, for non-video content like text and images, you may need to disable seamless resizing to prevent the content from becoming unreadable or distorted in the small window. Disabling seamless resizing can ensure that non-video content remains visible and usable in PiP mode.

4. Continue playing video in PiP mode.

   When an Activity switches to PiP mode, the system puts the Activity in a paused state and calls the Activity's onPause() method. However, video playback should continue in PiP mode, not pause.

   In Android 7.0 and later:

   • Pause video playback when the system calls the Activity's onStop() method.

   • Resume video playback when the system calls the Activity's onStart() method.

   This way, you do not need to check if the application is in PiP mode in the onPause() method. You can continue playing the video.

   If you must pause video playback in the onPause() implementation, check if the application is in PiP mode by calling isInPictureInPictureMode() and handle the playback state accordingly. Sample code:

   @Override
   public void onPause() {
       // If called when in PiP mode, do not pause playback.
       if (isInPictureInPictureMode()) {
           // Continue playback.
           ...
       } else {
           // Use existing playback logic for paused Activity behavior.
           ...
       }
   }

Floating window

You can create a new window using the UIWindow type, add the video player's view to it, and control the window's position and size with gestures to achieve a floating PiP effect.

PiP

The PiP feature was introduced in iOS 9, but in previous versions, it was only available on iPad. Starting with iOS 14, iPhone users can also use PiP.

There are two methods for PiP on iOS:

1. For iOS 14 and later

   

   In iOS 14, you can achieve PiP by initializing AVPictureInPictureController with the system-provided AVPlayer. This allows the PiP effect to appear when the application is sent to the background or when navigating to a secondary screen. This solution is suitable for scenarios with less demanding player requirements.

2. For iOS 15 and later

   

   In iOS 15 and later, you can use AVSampleBufferDisplayLayer to create an AVPictureInPictureController for seamless PiP playback. This solution is typically used to implement PiP with a custom player. The ApsaraVideo Player SDK supports this feature. For more details, see Picture-in-Picture (PiP).

Follow these steps:

The implementation for iOS 15 solution is very similar to the iOS 14 solution. This topic uses the iOS 14 solution as an example:

1. Enable background mode.

   

2. Import the framework #import <AVKit/AVKit.h> and create an AVPictureInPictureController.

   // 1. Check if PiP is supported.
   if ([AVPictureInPictureController isPictureInPictureSupported]) {
       // 2. Enable permissions.
       @try {
           NSError *error = nil;
           [[AVAudioSession sharedInstance] setCategory:AVAudioSessionOrientationBack error:&error];
           [[AVAudioSession sharedInstance] setActive:YES error:&error];
       } @catch (NSException *exception) {
           NSLog(@"AVAudioSession error occurred");
       }
       self.pipVC = [[AVPictureInPictureController alloc] initWithPlayerLayer:self.player];
       self.pipVC.delegate = self;
   }

3. Start or stop PiP.

   if (self.pipVC.isPictureInPictureActive) {
       [self.pipVC stopPictureInPicture];
   } else {
       [self.pipVC startPictureInPicture];
   }

4. Set the AVPictureInPictureControllerDelegate.

   // PiP is about to start.
   - (void)pictureInPictureControllerWillStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // PiP has started.
   - (void)pictureInPictureControllerDidStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // Failed to start PiP.
   - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController failedToStartPictureInPictureWithError:(NSError *)error;
   // PiP is about to stop.
   - (void)pictureInPictureControllerWillStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // PiP has stopped.
   - (void)pictureInPictureControllerDidStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // Restore UI for PiP stop.
   - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController restoreUserInterfaceForPictureInPictureStopWithCompletionHandler:(void (^)(BOOL restored))completionHandler;

   Important

   1. Hold a global reference to the PiP controller. You can retain it in pictureInPictureControllerWillStartPictureInPicture and release it in pictureInPictureControllerDidStopPictureInPicture.

   2. Sometimes, the PiP controller might be opened through other means than clicking the PiP button. You can check for and close it in the viewWillAppear method.

   3. If a PiP window is already active and you want to start a new one, wait for the current one to close before starting the new one to prevent unknown errors, as closing PiP is an animated process.

   4. Creating an AVPictureInPictureController and starting PiP at the same time might fail. If you encounter this, start PiP later.