Spatial Audio

English | 简体中文

A reference application for PICO OS 6 demonstrating spatial audio features with the PICO Spatial SDK. The sample loads a 3D scene from a Spatial Editor asset bundle, plays both ambient and object-based spatial audio, and exposes UI toggles to control playback independently.

Spatial Audio presents an immersive scene with a flying bird and jungle ambience. The immersive Stage renders the 3D scene and drives the bird movement via an ECS system, while a planar Control Panel window lets users enable/disable ambient audio and bird audio independently.

The scene is loaded from asset://editor-asset.bundle, generated by the PICO Spatial Editor project under editor-asset/. Audio files are loaded from Android assets and managed by a lifecycle-owned resource store.

Spatial Audio highlights the following core capabilities of the PICO Spatial SDK:

• Ambient + Object Spatial Audio: background ambience plus a moving sound source attached to the bird entity
• Interactive Toggles: independent switches to enable/disable ambience and bird sounds
• Lifecycle-Aware Resource Handling: ViewModel-owned audio resource store (load/cache/close) and playback controller cleanup
• Procedural Trajectory (ECS): circular flight path with vertical oscillation and orientation updates
• Editor-to-App Asset Pipeline: 3D scene authored in Spatial Editor and packed into editor-asset.bundle for runtime loading

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 SpatialAudio

Launch Android Studio, select Open an Existing Project, and choose the SpatialAudio directory.

1. Open Device Manager (toolbar or Tools > Device Manager)
2. Click Add a new device > Create a PICO Emulator
3. Start the emulator from Device Manager
4. Click Run 'app' to launch the app

1. Connect your PICO device to your development machine
2. Enable USB Debugging on the device
3. Click Run 'app' to deploy directly to your device

Spatial Audio follows a modular architecture to separate application logic from 3D resources:

SpatialAudio/
├── app/                                               # Main application module
│   └── src/main/
│       ├── java/com/pico/spatial/sample/spatialaudio/ # Kotlin source files
│       │   ├── Main.kt                                # Entry point: Stage + Control Panel, startup preloading
│       │   ├── data/
│       │   │   ├── AssetBundle.kt                     # Lazy global `asset://editor-asset.bundle` loader
│       │   │   └── AudioResourceStore.kt              # Audio name/path registry and resource load/cache/close
│       │   ├── ecs/
│       │   │   └── FlyTrajectory.kt                   # Bird trajectory component and ECS system (transform updates)
│       │   ├── manager/
│       │   │   ├── AudioPlayer.kt                     # Ambient loop and randomized bird calls, controller cleanup
│       │   │   └── EventManager.kt                    # Audio event subscriptions (lifecycle owned by ViewModel)
│       │   ├── platform/                              # Platform bootstrap (Application/Activity)
│       │   └── ui/
│       │       ├── AudioControlViewModel.kt           # Scene load, audio node prep, state management, and cleanup
│       │       ├── ControlPanel.kt                    # UI toggles for ambience and bird audio
│       │       └── ImmersiveScene.kt                  # Root entity, scene load hook, and ECS registration
│       ├── assets/audio/                              # WAV audio assets (ambience + bird sounds)
│       ├── res/                                       # Android resources
│       └── AndroidManifest.xml                        # App manifest with Spatial component declarations
├── editor-asset/                                      # 3D resources and scene definitions
│   └── src/main/res3d/PicoSpatialAudio/               # Spatial Editor project
│       ├── Sources/Assets/                            # 3D models, textures, and audio
│       └── Sources/Scenes/                            # Scene definitions (SpatialAudioScene.usda)
├── gradle/                                            # Gradle dependencies and scripts
├── build.gradle.kts                                   # Root build configuration
└── settings.gradle.kts                                # Project settings and SDK configuration

Audio assets are located in app/src/main/assets/audio/. To add or replace audio files:

1. Add your WAV files to app/src/main/assets/audio/
2. Register names and paths in AudioResourceStore.kt (update BIRD_AUDIO_NAME_PATH_LIST and/or AMBIENT_AUDIO_NAME)
3. Optionally copy the same files into the Spatial Editor project (editor-asset/src/main/res3d/PicoSpatialAudio/Sources/Assets/audio/) if you want them available while authoring the scene

3D assets are authored in the Spatial Editor project under editor-asset/src/main/res3d/PicoSpatialAudio/. To modify or extend them:

1. In Android Studio, expand the editor-asset module
2. Navigate to res3d/PicoSpatialAudio/ModelView
3. Click Open in Editor in the top-right corner to launch the PICO Spatial Editor
4. Edit the scene (replace models/textures or adjust the SpatialAudioScene content)
5. Build the project to regenerate editor-asset.bundle; the app loads it at runtime via asset://editor-asset.bundle

To deepen your understanding of spatial app development, explore the resources on our official developer websites:

• PICO Developer Website (Outside Chinese Mainland)
• PICO Developer Website (Chinese Mainland)

© 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.

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