Live コントローラー

@realsee/live#

メッセージの仕組み#

Live は永続 WebSocket の双方向通信で複数クライアントの共有画面を実現します。ユーザー間の通信は WebSocket メッセージに基づきます。

メッセージはキーフレーム、ブロードキャスト、ルーム情報に分かれ、それぞれ送受信 API があります。詳細は Live API を参照してください。

キーフレーム は共有画面の同期データです。同期する情報を選び {key: value} にまとめます。

ブロードキャスト は指定ユーザーからメンバーへの独自イベントです。例えばホストが視聴者へ挨拶を送れます。

ルーム情報 はサーバーが配信する組み込みメッセージで、ルーム状態、自分、参加ユーザー一覧を含みます。一部は Live の更新メソッドで変更できます。

キーフレームの同期#

現在の UI 操作状態を同期します：

Five SDK の共有画面を例にします：

// Send local keyframe data (Five State)
live.sendKeyframe("five", { panoIndex: 13 });

// Receive remote keyframe data (Five State)
live.keyframes.on("five", (newState, prevState) => {
  // You can use the latest `newState` to update the local UI state
});

live.snapshot から現在の全キーフレームのスナップショットを取得できます。

ルーム情報#

WebSocket 接続後はルームにユーザーとして参加します。他のユーザーも参加でき、情報を次のように取得・更新できます：

// Property: get the local user's information
live.selfInfo;

// Property: get the list of all users currently in the room
live.userList;

// Method: update the local user's information
live.setSelfInfo({});

// Event: the local user's information has changed
live.on("selfInfoUpdate", (userInfo) => {});

// Event: the room's user list information has changed
live.on("userListUpdate", (userList) => {});

ブロードキャスト#

キーフレームやルーム情報に加え、他ユーザーへ独自イベントを送信できます：

live.broadcast(
  data /* the data to broadcast */,
  ["user_id_1", "user_id_2"] /* userIds of the users who should receive this */
);

この例では user_id_1 と user_id_2 だけが受信し、他のユーザーは受信しません：

live.on("broadcast", (data /* the broadcast data */) => {});

追加例は Live API を参照してください。

イベントの仕組み#

非同期 Live イベントは live.on('/* event name */', callback)、任意の RTC イベントは live.$RTC.on('/* event name */', callback) で購読します。

例えば公開接続状態の変化を監視します：

import { LiveState } from "@realsee/live";

live.on("stateChange", (state, previousState) => {
  if (state === LiveState.OPEN) {
    console.log("Live connection opened", { previousState });
  }
});

接続状態#

• stateChange(state: LiveState, previousState?: LiveState): void：公開接続状態の変化。

WebSocket 接続状態：

Live のフロントとバックエンドは永続 WebSocket を使います。OPEN と CLOSED が参加・退出の状態を表します。VRTC のイベント処理は OPEN の後に行います。

Live イベント#

• broadcast(evtMsg: Record<string, any>, frontRequestId: string): void：他ユーザーからブロードキャストを受信。
• builtinEvent(builtinMsg: BuiltinMsg): void：サーバーの組み込みイベントを受信。
• keyframes(keyframes: Partial<Snapshot>, frontRequestId: string): void：他ユーザーからキーフレームを受信。
• selfInfoUpdate(userInfo: UserInfo, frontRequestId: string): void：自分の情報の変化。
• userListUpdate(userList: UserInfo[], frontRequestId: string): void：ユーザー一覧の変化。

live.connect()、live.broadcast()、live.sendKeyframe() などは非同期で応答し、他ユーザーにも影響します。上のイベントで変化を把握できます。

LiveState.OPEN がキーフレーム送信可能の状態です。初回・後続の更新は keyframes または live.keyframes.on(key, callback) で購読します。古い readyKeyframeSync は 0.7.6 で非推奨です。

RTC イベント#

• error(error: Error): void：エラー。
• initWillStart(): void：初期化開始前。
• inited(): void：初期化完了。
• joinWillStart(): void：音声ルーム参加前。
• joined(): void：音声ルーム参加成功。
• userVolumes(userVolumes: UserVolume[]): void：発話ユーザーごとの音量。
• weakNetwork(): void：弱いネットワークの警告。

live.$RTC は RTC プロトコルを満たす必要があります。live.$RTC.on('/*event name*/', /*event callback*/) で購読します。発話ユーザーと音量の監視例です：

live.$RTC.on("userVolumes", (userVolumes: UserVolume[]) => {
  console.log(userVolumes); // userVolumes: the speaking users and their volume data.
});

エラー処理#

• ws.error(error: WebSocketError): void：WebSocket 接続エラー。

WebSocket エラー状態：

• error(liveMsg: LiveMsg): void：サーバー配信エラー。

WebSocket 通信の LiveMsg は以下の構造です：

配信データが LiveMsg を満たさない場合や code が SUCCESS でない場合は error イベントになります。

• error(error: Error): void：RTC 音声エラー。

RTC プロトコル#

音声は任意です。0.7.6 は BrowserRTC、BrowserRTC4Chime、VRWebViewRTC、RTCProtocol を公開します。対応ブラウザーには組み込み実装、他コンテナーには独自実装を使います。RTC と環境 を参照してください。

Live は jsbridge-x でコンテナー SDK 導入済みのクライアントアプリや WeChat ミニプログラムのネイティブ機能を呼びます。このインスタンスは createLive() に設定として渡します。

iOS・Android アプリで Realsee VRTC コンテナー SDK を導入済みの場合：

import { JSBridgeApp } from "@realsee/jsbridge-x/lib/app";
import { createLive } from "@realsee/live";
import { VRWebViewRTC } from "@realsee/live";

const jsBridge = new JSBridgeApp();

const rtcInstance = new VRWebViewRTC({
  jsBridge,
  getVoiceSign: () => {},
});

const live = createLive({
  rtc: rtcInstance,
  jsBridge,
  getTicket: async () => "",
});

RTC を指定すると音声の接続・切断・再接続を Live に委ねられます。$RTC から音声の状態とイベントを扱います。

// State: whether the user has successfully joined the voice room
live.$RTC.joined;
// State: the user's microphone status
live.$RTC.micro;
// Listen for changes in user volume
live.$RTC.on("userVolumes", (userVolumes) => {});