visionos-immersive-media-developer_skill

Overview

This skill is a practical playbook for implementing immersive and spatial video experiences on Apple Vision Pro (visionOS). It focuses on RealityKit VideoPlayerComponent with AVPlayer, immersive viewing modes (portal, progressive, full), transitions, event handling, comfort mitigation, and Apple Immersive Video authoring workflows. It helps you choose playback surfaces, implement safe transitions, and ship comfortable, accessible experiences.

How this skill works

The skill guides you to configure RealityKit VideoPlayerComponent backed by AVPlayer, attach it to entities, and enable visionOS features like passthrough tinting and immersive viewing. It treats mode changes (window ↔ portal ↔ progressive ↔ full) as scene orchestration problems and shows how to subscribe to VideoPlayerEvents for transitions and comfort mitigation. It also outlines when to use ImmersiveMediaSupport for authoring and packaging Apple Immersive Video content.

When to use it

• Adding 2D video surfaces, portal windows, or full immersive playback to a visionOS app.
• Supporting Spatial Video, stereo/mono streams, or progressive immersive content with crown-driven transitions.
• Needing robust handling of viewing-mode transitions and scene orchestration.
• Implementing comfort mitigation and accessibility measures for visionOS 26+.
• Authoring and packaging Apple Immersive Video content as part of a content pipeline.

Best practices

• Choose the playback surface based on content type: window for UI video, portal for framed immersion, progressive for crown-controlled expansion, full for FOV-filling experiences.
• Use RealityKit VideoPlayerComponent + AVPlayer by default; escalate to CompositorServices only for custom engines or full-space renderers.
• Treat immersive switches as scene transitions—disable nonessential UI, prepare entity transforms, and subscribe early to transition events.
• Handle VideoComfortMitigation events (pause, reduceImmersion, play) on visionOS 26+ and provide clear exit/return affordances.
• Always support captions, reduce motion options, and obvious exit paths to meet accessibility and comfort requirements.

Example use cases

• A media viewer that opens a video on a 2D surface and lets users move it into a portal or full immersive view.
• An educational app that plays spatial video in a portal, offering a crown-controlled progressive expansion for gradual immersion.
• A social playback app that syncs AVPlayer instances for multi-user viewing and responds to comfort mitigation events.
• A content pipeline that packages stereo/immersive assets using ImmersiveMediaSupport for distribution as Apple Immersive Video.