# 同期 — Live

Live で Five SDK 状態、ルームのユーザー、ブロードキャスト、ライフサイクルを同期します。

Canonical: https://developer.realsee.ai/ja/docs/live/synchronization
Source: https://developer.realsee.ai/ja/docs/live/synchronization.md
Language: ja

# Live の同期

Live はキーフレーム、ルームデータ、ブロードキャストで状態を同期します。Yjs で保持するため、各キーは他クライアントへ冪等に適用できる JSON シリアライズ可能な状態にします。

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

## キーフレーム

ローカル変更には `live.sendKeyframe(key, frame)`、遠隔更新には `live.keyframes.on(key, callback)` を使います。

```ts
five.on('stateChange', (state, userAction) => {
  if (!userAction || live.state !== LiveState.OPEN) return

  live.sendKeyframe('FiveState', state)
})

live.keyframes.on('FiveState', (nextState, prevState, frontRequestId) => {
  five.setState(nextState, false, false)
})
```

遠隔 Five 状態の適用時は `userAction = false` 相当を指定し、同じフレームをルームに送り返さないようにします。

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

## スナップショットを読む

`live.snapshot` は現在の部分スナップショットを返します。1 キーの取得には `live.getFramesByKey(key)` と `live.getSnapshotForKey(key)` を使います。

```ts
const snapshot = live.snapshot
const fiveState = live.getFramesByKey('FiveState')
```

<span id="room-and-user-state" class="docs-anchor-alias" aria-hidden="true"></span>

## ルームとユーザーの状態

接続後はルームとユーザー情報を取得できます：

```ts
live.selfInfo
live.userList
live.roomInfo

await live.setSelfInfo({
  extension: {
    displayName: 'Alex',
    role: 'host',
  },
})

live.on('selfInfoUpdate', (userInfo, frontRequestId) => {})
live.on('userListUpdate', (userList, frontRequestId) => {})
```

`UserInfo` の権限項目はサービスが提供します。他ユーザーのマイク・同期状態・参加状態などホスト専用の操作前に権限を確認してください。

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

## ブロードキャスト

永続キーフレームではない独自のルームイベントに使います。

```ts
type Ping = { type: 'ping'; sentAt: number }
type Pong = { ok: true; receivedAt: number }

const response = await live.broadcast<Ping, Pong>(
  { type: 'ping', sentAt: Date.now() },
  ['user-id-1'],
  5000
)

live.on('broadcast', (data, frontRequestId) => {
  console.log(data, frontRequestId)
})
```

全員に配信する場合は空の宛先配列を渡します。timeout `0` は無期限の応答待ちを許容できる場合だけ使います。

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

## ライフサイクルのイベント

`LiveState.OPEN` が送信可能の状態です。0.7.6 は以下を公開します：

| 状態 | 意味 |
| --- | --- |
| `LiveState.NOTINITIALIZED` | まだ接続していません。 |
| `LiveState.CONNECTING` | WebSocket を接続中。 |
| `LiveState.OPEN` | メッセージ交換が可能。 |
| `LiveState.CLOSED` | 切断または接続失敗。 |

`live.on('stateChange', callback)` で購読します。

```ts
live.on('stateChange', (state, prevState) => {
  if (state === LiveState.OPEN) {
    console.info('Live room ready')
  }
})
```

0.7.6 の `readyKeyframeSync` は非推奨です。同期準備と更新には `keyframes` または `live.keyframes.on(key, ...)` を使います。

<span id="exit-and-close" class="docs-anchor-alias" aria-hidden="true"></span>

## 退出と終了

参加者の退出は `live.exit()`、オーナーのルーム終了は `live.close()` を使います。`live.dispose()` は購読、RTC リソース、内部 Yjs 文書を破棄します。