# ストーリーのキーフレームを作成する — Vreo

実際の時間軸、カメラ移動、字幕を持つ型付き VreoUnit を作成します。

Canonical: https://developer.realsee.ai/ja/docs/vreo/narrative-keyframes
Source: https://developer.realsee.ai/ja/docs/vreo/narrative-keyframes.md
Language: ja

# ストーリーのキーフレームを作成する

ストーリーはメディアと操作の組み合わせで、単なる座標配列ではありません。音声付きなら配信可能なナレーションと実測した長さ、意図した無音のカメラ・字幕なら空の URL と明示的な時間を指定します。どちらも現在の Work の index を使います。

```ts title="examples/sdk-guides/src/vreo/keyframes.ts"
import { Five } from '@realsee/five'
import { VreoKeyframeEnum, type VreoUnit, type VreoKeyframe, type CameraMovementData, type PrompterData } from '@realsee/vreo/typings'

// Use an accessible media asset, or an empty URL for Vreo's built-in silent timeline.
export function createNarrative(narrationUrl: string, durationMs: number, panoIndex: number, fov = 90): VreoUnit {
  if (!Number.isFinite(durationMs) || durationMs < 4000) throw new Error('Use a timeline at least four seconds long')
  const camera: CameraMovementData = { mode: Five.Mode.Panorama, panoIndex, longitude: 0, latitude: 0, fov }
  const caption: PrompterData = { text: 'Welcome to this space.' }
  const keyframes: VreoKeyframe[] = [
    { type: VreoKeyframeEnum.CameraMovement, start: 0, end: 2000, data: camera },
    { type: VreoKeyframeEnum.Prompter, start: 0, end: 4000, data: caption }
  ]
  return { video: { url: narrationUrl, duration: durationMs, start: 0, end: durationMs }, keyframes }
}
```

両方の操作が収まるよう 4 秒以上を要求します。実 URL で呼び、返された unit を [Player クイックスタート](https://developer.realsee.ai/ja/docs/vreo/quickstart) に渡します。

<span id="use-the-published-model" class="docs-anchor-alias" aria-hidden="true"></span>

## 公開モデルを使う

| 項目 | 意味 |
| --- | --- |
| `video.url` | 取得可能な音声・動画、または組み込み無音時間軸用の空文字 |
| `video.duration`, `start`, `end` | ミリ秒単位の時間軸 |
| `keyframes[].start`, `end` | 操作の時間区間（ミリ秒） |
| `CameraMovementData.panoIndex` | 現在の Work のパノラマ index |
| `longitude`, `latitude` | ラジアン単位の角度 |

enum と型は **`@realsee/vreo/typings`** から import します。ルートは Player を公開しますが全スクリプト型は再公開しません。data は広い型なので、CameraMovementData と PrompterData を別に宣言すると誤りを検出しやすくなります。

他種のフレームは専用データと有効アセットが必要です。特にパノラマ更新は署名済みシーンデータを含み、捏造や SK の埋め込みで取得してはいけません。

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

## 確認する

読み込み前に応答、長さ、時間順序、パノラマ所属を検証します。再生中に字幕区間と移動先を確認し、操作 UI で再生・シークを試します。

[公開スクリプトとデータ型](https://unpkg.com/@realsee/vreo@2.6.4/lib/typings/VreoUnit.d.ts)