In Android N, Android TV users can now watch a video in a pinned window in a corner of the screen when navigating within apps. Picture-in-picture (PIP) mode lets apps run a video activity in the pinned window while another activity continues in the background. The PIP window lets users multitask while using your app, which helps users be more productive.
Your app can decide when to trigger PIP mode. Here are some examples of when to enter PIP mode:
The PIP window is 240x135 dp and is shown at the top-most layer in one of the four corners of the screen, chosen by the system. The user can bring up a PIP menu that lets them toggle the PIP window to full-screen, or close the PIP window, by holding down the Home button on the remote. If another video starts playing on the main screen, the PIP window is automatically closed. Users can also close the PIP window through Recents.
Figure 1. A Picture-in-picture video visible in a corner of the screen while the user browses content on the main screen.
PIP leverages the multi-window APIs available in Android N 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.
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"
...
When registering your activity, keep in mind that in PIP mode, your activity is shown in a small overlay window on a TV screen. Video playback activities with minimal UI provide the best user experience. Activities that contain small UI elements might not provide a good user experience when switched to PIP mode, because users can't see details of the UI elements in the PIP window.
Activity.enterPictureInPicture(). The following example switches
to PIP mode when the user selects a dedicated PIP button on a media control
bar:
@Override
public void onActionClicked(Action action) {
if (action.getId() == R.id.lb_control_picture_in_picture) {
getActivity().enterPictureInPicture();
return;
}
...
Adding a PIP button to your media control bar lets your user easily switch to PIP mode while controlling video playback.
Figure 1. A Picture-in-picture button on a media control bar.
Android N includes a new
PlaybackControlsRow.PictureInPictureAction class which defines
control bar PIP actions and uses the PIP icon.
When your activity enters PIP mode, your activity should only show video
playback. Remove UI elements before your activity enters PIP,
and restore these elements when your activity becomes full-screen again.
Override Activity.onPictureInPictureChanged() or
Fragment.onPictureInPictureChanged() and enable or
disable your UI elements as needed, for example:
@Override
public void onPictureInPictureChanged(boolean inPictureInPicture) {
if (inPictureInPicture) {
// Hide the controls in picture-in-picture mode.
...
} else {
// Restore the playback UI based on the playback status.
...
}
}
When your activity switches to PIP, the system considers the activity in a
paused state, and calls your activity's onPause() method. Video
playback should not be paused and should continue playing if the activity is
paused due to PIP mode. Check for PIP in your activity's
onPause() method and handle playback appropriately, for
example:
@Override
public void onPause() {
// If called due to PIP, do not pause playback
if (inPictureInPicture()) {
// Continue playback
...
}
// If paused but not in PIP, pause playback if necessary
...
}
When your activity switches out of PIP mode back to full-screen mode, the
system resumes your activity and calls your onResume() method.
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 {@link android.app.Activity#onNewIntent Activity.onNewIntent()} and handle the new video, stopping any existing video playback if needed.
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.setMediaButtonReceiver().