tv/playback/picture-in-picture.jd

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

@jd:body

<div id="tb-wrapper">
<div id="tb">

<h2>En este documento</h2>
<ol>
  <li><a href="#declaring">Declarar que la actividad permite
el modo Picture-in-Picture</a></li>
  <li><a href="#pip_button">Cambiar la actividad al modo Picture-in-picture</a>
</li>
  <li><a href="#handling_ui">Gestionar las IU durante el modo Picture-in-picture</a>
</li>
  <li><a href="#continuing_playback">Continuar la reproduccin de video durante
el modo Picture-in-picture</a></li>
  <li><a href="#single_playback">Usar una nica actividad de reproduccin para
el modo Picture-in-picture</a></li>
  <li><a href="#best">Prcticas recomendadas</a></li>
</ol>

<h2>Consulta tambin</h2>
<ol>
  <li><a href="{@docRoot}preview/features/multi-window.html">Compatibilidad con
ventanas mltiples</a></li>
</ol>

</div>
</div>

<p>Con Android N, los usuarios de Android TV ahora pueden ver un video
en una ventana fija que se ubica en una esquina de la pantalla mientras navegan dentro de
aplicaciones. El modo picture-in-picture (PIP) permite que las aplicaciones reproduzcan un video
en una ventana fija mientras se lleva a cabo otra actividad
en el fondo. La ventana de PIP les permite a los usuarios realizar mltiples tareas mientras usan tu aplicacin, lo cual les permite
ser ms productivos.</p>

<p>Tu aplicacin puede decidir cundo activar el modo PIP. Aqu te mostramos algunos ejemplos de
situaciones en las que se podra usar el modo PIP:</p>

<ul>
<li>Tu aplicacin puede pasar un video al modo PIP cuando el usuario retrocede
en la navegacin desde el video para explorar otro contenido.</li>
<li>Tambin puede hacerlo mientras el usuario est viendo el final
de un episodio de contenido. La pantalla principal muestra informacin promocional
o de resumen sobre el prximo captulo de la serie.</li>
<li>Tu aplicacin puede brindarles a los usuarios una forma de poner en cola otro contenido mientras
miran un video. El video contina reproducindose en modo PIP mientras la pantalla
principal muestra una actividad de seleccin de contenido.</li>
</ul>

<p>La ventana de PIP es de 240x135 dp y se muestra en la capa delantera en una de las
cuatro esquinas de la pantalla que el sistema elige. El usuario puede acceder a un men de
PIP que le permite activar o desactivar la ventana de PIP a pantalla completa o cerrarla
presionando el botn <b>Home</b> en el control remoto. Si se comienza a reproducir
otro video en la pantalla principal, la ventana de PIP se cierra
automticamente. Los usuarios tambin pueden cerrar la ventana de PIP desde Recents.</p>

<img src="{@docRoot}images/android-7.0/pip-active.png" />
<p class="img-caption"><strong>Imagen 1.</strong> Un video picture-in-picture
visible en una esquina de la pantalla mientras el usuario explora contenido
en la pantalla principal.</p>

<p>El modo PIP aprovecha las API de ventanas mltiples disponibles en Android N para
brindar la ventana superpuesta fija de video. Para agregarle el modo PIP a tu aplicacin, debes
registrar las actividades que permitan este modo, cambiar la actividad al modo PIP segn
sea necesario y asegurarte de que los elementos de IU se oculten y que la reproduccin de video contine mientras
la actividad se encuentra en modo PIP.</p>

<h2 id="declaring">Declarar que la actividad permite el modo picture-in-picture</h2>

<p>De forma predeterminada, el sistema no permite el modo PIP para aplicaciones automticamente.
Si deseas permitir este modo en tu aplicaciones, registra la actividad
de video en tu manifiesto configurando
<code>android:supportsPictureInPicture</code> y
<code>android:resizeableActivity</code> en <code>true</code>. Adems, debes especificar
que tu actividad gestiona los cambios de configuracin de la presentacin para que la actividad
no se reinicie cuando ocurran cambios de presentacin durante las transiciones en el modo PIP.</p>

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

<p>Cuando registres la actividad, ten en cuenta que, en el modo PIP, la
actividad se muestra en una ventana superpuesta pequea en una pantalla de TV. Las actividades de reproduccin
de videos con IU mnimas brindan la mejor experiencia de usuario. Las actividades que
incluyen elementos de IU pequeos podran no brindar una buena experiencia de usuario
cuando se cambian al modo PIP, porque los usuarios no podrn ver los detalles de los elementos de IU
en la ventana PIP.</p>

<h2 id="pip_button">Cambiar la actividad al modo Picture-in-picture</h2>

Cuando necesites cambiar la actividad al modo PIP, llama a
<code>Activity.enterPictureInPictureMode()</code>. En el siguiente ejemplo, se
cambia al modo PIP cuando el usuario selecciona un botn PIP especial en una barra
de control de medios:</p>

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

<p>Agregar un botn PIP a la barra de control de medios le permite al usuario cambiar
fcilmente al modo PIP y seguir controlando la reproduccin de video.</p>

<img src="{@docRoot}images/android-7.0/pip-button.png" />
<p class="img-caption"><strong>Imagen 1.</strong> Un botn
PIP en una barra de control de medios.</p>

<p>Android N incluye una nueva clase
<code>PlaybackControlsRow.PictureInPictureAction</code> que define
las acciones de PIP de la barra de control y usa el cono PIP.</p>

<h2 id="handling_ui">Gestionar las IU durante el modo picture-in-picture</h2>

<p>Cuando la actividad ingresa al modo PIP, esta solo debera mostrar la reproduccin
de video. Debes quitar los elementos de IU antes de que la actividad ingrese al modo PIP
y volver a mostrarlos cuando la actividad vuelva al modo de pantalla completa.
Anula <code>Activity.onPictureInPictureModeChanged()</code> o
<code>Fragment.onPictureInPictureModeChanged()</code> y habilita
o inhabilita los elementos de IU segn sea necesario, por ejemplo:</p>

<pre>
&#64;Override
public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
    if (isInPictureInPictureMode) {
        // Hide the controls in picture-in-picture mode.
        ...
    } else {
        // Restore the playback UI based on the playback status.
        ...
    }
}
</pre>

<h2 id="continuing_playback">Continuar la reproduccin de video durante
el modo Picture-in-picture</h2>

<p>Cuando la actividad cambia al modo PIP, el sistema considera que se encuentra en
pausa y llama al mtodo <code>onPause()</code> de la actividad. La reproduccin
de video no debera pausarse y debera continuar si la actividad se
pausa debido al modo PIP. Busca el modo PIP en el mtodo
<code>onPause()</code> de la actividad y controla la reproduccin segn corresponda, por
ejemplo:</p>

<pre>
&#64;Override
public void onPause() {
    // If called while in PIP mode, do not pause playback
    if (isInPictureInPictureMode()) {
        // Continue playback
        ...
    }
    // If paused but not in PIP, pause playback if necessary
    ...
}
</pre>

<p>Cuando la actividad sale del modo PIP y vuelve al modo de pantalla completa, el
sistema reinicia la actividad y llama al mtodo <code>onResume()</code>.</p>

<h2 id="single_playback">Usar una nica actividad de reproduccin para
el modo Picture-in-picture</h2>

<p>En tu aplicacin, un usuario puede seleccionar un nuevo video cuando busca contenido en la
pantalla principal, mientras una actividad de reproduccin de video est en modo PIP. Reproduce el nuevo
video en la actividad de reproduccin actual en modo de pantalla completa, en lugar de
iniciar una nueva actividad que podra confundir al usuario.</p>

<p>A fin de garantizar que se utilice una nica actividad para las solicitudes de reproduccin de video y que esta
 ingrese en el modo PIP o salga de este cuando sea necesario, configura el
<code>android:launchMode</code> de la actividad en <code>singleTask</code>, en el manifiesto:
</p>

<pre>
&lt;activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...
</pre>

<p>En tu actividad, anula {@link android.app.Activity#onNewIntent
Activity.onNewIntent()} y administra el nuevo video, deteniendo cualquier reproduccin
de video actual si es necesario.</p>

<h2 id="best">Prcticas recomendadas</h2>

<p>El modo PIP est diseado para actividades que reproducen un video en pantalla completa. Cuando cambies la
actividad al modo PIP, evita que se muestre cualquier elemento que no sea el contenido del video.
Rastrea el cambio a modo PIP de la actividad y oculta los elementos de IU, como se explica
en la seccin <a href="#handling_ui">Gestionar las IU durante el modo picture-in-picture</a>.</p>

<p>Debido a que la ventana de PIP se muestra como una ventana flotante en una
esquina de la pantalla, debes evitar mostrar informacin importante en la pantalla principal
en cualquier rea que pueda quedar oculta detrs de la ventana de PIP.</p>

<p>Cuando una actividad se encuentra en modo PIP, de forma predeterminada, no tiene focalizacin en las entradas. Para
recibir eventos de entradas durante este modo, usa
<code>MediaSession.setMediaButtonReceiver()</code>.</p>