Take controller

tip

With your controller details about watching message systems, event mechanisms, and voice protocol.Learn about the controller to take a better practice to see the business.

@realsee/live

info

Live The controller is the browser with the ability to view on the line. needs to be used with the TRTC service and is responsible for scheduling TRTC logic.

Message system

The core function of Live is to use WebSocket long chain communications to connect multiple users to the same screen.Communications between users are based on WebSocket messages.

Live sends messages intoframe data,broadcast,room informationclassesProvide corresponding sending, receiving API, and more API for each class of information refer to Live API document

Frame data is the information carrier that performs the same screen, leaving the user to define which information in the current scene should be used for the same screen and organize the information into {key: value}.

Broadcast messages is used to specify a user to send a custom broadcast message to room members in event form.e.g.：moderators send greeting messages to viewers.

Room info is built-in messages, actively pushed by WebSocket service, including room status, current user and participant list etc.Some information can also be modified by the update provided by Live.

Frame Data Sync

Synchronization of current UI interaction：

Example with Five

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

// receive remote frame data (Five State)
live.eyframes.on("five", (newState, prevState) => {
  // can take the latest `newState` to update local UI status
});

You can also get the "snapshot" of all the current series of frame data with the live.snapshot.

Room Info

Live has the concept of a session room. When you successfully connect to the WebSocket service you have joined a room as a user.This room user will have other users besides you, you can get or update user information in the following ways:：

// Attribute：for local user information
live.selfInfo;

// attribute：for all users in the current room
live.userList;

// Method：update local user information
live.setSelfInfo({});

// Event：Changes to Local User Information
live.on("selfInfoUpdate", (userInfo) => {});

// Event：Changes to Room User List Information
live.on("userListUpdate", (userList) => {});

Broadcast message

In addition to frame data and room information, messages can be broadcast to other users in the room in the form of events：

live.broadcast(
  data /* broadcast data*/,
  ["user_id_1", "user_id_2"] /* userId */
);

At this point, the user ID in the room is user_id_1,user_id_2 will receive this broadcast message (unknown to other users)：

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

For more examples, see Live API documents.

Incident mechanism

Live provides listening WebSocket Events,live events and RTC events

Of these, WebSocket eventsandlive events can be listened to by live.on('/*event name*/', /*event call*/).

For example, listening to changes in the WebSocket status：

live.on('ws.readyStateUpdate', (readyState: WebSocketState) => \
  console.log(readyState// readyState is the latest WebScoket status
})

WebSocket Events

• ws.beforeConnect(reconnect?: number@@): void after WebSocket finished.

• ws.afterConnect(reconnect?: number@@): void WebSocket before completing connection.

• ws.readyStateUpdate(readyState: WebSocketState): void WebSocket finished state changed.

WebSocket connection status list：

Status Name	Status Description
NOTINITIALIZED	Not initialized
CONNECTING	Connecting
OPEN	Connection successful
CLOSING	Closing
CLOSED	Close successful

Live Forward-end service interaction is based on WebSocket long links.With a view of successful entry, exit identifier is displayed in WebSocket status OPEN,CLOSED. Therefore, all the relevant event processing logic for VRTC should ensure that it takes place afterOPEN events.

live event

• Broadcast(evtMsg: Record<string, any>, frontRequestId: string): void to receive broadcast messages from other users.

• builtinEvent(builtinMsg: BuiltinMsg): void to receive built-in event messages from the server side.

• keyframes (keyframes: Partial<Snapshot>, frontRequestId: string): void for other users.

• readyKeyframeSync(lastKeyframe: Partial<Snapshot>): void indicates frame synchronization.

• selfInfoUpdate(userInfo: UserInfo, frontRequestId: string): void has changed.

• userListUpdate(userList: UserInfo[], frontRequestId: string): void user list changed

live instances provide many methods such aslive.connect(),live.broadcast(),live.sendKeyframe()that are asynchronous feedback and may affect other users in the room. You can learn about these effects by listening to the above events.

Note that readyKeyframeSync events are framerable peer-syncing nodes. Your frame sync behavior will only take effect after receiving this event.

RTC Event

• error(error: Error): void unusual events.

• initWillStart(): void about to initialize events.

• inited(): void initialize completed events.

• joinWillStart(): void will join the voice room.

• joined(): void successfully joined the voice room.

• userVolumes (userVolumes: UserVolume[]): void per user in room.

• weakNetwork(): void weak web alarm events.

live.$RTC The instance needs to be satisfied with [the RTC protocol], the events of which are live.$RTC.on('/*event name*/', /*event calls*/) listen in like listeners who are speaking in the voice room and their volume：

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

Exceptions processed

• ws.error(error: WebSocketError): void WebSocket connection error.

WebSocket error state enumeration：

Error field	Error description	Trigger Scene
Close	Error type enumeration referenceCloseEvent	Error reference toCloseEvent
Error
MicroAuth	Microphone authorization error	Voice function failed to get microphone authorization
DuplicateConnect	Repeat connection	Request connection with the same WS link
Illegal URL	Invalid WS link	Incoming WS links are not valid
Unknown	Unknown error	Returns other unenumerated errors

• error(liveMsg: LiveMsg): void server push exceptions.

The structure of communication with WebSocketLiveMsgThe format is as follows：

Name	Type	Description
appId	String
code	String	Return code, refer toserver API Code table
Command	Instruction	WebSocket communication instruction type, please refer toLive API document for details
Data	Record<string, any>	Business data corresponding to this directive
frontRequestId:	String	Frontend Request ID, Revert to Frontend by the WS Service
Message	String	Return description
requestId	String	Backend Request ID
roomCode	String	See room number
riggerUserId	String	User ID for triggering instructions

When WebSocket pushes data structures are not satisfactory LiveMsg or code values are not available SUCCESS will be cast in the form of error events.

• error(error: Error): void RTC voice exception

caution

RTC has different speech containers or RTC solutions and may not be fully consistent with the content of its error message.

RTC Protocol

Voice ability is dependent on the WebView/Browser container, which requires the container endside to implement RTC capability.

To facilitate developer access,like the VRTC service of the Developer Center provides the mainstream platform container SDK and jsbridge-x.

Live implements native ability calls by jsbridge-x bridge with client applications or micromessaging apps that integratecontainer SDK.This jsbridge-x instance needs to be provided as a configuration parameter tocreateLive().

If iOS/Android Apps (accessed like VRTC container SDK)

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

const jsBridgeInstance = new JSBridgeApp();

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

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

After providing RTC instance configuration parameters, the voice connections, disconnects, reconnections, etc. are hosted by Live.You can access voice-related states and events through the $RTC namespace on the live instance.

// Status：Users successfully joined the voice
live.$RTC.joined;
// Status：User Microphone Status
live.$RTC.micro;
// Listen to user volume
live.$RTC.on("userVolumes", (userVolumes) => {});