A reference application for PICO OS 6 demonstrating best practices for spatial video playback with the PICO Spatial SDK, showcasing 3D video rendering, immersive playback, and Spatial UI components.
Spatial Video enables immersive video playback in a spatial environment with interactive controls and immersive scenes. It serves as a practical guide for implementing video playback, Spatial UI design, and immersive media experiences using the Spatial SDK.
Spatial Video Sample highlights the following core capabilities of the PICO Spatial SDK:
- Immersive Video Playback: Side-by-Side (SBS) stereoscopic video in 3D with 4K/8K support
- Dual Display Modes: Planar video panel and immersive 360° sphere modes
- Interactive Controls: Play/pause, seek, volume adjustment, and immersive mode controls
- Spatial UI Design: 3D UI elements following PICO design guidelines
- Advanced Video Management: Playback state handling, progress tracking, and lifecycle management
- WindowContainer & Stage Management: Spatial layout management using PICO's spatial containers
To build and run this project, configure your development environment by following the official PICO Spatial SDK setup guide:
- PICO Spatial SDK Setup Guide (Outside Chinese Mainland)
- PICO Spatial SDK Setup Guide (Chinese Mainland)
git clone <repository-url>
cd SpatialVideoLaunch Android Studio, select Open an Existing Project, and choose the SpatialVideo directory.
- Open Device Manager (toolbar or Tools > Device Manager)
- Click Add a new device > Create a PICO Emulator
- Start the emulator from Device Manager
- Click Run 'app' to launch the app
- Connect your PICO device to your development machine
- Enable USB Debugging on the device
- Click Run 'app' to deploy directly to your device
Spatial Video follows a modular architecture optimized for video playback applications:
SpatialVideo/
├── app/ # Main application module
│ └── src/main/
│ ├── java/com/pico/spatial/sample/spatialvideo/ # Kotlin source files
│ │ ├── Main.kt # App entry point
│ │ ├── data/ # Data and state management
│ │ │ ├── PlaybackManager.kt # Video playback control
│ │ │ ├── PlaybackState.kt # Playback state definitions
│ │ │ ├── VideoAssetBundle.kt # Video asset management
│ │ │ └── VideoEffectManager.kt # Video effect control
│ │ ├── di/ # Dependency injection
│ │ │ └── VideoModule.kt # Video-related DI module
│ │ ├── ecs/ # ECS for video panels
│ │ │ └── VideoEntityAssembler.kt # Video entity creation
│ │ ├── platform/ # Platform-specific implementations
│ │ │ ├── LaunchActivity.kt # Android launch activity
│ │ │ └── SpatialApplication.kt # App initialization
│ │ └── ui/ # UI components
│ │ ├── ImmersiveScene.kt # Immersive 3D scene
│ │ ├── PlaybackToolbar.kt # Playback control toolbar
│ │ ├── SpatialVideoScreen.kt # Main video screen
│ │ └── VideoViewModel.kt # ViewModel for UI state
│ ├── res/ # Android resources
│ └── AndroidManifest.xml # App manifest with Spatial component declarations
├── editor-asset/ # Editor assets for spatial development
│ └── src/main/res3d/videoSample/ # Spatial Editor project
│ ├── Build/ # Built asset bundles
│ ├── Sources/ # Source assets and scenes
│ │ ├── Assets/ # Textures and 3D models
│ │ ├── Components/ # ECS components
│ │ └── Scenes/ # Scene definitions (USDZ files)
│ └── ModelView # 3D model views
├── gradle/ # Gradle dependencies and scripts
├── build.gradle.kts # Root build configuration
└── settings.gradle.kts # Project settings and SDK configurationThe editor-asset/ directory contains Spatial Editor project files and shader graph materials that define advanced video effects:
The application includes three specialized shader graph materials:
Basic video playback with standard rendering. Uses simple texture sampling and conversion as the default material for normal video playback scenarios.
Creates a portal-like video projection effect with a geometry modifier. Key features include ray-sphere intersection calculations for 3D projection, dynamic UV generation based on view angle and position, and customizable parameters (sphere radius, FOV, distance scale).
Handles stereoscopic video rendering for immersive experiences. Key features include left/right eye detection and switching, video mask blending using blurMask2.png, IPD adjustment for 3D effect, and advanced UV warping based on viewport depth and camera position.
To modify or customize the shader graph materials:
- Open
editor-asset/src/main/res3d/videoSample/videoSample.spatialprojectin Spatial Editor - Navigate to the Scenes folder to access the USD files
- Edit materials using the Shader Graph editor
- Rebuild the asset bundle for use in the application
The application uses the following additional 3D assets located in editor-asset/src/main/res3d/videoSample/Sources/Assets/:
- sphere.usdz: 3D sphere model for immersive 360° video projection
- blurMask2.png: Alpha mask for smooth video edges and transitions
This sample streams a Side-by-Side (SBS) stereoscopic video from a remote HTTPS URL.
- Default source for PICO Emulator:
https://lf-devtools.picoxr.com/obj/spatial-toolbox/examples/cave_4096x2048_sbs.mp4 - Higher-resolution source for physical devices:
https://lf-devtools.picoxr.com/obj/spatial-toolbox/examples/cave_8192x4096_sbs.mp4 - Network access is required for playback.
To deepen your understanding of spatial app development, explore the resources on our official developer websites:
© 2026 PICO. The project's source code is licensed under the Apache 2.0 License. All assets, including textures, 3D models, audio, and others, are licensed via Creative Commons BY 4.0.
The streamed spatial video content used by this sample remains the exclusive property of its respective copyright holders and is licensed for limited use within this sample project only.
Restrictions:
- Any form of modification, editing, adaptation, or creation of derivative works
- Any reproduction, distribution, publication, or upload to external platforms or services
- Any commercial, promotional, or otherwise unauthorized use beyond the scope of this project
Use of these assets constitutes acceptance of the above restrictions. All rights reserved by PICO.
For questions, issues, or feature requests, please contact us through the PICO Developer Support Portal and submit a ticket.
Developed as a reference for spatial application developers