# 空間ストーリーを再生する — Vreo

準備済み Five SDK シーンに実際の VreoUnit を読み込み、ユーザー操作から再生します。

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

# 空間ストーリーを再生する

動作する [Five SDK シーン](https://developer.realsee.ai/ja/docs/five-sdk/quickstart) から始めます。音声付きには実音声・動画が必要で、無音では組み込みの空メディア時間軸を使えます。index は同じ Work に属する必要があり、公開デモだけでは Vreo の作成済みストーリーは提供されません。

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

## 公開ブラウザーデモを実行する

[リリースマニフェスト](https://developer.realsee.ai/starters/react-five/manifest.json) または上の「サンプルをダウンロード」から公式 ZIP を取得します。新しいディレクトリに展開し、`realsee-react-five/extensions` でターミナルを開きます。この任意プロジェクトは独立した依存関係とロックファイルを持ちます：

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

表示されたローカル URL（通常 `http://127.0.0.1:4188`）を開きます。公開版 `@realsee/open-works@0.1.1` を使い、WebGL とアセットへの接続が必要ですが認証情報や Team API は不要です。下記と同じタスク関数を使い、メインスターターの依存関係を変えずに実行できます。

Ready の後に **Play camera and caption** を選びます。空メディアの時計を使う意図的な 8 秒の無音ストーリーで、実カメラ移動と字幕があります。音声の実演ではありません。Pause・Resume・Stop を別々に試します。Vreo は補助キャンバスを持ちますが、Five シーンは 1 つです。

無音経路は公開 [VideoAgent](https://unpkg.com/@realsee/vreo@2.6.4/lib/Player/modules/VideoAgent/VideoAgentMesh.js) が URL 空のとき [AudioLike](https://unpkg.com/@realsee/vreo@2.6.4/lib/shared-utils/AudioLike.js) を使う実装に基づきます。

<span id="install-the-compatible-release-set" class="docs-anchor-alias" aria-hidden="true"></span>

## 互換性のある版をインストールする

新しい Five SDK 6.9.2 / React 18.3.1 / Three.js 0.117.1 プロジェクトで実行します：

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

既存の依存関係を先に調べます。別 Dnalogel・React メジャー版があれば停止して整合させます。ロックファイルの置換や force・legacy-peer-deps は使いません。tween は公開実装が import するため、省略するとビルドが失敗します。

同梱 extensions には互換版が設定されています。ロックファイルと npm ci を使い、上の install は自分の互換プロジェクトへの追加時に使います。

拡張時も @realsee/five → protobufjs 8.8.1 の npm override を保持します。同梱 extensions も同じ指定です。

<span id="start-the-player-in-the-browser" class="docs-anchor-alias" aria-hidden="true"></span>

## ブラウザーで Player を起動する

準備済み Five、VreoUnit、空の UI コンテナーを用意し、開始ボタンから関数を呼びます。Player を [操作と終了処理](https://developer.realsee.ai/ja/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
  }
}
```

同梱 UI には CSS の import が必要です。モジュール評価時に location などのブラウザー変数を読むため、SSR ではクライアント境界内だけで import・生成してください。

<span id="supply-a-real-script" class="docs-anchor-alias" aria-hidden="true"></span>

## 実際のスクリプトを渡す

[キーフレーム](https://developer.realsee.ai/ja/docs/vreo/narrative-keyframes) で型付きスクリプトを作るか、バックエンドの作成済みデータを使います。URL、実測のミリ秒長、全パノラマを検証します。API の応答全体がそのまま VreoUnit になるわけではありません。

<span id="verify" class="docs-anchor-alias" aria-hidden="true"></span>

## 確認する

読み込み、操作後の開始、許可された音声、期待する移動と字幕を確認します。一時停止・再開・再生を試し、スクリプト失敗、通信失敗、音声ポリシーの拒否、再生成功を区別します。