Proyección de contenido multimedia

Las APIs de android.media.projection que se introdujeron en Android 5 (nivel de API 21) te permiten capturar el contenido de la pantalla de un dispositivo como una transmisión de contenido multimedia que puedes reproducir, grabar o transmitir a otros dispositivos, como TVs.

Android 14 (nivel de API 34) presenta la función de compartir pantalla de la app, que permite a los usuarios compartir una sola ventana de la app en lugar de toda la pantalla del dispositivo, independientemente del modo de ventana. La función de compartir pantalla de la app excluye la barra de estado, la barra de navegación, las notificaciones y otros elementos de la IU del sistema de la pantalla compartida, incluso cuando se usa para capturar una app en pantalla completa. Solo se comparte el contenido de la app seleccionada.

El uso compartido de pantalla de la app garantiza la privacidad del usuario, aumenta su productividad y mejora la realización de varias tareas a la vez, ya que permite que los usuarios ejecuten varias apps, pero restringe el uso compartido de contenido a una sola app.

Tres representaciones de visualización

Una proyección de contenido multimedia captura el contenido de la pantalla de un dispositivo o la ventana de una app y, luego, proyecta la imagen capturada en una pantalla virtual que renderiza la imagen en Surface.

Figura 1: Pantalla real del dispositivo o ventana de la app proyectada en una pantalla virtual. Pantalla virtual escrita en Surface que brinda la aplicación.

La aplicación proporciona Surface a través de MediaRecorder, SurfaceTexture o ImageReader, que consume el contenido de la pantalla capturada y te permite administrar las imágenes renderizadas en Surface en tiempo real. Puedes guardar las imágenes como una grabación, o transmitirlas a una TV o a otro dispositivo.

Pantalla real

Para iniciar una sesión de proyección de contenido multimedia, obtén un token que le otorgue a tu app la capacidad de capturar el contenido de la pantalla del dispositivo o la ventana de la app. El token es representado por una instancia de la clase MediaProjection.

Usa el método getMediaProjection() del servicio del sistema MediaProjectionManager para crear una instancia de MediaProjection cuando inicies una actividad nueva. Inicia la actividad con un intent del método createScreenCaptureIntent() para especificar una operación de captura de pantalla:

Kotlin

val mediaProjectionManager = getSystemService(MediaProjectionManager::class.java)
var mediaProjection : MediaProjection

val startMediaProjection = registerForActivityResult(
    StartActivityForResult()
) { result ->
    if (result.resultCode == RESULT_OK) {
        mediaProjection = mediaProjectionManager
            .getMediaProjection(result.resultCode, result.data!!)
    }
}

startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())

Java

final MediaProjectionManager mediaProjectionManager =
    getSystemService(MediaProjectionManager.class);
final MediaProjection[] mediaProjection = new MediaProjection[1];

ActivityResultLauncher startMediaProjection = registerForActivityResult(
    new StartActivityForResult(),
    result -> {
        if (result.getResultCode() == Activity.RESULT_OK) {
            mediaProjection[0] = mediaProjectionManager
                .getMediaProjection(result.getResultCode(), result.getData());
        }
    }
);

startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent());

Nota: Las apps que usan las APIs de android.media.projection pueden compartir la pantalla de la app automáticamente a través de la llamada a createScreenCaptureIntent().

Pantalla virtual

La pieza central de una proyección de contenido multimedia es la pantalla virtual, que creas cuando llamas a createVirtualDisplay() en una instancia de MediaProjection:

Kotlin

virtualDisplay = mediaProjection.createVirtualDisplay(
                     "ScreenCapture",
                     width,
                     height,
                     screenDensity,
                     DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
                     surface,
                     null, null)

Java

virtualDisplay = mediaProjection.createVirtualDisplay(
                     "ScreenCapture",
                     width,
                     height,
                     screenDensity,
                     DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
                     surface,
                     null, null);

Los parámetros width y height especifican las dimensiones de la pantalla virtual. Para obtener valores de ancho y altura, usa las APIs de WindowMetrics que se introdujeron en Android 11 (nivel de API 30). (Para obtener más información, consulta la sección Tamaño de proyección de contenido multimedia).

Nota: El parámetro de densidad de pantalla del método createVirtualDisplay() habilita el ajuste de la resolución de la pantalla capturada para compartir o transmitir a una pantalla externa con menor resolución. Usa Configuration#densityDpi en lugar de Display#getRealMetrics() (que dejó de estar disponible) para obtener el valor del argumento de densidad de pantalla.

Superficie

Debes dimensionar la superficie de proyección de contenido multimedia para producir resultados en la resolución adecuada. Haz que la superficie sea grande (baja resolución) para transmitir la pantalla a televisiones o monitores de computadora, y pequeña (alta resolución) para grabar la pantalla de dispositivos.

A partir de Android 12L (nivel de API 32), cuando se renderiza contenido capturado en la superficie, el sistema ajusta el contenido de forma uniforme y mantiene la relación de aspecto, de modo que ambas dimensiones del contenido (ancho y alto) sean iguales o menores que las dimensiones correspondientes de la superficie. Luego, el contenido capturado se centra en la superficie.

El enfoque de escalamiento de Android 12L mejora la transmisión de la pantalla a televisiones y otras pantallas grandes, ya que se maximiza el tamaño de la imagen de la superficie, a la vez que se garantiza la relación de aspecto correcta.

Permiso de servicios en primer plano

Si tu app está orientada a Android 14 o versiones posteriores, el manifiesto de la app debe incluir una declaración de permiso para el tipo de servicio en primer plano mediaProjection:

<manifest ...>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
    <application ...>
        <service
            android:name=".MyMediaProjectionService"
            android:foregroundServiceType="mediaProjection"
            android:exported="false">
        </service>
    </application>
</manifest>

Inicia el servicio de proyección de contenido multimedia con una llamada a startForeground().

Si no especificas el tipo de servicio en primer plano en la llamada, el tipo se establece de forma predeterminada en un número entero de bits de los tipos de servicio en primer plano definidos en el manifiesto. Si el manifiesto no especifica ningún tipo de servicio, el sistema arroja MissingForegroundServiceTypeException.

Consentimiento del usuario

Tu app debe solicitar el consentimiento del usuario antes de cada sesión de proyección de contenido multimedia. Una sesión es una sola llamada a createVirtualDisplay(). Se debe usar un token MediaProjection solo una vez para realizar la llamada.

En Android 14 o versiones posteriores, el método createVirtualDisplay() arroja una SecurityException si tu app realiza alguna de las siguientes acciones:

• Pasa una instancia de Intent que se muestra de createScreenCaptureIntent() a getMediaProjection() más de una vez
• Llama a createVirtualDisplay() más de una vez en la misma instancia de MediaProjection

Tamaño de la proyección de contenido multimedia

Una proyección de contenido multimedia puede capturar toda la pantalla del dispositivo o una ventana de la app, independientemente del modo de ventana.

Tamaño inicial

Con la proyección de contenido multimedia en pantalla completa, la app debe determinar el tamaño de la pantalla del dispositivo. En el uso compartido de pantalla de la app, la app no podrá determinar el tamaño de la pantalla capturada hasta que el usuario seleccione la región de captura. Por lo tanto, el tamaño inicial de cualquier proyección multimedia es el tamaño de la pantalla del dispositivo.

Usa el método WindowManager getMaximumWindowMetrics() de la plataforma para mostrar un objeto WindowMetrics para la pantalla del dispositivo, incluso si la app host de proyección de contenido multimedia está en el modo multiventana y ocupa solo una parte de la pantalla.

Para brindar compatibilidad hasta el nivel de API 14, usa el método WindowMetricsCalculator computeMaximumWindowMetrics() de la biblioteca de WindowManager de Jetpack.

Llama al método WindowMetrics getBounds() para obtener el ancho y la altura de la pantalla del dispositivo.

Cambios de tamaño

El tamaño de la proyección multimedia puede cambiar cuando se rota el dispositivo o cuando el usuario selecciona una ventana de la app como la región de captura en el uso compartido de pantalla de la app. Es posible que la proyección de contenido multimedia tenga formato letterbox si el contenido capturado tiene un tamaño diferente al de las métricas de ventana máxima obtenidas cuando se configuró la proyección de contenido multimedia.

Para garantizar que la proyección de contenido multimedia se alinee con precisión con el tamaño del contenido capturado para cualquier región capturada y en todas las rotaciones del dispositivo, usa la devolución de llamada onCapturedContentResize() para cambiar el tamaño de la captura. (Para obtener más información, consulta la sección Personalización que aparece a continuación).

Personalización

Tu app puede personalizar la experiencia del usuario de proyección de contenido multimedia con las siguientes APIs de MediaProjection.Callback:

• onCapturedContentVisibilityChanged(): Permite que la app host (la app que inició la proyección multimedia) oculte o muestre el contenido compartido.

  Usa esta devolución de llamada para personalizar la IU de tu app según si el usuario puede ver la región capturada. Por ejemplo, si el usuario puede ver tu app y esta muestra el contenido capturado dentro de su IU, y el usuario también puede ver la app capturada (como se indica a través de esta devolución de llamada), el usuario ve el mismo contenido dos veces. Usa la devolución de llamada para actualizar la IU de tu app y ocultar el contenido capturado y liberar espacio de diseño en tu app para otro contenido.

• onCapturedContentResize(): Permite que la app host cambie el tamaño de la proyección de contenido multimedia en la pantalla virtual y la proyección de contenido multimedia Surface según el tamaño de la región de la pantalla capturada.

  Se activa cada vez que el contenido capturado (una sola ventana de la app o la pantalla completa del dispositivo) cambia de tamaño (debido a la rotación del dispositivo o a que la app capturada ingresa a un modo de ventana diferente). Usa esta API para cambiar el tamaño de la pantalla y la superficie virtuales para garantizar que la relación de aspecto coincida con el contenido capturado y que la captura no tenga formato letterbox.

Recuperación de recursos

Tu app debe registrar la devolución de llamada MediaProjection onStop() para que se le informe cuando se detenga la sesión de proyección multimedia y deje de ser válida. Cuando se detenga la sesión, la app debe liberar los recursos que contiene, como la pantalla virtual y la superficie de proyección. Una sesión de proyección de contenido multimedia detenida ya no puede crear una pantalla virtual nueva, incluso si tu app no creó una pantalla virtual para esa proyección de contenido multimedia.

El sistema invoca la devolución de llamada cuando finaliza la proyección de contenido multimedia. Esta terminación puede ocurrir por varios motivos, como los siguientes:

• El usuario detiene la sesión con la IU de la app o el chip de la barra de estado de proyección de contenido multimedia del sistema.
• se está bloqueando la pantalla
• se inicia otra sesión de proyección multimedia
• se finaliza el proceso de la app

Si tu app no registra la devolución de llamada, cualquier llamada a createVirtualDisplay() arroja IllegalStateException.

Inhabilitar

Android 14 o versiones posteriores habilitan el uso compartido de pantalla de la app de forma predeterminada. Cada sesión de proyección multimedia les brinda a los usuarios la opción de compartir una ventana de la app o toda la pantalla.

Tu app puede inhabilitar el uso compartido de pantalla de la app llamando al método createScreenCaptureIntent(MediaProjectionConfig) con un argumento MediaProjectionConfig que se muestra desde una llamada a createConfigForDefaultDisplay().

Una llamada a createScreenCaptureIntent(MediaProjectionConfig) con un argumento MediaProjectionConfig que se muestra desde una llamada a createConfigForUserChoice() es igual que el comportamiento predeterminado, es decir, una llamada a createScreenCaptureIntent().

Advertencia: Los fabricantes de dispositivos pueden anular la inhabilitación del uso compartido de la pantalla de la app si esta usa de forma inadecuada la inhabilitación para mostrar datos privados del usuario desde una ventana de la app que no se debe compartir. Consulta Modo de compatibilidad del dispositivo.

Apps de tamaño variable

Siempre configura las apps de proyección de contenido multimedia para que puedan cambiar de tamaño (resizeableActivity="true"). Las apps que pueden cambiar de tamaño admiten cambios en la configuración del dispositivo y el modo multiventana (consulta Compatibilidad con el modo Multiventana).

Si no se puede cambiar el tamaño de la app, esta debe consultar los límites de la pantalla desde un contexto de ventana y usar getMaximumWindowMetrics() para recuperar el WindowMetrics del área de visualización máxima disponible para la app :

Kotlin

val windowContext = context.createWindowContext(context.display!!,
      WindowManager.LayoutParams.TYPE_APPLICATION, null)
val projectionMetrics = windowContext.getSystemService(WindowManager::class.java)
      .maximumWindowMetrics

Java

Context windowContext = context.createWindowContext(context.getDisplay(),
      WindowManager.LayoutParams.TYPE_APPLICATION, null);
WindowMetrics projectionMetrics = windowContext.getSystemService(WindowManager.class)
      .getMaximumWindowMetrics();

Precaución: Display#getRealSize() y Display#getRealMetrics() dejaron de estar disponibles a partir del nivel de API 31. En el caso de las apps que no pueden cambiar de tamaño (resizeableActivity="false"), los métodos muestran los límites de la ventana de la app en lugar de los límites de la pantalla del dispositivo.

Chip de la barra de estado y detención automática

Los exploits de proyección de pantalla exponen datos privados del usuario, como información financiera, porque los usuarios no se dan cuenta de que se está compartiendo la pantalla de su dispositivo.

Android 15 (nivel de API 35) y versiones posteriores muestran un chip de barra de estado grande y prominente para alertar a los usuarios sobre cualquier proyección de pantalla en curso. Los usuarios pueden presionar el chip para evitar que se comparta, transmita o grabe su pantalla. Además, la proyección de pantalla se detiene automáticamente cuando se bloquea la pantalla del dispositivo.

Figura 2: Chip de la barra de estado para compartir, transmitir y grabar pantallas.

Para probar la disponibilidad del chip de la barra de estado de la proyección multimedia, inicia la grabación, la transmisión o el uso compartido de pantalla. El chip debería aparecer en la barra de estado.

Para asegurarte de que tu app libere recursos y actualice su IU cuando la interacción del usuario con el chip de la barra de estado o la activación de la pantalla de bloqueo detenga la proyección de pantalla, haz lo siguiente:

• Crea una instancia de MediaProjection.Callback.

• Implementa el método de devolución de llamada onStop(). Se llama al método cuando se detiene la proyección de la pantalla. Libera los recursos que tu app esté reteniendo y actualiza la IU de la app según sea necesario.

Para probar la devolución de llamada, presiona el chip de la barra de estado o bloquea la pantalla del dispositivo para detener la proyección de pantalla. Verifica que se llame al método onStop() y que tu app responda según lo previsto.

Recursos adicionales

Para obtener más información sobre la proyección de contenido multimedia, consulta Cómo capturar la reproducción de audio y video.