Synchronization

Live synchronizes application state through keyframes, room data, and broadcasts. The package stores keyframe state with Yjs, so each key should contain JSON-serializable state that can be applied idempotently on another client.

Keyframes

Use live.sendKeyframe(key, frame) for local state changes and live.keyframes.on(key, callback) for remote updates.

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)
})

When you apply a remote Five SDK state, pass the equivalent of userAction = false so the receiving client does not echo the same frame back into the room.

Snapshot reads

live.snapshot returns the current partial keyframe snapshot. live.getFramesByKey(key) and live.getSnapshotForKey(key) read one key.

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

Room and user state

After connection, Live exposes room and user information:

live.selfInfo
live.userList
live.roomInfo

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

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

The concrete UserInfo permission fields are provided by the Live service. Check permission fields before host-only actions such as controlling another user's microphone, sync state, or room membership.

Broadcasts

Use broadcasts for custom room events that are not durable keyframe state.

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)
})

Pass an empty recipient list when the Live service should broadcast to everyone. Use a timeout of 0 only when your caller can tolerate an indefinitely pending response.

Lifecycle events

LiveState.OPEN is the durable signal that the Live channel can send keyframes. The 0.7.6 package exposes these states:

Listen with live.on('stateChange', callback).

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

readyKeyframeSync is deprecated in @realsee/live@0.7.6; use live.on('keyframes', ...) or live.keyframes.on(key, ...) for synchronization readiness and updates.

Exit and close

Use live.exit() for a participant leaving the room. Use live.close() for owner-style room closure. live.dispose() clears listeners, RTC resources, and the internal Yjs document when the page is done with the instance.