Skip to content

Most visited

Recently visited

navigation

Picture-in-picture Support

Android 8.0 (API level 26) allows activities to launch in picture-in-picture (PIP) mode. PIP is a special type of multi-window mode mostly used for video playback. It lets the user watch a video in a small window pinned to a corner of the screen while navigating between apps or browsing content on the main screen.

PIP leverages the multi-window APIs available in Android 7.0 to provide the pinned video overlay window. To add PIP to your app, you need to register your activities that support PIP, switch your activity to PIP mode as needed, and make sure UI elements are hidden and video playback continues when the activity is in PIP mode.

The PIP window appears in the top-most layer of the screen, in a corner chosen by the system. You can drag the PIP window to another location. When you tap on the window two special controls appear: a full-screen toggle (in the center of the window) and a close button (an "X" in the upper right corner).

Your app controls when the current activity enters PIP mode. Here are some examples:

Declaring picture-in-picture support

By default, the system does not automatically support PIP for apps. If you want support PIP in your app, register your video activity in your manifest by setting android:supportsPictureInPicture and android:resizeableActivity to true. Also, specify that your activity handles layout configuration changes so that your activity doesn't relaunch when layout changes occur during PIP mode transitions.

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

Switching your activity to picture-in-picture

To enter picture-in-picture mode, an activity must call enterPictureInPictureMode(). For example, the following code switches an activity to PIP mode when the user clicks a dedicated button in the app's UI:

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

You might want to include logic that switches an activty into PIP mode instead of going into the background. For example, Google Maps switches to PIP mode if the user presses the home or recents button while the app is navigating. You can catch this case by overriding onUserLeaveHint():

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

Handling UI during picture-in-picture

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

You should override these callbacks to redraw the activity's UI elements. Keep in mind that in PIP mode your activity is shown in a small window. Users cannot interact with UI elements when in PIP mode and the details of small UI elements may be difficult to see. Video playback activities with minimal UI provide the best user experience. The activity should only show video playback controls. Remove other UI elements before your activity enters PIP and restore them when your 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.
        ...
    }
}

Adding controls

The PIP window can display controls when the user opens the window's menu (by tapping the window on a mobile device, or selecting the menu from the TV remote.)

If an app has an active media session, then play, pause, next, and previous controls will appear.

You can also specify custom actions explicitly by building PictureInPictureParams with PictureInPictureParams.Builder.setActions() before entering PIP mode, and pass the params when you enter PIP mode using enterPictureInPictureMode(android.app.PictureInPictureParams) or setPictureInPictureParams(android.app.PictureInPictureParams). Be careful. If you try to add more than getMaxNumPictureInPictureActions() you'll only get the maximum number.

Continuing video playback while in picture-in-picture

When your activity switches to PIP, the system places the activity in the paused state and calls the activity's onPause() method. Video playback should not be paused and should continue playing if the activity is paused while in PIP mode.

In Android 7.0 and later, you should pause and resume video playback when the system calls your activity's onStop() and onStart(). By doing this, you can avoid having to check if your app is in PIP mode in onPause() and explicitly continuing playback.

If you have to pause playback in your onPause() implementation, check for PIP mode by calling isInPictureInPictureMode() and handle playback appropriately, 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 out of PIP mode back to full-screen mode, the system resumes your activity and calls your onResume() method.

Using a single playback activity for picture-in-picture

In your app, a user might select a new video when browsing for content on the main screen, while a video playback activity is in PIP mode. Play the new video in the existing playback activity in full screen mode, instead of launching a new activity that might confuse the user.

To ensure a single activity is used for video playback requests and switched into or out of PIP mode as needed, set the activity's android:launchMode to singleTask in your manifest:

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

In your activity, override onNewIntent() and handle the new video, stopping any existing video playback if needed.

Best practices

PIP is intended for activities that play full-screen video. When switching your activity into PIP mode, avoid showing anything except video content. Track when your activity enters PIP mode and hide UI elements, as described in Handling UI during picture-in-picture.

Since the PIP window is shown as a floating window in the corner of the screen, you should avoid showing critical information in the main screen in any area that can be obscured by the PIP window.

When an activity is in PIP mode, by default it doesn't get input focus. To receive input events while in PIP mode, use MediaSession.setCallback(). For more information on using setCallback() see Displaying a Now Playing Card.

When your app is in PIP mode, video playback in the PIP window can cause audio interference with another app, such as a music player app or voice search app. To avoid this, request audio focus when you start playing the video, and handle audio focus change notifications, as described in Managing Audio Focus. If you receive notification of audio focus loss when in PIP mode, pause or stop video playback.

Additional sample code

To download a sample app written in Android, see Android Picture-in-Picture Sample. To download a sample app written in Kotlin, see Android PictureInPicture Sample (Kotlin).

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)