# Spatial Audio

[English](README.md) | [简体中文](README_zh.md)

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.

## Overview

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.

![Screenshot](.github/screenshot.png)

## Features

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

## Requirements

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)](https://developer.picoxr.com/document/spatial-sdk/set-up-development-environment/)
- [PICO Spatial SDK Setup Guide (Chinese Mainland)](https://developer-cn.picoxr.com/document/spatial-sdk/set-up-development-environment/)

## Getting Started

### 1. Clone the Repository

```bash
git clone <repository-url>
cd SpatialAudio
```

### 2. Open in Android Studio

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

### 3. Run the App

#### On Emulator

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

#### On Physical Device

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

## Project Structure

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

```txt
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

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

## Editing 3D Assets

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`

![Spatial Editor](.github/editor.png)

## Learning Resources

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

- [PICO Developer Website (Outside Chinese Mainland)](https://developer.picoxr.com/)
- [PICO Developer Website (Chinese Mainland)](https://developer-cn.picoxr.com/)

## License

© 2026 PICO. The project's source code is licensed under the [Apache 2.0 License](LICENSE.txt). All assets, including textures, 3D models, audio, and others, are licensed via [Creative Commons BY 4.0](https://creativecommons.org/licenses/by/4.0/).

## Support

For questions, issues, or feature requests, please contact us through the [PICO Developer Support Portal](https://picodevsupport.freshdesk.com/support/home) and submit a ticket.

---

Developed as a reference for spatial application developers
