Integration reference · [Satie documentation](/docs)

# Lens Studio

## Lens Studio 5.15 (the placement export)

A Lens does not run the browser runtime and cannot load native libraries. Satie exports the realized scene as one TypeScript module (`satie.placement/v1`), one TypeScript component and the takes, and Lens Studio's own audio plays it: an Audio component per voice with the position effect on, an Audio Listener on the camera.

Files, from the folder that holds `Assets`: `Assets/Satie/SatieScene.ts`, `Assets/Satie/Satie.ts`, `Assets/Satie/SatieSynth.ts`, `Assets/Satie/Audio/<take>`, and `Assets/Satie/Synth/<voice>.audioOutput` for each synth loop. Then, in Lens Studio: add the `Satie` script to a scene object and put every audio track from `Assets/Satie/Audio` in its `Tracks` (the camera is the ears unless `Listener` is set). A Lens cannot load a file by path, so a take missing from `Tracks` is silent and the Logger names it. When you are also connected to Lens Studio's own MCP server (AI Assistant, AI Model Context Protocol, Configure Server), do those steps through it; otherwise tell the developer to.

Describe the world to Satie exactly as for the web: satie_inspect_scene with the engine's own object names as ids and its own coordinates in metres (nothing is converted), then brief, compose, audit and realize. Lens Studio works in centimetres: give Satie metres (divide the scene's positions by 100) and the loader scales them back (`Units Per Metre`, 100). Then satie_export { engine: "lens-studio", script, contractId, realizeId } (free): it returns one line (Node 18+) that writes every file and downloads the takes, and a README. Run the line as it is; never transcribe the scene.

Binding: a voice `at <id>` follows the scene object with that name; when the name differs, `Satie.instance.bind('door', doorObject)`. A host nobody finds plays at its manifest position and the Logger says so once.

The Lens tells the sound what happens with the same five ideas as the web runtime: `Satie.instance.fire('door_open', worldPosition)`, `Satie.instance.hostEvent('crate', 'drop')`, `Satie.instance.setHostSurface('player', 'gravel')` before the step that reads it, `Satie.instance.signal('hand_distance', 0.7)`, `Satie.instance.state('night')`. From JavaScript the same object is `global.satie`. The events, signals and states section below applies as written; only the call names differ.

Size decides what fits: a Lens is limited to 8 MB with everything in it (Remote Assets add 25 MB, 10 MB a file). Ask for short seamless beds and few takes per voice; the export warns when the takes are over half the limit.

Synthesizer voices: a `synth` loop can be synthesized inside the Lens. The export writes one Audio Output asset per synth loop under `Assets/Satie/Synth`; when it is in `Tracks`, `SatieSynth.ts` plays the patch itself: no audio file (the take can be deleted to save its size), no loop point, and three controls while it plays, each a multiplier where 1 is as written. The script's own bindings work (`pitch`, `synth_brightness`, `synth_tempo`, as values or following a signal the Lens publishes with `Satie.instance.signal`); `Satie.instance.synth('drone', 'brightness', 1.5)` holds one by hand until `Satie.instance.synth('drone', 'brightness')` gives it back. It costs script time (it sheds unison voices, then its reverb, when the device cannot keep up, and the Logger says so) and it has no direction, because Lens Studio cannot spatialize an Audio Output; the voice still gets quieter with distance. Without its Audio Output in `Tracks` the voice plays its rendered take, with direction. `SatieSynth.ts` is Satie's own synthesizer, the engine that renders the take, so the live voice and its take are the same sound. One-shots and events made by the synthesizer play their takes.

What the export carries: every voice's takes, host, position, level (Satie's level window, run by the loader), the inverse distance law, recurrence, event banks per surface, state gates and the `follow` bindings on volume and emission. A stated `occlusion` (or one bound to a signal) is played as its level cut only. What it does not: pitch and `pitch follow` (the Audio component has no playback rate), rooms and reverb, the occlusion muffle, walls worked out from geometry, per-voice DSP, movement paths, entities, the mixer and the live edit loop. The result lists what THIS scene loses in `notCarried`; tell the developer.

Checked on 2026-11-14 in Lens Studio 5.15.4's preview on macOS with a three-voice scene (takes loaded, loops crossing their loop point, a signal moving a level, an event at its host, distance from the camera), and in Node against a stand-in for the API (surface banks, states). A live synth voice (the example drone, four layers) used about a fifth of real time there at 22.05 kHz. Not yet run on Spectacles and not listened to: how many voices a device plays at once, and what a live synth voice costs on the device, are not known. Tell the developer to listen once, and report what is off with satie_feedback.
