In the Android N Developer Preview, Android TV users can now watch a video +in a pinned window in a corner of the screen when navigating within +applications. This new 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 multi-task while using your app, making +browsing and exploring your app easier and more engaging.
+ +Your app can decide when to trigger PIP mode. Here are some examples on +when to enter PIP mode:
+ +The PIP window is 240 x 135 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, or the user leaves the app, the PIP +window is automatically closed.
+ +PIP leverages the multi-window APIs available in the N Developer Preview 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 will not automatically support PIP for applications.
+If you want support PIP in your application, you need to 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
+won'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. Non-video +activities with detailed UI may not provide a good user experience in PIP +mode.
+ +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.
+ +A new PlaybackControlsRow.PictureInPictureAction class is
+provided to use the PIP icon and handle control bar PIP actions.
When your activity enters PIP mode, your activity should only show video
+playback. You should 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.
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 Mode.
+ +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().
For more information on multi-window APIs, see +Android N +Developer Preview Multi-Window Support.
diff --git a/docs/html/preview/images/pip-active.png b/docs/html/preview/images/pip-active.png new file mode 100644 index 0000000000000..1e4bb634553ae Binary files /dev/null and b/docs/html/preview/images/pip-active.png differ diff --git a/docs/html/preview/images/pip-button.png b/docs/html/preview/images/pip-button.png new file mode 100644 index 0000000000000..b876b12605e13 Binary files /dev/null and b/docs/html/preview/images/pip-button.png differ