# Play a spatial narrative — Vreo

Load a real VreoUnit on a ready Five SDK scene and start playback from a user action.

Canonical: https://developer.realsee.ai/docs/vreo/quickstart
Source: https://developer.realsee.ai/docs/vreo/quickstart.md
Language: en

[Download examples](https://developer.realsee.ai/starters/react-five/1.3.0/starter.zip)

Start from a working [Five SDK scene](https://developer.realsee.ai/docs/five-sdk/quickstart). For audible narration you also need a real audio or video asset. A silent story can use the SDK's built-in empty-media timeline. In both cases, script panorama indexes must belong to the same Work. The Public Demo proves the Five scene path; it does not supply an authored Vreo narrative.

<span id="run-the-maintained-public-browser-demo" class="docs-anchor-alias" aria-hidden="true"></span>

## Run the public browser demo

Download the official starter ZIP using [the release manifest](https://developer.realsee.ai/starters/react-five/manifest.json) or **Download examples** above. Extract it into a new directory, then open a terminal in its `realsee-react-five/extensions` directory. This optional project has its own dependencies and lockfile:

```bash
npm ci
npm run check
npm run build
npm run dev
```

Open the local URL printed by the terminal, normally `http://127.0.0.1:4188`. The page uses the published `@realsee/open-works@0.1.1` sample; it needs WebGL and public scene asset access, but no credentials or Team API. It reuses the task functions shown below. Running this optional example does not require changing the main starter's dependencies.

After the scene reports Ready, choose **Play camera and caption**. This is an intentionally silent eight-second story using Vreo's published empty-media clock, with real camera movement and a timed caption. It does not demonstrate narration audio. Test Pause, Resume, and Stop separately. Vreo owns an auxiliary canvas inside its UI; the example creates only one Five scene.

The silent path comes from the published [VideoAgent media implementation](https://unpkg.com/@realsee/vreo@2.6.4/lib/Player/modules/VideoAgent/VideoAgentMesh.js), which uses [AudioLike](https://unpkg.com/@realsee/vreo@2.6.4/lib/shared-utils/AudioLike.js) when the media URL is empty.

## Install the compatible release set

In a fresh Five SDK 6.9.2 / React 18.3.1 / Three.js 0.117.1 project:

```bash
npm install --save-exact @realsee/vreo@2.6.4 @realsee/dnalogel@3.81.10 @tweenjs/tween.js@18.6.4
npm run check
npm run build
```

Inspect the existing dependencies first. If you already use another Dnalogel or React major, stop and resolve the conflict explicitly. Do not replace the lockfile or use `--force` / `--legacy-peer-deps`. The extra tween dependency is required by the published runtime import; omitting it causes an unresolved-module build failure.

The downloaded `extensions` project already contains this compatible release set. Keep its lockfile and use `npm ci`; the install command above is for adding Vreo to your own compatible project.

Keep the starter's package-specific npm override for `@realsee/five` → `protobufjs` 8.8.1 when extending it. The downloaded `extensions` project includes the same override.

## Start the player in the browser

Prepare a ready Five instance, a `VreoUnit`, and an empty DOM container for Vreo's UI. Call this function from your Start button. Retain the returned player for [controls and cleanup](https://developer.realsee.ai/docs/vreo/playback-controls).

```ts title="examples/sdk-guides/src/vreo/player.ts"
import type { Five } from '@realsee/five'
import { Player } from '@realsee/vreo'
import type { VreoUnit } from '@realsee/vreo/typings'
import '@realsee/vreo/stylesheets/default.css'

// Call from a browser UI action, with an already loaded Five scene and a real script.
export async function startNarrative(five: Five, unit: VreoUnit, container: HTMLElement) {
  const player = new Player(five, { container, autoPreload: false })
  try {
    const loaded = await player.load(unit, 0, false, false, true)
    if (!loaded) throw new Error('Narrative did not load')
    if (!player.play(0, true)) throw new Error('Narrative did not start')
    return player
  } catch (error) {
    player.dispose()
    throw error
  }
}
```

The stylesheet import is required for the supplied player interface. The package reads browser globals, including `location`, during module evaluation. In an SSR application, import and create Vreo only in the client boundary; do not instantiate it during server rendering.

## Supply a real script

Use [Narrative keyframes](https://developer.realsee.ai/docs/vreo/narrative-keyframes) to build a small typed script, or load an authored script from your backend. Verify the media URL, its measured duration in milliseconds, and every referenced panorama. An API response wrapper is not automatically a `VreoUnit`.

## Verify

Check that loading succeeds, playback starts after the user action, the media is audible when allowed, and the expected camera or caption action appears. Pause, resume, and replay. Distinguish a script-loading failure, a media/network failure, a browser audio policy block, and a successfully played narrative.