1page.title=Adding Picture-in-picture 2page.keywords=preview,sdk,PIP,Picture-in-picture 3page.tags=androidn 4helpoutsWidget=true 5 6trainingnavtop=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 16Picture-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 22Picture-in-picture</a></li> 23 <li><a href="#single_playback">Using a Single Playback Activity for 24Picture-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 31Support</a></li> 32</ol> 33 34</div> 35</div> 36 37<p>In Android 7.0, Android TV users can now watch a video 38in a pinned window in a corner of the screen when navigating within or 39between apps. Picture-in-picture (PIP) mode lets apps run a video 40activity in the pinned window while another activity continues in the 41background. The PIP window lets users multitask while using Android TV, 42which helps users be more productive.</p> 43 44<p>Your app can decide when to trigger PIP mode. Here are some examples of 45when to enter PIP mode:</p> 46 47<ul> 48<li>Your app can move a video into PIP mode when the user navigates 49back 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 51of an episode of content. The main screen displays promotional or summary 52information about the next episode in the series.</li> 53<li>Your app can provide a way for users to queue up additional content while 54they watch a video. The video continues playing in PIP mode while the main 55screen 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 59the four corners of the screen, chosen by the system. The user can bring up a 60PIP menu that lets them toggle the PIP window to full-screen, or close the PIP 61window, by holding down the <b>Home</b> button on the remote. If another 62video starts playing on the main screen, the PIP window is automatically 63closed.</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 67video visible in a corner of the screen while the user browses content 68on the main screen.</p> 69 70<p>PIP leverages the multi-window APIs available in Android 7.0 to 71provide the pinned video overlay window. To add PIP to your app, you need to 72register your activities that support PIP, switch your activity to PIP mode as 73needed, and make sure UI elements are hidden and video playback continues when 74the 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. 79If you want support PIP in your app, register your video 80activity in your manifest by setting 81<code>android:supportsPictureInPicture</code> and 82<code>android:resizeableActivity</code> to <code>true</code>. Also, specify 83that your activity handles layout configuration changes so that your activity 84doesn't relaunch when layout changes occur during PIP mode transitions.</p> 85 86<pre> 87<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 96activity is shown in a small overlay window on a TV screen. Video playback 97activities with minimal UI provide the best user experience. Activities that 98contain small UI elements might not provide a good user experience 99when switched to PIP mode, because users can't see details of the UI elements 100in the PIP window.</p> 101 102<h2 id="pip_button">Switching Your Activity to Picture-in-picture</h2> 103 104When you need to switch your activity into PIP mode, call 105{@link android.app.Activity#enterPictureInPictureMode 106enterPictureInPictureMode()}. The following example 107switches to PIP mode when the user selects a dedicated PIP button on a media 108control bar:</p> 109 110<pre> 111@Override 112public 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 121to 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 125button on a media control bar.</p> 126 127<p>Android 7.0 includes a 128{@link android.support.v17.leanback.widget.PlaybackControlsRow.PictureInPictureAction 129PlaybackControlsRow.PictureInPictureAction} class which defines 130control 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 135playback. Remove UI elements before your activity enters PIP, 136and restore these elements when your activity becomes full-screen again. 137Override {@link android.app.Activity#onPictureInPictureModeChanged 138Activity.onPictureInPictureModeChanged()} or 139{@link android.app.Fragment#onPictureInPictureModeChanged 140Fragment.onPictureInPictureModeChanged()} and enable or 141disable your UI elements as needed, for example:</p> 142 143<pre> 144@Override 145public 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 157Picture-in-picture</h2> 158 159<p>When your activity switches to PIP, the system considers the activity in a 160paused state, and calls your activity's {@link android.app.Activity#onPause 161onPause()} method. Video playback should not be paused and should continue 162playing 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 165calls your activity's {@link android.app.Activity#onStop onStop()} and 166{@link android.app.Activity#onStart onStart()}. By doing this, you can avoid 167having to check if your app is in PIP mode in 168{@link android.app.Activity#onPause onPause()} and explicitly 169continuing playback.</p> 170 171<p>If you have to pause playback in your {@link android.app.Activity#onPause 172onPause()} implementation, check for PIP mode by calling {@code 173isInPictureInPictureMode()} and handle playback appropriately, for example:</p> 174 175<pre> 176@Override 177public 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 189system 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 193Picture-in-picture</h2> 194 195<p>In your app, a user might select a new video when browsing for content on 196the main screen, while a video playback activity is in PIP mode. Play the new 197video in the existing playback activity in full screen mode, instead of 198launching a new activity that might confuse the user.</p> 199 200<p>To ensure a single activity is used for video playback requests and 201switched 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<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 214onNewIntent()} and handle the new video, stopping any existing video 215playback 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 220your activity into PIP mode, avoid showing anything except video content. 221Track when your activity enters PIP mode and hide UI elements, as described 222in <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 225screen, you should avoid showing critical information in the main screen 226in 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 229receive input events while in PIP mode, use 230{@link android.media.session.MediaSession#setCallback 231MediaSession.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 234a Now Playing Card</a>.</p> 235 236<p>When your app is in PIP mode, video playback in the PIP window can cause 237audio interference with another app, such as a music player app or voice search 238app. To avoid this, request audio focus when you start playing the video, 239and handle audio focus change notifications, as described in 240<a href="{@docRoot}training/managing-audio/audio-focus.html">Managing Audio 241Focus</a>. If you receive notification of audio focus loss when in PIP mode, 242pause or stop video playback.</p> 243