Home | History | Annotate | Download | only in playback 
      1 page.title=Adding Picture-in-picture
      2 page.keywords=preview,sdk,PIP,Picture-in-picture
      3 page.tags=androidn
      4 helpoutsWidget=true
      5 
      6 trainingnavtop=true
      7 
      8 @jd:body
      9 
     10 <div id="tb-wrapper">
     11 <div id="tb">
     12 
     13 <h2>In this document</h2>
     14 <ol>
     15   <li><a href="#declaring">Declaring Your Activity Supports
     16 Picture-in-picture</a></li>
     17   <li><a href="#pip_button">Switching Your Activity to Picture-in-picture</a>
     18 </li>
     19   <li><a href="#handling_ui">Handling UI During Picture-in-picture</a>
     20 </li>
     21   <li><a href="#continuing_playback">Continuing Video Playback While in
     22 Picture-in-picture</a></li>
     23   <li><a href="#single_playback">Using a Single Playback Activity for
     24 Picture-in-picture</a></li>
     25   <li><a href="#best">Best Practices</a></li>
     26 </ol>
     27 
     28 <h2>See Also</h2>
     29 <ol>
     30   <li><a href="{@docRoot}preview/features/multi-window.html">Multi-Window
     31 Support</a></li>
     32 </ol>
     33 
     34 </div>
     35 </div>
     36 
     37 <p>In Android 7.0, Android TV users can now watch a video
     38 in a pinned window in a corner of the screen when navigating within or
     39 between apps. Picture-in-picture (PIP) mode lets apps run a video
     40 activity in the pinned window while another activity continues in the
     41 background. The PIP window lets users multitask while using Android TV,
     42 which helps users be more productive.</p>
     43 
     44 <p>Your app can decide when to trigger PIP mode. Here are some examples of
     45 when to enter PIP mode:</p>
     46 
     47 <ul>
     48 <li>Your app can move a video into PIP mode when the user navigates
     49 back from the video to browse other content.</li>
     50 <li>Your app can switch a video into PIP mode while a user watches the end
     51 of an episode of content. The main screen displays promotional or summary
     52 information about the next episode in the series.</li>
     53 <li>Your app can provide a way for users to queue up additional content while
     54 they watch a video. The video continues playing in PIP mode while the main
     55 screen displays a content selection activity.</li>
     56 </ul>
     57 
     58 <p>The PIP window is 240x135 dp and is shown at the top-most layer in one of
     59 the four corners of the screen, chosen by the system. The user can bring up a
     60 PIP menu that lets them toggle the PIP window to full-screen, or close the PIP
     61 window, by holding down the <b>Home</b> button on the remote. If another
     62 video starts playing on the main screen, the PIP window is automatically
     63 closed.</p>
     64 
     65 <img src="{@docRoot}images/android-7.0/pip-active.png" />
     66 <p class="img-caption"><strong>Figure 1.</strong> A Picture-in-picture
     67 video visible in a corner of the screen while the user browses content
     68 on the main screen.</p>
     69 
     70 <p>PIP leverages the multi-window APIs available in Android 7.0 to
     71 provide the pinned video overlay window. To add PIP to your app, you need to
     72 register your activities that support PIP, switch your activity to PIP mode as
     73 needed, and make sure UI elements are hidden and video playback continues when
     74 the activity is in PIP mode.</p>
     75 
     76 <h2 id="declaring">Declaring Your Activity Supports Picture-in-picture</h2>
     77 
     78 <p>By default, the system does not automatically support PIP for apps.
     79 If you want support PIP in your app, register your video
     80 activity in your manifest by setting
     81 <code>android:supportsPictureInPicture</code> and
     82 <code>android:resizeableActivity</code> to <code>true</code>. Also, specify
     83 that your activity handles layout configuration changes so that your activity
     84 doesn't relaunch when layout changes occur during PIP mode transitions.</p>
     85 
     86 <pre>
     87 &lt;activity android:name="VideoActivity"
     88     android:resizeableActivity="true"
     89     android:supportsPictureInPicture="true"
     90     android:configChanges=
     91         "screenSize|smallestScreenSize|screenLayout|orientation"
     92     ...
     93 </pre>
     94 
     95 <p>When registering your activity, keep in mind that in PIP mode, your
     96 activity is shown in a small overlay window on a TV screen. Video playback
     97 activities with minimal UI provide the best user experience. Activities that
     98 contain small UI elements might not provide a good user experience
     99 when switched to PIP mode, because users can't see details of the UI elements
    100 in the PIP window.</p>
    101 
    102 <h2 id="pip_button">Switching Your Activity to Picture-in-picture</h2>
    103 
    104 When you need to switch your activity into PIP mode, call
    105 {@link android.app.Activity#enterPictureInPictureMode
    106 enterPictureInPictureMode()}. The following example
    107 switches to PIP mode when the user selects a dedicated PIP button on a media
    108 control bar:</p>
    109 
    110 <pre>
    111 &#64;Override
    112 public void onActionClicked(Action action) {
    113     if (action.getId() == R.id.lb_control_picture_in_picture) {
    114         getActivity().enterPictureInPictureMode();
    115         return;
    116     }
    117     ...
    118 </pre>
    119 
    120 <p>Adding a PIP button to your media control bar lets your user easily switch
    121 to PIP mode while controlling video playback.</p>
    122 
    123 <img src="{@docRoot}images/android-7.0/pip-button.png" />
    124 <p class="img-caption"><strong>Figure 1.</strong> A Picture-in-picture
    125 button on a media control bar.</p>
    126 
    127 <p>Android 7.0 includes a
    128 {@link android.support.v17.leanback.widget.PlaybackControlsRow.PictureInPictureAction
    129 PlaybackControlsRow.PictureInPictureAction} class which defines
    130 control bar PIP actions and uses the PIP icon.</p>
    131 
    132 <h2 id="handling_ui">Handling UI During Picture-in-picture</h2>
    133 
    134 <p>When your activity enters PIP mode, your activity should only show video
    135 playback. Remove UI elements before your activity enters PIP,
    136 and restore these elements when your activity becomes full-screen again.
    137 Override {@link android.app.Activity#onPictureInPictureModeChanged
    138 Activity.onPictureInPictureModeChanged()} or
    139 {@link android.app.Fragment#onPictureInPictureModeChanged
    140 Fragment.onPictureInPictureModeChanged()} and enable or
    141 disable your UI elements as needed, for example:</p>
    142 
    143 <pre>
    144 &#64;Override
    145 public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
    146     if (isInPictureInPictureMode) {
    147         // Hide the controls in picture-in-picture mode.
    148         ...
    149     } else {
    150         // Restore the playback UI based on the playback status.
    151         ...
    152     }
    153 }
    154 </pre>
    155 
    156 <h2 id="continuing_playback">Continuing Video Playback While in
    157 Picture-in-picture</h2>
    158 
    159 <p>When your activity switches to PIP, the system considers the activity in a
    160 paused state, and calls your activity's {@link android.app.Activity#onPause
    161 onPause()} method. Video playback should not be paused and should continue
    162 playing if the activity is paused due to PIP mode.</p>
    163 
    164 <p>In Android 7.0, you should pause and resume video playback when the system
    165 calls your activity's {@link android.app.Activity#onStop onStop()} and
    166 {@link android.app.Activity#onStart onStart()}. By doing this, you can avoid
    167 having to check if your app is in PIP mode in
    168 {@link android.app.Activity#onPause onPause()} and explicitly
    169 continuing playback.</p>
    170 
    171 <p>If you have to pause playback in your {@link android.app.Activity#onPause
    172 onPause()} implementation, check for PIP mode by calling {@code
    173 isInPictureInPictureMode()} and handle playback appropriately, for example:</p>
    174 
    175 <pre>
    176 &#64;Override
    177 public void onPause() {
    178     // If called while in PIP mode, do not pause playback
    179     if (isInPictureInPictureMode()) {
    180         // Continue playback
    181         ...
    182     }
    183     // If paused but not in PIP, pause playback if necessary
    184     ...
    185 }
    186 </pre>
    187 
    188 <p>When your activity switches out of PIP mode back to full-screen mode, the
    189 system resumes your activity and calls your
    190 {@link android.app.Activity#onResume onResume()} method.</p>
    191 
    192 <h2 id="single_playback">Using a Single Playback Activity for
    193 Picture-in-picture</h2>
    194 
    195 <p>In your app, a user might select a new video when browsing for content on
    196 the main screen, while a video playback activity is in PIP mode. Play the new
    197 video in the existing playback activity in full screen mode, instead of
    198 launching a new activity that might confuse the user.</p>
    199 
    200 <p>To ensure a single activity is used for video playback requests and
    201 switched into or out of PIP mode as needed, set the activity's
    202 <code>android:launchMode</code> to <code>singleTask</code> in your manifest:
    203 </p>
    204 
    205 <pre>
    206 &lt;activity android:name="VideoActivity"
    207     ...
    208     android:supportsPictureInPicture="true"
    209     android:launchMode="singleTask"
    210     ...
    211 </pre>
    212 
    213 <p>In your activity, override {@link android.app.Activity#onNewIntent
    214 onNewIntent()} and handle the new video, stopping any existing video
    215 playback if needed.</p>
    216 
    217 <h2 id="best">Best Practices</h2>
    218 
    219 <p>PIP is intended for activities that play full-screen video. When switching
    220 your activity into PIP mode, avoid showing anything except video content.
    221 Track when your activity enters PIP mode and hide UI elements, as described
    222 in <a href="#handling_ui">Handling UI During Picture-in-picture</a>.</p>
    223 
    224 <p>Since the PIP window is shown as a floating window in the corner of the
    225 screen, you should avoid showing critical information in the main screen
    226 in any area that can be obscured by the PIP window.</p>
    227 
    228 <p>When an activity is in PIP mode, by default it doesn't get input focus. To
    229 receive input events while in PIP mode, use
    230 {@link android.media.session.MediaSession#setCallback
    231 MediaSession.setCallback()}. For more information on using
    232 {@link android.media.session.MediaSession#setCallback setCallback()} see
    233 <a href="{@docRoot}training/tv/playback/now-playing.html">Displaying
    234 a Now Playing Card</a>.</p>
    235 
    236 <p>When your app is in PIP mode, video playback in the PIP window can cause
    237 audio interference with another app, such as a music player app or voice search
    238 app. To avoid this, request audio focus when you start playing the video,
    239 and handle audio focus change notifications, as described in
    240 <a href="{@docRoot}training/managing-audio/audio-focus.html">Managing Audio
    241 Focus</a>. If you receive notification of audio focus loss when in PIP mode,
    242 pause or stop video playback.</p>
    243