android_frameworks_base/docs/html/preview/features/picture-in-picture.jd

page.title=Picture-in-picture
page.keywords=preview,sdk,PIP,Picture-in-picture
page.tags=androidn

@jd:body

<div id="tb-wrapper">
<div id="tb">
  <h2>In this document</h2>
  <ol>
    <li><a href="#declaring">Declaring Your Activity Supports
    Picture-in-picture</a></li>
    <li><a href="#pip_button">Switching Your Activity to Picture-in-picture</a>
    </li>
    <li><a href="#handling_ui">Handling UI During Picture-in-picture</a>
    </li>
    <li><a href="#continuing_playback">Continuing Video Playback While in
Picture-in-picture</a></li>
    <li><a href="#best">Best Practices</a></li>
  </ol>
</div>
</div>

<p>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.</p>

<p>Your app can decide when to trigger PIP mode. Here are some examples on
when to enter PIP mode:</p>

<ul>
<li>When the user is navigating back from a video, the video activity can be
placed in PIP mode instead of being closed.</li>
<li>When the user is watching the end of an episode of content, the video can
be placed in PIP mode while the main screen displays promotional or summary
information about the next episode in the series.</li>
<li>When the user wants to queue up additional content to watch while watching
the currently playing content, the video can be placed in PIP mode and a
content selection activity can be shown in the main screen.</li>
</ul>

<p>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 <b>Home</b> 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.</p>

<p>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.</p>

<h2 id="declaring">Declaring Your Activity Supports Picture-in-picture</h2>

<p>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
<code>android:supportsPictureInPicture</code> and
<code>android:resizeableActivity</code> to <code>true</code>. Also, specify
that your activity handles layout configuration changes so that your activity
won't relaunch when layout changes occur during PIP mode transitions.</p>

<pre>
&lt;activity android:name="VideoActivity"
    android:resizeableActivity="true"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation"
    ...
</pre>

<p>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.</p>

<h2 id="pip_button">Switching Your Activity to Picture-in-picture</h2>

When you need to switch your activity into PIP mode, call
<code>Activity.enterPictureInPicture()</code>. The following example switches
to PIP mode when the user selects a dedicated PIP button on a media control
bar:</p>

<pre>
&#64;Override
public void onActionClicked(Action action) {
    if (action.getId() == R.id.lb_control_picture_in_picture) {
        getActivity().enterPictureInPicture();
        return;
    }
    ...
</pre>

<p>Adding a PIP button to your media control bar lets your user easily switch
to PIP mode while controlling video playback.</p>

<img src="{@docRoot}preview/images/pip-button.png" />
<p class="img-caption"><strong>Figure 1.</strong> A Picture-in-picture
button on a media control bar.</p>

<p>A new <code>PlaybackControlsRow.PictureInPictureAction</code> class is
provided to use the PIP icon and handle control bar PIP actions.</p>

<h2 id="handling_ui">Handling UI During Picture-in-picture</h2>

<p>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 <code>Activity.onPictureInPictureChanged()</code> or
<code>Fragment.onPictureInPictureChanged()</code> and enable or
disable your UI elements as needed, for example:</p>

<pre>
&#64;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.
        ...
    }
}
</pre>

<h2 id="continuing_playback">Continuing Video Playback While in
Picture-in-picture</h2>

<p>When your activity switches to PIP, the system considers the activity in a
paused state, and calls your activity's <code>onPause()</code> 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
<code>onPause()</code> method and handle playback appropriately, for
example:</p>

<pre>
&#64;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
    ...
}
</pre>

<p>When your activity switches out of PIP mode back to full screen mode, the
system resumes your activity and calls your <code>onResume()</code> method.</p>

<h2 id="best">Best Practices</h2>

<p>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 <a href="#handling_ui">Handling UI During Picture-in-picture Mode</a>.</p>

<p>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.</p>

<p>When an activity is in PIP mode, by default it doesn't get input focus. To
receive input events while in PIP mode, use
<code>MediaSession.setMediaButtonReceiver()</code>.</p>

<p>For more information on multi-window APIs, see
<a href="{@docRoot}preview/features/multi-window.html">Android N 
Developer Preview Multi-Window Support</a>.</p>