visionos-immersive-media-developer

visionOS Immersive Media Developer

Quick Start

Decide first whether the app should use the system AVKit experience or a custom RealityKit playback surface.

1. Clarify the media shape: surface video, portal, progressive immersive, full immersive, spatial video, or Apple Immersive Video.
2. Load only the matching reference files.
3. Treat playback-mode changes as both media and scene-orchestration work.

Load References When

Reference	When to Use
playback-decision-tree.md	Decision tree: window vs portal vs progressive vs full immersive playback.
avkit-visionos-playback.md	When using AVKit AVPlayerViewController and AVExperienceController as the system playback surface.
avexperiencecontroller.md	When AVKit AVExperienceController is the right surface for the product.
videoplayercomponent-basics.md	When you need to set up VideoPlayerComponent + AVPlayer correctly.
video-player-events.md	When RealityKit video playback must drive UI, scene transitions, rendering readiness, or comfort mitigation from VideoPlayerEvents.
apmp-and-spatial-video.md	When the content is spatial video, APMP, or Apple Immersive Video.
immersive-viewing-modes.md	When implementing portal, progressive, or full modes and related scene transitions.
comfort-mitigation.md	When handling comfort violations and mitigation strategies.
apple-immersive-video-authoring.md	When you need Apple Immersive Video authoring or packaging references.

Workflow

1. Choose the playback architecture.
2. Load the references for that surface and media type.
3. Implement playback and viewing-mode transitions.
4. Add event handling and comfort mitigation where relevant.
5. Summarize the playback path, transition model, and remaining validation work.

Guardrails

• Start with AVKit AVExperienceController when the system player experience fits the product.
• Use RealityKit VideoPlayerComponent when the video must live in a custom scene graph.
• Do not treat immersive-mode transitions as a simple property flip when the app also needs scene changes.
• Make sure the user has a clear exit path from immersive playback.

Output Expectations

Provide:

• the chosen playback architecture
• the media type and viewing mode
• which references were used
• the transition or event model involved
• the next validation step