Integration reference · [Satie documentation](/docs)

# Satie WebXR starter

A small three.js world you can enter with a headset, with its sound by Satie. Copy the folder and
replace the scene with your own.

What is in it: rain and wind around you, an orb that circles the room and rings like a bell, and
your right hand. Pull the trigger and the bell rings where your hand is. The left stick walks, the
right stick turns.

## Copying it out of the Satie repository

Inside the repository the starter uses the runtime next to it (`"satie-runtime": "file:../../packages/satie-runtime"`
in `package.json`). When you copy the folder somewhere else, change that line to the hosted
package:

```json
"satie-runtime": "https://www.satie.world/runtime/0.4.5/satie-runtime.tgz"
```

`npm run verify` (the emulated headset check) needs the repository's Playwright and only runs
there.

## Run it

```sh
npm install
npm run dev
```

Open the address Vite prints. On a computer, press "Listen without a headset". On a headset, open
the same address in its browser and press "Enter VR".

A headset only allows WebXR on a secure address. `localhost` on the computer is fine. To reach your
computer from the headset, either forward the port over USB (`adb reverse tcp:5173 tcp:5173`, then
open `localhost:5173` in the headset browser) or serve over HTTPS (for example the
`@vitejs/plugin-basic-ssl` plugin and `vite --host`).

No headset? Install Meta's Immersive Web Emulator extension in Chrome, or use the emulated check
below.

## The six lines that matter for XR

They are marked "XR 1" to "XR 6" in `main.ts`.

1. **Put the camera under a rig.** `rig.add(camera)`. The headset moves the camera; your code moves
   and turns the rig (walking, teleporting, snap turns). Controllers go under the rig too.
2. **The ears are the camera.** `audio.bindListener(camera)`. During a session three.js writes the
   head pose onto that camera each time it renders, so its place in the world, rig included, is
   where the player's head is.
3. **Start audio in the Enter VR click.** `enterVR.addEventListener('click', startAudio)`, and
   `startAudio` calls `audio.start()` straight away, before any `await`. A browser only opens audio
   from a tap or click. Load the sounds before you allow the click.
4. **One loop.** `renderer.setAnimationLoop(...)`, never `requestAnimationFrame`: in a session the
   headset drives the frames. Call `audio.update(camera)` once per frame, after you have moved
   things.
5. **A controller is a host.** `audio.bind('wand', renderer.xr.getControllerGrip(1), { anchor: 'origin' })`.
   Any sound written `at wand` in the script now comes from the hand, and
   `audio.hostEvent('wand', 'ring')` fires an event there.
6. **Pause when the session hides.** When the headset comes off or a system menu opens, the session's
   `visibilitychange` event fires. Suspend `audio.engine.audioContext` when it is `hidden`, resume
   when it is visible again.

One three.js trap, found while testing: ask for both controllers (`renderer.xr.getController(0)`
and `(1)`) even if you use one. three.js 0.183 throws when a controller it was never asked about
disconnects, and that happens every time the session hides.

## Your own scene

The sound lives in `public/satie/scene.satie` (the script) and `public/satie/samples.json` (where
each sound file is). With the Satie MCP connected, ask your coding agent to give the world its
sound: it describes your objects to Satie, gets a new script and samples, and saves them over
these two files. Every object a sound is `at` needs one `audio.bind(id, object)` line.

The three recordings here are local files, so this starter needs no account and spends nothing.

## The emulated check

```sh
npm run verify
```

This opens the starter in a headless Chromium with an emulated Quest 3 (Meta's IWER), enters an
immersive session, and measures 15 things. The run on 2026-11-12:

- The listener was the emulated head in the world in seven poses, including a rig moved and turned:
  forward within 0.001 degrees, position 17.7 mm behind the point between the eyes. That offset is
  three.js itself: it sets its one camera slightly back so its view covers both eyes. You will not
  hear 2 cm.
- The orb's sound stayed on the orb (0 mm apart over 1.8 m of travel), and the hand's sound stayed
  on the controller grip with the rig moved and turned.
- The trigger fired the `ring` event once, at the grip, and a take started.
- The audio clock ran 10.000 s over 10.000 s of wall clock (0.3 ms apart) while the session
  rendered at 120 frames a second.
- The audio clock stopped while the session was hidden and ran again when it was visible.

It takes a Chromium path as its first argument, or `SATIE_TEST_BROWSER`; the default is Playwright's
cached Chromium on a Mac. It imports `playwright-core` from the Satie repository, so run it from
inside this checkout.

## What this does not tell you

The check is a desktop browser with an emulated device. Nobody has run this starter on a real
headset yet. Unknown until someone does:

- **How many voices a headset can carry.** Satie spatialises each voice with HRTF in Web Audio, and a
  headset chip is far slower than a laptop. Start small. For a dense scene pass
  `engine: new SatieEngine({ loopVoiceBudget: { maxRealVoices: 16 } })` to the scene and watch that
  `audio.engine.audioContext.currentTime` keeps up with the wall clock on the device.
- **Hand tracking.** Only controllers were tested. A tracked hand from `renderer.xr.getHand(i)` is
  an object like any other and should bind the same way.
- **AR and passthrough.** Only `immersive-vr` was tested. `ARButton` uses the same camera path, but
  it was not run.
- **The headset's own audio output**, its latency, and Bluetooth headphones.
