A partir de Android 8.0 (nivel de API 26), Android permite que las actividades se inicien en el modo de pantalla en pantalla (PIP). PIP es un tipo especial de modo multiventana que se usa principalmente para la reproducción de videos. Permite al usuario ver un video en una ventana pequeña fijada en una esquina de la pantalla mientras navega entre apps o explora contenido en la pantalla principal.
PIP aprovecha las API de multiventana disponibles en Android 7.0 para proporcionar la ventana de video fijada superpuesta. Para agregar PIP a tu app, debes registrar las actividades que admitan PIP, cambiar tu actividad al modo de PIP según sea necesario y asegurarte de que los elementos de la IU estén ocultos y la reproducción de video continúe cuando la actividad esté en modo de PIP.
La ventana de PIP aparece en la capa superior de la pantalla, en una esquina que elige el sistema.
Cómo pueden interactuar los usuarios con la ventana de PIP
Los usuarios pueden arrastrar la ventana de PIP a otra ubicación. A partir de Android 12, los usuarios también pueden hacer lo siguiente:
Presionar una vez la ventana para mostrar un botón de activación de pantalla completa, un botón de cierre, un botón de configuración y acciones personalizadas que proporciona tu app (por ejemplo, controles de reproducción).
Presionar dos veces la ventana de PIP para cambiar de su tamaño actual al tamaño máximo. Para almacenar la ventana, arrástrala hacia el borde izquierdo o derecho. Si deseas dejar de almacenarla, presiona la parte visible de la ventana almacenada o arrástrala hacia afuera.
Cambiar el tamaño de la ventana de PIP con la función de pellizcar para hacerle zoom.
Tu app controla cuándo ingresa en modo de PIP la actividad actual. Estos son algunos ejemplos:
Una actividad puede ingresar al modo PIP cuando el usuario presiona el botón de inicio (en el modo de navegación con botones) o desliza el dedo hacia arriba para ir a la pantalla principal (en el modo de navegación por gestos). (Así es como Google Maps sigue mostrando indicaciones mientras el usuario ejecuta otra actividad al mismo tiempo).
Tu app puede mover un video al modo de PIP cuando el usuario navega hacia atrás desde el video para explorar otro contenido.
Tu app puede cambiar un video al modo de PIP mientras un usuario mira el final de un episodio de contenido. La pantalla principal muestra información promocional o de resumen sobre el próximo episodio de la serie.
Tu app puede proporcionar una manera para que los usuarios pongan en cola contenido adicional mientras miran un video. El video sigue reproduciéndose en modo de PIP mientras la pantalla principal muestra una actividad de selección de contenido.
Cómo declarar la compatibilidad con pantalla en pantalla
De forma predeterminada, el sistema no admite automáticamente PIP para apps.
Si deseas permitir este modo en tu app, configura android:supportsPictureInPicture en true para registrar la actividad de video en tu manifiesto. Además, especifica que tu actividad controla los cambios de configuración de diseño para que no se reinicie cuando se realicen cambios de diseño durante las transiciones del modo de PIP.
<activity android:name="VideoActivity"
android:supportsPictureInPicture="true"
android:configChanges=
"screenSize|smallestScreenSize|screenLayout|orientation"
...
Cómo cambiar tu actividad a pantalla en pantalla
Para ingresar al modo de pantalla en pantalla, una actividad debe llamar a enterPictureInPictureMode().
Por ejemplo, en el siguiente código, se cambia una actividad al modo de PIP cuando el usuario hace clic en un botón exclusivo en la IU de la app:
Kotlin
override fun onActionClicked(action: Action) {
if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
activity?.enterPictureInPictureMode()
return
}
}
Java
@Override
public void onActionClicked(Action action) {
if (action.getId() == R.id.lb_control_picture_in_picture) {
getActivity().enterPictureInPictureMode();
return;
}
...
}
Es posible que desees incluir lógica que cambie una actividad al modo de PIP en lugar de pasar a segundo plano. Por ejemplo, Google Maps cambia al modo de PIP si el usuario presiona el botón Recientes o de inicio mientras la app está navegando. Para solucionar este caso, anula onUserLeaveHint():
Kotlin
override fun onUserLeaveHint() {
if (iWantToBeInPipModeNow()) {
enterPictureInPictureMode()
}
}
Java
@Override
public void onUserLeaveHint () {
if (iWantToBeInPipModeNow()) {
enterPictureInPictureMode();
}
}
Cómo lograr que las transiciones al modo de PIP sean más fluidas desde la navegación por gestos
A partir de Android 12, puedes usar la marca setAutoEnterEnabled a fin de brindar transiciones más fluidas al modo de PIP cuando deslizas el dedo hacia arriba para ir a la pantalla principal en el modo de navegación por gestos.
Para implementar esta función, haz lo siguiente:
Usa
setAutoEnterEnabledpara construirPictureInPictureParams.Builderde la siguiente manera:setPictureInPictureParams(new PictureInPictureParams.Builder() .setAspectRatio(aspectRatio) .setSourceRectHint(sourceRectHint) .setAutoEnterEnabled(true) .build());Llama a
setPictureInPictureParamscon la clasePictureInPictureParamsactualizada con anticipación. La app no debe esperar la devolución de llamadaonUserLeaveHint(como sí habría sucedido con Android 11).Por ejemplo, una app puede llamar a
setPictureInPictureParamsen la primera reproducción y en cualquier reproducción posterior si se cambia la relación de aspecto.Llama a
setAutoEnterEnabled(false)según sea necesario. Por ejemplo, es probable que no sea óptimo que una app de video ingrese al modo de PIP si la reproducción actual está en pausa.
Cómo controlar las IU durante el modo de pantalla en pantalla
Cuando la actividad ingresa al modo de pantalla en pantalla o sale de este, el sistema llama a Activity.onPictureInPictureModeChanged() o a Fragment.onPictureInPictureModeChanged().
Debes anular estas devoluciones de llamada para volver a dibujar los elementos de la IU de la actividad. Ten en cuenta que, en el modo de PIP, tu actividad se muestra en una ventana pequeña. Los usuarios no pueden interactuar con los elementos de la IU de la app cuando están en modo de PIP, y los detalles de los elementos pequeños de la IU pueden ser difíciles de ver. Las actividades de reproducción de video con una IU mínima proporcionan la mejor experiencia del usuario.
Si la app necesita proporcionar acciones personalizadas para el modo de PIP, consulta Cómo agregar controles en este documento. Quita otros elementos de la IU antes de que la actividad ingrese a PIP y restablécelos cuando vuelva a ser de pantalla completa:
Kotlin
override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean,
newConfig: Configuration) {
if (isInPictureInPictureMode) {
// Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
} else {
// Restore the full-screen UI.
}
}
Java
@Override
public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
if (isInPictureInPictureMode) {
// Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
} else {
// Restore the full-screen UI.
...
}
}
Compatibilidad con animaciones más fluidas para salir del modo de PIP
A partir de Android 12, ahora la marca SourceRectHint se vuelve a usar para implementar animaciones más fluidas cuando se sale del modo de PIP.
Para salir, el sistema crea la animación con el elemento sourceRectHint disponible actualmente, ya sea el objeto Rect original que se usa a fin de ingresar al modo de PIP o un parámetro Rect actualizado que proporciona la app.
Para implementar esta función, actualiza la app de la siguiente manera:
Continúa construyendo
PictureInPictureParamsconsourceRectHintyaspectRatiopara lograr una animación de entrada fluida.Si es necesario, actualiza la marca
sourceRectHintantes de que el sistema inicie la transición de salida. Cuando el sistema está a punto de salir del modo de PIP, la jerarquía de vistas de la actividad se presenta en su configuración de destino (por ejemplo, pantalla completa). La app puede adjuntar un objeto de escucha para el cambio de diseño a su vista raíz o de destino (como la vista del reproductor de video) a fin de detectar el evento y actualizar la marca sourceRectHint antes de que comience la animación.Kotlin
// Listener is called immediately after the user exits PiP but before animating. playerView.addOnLayoutChangeListener { _, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom -> if (left != oldLeft || right != oldRight || top != oldTop || bottom != oldBottom) { // The playerView's bounds changed, update the source hint rect to // reflect its new bounds. val sourceRectHint = Rect() playerView.getGlobalVisibleRect(sourceRectHint) setPictureInPictureParams( PictureInPictureParams.Builder() .setSourceRectHint(sourceRectHint) .build() ) } }Java
// Listener is called right after the user exits PiP but before // animating. playerView.addOnLayoutChangeListener((v, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom) -> { if (left != oldLeft || right != oldRight || top != oldTop || bottom != oldBottom) { // The playerView’s bounds changed, update the source hint rect to // reflect its new bounds. final Rect sourceRectHint = new Rect(); playerView.getGlobalVisibleRect(sourceRectHint); setPictureInPictureParams( new PictureInPictureParams.Builder() .setSourceRectHint(sourceRectHint) .build()); } });
Agregar controles
La ventana de PIP puede mostrar controles cuando el usuario abre el menú de la ventana (tocando la ventana en un dispositivo móvil o seleccionando el menú desde el control remoto de la TV).
Si una app tiene una sesión multimedia activa, aparecerán los controles de reproducción, pausa, siguiente y anterior.
También puedes especificar acciones personalizadas de manera explícita. Para ello, compila PictureInPictureParams con PictureInPictureParams.Builder.setActions() antes de ingresar al modo de PIP y pasa los parámetros cuando ingreses al modo de PIP con enterPictureInPictureMode(android.app.PictureInPictureParams) o setPictureInPictureParams(android.app.PictureInPictureParams).
Ten cuidado. Si intentas agregar más de getMaxNumPictureInPictureActions(), solo obtendrás el número máximo.
Cómo inhabilitar el cambio fluido de tamaño de contenido que no sea video
En Android 12, se agrega la marca setSeamlessResizeEnabled, que brinda una animación entre difuminados mucho más fluida cuando se cambia el tamaño de contenido que no sea video en la ventana de PIP. Anteriormente, si se cambiaba el tamaño de este tipo de contenido en una ventana de PiP, se podían crear artefactos visuales molestos.
De forma predeterminada, la marca setSeamlessResizeEnabled se configura en true para ofrecer retrocompatibilidad. Configúrala en true para el contenido de video y cámbiala a false para el contenido que no sea video.
Para inhabilitar el cambio fluido de tamaño de contenido que no sea video, usa el siguiente fragmento de código:
setPictureInPictureParams(new PictureInPictureParams.Builder()
.setSeamlessResizeEnabled(false)
.build());
Cómo continuar con la reproducción de video durante el modo de pantalla en pantalla
Cuando tu actividad cambia a PIP, el sistema coloca la actividad en estado de pausa y llama al método onPause() de la actividad. La reproducción de video no se debe pausar y debe seguir reproduciéndose si la actividad está pausada en modo de PIP.
En Android 7.0 y versiones posteriores, debes pausar y reanudar la reproducción de video cuando el sistema llame a los elementos onStop() y onStart() de tu actividad. De esa forma, puedes evitar tener que verificar si la app está en modo de PIP en onPause() y continuar explícitamente la reproducción.
Si tienes que pausar la reproducción en la implementación de onPause(), verifica el modo de PIP llamando a isInPictureInPictureMode() y controla la reproducción de manera adecuada, por ejemplo:
Kotlin
override fun onPause() {
super.onPause()
// If called while in PiP mode, do not pause playback
if (isInPictureInPictureMode) {
// Continue playback
} else {
// Use existing playback logic for paused Activity behavior.
}
}
Java
@Override
public void onPause() {
// If called while in PiP mode, do not pause playback
if (isInPictureInPictureMode()) {
// Continue playback
...
} else {
// Use existing playback logic for paused Activity behavior.
...
}
}
Cuando tu actividad vuelve al modo de pantalla completa, el sistema reanuda la actividad y llama al método onResume().
Cómo usar una sola actividad de reproducción para el modo de pantalla en pantalla
En tu app, un usuario puede seleccionar un video nuevo cuando busca contenido en la pantalla principal mientras una actividad de reproducción de video está en modo de PIP. Reproduce el video nuevo en la actividad de reproducción existente en modo de pantalla completa en lugar de iniciar una actividad nueva que podría confundir al usuario.
A fin de asegurarte de que se use una sola actividad para las solicitudes de reproducción de video y se pase al modo de PIP o se salga de él, según sea necesario, configura android:launchMode en singleTask en tu manifiesto:
<activity android:name="VideoActivity"
...
android:supportsPictureInPicture="true"
android:launchMode="singleTask"
...
En la actividad, anula onNewIntent() y controla el video nuevo, lo cual detiene cualquier reproducción de video existente si es necesario.
Recomendaciones
El modo de PIP puede estar inhabilitado en dispositivos que tienen poca RAM. Antes de que tu app use PIP, verifica que esté disponible llamando a hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE).
El modo de PIP está destinado a actividades que reproducen video en pantalla completa. Cuando cambies tu actividad al modo de PIP, evita mostrar algo que no sea contenido de video. Realiza un seguimiento de cuándo tu actividad ingresa al modo de PIP y oculta los elementos de la IU, como se describe en Cómo controlar las IU durante el modo de pantalla en pantalla.
Cuando una actividad está en modo de PIP, de forma predeterminada, no recibe el foco de entrada. Para recibir eventos de entrada mientras se está usando el modo de PIP, usa MediaSession.setCallback().
Para obtener más información sobre el uso de setCallback(), consulta Cómo mostrar una tarjeta de Está sonando.
Cuando tu app está en modo de PIP, la reproducción de video en la ventana de PiP puede causar interferencia de audio en otra app, como una app de reproductor de música o de búsqueda por voz. Para evitar este problema, solicita el foco de audio cuando comiences a reproducir el video y controla las notificaciones de cambio del foco de audio, como se describe en Cómo administrar el foco de audio. Si recibes una notificación de pérdida de foco de audio cuando se esté usando el modo de PIP, pausa o detén la reproducción de video.
Cuando se esté por activar PIP en tu app, ten en cuenta que solo la actividad principal ingresará al modo de pantalla en pantalla. En algunos casos, como en los dispositivos multiventana, es posible que la actividad menor se muestre y se vuelva a ver junto con la actividad en modo de PIP. Debes controlar esta situación como corresponde, lo cual incluye proporcionar una devolución de llamada onResume() o onPause() a la actividad menor. También es posible que el usuario interactúe con la actividad. Por ejemplo, si se mostrara una actividad de lista de videos y la actividad de reproducción de video estuviera en modo de PIP, el usuario podría seleccionar un video nuevo de la lista y la actividad en modo de PIP debería actualizarse en consecuencia.
Código de ejemplo adicional
Para descargar una app de ejemplo escrita en Android, consulta Muestra de pantalla en pantalla. Para descargar una app de ejemplo escrita en Kotlin, consulta Muestra de Android PictureInPicture (Kotlin).