Of Stack

An Implementation Example of Android Picture in Picture Mode

  • 2021-12-11 08:49:15
  • OfStack

Picture-in-picture support

Android 8.0 (API level 26) allows Activity to start in picture-in-picture mode. Picture-in-picture is a special type of multi-window mode, which is most commonly used for video playback. With this mode, users can watch videos through a small window fixed to the corner of the screen 1, while navigating between applications or browsing the contents on the home screen.

Picture-in-picture uses the multi-window mode API in Android 7.0 to provide a fixed video overlay window. To add picture-in-picture to your application, you need to register Activity that supports picture-in-picture, switch Activity to picture-in-picture mode as needed, and ensure that when Activity is in picture-in-picture mode, the interface elements are hidden and the video can continue to play.

The picture-in-picture window is displayed at the top of the screen, at the corner selected by the system. You can drag the picture-in-picture window to another location. When you click on the window, you will see two special controls: the full screen switch (located in the center of the window) and the close button ("X" in the upper right corner).

Your application will control when the current Activity enters picture-in-picture mode. Here are one example:

Activity can enter picture-in-picture mode when the user clicks the home screen or recently used application button to select other applications. (This is how the Google map continues to show directions when users run other Activity at the same time.) Your application can switch a video to picture-in-picture mode when the user returns from the video to browse other content. Your application can switch video to picture-in-picture mode when users watch the end of an episode. The main screen will display promotional information or plot summary information about the next episode of this TV series. Your app can provide a way for users to add other content to the playback queue while watching video. When Activity is selected for the main screen display, the video continues to play in picture-in-picture mode.

Declare support for picture-in-picture

By default, the system does not automatically provide picture-in-picture support for applications. To support picture-in-picture in your application, you can register the video Activity in the manifest by setting android: supportsPictureInPicture and android: resizeableActivity to true. Also, specify that your Activity handles layout configuration changes so that your Activity does not restart when layout changes occur during a picture-in-picture mode transition. 


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

Switch your Activity to picture-in-picture mode

To enter picture-in-picture mode, Activity must call enterPictureInPictureMode (). For example, the following code switches Activity to picture-in-picture mode when the user clicks a dedicated button in the application interface: 


  @Override
  public void onActionClicked(Action action) {
    if (action.getId() == R.id.lb_control_picture_in_picture) {
      getActivity().enterPictureInPictureMode();
      return;
    }
    ...
  }

You may need to add logic to switch Activity to picture-in-picture mode instead of going into the background. For example, if the user presses the home screen or recently used application button while the Google map is navigating, the application switches to picture-in-picture mode. You can learn more about this by replacing onUserLeaveHint (): 


  @Override
  public void onUserLeaveHint () {
    if (iWantToBeInPipModeNow()) {
      enterPictureInPictureMode();
    }
  }

Processing the interface during picture-in-picture

When Activity enters or exits picture-in-picture mode, the system calls Activity. onPictureInPictureModeChanged () or Fragment. onPictureInPictureModeChanged ().

You should replace these callbacks to redraw the interface elements of Activity. Please note that in picture-in-picture mode, your Activity will be displayed in a small window. In picture-in-picture mode, users may not be able to see the details of small interface elements and therefore will not interact with them. Video playback Activity with minimal interface can provide excellent user experience. Activity should display only video playback controls. Remove other interface elements before Activity enters picture-in-picture mode, and restore them when Activity becomes full screen again: 


  @Override
  public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
    if (isInPictureInPictureMode) {
      // Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
    } else {
      // Restore the full-screen UI.
      ...
    }
  }

Add Control

A picture-in-picture window displays controls when the user opens a window menu, either by clicking a window on a mobile device or by using a TV remote control to select a menu.

If the application has 1 active media session, the window displays the Play, Pause, Next 1, and Last 1 controls.

You can also explicitly specify custom actions by building PictureInPictureParams (using PictureInPictureParams. Builder. setActions ()) before entering picture-in-picture mode, and passing these parameters when entering picture-in-picture mode using enterPictureInPictureMode (android. app. PictureInPictureParams) or setPictureInPictureParams (android. app. PictureInPictureParams). Note that if you try to add more controls than getMaxNumPictureInPictureActions (), only the maximum number of controls will be added.

Continue playing video in picture-in-picture mode

When your Activity switches to picture-in-picture mode, the system puts the Activity in a paused state and calls the onPause () method of Activity. If the Activity is paused in picture-in-picture mode, video playback must not be paused, but should continue.

In Android 7.0 and later, you should pause video playback when the system calls onStop () of Activity; When the system calls onStart () of Activity, you should resume video playback. In this way, you don't need to check whether the application is in picture-in-picture mode in onPause (), just continue to play the video.

If you have to pause playback in the onPause () implementation, check the picture-in-picture mode by calling isInPictureInPictureMode () and handle the playback accordingly, for example: 


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

When your Activity switches back from picture-in-picture mode to full screen mode, your Activity is restored and the onResume () method is called.

Use picture-in-picture mode for single playback Activity

In your application, users may choose a new video while browsing content on the home screen, and there is also a video playback Activity in picture-in-picture mode. Play new video in full-screen mode in an existing playback Activity instead of starting a new Activity that might confuse the user.

To ensure that a single Activity is used for video playback requests and enters or exits picture-in-picture mode as needed, set android: launchMode of Activity to singleTask in the listing: 


  <activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

In your Activity, replace onNewIntent () and process the new video to stop any existing video playback as needed.

Best practices

Low memory devices may not be able to use picture-in-picture mode. Before using picture-in-picture applications, be sure to check to make sure you can use picture-in-picture by calling hasSystemFeature (PackageManager.FEATURE_PICTURE_IN_PICTURE).

Picture-in-picture Activity designed to play full-screen video. When switching Activity to picture-in-picture mode, avoid displaying anything other than video content. Track when your Activity enters picture-in-picture mode and hides interface elements, as described in Processing the interface during picture-in-picture.

Because the Picture-in-Picture window appears as a floating window at the 1 corner of the screen, you should avoid displaying important information in any area of the home screen that may be obscured by the Picture-in-Picture window.

When Activity enters picture-in-picture mode, it does not get input focus by default. To receive input events in picture-in-picture mode, use MediaSession. setCallback (). For more information on how to use setCallback (), see Displaying "Playing" cards.

When your application is in picture-in-picture mode, video playback in the picture-in-picture window may cause audio interference to other applications (for example, music player applications or voice search applications). To avoid this problem, request audio focus when you start playing your video and process audio focus change notifications, as described in Managing Audio Focus. If you receive an audio focus loss notification while you are in picture-in-picture mode, pause or stop video playback.

Related articles: