Picture-in-picture support
Android 8.0 (API level 26) allows to start the activity in picture-in-picture mode. Picture-in-picture is a special type of multi-window mode, most commonly used for video playback. Using this mode, users can watch videos through small windows fixed to a corner of the screen, while navigating between applications or browsing content 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 P-in-Picture to your app, you need to register for P-in-Picture activities, switch Activity to P-in-Picture mode as needed, and ensure that when Activity is in P-in-Picture mode, the interface elements are hidden and the video can continue to play.
The Picture-in-Picture window will be displayed on the top level of the screen, located in a corner of the system selection. You can drag the Picture-in-Picture window to another location. When you click the window, you will see two special controls: the full screen toggle switch (located in the center of the window) and the close button (the "X" in the upper right corner).
Your app controls when the current activity enters Picture-in-Picture mode. Here are some examples:
- Activity You can enter Picture-in-Picture mode when the user taps the Home screen or the Recently Used App button to select other apps. (This is how Google Maps continues to display orientations when users run other activities at the same time.)
- Your app can switch the video to Picture-in-Picture mode when the user returns from a video to browse other content.
- Your app can switch the video to Picture-in-Picture mode when the user sees the end of an episode. The home screen will display promotional information or plot summary information about the next episode of the TV series.
- Your app can provide a way for users to queue other content when watching videos. When the home screen displays content selection, the video continues to play in picture-in-picture mode.
State support for picture-in-picture
By default, the system does not automatically provide picture-in-picture support for the application. To support picture-in-picture in your app, you can register the video activity in the manifest by setting android:supportsPictureInPicture and android:resizeableActivity to true. Additionally, specifying your Activity handles layout configuration changes so that your Activity does not restart when a layout change occurs 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, the 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 (() == .lb_control_picture_in_picture) {
getActivity().enterPictureInPictureMode();
return;
}
...
}
You may need to add logic to switch Activity to Picture-in-Picture mode (rather than going into the background). For example, if a user presses the Home screen or the Recently Used App button while Google Maps is navigating, the app switches to Picture-in-Picture mode. You can learn more about this by replacing onUserLeaveHint():
@Override
public void onUserLeaveHint () {
if (iWantToBeInPipModeNow()) {
enterPictureInPictureMode();
}
}
Processing interfaces during picture-in-picture
When the Activity enters or exits P-in-Picture mode, the system calls () or ().
You should replace these callbacks to repaint the interface elements of the Activity. 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 clearly, so they will not interact with these interface elements. The minimalist video playback Activity provides an excellent user experience. Activity should only display video playback controls. Remove other interface elements before the Activity enters Picture-in-Picture mode and restore these elements when the 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 controls
The Picture-in-Picture window displays controls when the user opens the window menu (by tapping the window on the mobile device or selecting the menu using the TV remote).
If the app has an active media session, the window displays Play, Pause, Next, and Previous controls.
You can also explicitly specify custom actions by building PictureInPictureParams before entering PictureInPicture mode (using ()) and pass these parameters when entering PictureInPictureMode() or setPictureInPictureParams(). Note that if you try to add more than getMaxNumPictureInPictureActions(), only the upper limit number of controls will be added.
Continue playing video in picture-in-picture mode
When your activity switches to Picture-in-Picture mode, the activity is put into a pause state and the onPause() method of the Activity is called. If the Activity is paused in Picture-in-Picture mode, the video playback must not be paused, but should continue to play.
In Android 7.0 and later, you should pause video playback when the system calls onStop() of the Activity; you should resume video playback when the system calls onStart() of the Activity. This way, you don't need to check if the app is in Picture-in-Picture mode in onPause(), just continue playing the video.
If you have to pause playback in the onPause() implementation, check the P-in-Picture mode and handle the playback accordingly by calling isInPictureInPictureMode(), 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 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 a single playback activity
In your app, users may select a new video while browsing content on the home screen, and there is also a video playback Activity in Picture-in-Picture mode. New videos should be played in an existing playback activity in full screen mode, rather than launching a new activity that may confuse users.
To ensure that a single Activity is used for video playback requests and enter or exit P-in-Picture mode as needed, set the Activity's android:launchMode to singleTask in the list:
<activity android:name="VideoActivity"
...
android:supportsPictureInPicture="true"
android:launchMode="singleTask"
...
In your Activity, replace onNewIntent() and process new videos, thus stopping any existing videos as needed.
Best practices
Low memory devices may not be able to use Picture-in-Picture mode. Before the application uses picture-in-picture, be sure to check by calling hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE) to make sure that picture-in-picture is available.
Picture-in-picture is intended for activities that play full-screen videos. When switching Activity to Picture-in-Picture mode, avoid displaying anything other than video content. Track when your activity enters P-in-Picture mode and hides interface elements as described in Processing Interface During P-in-Picture.
Since the Picture-in-Picture window appears as a floating window at one corner of the screen, you should avoid displaying important information in any area in the home screen that may be obscured by the Picture-in-Picture window.
When the Activity enters P-in-Picture mode, it does not get input focus by default. To receive input events in Picture-in-Picture mode, use (). For more information on how to use setCallback(), see Showing "Playing" cards.
When your app is in PG mode, video playback in the PG window may cause audio interference to other applications, such as music player apps or voice search apps. To avoid this problem, request audio focus when you start playing video and process audio focus change notifications, as described in Manage Audio Focus. If you receive a notification of audio focus loss while in Picture-in-Picture mode, pause or stop video playback.
This is the end of this article about the implementation example of Android's picture-in-picture mode. For more related content on Android's picture-in-picture, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!