Admite reproducción de video envolvente en apps de visionOS

¡Hola! Soy Jamal, ingeniero de aplicaciones multimedia del equipo de AVKit. Y yo soy Michael, ingeniero de software del equipo de visionOS Spatial Media. Una de mis tareas favoritas en visionOS es ver videos de una forma única de la plataforma. En visionOS 2, eso incluye experiencias increíbles, como la reproducción acoplada y los videos espaciales. En visionOS 26, hemos expandido todas tus estructuras de medios favoritas, como QuickLook, AVKit y RealityKit, para admitir perfiles de medios más inmersivos y ayudarte a crear una experiencia de reproducción de video completamente inmersiva en visionOS. Hoy, Jamal y yo te contaremos cómo admitir esta reproducción de video inmersiva en tu aplicación. Adelante, Jamal. Gracias, Michael. Primero, voy a repasar brevemente los distintos tipos de perfiles de video. Después, explicaré cómo QuickLook y las nuevas API de AVKit admiten la reproducción de medios inmersivos. Por último, Michael mostrará cómo las aplicaciones pueden personalizar las experiencias de reproducción inmersiva con RealityKit. Al final de este video, aprenderás todo lo que necesitas saber para admitir y crear una experiencia de reproducción de video inmersiva en tu aplicación de visionOS. Comenzaré repasando los distintos tipos de perfiles de video compatibles con visionOS 26.

En visionOS 1, los videos 2D y 3D eran la principal forma de ofrecer reproducción de video en las aplicaciones. Los medios espaciales permitieron a las personas grabar contenido estereoscópico fascinante y disfrutar de sus creaciones de forma inmersiva. visionOS 26 ahora incluye el Apple Projected Media Profile, o APMP, para videos de 180° y 360°, y campo de visión amplio. Y para la experiencia inmersiva definitiva, está Apple Immersive Video. Cada uno de estos perfiles es único a su manera. Si estos términos no te resultan familiares, en la sesión “Explore video experiences for visionOS” se explica todo. Hay muchas formas de admitir todos los perfiles de video que acabo de mencionar. Para lograrlo, elegir la tecnología adecuada para tu aplicación es fundamental para ofrecer una experiencia inmersiva excepcional.

QuickLook es una estructura ideal para presentar rápidamente cualquier tipo de medio, incluidos los medios inmersivos. AVKit ofrece una experiencia de video familiar y coherente en todas las plataformas, y al mismo tiempo brinda controles mejorados para la reproducción. RealityKit está diseñado para aquellas aplicaciones que exigen una experiencia de reproducción inmersiva única, como las que encuentras en entornos de videojuegos. Por último, si buscas compatibilidad con la reproducción inmersiva en un navegador, ve la sesión “What's new for spatial web”, donde explicamos con más detalle la reproducción inmersiva de contenido web.

A continuación, repasaré las herramientas disponibles para QuickLook y AVKit en visionOS 26, para que puedas empezar ya mismo a crear tu aplicación de reproducción de video inmersiva. QuickLook ofrece dos API para mostrar y previsualizar medios rápidamente en apps. Tenemos PreviewApplication, una API que habilita una ventana externa al proceso para la presentación de medios, y QLPreviewController, una API para previsualizar medios dentro de la ventana de una app o en una presentación modal. En visionOS 26, QLPreviewController se mejoró para admitir fotos y videos espaciales. Además, PreviewApplication ahora admite Apple Immersive Video y Apple Projected Media Profile, lo que incluye videos de 180°, 360° y campo de visión amplio.

QLPreviewController y PreviewApplication gestionan la presentación y las transiciones de estos nuevos perfiles de video y adaptan la vista previa con el estilo de video adecuado. En visionOS 26, todas las aplicaciones que ya implementan las API de QuickLook admitirán automáticamente los perfiles de medios inmersivos. Si quieres saber cómo implementar las API de PreviewApplication o QLPreviewController, consulta nuestros videos “Discover QuickLook for spatial computing” de la WWDC23 y “What’s new in QuickLook for visionOS” de la WWDC24. Pasemos ahora a las nuevas API de AVKit, que introdujimos para ofrecer compatibilidad total con la reproducción de video inmersiva. En visionOS 26, la API AVExperienceController se utiliza para realizar transiciones a una nueva experiencia inmersiva. Hay varias opciones para efectuar esta transición con AVExperienceController. La primera es Expanded. La experiencia que ofrece Expanded permite que AVPlayerViewController ocupe toda la escena de la ventana de la interfaz y, ahora, en visionOS 26, puede configurarse para lograr la reproducción de video inmersiva. Dentro de la configuración de Expanded, la nueva propiedad AutomaticTransitionToImmersive determina si deben iniciarse transiciones automáticas a una experiencia inmersiva. Esta propiedad puede establecerse en default, cuando se prefiere el comportamiento predeterminado del sistema, o en none, cuando no se desean transiciones automáticas.

Si se define none como valor de AutomaticTransitionToImmersive, AVPlayerViewController aplica un tratamiento de portal al contenido inmersivo cuando lo detecta. Mientras mantienes AVExperienceController en la experiencia Expanded. Aquí tienes un ejemplo para desactivar las transiciones automáticas a una experiencia inmersiva cuando se desea el tratamiento de portal para contenido inmersivo. Primero, crearé un AVPlayerViewController y lo configuraré con el contenido multimedia inmersivo. Luego, agregaré a su experienceController el conjunto recomendado, que incluye las experiencias adecuadas para la plataforma y garantiza que Expanded e Immersive formen parte de él. Dado que la propiedad AutomaticTransitionToImmersive tiene como valor inicial default, ahora debo establecerla en .none. Suponiendo que AVPlayerViewController ya está en la jerarquía de vistas de la aplicación, estoy listo para que AVExperienceController cambie a la experiencia Expanded. Con la nueva API de Immersive, que forma parte de Experiences en AVExperienceController, es posible pasar explícitamente a esta experiencia en lugar de depender solo de un disparador automático, igual que se hace con Expanded.

La API de Immersive incluye una nueva API Configuration que permite a las apps definir el lugar donde debe reproducirse el video inmersivo. El siguiente fragmento de código muestra cómo usar la experiencia Immersive con la API Configuration. Si AVPlayerViewController aún no se agregó a la jerarquía de vistas, debes indicar la escena de destino mediante la API Configuration. Para ello, accede a Experience Controller Configuration y proporciona el valor de placement con la función .over para la escena de ventana de interfaz que prefieras. Una vez definido, AVExperienceController está listo para pasar a la experiencia Immersive. Si AVPlayerViewController ya está en la jerarquía de vistas, AVExperienceController asumirá que la escena de ventana en la que se encuentra es la escena de destino deseada. Así es como las aplicaciones pueden pasar a una experiencia Immersive con AVKit. Al cambiar dentro y fuera de la experiencia Immersive, AVExperienceController gestiona las animaciones y las transiciones entre experiencias. Estas transiciones pueden iniciarse en cualquier momento: por el usuario, por la lógica de la aplicación o por el sistema.

Por ello, al usar AVExperienceController es importante comprender los cambios de estado de transición o presentación; esto te dará la flexibilidad necesaria para gestionar correctamente el estado activo de tu aplicación. Para esto, el Delegate Protocol de AVExperienceController es la solución. El protocolo cuenta con tres métodos de delegado: didChangeAvailableExperiences notifica cuando cambian las experiencias disponibles. prepareForTransitionUsing avisa cuando AVExperienceController está a punto de iniciar una transición, lo que permite que tu app se prepare por última vez para el nuevo estado. didChangeTransitionContext notifica cuando la transición a la nueva experiencia ha finalizado.

La experiencia Immersive depende del tipo de contenido que se proporcione. Usa el método didChangeAvailableExperiences para determinar si la experiencia inmersiva está disponible para el tipo de contenido actual. Por ejemplo, si se proporciona contenido multimedia 2D a AVPlayerViewController, la experiencia Immersive no estará disponible. Para obtener más información sobre cómo utilizar AVExperienceController y sus métodos de delegado, consulta el código de ejemplo “Playing immersive media with AVKit”. Además de las nuevas API para la reproducción de video inmersiva, QuickLook y AVKit ahora detectan la mitigación de comodidad en visionOS 26. Los videos inmersivos pueden mostrar un movimiento de cámara considerable, lo que podría provocar molestias en los espectadores. Para abordar este problema, ahora se admite la detección de movimiento en el contenido Apple Projected Media Profile. QuickLook y AVKit detectan un movimiento alto durante la reproducción y reducen automáticamente el nivel de inmersión. El espectador puede ajustar las opciones en la app Configuración, lo que permite que QuickLook y AVKit se comporten justo como el usuario desee. Para la mayoría de las experiencias de reproducción de video inmersivo, QuickLook y AVKit son excelentes. Para una experiencia inmersiva más personalizada, RealityKit es la elección ideal. Michael explicará por qué. Gracias, Jamal. Coincido: RealityKit es una gran estructura para la reproducción de video personalizada, como incluir video en un juego inmersivo o renderizar video con una interfaz personalizada. En visionOS 26, RealityKit admite la reproducción nativa de videos inmersivos. En esta sección, revisaré un nuevo modo inmersivo progresivo para videos de 180°, 360° y campo de visión amplio, y para Apple Immersive Video, además del renderizado de video espacial con estilo espacial completo, igual que en la app Fotos. También demostraré cómo detectar cuándo se aplican mitigaciones de comodidad en el video. Por último, compartiré consejos sobre el uso de RealityKit para reproducir video en una escena de SwiftUI. VideoPlayerComponent es una API potente para renderizar videos en RealityKit. Al adjuntar VideoPlayerComponent a una entidad de RealityKit, este crea su propia malla y material basados en el video actual del AVPlayer y en las propiedades del componente. VideoPlayerComponent es ideal para renderizar videos con modos de visualización inmersivos porque las actualizaciones de la malla y las animaciones se gestionan automáticamente, como en el ejemplo de acoplamiento de video del proyecto Destination Video en developer.apple.com. Consulta “Enhance your spatial computing app with RealityKit” para acceder a una introducción a VideoPlayerComponent.

En visionOS 26, VideoPlayerComponent admite los mismos perfiles de video inmersivo que ahora admiten QuickLook y AVKit. Comenzaré con los videos Apple Projected Media Profile y Apple Immersive Video. VideoPlayerComponent admite tres modos inmersivos para estos perfiles de video. Portal mode renderiza el video en un portal para una presentación en ventana. Progressive mode es una API nueva que permite a las personas ajustar su propio nivel de inmersión con la Digital Crown, lo que les permite mantenerse conectadas con el mundo que las rodea mientras continúan disfrutando del video. Y al 100 % de inmersión, Progressive mode equivale al modo de visualización inmersivo completo.

A partir de visionOS 26, la API Progressive mode se prefiere sobre el modo inmersivo completo para videos Apple Projected Media Profile y Apple Immersive Video, por la flexibilidad adicional que ofrece y porque admite la mitigación de confort, que explicaré más adelante. Aquí crearé una vista para renderizar un video de 180 grados en Portal mode y lo colocaré en un WindowGroup en el espacio compartido. Para configurar la reproducción en Portal mode, primero crea un AVPlayerItem y un AVPlayer con una URL local o HTTP Live Streaming. Luego, inicializa un VideoPlayerComponent con el reproductor. Define desiredImmersiveViewingMode del componente en portal y adjunta el componente a una entidad. La malla de VideoPlayerComponent tiene una altura de 1 metro por defecto. Reduce la escala del video a 0.4 metros para que quepa en la escena de ventana de SwiftUI. Por último, agrega la entidad a la escena. Para renderizar este video en Progressive mode, cambia desiredImmersiveViewingMode de Portal a Progressive. Como el componente controla la escala en Progressive mode, las operaciones de escala no surten efecto. La eliminaré para mantener todo claro. Pero actualizar el componente a Progressive mode no basta cuando se renderiza en una escena de SwiftUI. Para evitar que la malla se recorte con los bordes de la escena de ventana al expandirse, hay que colocar el nuevo ProgressiveVideoView en un ImmersiveSpace. Y al renderizar en Pogressive mode, ese ImmersiveSpace debe tener un ImmersionStyle progressive. Aquí, el nivel de inmersión inicial es 1, equivalente a la inmersión completa. Elegí un rango amplio, del 10% al 100%, para que las personas puedan ajustar su propio nivel de inmersión. Si hubiera incluido el 0%, la inmersión podría reducirse hasta que el contenido desapareciera, y ese no es el comportamiento que quiero para mi app. Tanto el ImmersionStyle de SwiftUI como el modo de visualización inmersiva del componente son importantes para configurar la reproducción. Cuando renderices en un RealityView, siempre haz que coincida desiredImmersiveViewingMode con ImmersionStyle. Para obtener más información sobre Immersion Styles, ve el video de 2024 “Dive deep into volumes and immersive spaces”. Para pasar de Portal mode a Progressive mode, espera el evento ImmersiveViewingModeDidChange al cambiar de escena SwiftUI. Los eventos ImmersiveViewingModeWillTransition y ImmersiveViewingModeDidTransition indican cuándo alternar la visibilidad de la interfaz durante las transiciones animadas para reducir los conflictos de movimiento y estereoscopía. Para ver ejemplos de estos eventos en acción, consulta el código de muestra “Playing immersive media with RealityKit” en developer.apple.com. Repasemos: para renderizar en portal los videos Apple Projected Media Profile y Apple Immersive Video, establece desiredImmersiveViewingMode en Portal. Los portales suelen estar en un SwiftUI WindowGroup en el espacio compartido, pero también pueden ser exclusivos en un ImmersiveSpace con un ImmersionStyle mixed. Para lograr una reproducción inmersiva, establece desiredImmersiveViewingMode en Progressive dentro de un ImmersiveSpace con un ImmersionStyle progressive, como en mi código anterior. Para obtener el comportamiento preferido del sistema, no establezcas desiredViewingMode. viewingMode será mono automáticamente para los videos monoscópicos y stereo para los videos estereoscópicos, como stereo 180 y Apple Immersive Video. Los videos espaciales son videos estéreo que quizás ya hayas estado grabando en todo el ecosistema de Apple. Incluyen metadatos espaciales que permiten un renderizado más cómodo e inmersivo. Al igual que los videos Apple Projected Media Profile y Apple Immersive Video, los videos espaciales ahora cuentan con compatibilidad nativa en RealityKit y se renderizan con estilo espacial completo y modos inmersivos.

El estilo espacial para los videos espaciales se configura con la propiedad desiredSpatialVideoMode en VideoPlayerComponent. Establece esta propiedad para especificar cómo debe renderizarse un video espacial. Lee la propiedad de solo lectura spatialVideoMode para determinar cómo se está renderizando un video espacial. Para activar el estilo espacial en los videos espaciales, define desiredSpatialVideoMode en .spatial.

El renderizado espacial es compatible con los ImmersiveViewingModes .portal y .full. A diferencia de otros tipos de video inmersivo, el renderizado inmersivo de video espacial siempre se configura con un modo de visualización inmersiva full. Los videos espaciales inmersivos se renderizan con un tamaño fijo basado en el campo de visión del contenido.

Establece desiredSpatialVideoMode en .screen, el valor predeterminado, para reproducir los videos espaciales en estéreo tradicional sobre una malla de pantalla. SpatialVideoMode no se actualizará, a menos que el video actual sea un video espacial válido. Como su nombre indica, este modo solo se aplica a los videos espaciales. Suscríbete al nuevo VideoPlayerEvent: SpatialVideoModeDidChange, o bien observa directamente la propiedad spatialVideoMode, para determinar si y cuándo se ha actualizado spatialVideoMode. Para renderizar un video espacial en Portal mode, primero crea un VideoPlayerComponent con un AVPlayer que contenga un video espacial. Establece desiredViewingMode en stereo. Es el valor predeterminado para los videos espaciales, pero prefiero ser explícito. Luego, establece desiredSpatialVideoMode en spatial y elige portal como desiredImmersiveViewingMode. Como antes, escala el video para que quepa dentro de la ventana. Cuando está en Spatial mode, el video puede ampliarse definiendo el modo de visualización inmersiva como completa. También quitaré la operación de escala, ya que el componente controla el tamaño durante la presentación inmersiva. Al igual que en mi ejemplo anterior, la vista debe estar en un ImmersiveSpace para evitar recortes. Pero el renderizado inmersivo de video espacial no está bloqueado a la cabeza, como otros tipos de video inmersivo, así que tendré que establecer la posición de la entidad. Elegiré un metro y medio por encima del suelo y un metro hacia adelante. Para una solución más robusta, usa un head anchor para inicializar la entidad con una posición frente al espectador. Finalmente, envolveré este ImmersiveSpatialVideoView en un ImmersiveSpace. Para los videos espaciales, utiliza un ImmersionStyle mixed para renderizar el modo inmersivo en lugar del Passthrough. Para permitir que los videos espaciales también se reproduzcan en entornos de sistema, que es el comportamiento que siempre busco, usa el nuevo modificador de escena immersiveEnvironmentBehavior con la opción Coexist.

Para repasar, los portales de video espacial se configuran con desiredSpatialVideoMode en spatial y desiredImmersiveViewingMode en portal, ya sea en el espacio compartido o en un ImmersiveSpace con un ImmersionStyle mixto. El modo de visualización será stereo de manera predeterminada para los videos espaciales. El modo inmersivo de video espacial se establece con desiredImmersiveViewingMode en full y un ImmersiveSpace con ImmersionStyle mixto para renderizar en lugar de Passthrough.

Para reproducir en estéreo tradicional, sin estilo espacial, establece desiredSpatialVideoMode en Screen. En este modo, los modos de visión inmersiva no tienen efecto. Los videos espaciales también pueden renderizarse en monoscopio con desiredViewingMode en mono. En ese caso, ni SpatialVideoMode ni ImmersiveViewingMode influyen. Estos modos no inmersivos suelen ubicarse en un WindowGroup dentro del espacio compartido. Ver videos inmersivos es una experiencia increíblemente inmersiva. La reproducción puede ser muy sensible a los movimientos bruscos del video. Por eso, en los videos Apple Projected Media Profile, RealityKit aplica automáticamente mitigaciones de comodidad durante la reproducción, como explicó Jamal para AVKit y QuickLook.

El nuevo evento VideoComfortMitigationDidOccur señala cuando el sistema aplica una mitigación en respuesta a un movimiento elevado en el video. No hace falta realizar ninguna acción al recibir este evento; simplemente indica que se aplicó una mitigación. La mitigación reducedImmersion solo está disponible durante la reproducción progresiva. Por eso, es importante usar un modo de visión inmersiva y un ImmersionStyle progresivos, en lugar de completo, para los videos Apple Projected Media Profile. En la reproducción Portal, no se aplican mitigaciones porque ya resulta cómoda para la mayoría del contenido. Los comportamientos y estilos de renderizado admitidos por un VideoPlayerComponent dependen del perfil de video presentado. Utiliza el evento ContentTypeDidChange para detectar el tipo de video en un VideoPlayerComponent, incluidos los nuevos tipos, como los videos Apple Projected Media Profile. Reacciona cada vez que cambie el tipo de video para comprender qué modos de visión están disponibles y si se aplicará alguna mitigación de comodidad, o para actualizar elementos de la interfaz. Cuando combines VideoPlayerComponent con IU, o simplemente lo presentes en una escena de SwiftUI, ten en cuenta algunos consejos para integrar sin problemas el contenido de RealityKit con SwiftUI. Por ejemplo, gestionar la escala de la malla es importante para colocar el contenido junto a la interfaz. En modo Portal, el tamaño de la malla se refleja en la propiedad playerScreenSize dentro del espacio de coordenadas local de la entidad. La malla del portal siempre se crea con una altura de 1 metro. Al escalar una entidad de video, siempre escala X e Y de manera uniforme para mantener la relación de aspecto. Si la escena de la ventana tiene una altura menor a 1 metro, la malla será recortada por los límites de la escena, a menos que se reduzca la escala de la entidad. Para escalar un video para que encaje dentro de la escena, configura la escala según el tamaño de la ventana disponible usando GeometryReader3D. Consulta el proyecto de muestra “Playing immersive media with RealityKit” en developer.apple.com para ver un ejemplo de cómo escalar un portal de video para que se ajuste a una escena.

Un comentario sobre la ordenación: la interfaz personalizada que quede en el mismo plano que la malla de video tendrá un comportamiento de ordenación indefinido. Agrega un ModelSortGroupComponent a la misma entidad donde está el VideoPlayerComponent y usa un ModelSortGroup con la categoría planarUIPlacement para ordenar explícitamente la entidad frente a la interfaz coplanar. Ya sea QuickLook, AVKit o RealityKit, te corresponde elegir qué estructura usar para la reproducción de video inmersiva, y tienes las herramientas para incorporar estas experiencias increíbles en tu app.

Crea nuevas experiencias inmersivas en tu app añadiendo video APMP de 360° a un juego inmersivo o transmitiendo Apple Immersive Video o video espacial, entre otros casos de uso. Para profundizar en los nuevos tipos de video APMP, ve el video “Learn about the Apple Projected Media Profile”, y para profundizar en Apple Immersive Video, ve el video “Learn about Apple Immersive Video technologies”. Ahora ve y crea experiencias de video inmersivas asombrosas.