Integre a reprodução de vídeo imersivo em apps para visionOS

Olá! Meu nome é Jamal. Sou media applications engineer na equipe AVKit. Sou Michael, software engineer na equipe visionOS Spatial Media. O que mais gosto de fazer no visionOS é assistir a vídeos de maneira única da plataforma. No visionOS 2, isso inclui experiências incríveis, como reprodução ancorada e vídeos espaciais. No visionOS 26, seus frameworks de mídia favoritos foram expandidos, como Visualização Rápida, AVKit e RealityKit, para oferecer suporte a perfis de mídia mais imersivos e ajudar a criar uma experiência de reprodução de vídeo envolvente. Jamal e eu vamos mostrar como oferecer suporte a essa reprodução de vídeo imersiva no app. É com você, Jamal. Obrigado, Michael. Primeiro, farei uma revisão dos diferentes tipos de perfis de vídeo. Vou explicar como a Visualização Rápida e as novas APIs do AVKit dão suporte à reprodução de mídia imersiva. E Michael explicará como os apps podem personalizar experiências de reprodução imersiva usando o RealityKit. Ao final deste vídeo, você terá aprendido a oferecer suporte e criar uma experiência de reprodução de vídeo imersiva no seu app visionOS. Vou começar revisando os diferentes tipos de perfis de vídeo aceitos no visionOS 26.

No visionOS 1, vídeos 2D e 3D eram as principais formas de oferecer reprodução de vídeo em apps. A mídia espacial permitia capturar conteúdo estéreo envolvente e aproveitar as criações de maneira imersiva. O visionOS 26 inclui o Apple Projected Media Profile, ou APMP, para vídeos em 180°, 360° e ultra-angular. E, para a experiência imersiva, existe o Apple Immersive Video. Cada um desses perfis é único à sua maneira. Se você não tem familiaridade com esses termos, a sessão “Explorar experiências de vídeo para o visionOS” vai ajudar. Há vários jeitos de dar suporte a todos os perfis de vídeo que mencionei. Para isso, é fundamental escolher a tecnologia certa para o seu app para oferecer uma experiência imersiva excepcional.

Visualização Rápida é o framework ideal para apresentar qualquer tipo de mídia, incluindo mídia imersiva. O AVKit oferece uma experiência de vídeo consistente em todas as plataformas e disponibiliza controles aprimorados para a experiência de reprodução. O RealityKit foi desenvolvido para apps que exigem uma experiência de reprodução imersiva única, como as encontradas em ambientes de videogame. Se você está buscando suporte para reprodução imersiva no navegador, confira a sessão “Novidades dos recursos espaciais para a web” para ver uma explicação detalhada sobre reprodução imersiva para conteúdo da web.

Vou revisar as ferramentas disponíveis para Visualização Rápida e AVKit no visionOS 26, para você criar seu app de reprodução de vídeo imersiva. Visualização Rápida oferece duas APIs para exibir e pré-visualizar mídia em apps. O PreviewApplication é uma API que permite criar uma janela fora do processo para apresentação de mídia. O QLPreviewController é uma API para pré-visualizar mídia dentro da janela do app ou em um estilo de apresentação modal. No visionOS 26, o QLPreviewController foi aprimorado para dar suporte a fotos e vídeos espaciais. Além disso, o PreviewApplication agora aceita Apple Immersive Video e Apple Projected Media Profile, incluindo vídeos em 180°, 360° e ultra-angular.

O QLPreviewController e o PreviewApplication podem gerenciar a apresentação e transições dos novos perfis de vídeo. Eles adaptam a pré-visualização com o estilo de vídeo apropriado. No visionOS 26, todos os apps que já usam as APIs para Visualização Rápida darão suporte aos perfis de mídia imersiva. Para saber como implementar as APIs PreviewApplication ou QLPreviewController, confira os vídeos “Descobrir a Visualização Rápida para computação espacial”, da WWDC23, e “Novidades da Visualização Rápida para o visionOS”, da WWDC24. Depois, vou apresentar as novas APIs do AVKit, lançadas para dar suporte à reprodução de vídeo imersiva. No visionOS 26, a API AVExperienceController é usada para realizar transições para uma nova experiência imersiva. Há várias opções para realizar a transição para uma experiência imersiva com o AVExperienceController. A primeira opção é o modo Expanded. Expanded permite que o AVPlayerViewController ocupe toda a cena da janela da interface. No visionOS 26, Expanded pode ser configurado para oferecer reprodução de vídeo imersiva. Novidade na configuração de Expanded: a propriedade AutomaticTransitionToImmersive é usada para determinar se as transições automáticas para uma experiência imersiva devem ser iniciadas. AutomaticTransitionToImmersive pode ser configurada com o valor default, quando se prefere o comportamento padrão do sistema, ou none, quando não se deseja nenhuma transição automática.

Configurar o valor none para a propriedade AutomaticTransitionToImmersive permite que o AVPlayerViewController utilize um tratamento de portal para conteúdo imersivo quando detectado, enquanto mantém o AVExperienceController na experiência Expanded. Este é um exemplo de como desativar as transições automáticas para uma experiência imersiva, caso queira tratar o conteúdo imersivo como um portal. Primeiro, vou criar um AVPlayerViewController e configurá-lo com o conteúdo de mídia imersiva. Vou adicionar ao experienceController o conjunto recomendado, que inclui as experiências apropriadas para a plataforma, para que os modos Expanded e Immersive façam parte dele. Considerando que a propriedade AutomaticTransitionToImmersive está inicialmente como default, é necessário definir seu valor como .none. Supondo que o AVPlayerViewController já esteja na hierarquia de visualização do app, vou fazer a transição do AVExperienceController para a experiência Expanded. Com a nova API Immersive, parte das experiências no AVExperienceController, faça a transição explícita para essa experiência, em vez de depender de um acionamento automático, assim como é feito para Expanded.

A API da experiência Immersive vem com uma nova API de configuração que permite aos apps definir a posição onde a reprodução de vídeo imersiva deve ocorrer. Este fragmento de código demonstra como usar a experiência Immersive com a API Configuration. Considerando que o AVPlayerViewController não foi adicionado à hierarquia de visualização, você precisará especificar isso por meio da API Configuration. Para isso, acesse a configuração experienceController e defina a posição usando a função .over para preferredWindowUIScene. Uma vez definido, o AVExperienceController já pode fazer a transição para uma experiência imersiva. Se o AVPlayerViewController estiver contido na hierarquia de view, o AVExperienceController assumirá que a cena de janela onde está contido é a cena de posicionamento desejada. E é assim que os apps conseguem fazer a transição para uma experiência imersiva com o AVKit. Ao fazer a transição para dentro ou fora da experiência imersiva, o AVExperienceController gerencia as animações e transições entre as experiências. Essas transições podem ser iniciadas a qualquer momento pelo usuário, pela lógica do app ou pelo sistema.

Ao usar o AVExperienceController, é importante entender qualquer transição ou mudança de estado de apresentação. Isso trará flexibilidade para lidar adequadamente com o estado ativo do app. Para isso, o Protocolo Delegado do AVExperienceController é a solução. O protocolo tem três métodos delegados: didChangeAvailableExperiences, que notifica quando as experiências disponíveis possíveis forem alteradas. prepareForTransitionUsing, que notifica quando o AVExperienceController está prestes a fazer a transição, permitindo que seu app se prepare para o novo estado. E didChangeTransitionContext, que notifica quando a transição para a nova experiência foi finalizada.

A experiência imersiva depende do tipo de conteúdo fornecido. Use o método didChangeAvailableExperiences para determinar se uma experiência imersiva está disponível para o tipo de conteúdo. Se um conteúdo de mídia 2D for fornecido ao AVPlayerViewController, a experiência imersiva não estará disponível. Para saber como usar o AVExperienceController e seus métodos de delegado, confira o código de exemplo “Reproduzir mídia imersiva com o AVKit”. Além das novas APIs para reprodução de vídeo imersivo, a Visualização Rápida e o AVKit dão suporte à detecção de mitigação de conforto no visionOS 26. Vídeos imersivos podem apresentar movimentos de câmera intensos, causando desconforto aos espectadores. Para resolver isso, a detecção de movimento agora é compatível com conteúdo do Apple Projected Media Profile. A Visualização Rápida e o AVKit detectam movimentos intensos durante a reprodução e reduzem o nível de imersão. O espectador pode ajustar as opções no app Ajustes, permitindo que a Visualização Rápida e o AVKit se comportem da maneira desejada. Para a maioria das experiências de reprodução de vídeo imersivo, a Visualização Rápida e o AVKit são ótimos! Para uma experiência imersiva personalizada, o RealityKit é a escolha ideal, e Michael vai explicar o porquê. Obrigado, Jamal. O RealityKit é um ótimo framework para reprodução de vídeo personalizada, como incluir vídeo em um jogo imersivo ou renderizar vídeo com uma interface personalizada. No visionOS 26, o RealityKit oferece suporte nativo à reprodução de vídeos imersivos. Vou mostrar um novo modo imersivo progressivo para vídeos em 180°, 360° e ultra-angular, além do Apple Immersive Video, e a renderização de vídeo espacial com estilo espacial completo, assim como no app Fotos. Vou demonstrar como detectar quando as medidas de mitigação de conforto para vídeo são aplicadas. E vou compartilhar dicas sobre como usar o RealityKit para reprodução de vídeo em uma cena SwiftUI. O VideoPlayerComponent é uma API poderosa para renderizar vídeos no RealityKit. Quando anexado a uma entidade do RealityKit, ele cria sua malha e material, baseado no vídeo atual do AVPlayer e nas propriedades do componente. Isso torna o VideoPlayerComponent ideal para renderizar vídeos com modos de visualização imersivos, pois as atualizações da malha e as animações são gerenciadas automaticamente, como no exemplo de encaixe de vídeo do projeto Destination Video em developer.apple.com. Confira “Aprimorar seu app de computação espacial com o RealityKit” para ver uma introdução ao VideoPlayerComponent.

No visionOS 26, o VideoPlayerComponent aceita os mesmos perfis de vídeo imersivo que a Visualização Rápida e o AVKit. Vou começar com vídeos do Apple Projected Media Profile e do Apple Immersive Video. O VideoPlayerComponent aceita três modos imersivos para esses perfis de vídeo. O modo Portal renderiza o vídeo em um portal, para uma apresentação em janela. O modo Progressive é uma API que permite às pessoas ajustarem seu nível de imersão usando a Digital Crown, possibilitando que continuem conectadas ao mundo ao redor enquanto aproveitam o vídeo. E, com 100% de imersão, o modo Progressive equivale ao modo de visualização totalmente imersivo.

No visionOS 26, o modo Progressive Immersive Viewing é a opção preferida ao modo totalmente imersivo para vídeos do Apple Projected Media Profile e Apple Immersive Video por oferecer mais flexibilidade e para ajudar na mitigação do conforto, que vou explicar melhor mais adiante. Vou criar um view para renderizar um vídeo de 180° no modo Portal e colocá-la em um WindowGroup no espaço compartilhado. Para configurar a reprodução no modo Portal, crie um AVPlayerItem e um AVPlayer, usando um URL local ou HTTP Live Streaming. Depois, inicialize um VideoPlayerComponent com o reprodutor. Defina o desiredImmersiveViewingMode do componente como portal e anexe o componente a uma entidade. A malha do VideoPlayerComponent tem 1 metro de altura por padrão. Ajusto o vídeo para 0,4 metro, para caber na cena da janela do SwiftUI. Por fim, adicione a entidade à cena. Para renderizar o vídeo no modo Progressive, altere a propriedade desiredImmersiveViewingMode do componente de "portal" para "progressive". Como o componente controla a escala no modo Progressive, operações de escala não têm efeito. Vou removê-la para deixar tudo mais claro. Atualizar o componente para progressive não é suficiente ao renderizar em uma cena SwiftUI. Para evitar que a malha seja cortada pelos limites da cena da janela ao se expandir, preciso colocar a nova ProgressiveVideoView em um ImmersiveSpace. Ao renderizar com o modo Progressive, esse ImmersiveSpace deve ter um estilo de imersão progressiva. Aqui, o nível inicial de imersão é 1: equivalente à imersão total. Escolhi uma faixa de 10% a 100%, para que as pessoas possam ajustar seu nível de imersão. Se eu tivesse incluído 0%, a imersão poderia ser reduzida até o conteúdo desaparecer, o que não é o comportamento desejado para o app. O ImmersionStyle do SwiftUI e o modo Immersive Viewing do componente são importantes para configurar a reprodução. Corresponda o desiredImmersiveViewingMode com o ImmersionStyle ao renderizar em uma RealityView. Para saber mais sobre ImmersionStyles, confira o vídeo de 2024 “Aprofundar-se em volumes e espaços imersivos”. Para fazer a transição entre os modos Portal e Progressive, aguarde o evento ImmersiveViewingModeDidChange ao trocar de cenas SwiftUI. ImmersiveViewingModeWillTransition e DidTransition indicam quando alternar a visibilidade da interface em transições animadas para reduzir conflitos de movimento e estéreo. Para ver exemplos desses eventos em ação, confira o código de exemplo “Reproduzir mídia imersiva com o RealityKit” em developer.apple.com. Recapitulando: para renderização em Portal de vídeos do Apple Projected Media Profile e Apple Immersive Video, defina o desiredImmersiveViewingMode como portal. Portais ficam em um WindowGroup do SwiftUI no espaço compartilhado, mas podem ser exclusivos em um espaço imersivo com um estilo de imersão misto. Para renderização imersiva, defina o desiredImmersiveViewingMode como progressive, em um ImmersiveSpace com um ImmersionStyle progressivo, como no meu código. Para obter o comportamento preferido do sistema, não defina o desiredViewingMode. O viewingMode será mono para vídeos monoscópicos e estéreo para vídeos estéreo, como vídeos estéreo em 180° e Apple Immersive Video. Vídeos espaciais são vídeos estéreo de que as pessoas gostam. Talvez você já tenha capturado alguns pelo ecossistema da Apple. Eles contêm metadados espaciais que permitem uma renderização mais confortável e imersiva. Assim como os vídeos do Apple Projected Media Profile e Apple Immersive Video, os vídeos espaciais têm suporte nativo no RealityKit e são renderizados com estilo espacial completo e modos imersivos.

O estilo espacial para vídeos espaciais é configurado com a propriedade desiredSpatialVideoMode no VideoPlayerComponent. Defina essa propriedade para especificar como um vídeo espacial deve ser renderizado. Leia a propriedade get-only spatialVideoMode para saber como um vídeo espacial está sendo renderizado. Para ativar o estilo espacial para vídeos espaciais, defina desiredSpatialVideoMode como .spatial.

A renderização espacial aceita ImmersiveViewingModes .portal e .full. A renderização imersiva de vídeos espaciais é configurada com o modo Immersive Viewing full. Os vídeos espaciais imersivos são renderizados em um tamanho fixo com base no campo de visão do conteúdo.

Defina desiredSpatialVideoMode como .screen, o valor padrão, para renderizar vídeos espaciais em estéreo tradicional em uma malha de tela. O SpatialVideoMode não será atualizado a menos que o vídeo seja espacial e válido. Como o nome sugere, esse modo se aplica apenas a vídeos espaciais. Inscreva-se no novo VideoPlayerEvent: SpatialVideoModeDidChange ou observe a propriedade spatialVideoMode para determinar se e quando essa propriedade foi atualizada. Para renderizar um vídeo espacial no modo Portal, crie um VideoPlayerComponent com um AVPlayer que contenha um vídeo espacial. Defina desiredViewingMode como stereo. Esse é o padrão para vídeos espaciais, mas gosto de ser explícito. Defina desiredSpatialVideoMode como spatial e escolha portal como desiredImmersiveViewingMode. Como antes, ajuste o vídeo para caber dentro da janela. No modo espacial, o vídeo pode ser ampliado definindo o modo Immersive Viewing como full. Vou remover a operação de escala, já que o componente controla o tamanho durante a apresentação imersiva. Como no meu exemplo, a visualização precisará estar em um ImmersiveSpace para evitar cortes. Mas a renderização imersiva de vídeo espacial não fica fixa à cabeça, então preciso definir a posição da entidade. Vou escolher um metro e meio acima do chão e um metro para a frente. Para ter uma solução mais robusta, use uma âncora de cabeça para inicializar a entidade com uma posição à frente do espectador. Por fim, vou envolver essa ImmersiveSpatialVideoView dentro de um ImmersiveSpace. Para vídeos espaciais, use um ImmersionStyle misto para renderizar o modo imersivo sobre o pass-through. Para que vídeos espaciais sejam renderizados em ambientes do sistema, use o novo modifier de cena immersiveEnvironmentBehavior com a opção coexist.

Para revisar, os portais de vídeo espacial são configurados com desiredSpatialVideoMode definido como spatial e desiredImmersiveViewingMode como portal, no espaço compartilhado e um ImmersiveSpace com ImmersionStyle mixed. O modo de visualização terá como padrão estéreo para vídeos espaciais. O modo imersivo de vídeo espacial é definido com um desiredImmersiveViewingMode completo e um ImmersiveSpace com um ImmersionStyle misto, para renderizar ao longo do pass-through.

Para renderizar em estéreo tradicional, sem estilo espacial, defina desiredSpatialVideoMode como screen. Os modos Immersive Viewing não têm efeito nesse modo. Para renderizar vídeos espaciais de modo monoscópico, defina desiredViewingMode como mono. Nesse modo, nem SpatialVideoMode nem ImmersiveViewingMode têm efeito. Esses modos não imersivos estão em um WindowGroup, no espaço compartilhado. Assistir a vídeos imersivos é uma experiência realmente imersiva. A reprodução pode ser bastante sensível a movimentos rápidos no vídeo. Para vídeos do Apple Projected Media Profile, o RealityKit realiza mitigações de conforto na reprodução, como Jamal mencionou para o AVKit e a Visualização Rápida.

O novo evento VideoComfortMitigationDidOccur sinaliza quando uma mitigação de conforto é aplicada pelo sistema, em resposta a movimentos intensos. Nenhuma ação é necessária ao receber este evento, é apenas um sinal de que uma mitigação foi aplicada. A mitigação reducedImmersion está disponível apenas durante a renderização progressiva. Por isso, use um modo de Immersive Viewing e um estilo de imersão progressive, em vez do modo full, para vídeos do Apple Projected Media Profile. Durante a renderização em modo portal, nenhuma mitigação ocorre, pois a reprodução em portal já é confortável. Os comportamentos e estilos de renderização aceitos por um VideoPlayerComponent dependem do perfil específico do vídeo apresentado. Use o evento ContentTypeDidChange para detectar o tipo de vídeo em um VideoPlayerComponent, incluindo novos tipos do Apple Projected Media Profile. Reaja sempre que o tipo de vídeo mudar: para entender os modos de visualização disponíveis, se a mitigação de conforto será aplicada ou para atualizar elementos da interface. Quando o VideoPlayerComponent é combinado com a interface, ou apresentado em uma cena SwiftUI, tenho umas dicas para uma integração suave entre o conteúdo do RealityKit e o SwiftUI. Por exemplo, gerenciar a escala de uma malha é importante para posicionar a mídia junto à interface. No modo portal, o tamanho da malha é refletido pela propriedade playerScreenSize, no espaço de coordenadas local da entidade. A malha do portal é sempre criada com uma altura de 1 metro. Ao ajustar uma entidade de vídeo, ajuste os eixos X e Y de modo uniforme para manter a proporção. Se a altura da cena da janela for menor que 1 metro, a malha será cortada pelos limites da cena, a menos que a entidade seja reduzida. Para ajustar um vídeo ao tamanho da cena, use GeometryReader3D para definir a escala com base no espaço disponível. Confira o projeto de exemplo “Reproduzir mídia imersiva com o RealityKit” em developer.apple.com para ver um exemplo de como ajustar um portal de vídeo. Uma observação sobre classificação: a interface no mesmo plano da malha de vídeo terá um comportamento de classificação indefinido. Adicione um ModelSortGroupComponent à mesma entidade que tem o VideoPlayerComponent e use um ModelSortGroup que especifique a categoria planarUIPlacement para ordenar a entidade em relação à interface coplanar. Seja Visualização Rápida, AVKit ou RealityKit, a escolha de qual framework usar para reprodução de vídeo imersivo é sua. E você tem as ferramentas para criar essas experiências incríveis no seu app.

Crie experiências imersivas no seu app adicionando vídeos APMP 360° a um jogo imersivo, ou transmitindo vídeos Apple Immersive Video ou vídeos espaciais. Para conhecer os novos tipos de vídeo APMP, confira o vídeo “Saber mais sobre as tecnologias Apple Immersive Video”. Para explorar mais o Apple Immersive Video, confira o vídeo “Saber mais sobre as tecnologias Apple Immersive Video”. Agora, crie experiências incríveis de vídeo imersivo!