Two-Way Communication with Video Embed

The communication channel enables two-way communication between the IFRAME Embed and the Parent Window, allowing real-time updates and notifications. For example, if there is a change in the Embed, it can be detected and communicated to the Parent Window. The parent window can also send data to the Embed. It enables application developers to create a more interactive experience for the user.

How it works?

JS Framework of Messaging between Browser Window Objects (parent, child, named-window) would help in this process. A window sends a message with JSON Data to another window that listens to incoming message and takes action.

So, Embed listens to the Message sent by Parent Page to take action and generate Message to Parent Page to notify various events.

To understand the overall workflow, follow the section below explanations with Code Samples:

Action from Parent Window

Example

When the parent window is ready to receive streaming data, it sends a message to the embedded window to initiate the streaming. The embedded window starts streaming the data from the source to the parent window.

Sample Code - Parent Window sends message to Embed to Start Streaming

const message = JSON.stringify({
    action: 'start-live-streaming',
    data: {
	"name": "Youtube",
	"rtmp_endpoint": "rtmp://a.rtmp.youtube.com/live2",
	"rtmp_key": "XOXOXO"
	}
});

EmbedIFrameElementID.contentWindow.postMessage(message, '*'); 
// EmbedIFrameElementID is the "id" of IFRAME Tag that uses Low Code Meeting URL

Listener at Parent Window

Example

When a notification is sent from Embed, Parent Window processes the message and determines what action needs to be taken. It could include updating the display, sending information to other windows, or any other action that needs to be taken in response to the notification.

Sample Code - Parent Window listens to notification message from Embed and takes appropriate action

window.addEventListener('notification', function (e) {
	// Get the sent data
	var evtdata = e;

	// If you encode the notification  in JSON before sending them,
	// then decode here
	var data_decoded = JSON.parse(evtdata);
	
	// data_decoded example:
	/*
	{
	    notification: 'room-connected',
	    data: {
		"room_name": "John's Room",
		"conf_num": "XOXOXO"
		}
	}
	*/

	switch (data_decoded.notification) {
		case 'room-connected':
			doDBPost(data_decoded.data);
			break;
		case 'other-notice':
			do_other_notice()
			break;
	}
});

Actions

Here is the list of Actions that can be passed from Parent Window to Embed in JSON Object. Note that this Document only provides the format of JSON Object that is used effectively in message passing to get an action executed.

Notification Subscription

The parent window must subscribe to Embed to receive the event notifications. The embedded Notification Group keeps sending notifications to the parent until unsubscribed.

Subscribe to start receiving notifications

Subscribe to receive notifications of Embed events and action statuses. You need to subscribe to one or more Notification Group(s) to start receiving all event notifications under that group.

Subscribing to a Notification Group ensures that you receive notifications whenever an Embed event or action status occurs in that group. It helps you stay up-to-date on what is happening with Embed and quickly react to changes.

For example, if you subscribe to the room-connection group, Embed will notify you of room connection, disconnection, and reconnection. .

To subscribed Notification, post the following code:

{
  "action": "subscribe-notification",
  "data": [   /* one or more notification group */
    "live-streaming",
    "room-connection",
    "user-connection",
    "stream-updates",  
    "messaging"
  ]
}

Data Object

There is an array of notification groups to subscribe to, so you receive notifications related to that group until you unsubscribe.

Unsubscribe to stop receiving notifications

This is to unsubscribe from receiving notifications of various events from Embed.

Each notification group has a unique name and contains a set of parameters that you can use to customize the notifications that you receive.

By opting out of one or more groups, you can ensure that you only receive notifications that are relevant to you.

To unsubscribe notification from one or more notification groups, post the following code:

{
  "action": "unsubscribe-notification",
  "data": [
    "live-streaming",
    "room-connection",
    "user-connection",
    "stream-updates",  
    "messaging"
  ]
}

Data Object

It contains an array of notification groups to unsubscribe to stop receiving notifications related to that group.

To unsubscribe notification from all notification groups, post the following code:

{
  "action": "unsubscribe-notification",
  "data": []
}

Room Connection

Disconnect from Room

This is to disconnect from the Virtual Rooms. When the Embed disconnects from the Virtual Rooms, they are removed from the Video Session, and the connection is terminated. It means they can no longer communicate with anyone in the Virtual Room, and they must rejoin the Session to do so.

To disconnect from Session with a Prompt to confirm exit from Session, send the following message:

{
  "action": "disconnect-room",
  "data": {
    "alert": true
  }
}

Data Object:

To disconnect from Session immediately without a Prompt to confirm exit from Session, send the following message:

{
  "action": "disconnect-room",
  "data": {
    "alert": false
  }
}

Data Object:

Destroy Video Session

A Moderator or Host can destroy Virtual Room to stop the Session immediately. Once the Session is destroyed, all connected users disconnect automatically from the Room.

To destroy Session with a Prompt to confirm, send the following message:

{
  "action": "destroy-room",
  "data": {
    "alert": true
  }
}

Data Object

To destroy Session immediately without a Prompt to confirm, send the following message:

{
  "action": "destroy-room",
  "data": {
    "alert": false
  }
}

Data Object

Note: It is a Host only feature, so must be executed from the Moderator/Host Side of UI only.

Stream Updates

These set of actions are related to updated local and remote stream media tracks, attributes, and configuration.

Mute Video

This functionality stops Video from Local Stream. The Stream immediately drops Video Track until unmuted

When the video track is muted, the stream does not send any data to the receiving end, which causes the receiving end to drop the video track from the stream. The Stream sends data again by unmuting the track, and the video track restores.

To mute Video, send the following message:

{
  "action": "mute-video"
}

Unmute Video

This functionality unmutes the video in the Local Stream. The stream immediately adds a video track.

When a video track is added to the local stream, the video unmutes, allowing it to be seen and heard by all participants in the stream. It ensures that all stream users have the same experience and can interact with each other in real-time.

To unmute Video, send the following message:

{
  "action": "unmute-video"
}

Mute Audio

This functionality mutes Audio from Local Stream. The Stream immediately drops Audio Track until unmuted.

To mute Audio, send the following message:

{
  "action": "mute-audio"
}

Unmute Audio

This functionality unmutes Audio in a Local Stream. The stream immediately adds an audio track.

A new audio track is added when the user un-mutes audio in the local stream. This audio track contains the user's audio and is transmitted to other users in the stream.

To unmute Audio, send the following message:

{
  "action": "unmute-audio"
}

Live Streaming

These actions are related to the Live Streaming of an ongoing Video Session to an RTMP Endpoint for content distribution to a larger audience.

The RTMP Endpoint is the destination to which the Live Streaming service provider sends the encoded video stream, which is then distributed to the intended audience. As a result, the video stream is transmitted efficiently to the largest possible audience.

Note: These are Host only features. So, these messages must be sent from the Moderator/Host Side of UI only.

Start Live Streaming

This functionality starts Live Streaming of ongoing Video sessions to an RTMP Endpoint

To start Live Streaming, send the following message:

{
  "action": "start-live-streaming",
  "data": {
    "name": "Youtube",
    "rtmp_endpoint": "rtmp://a.rtmp.youtube.com/live2",
    "rtmp_key": "XOXOXO"
  }
}

Data Object:

Stop Live Streaming

This functionality stops ongoing Live Streaming of the Video Session from all RTMP Endpoints.

To stop Live Streaming, send the following message:

{
  "action": "stop-live-streaming"
}

UI / UX

These actions are related to the UI and UX of the Video Embed on ongoing Video Session.

Change Video Layout

This functionality changes VIdeo Grid Layout either to Gallery View or Leader View at RTMP Endpoint and/or each Endpoint.

To change Layout, send the following message:

{
  "action": "change-layout",
  "data": {
    "target": "rtmp",
    "layout": "leader"  }
}

Data Object:

Messaging

This set of actions relates to signaling and messaging between video session participants.

It also allows participants to interact with each other and exchange messages, allowing for a more immersive video experience.

Send Custom Signaling

This functionality sends a custom data structure to all users in the Video Session. EnableX does not work for every endpoint. It only broadcasts a message among users; it doesn't do anything else. Therefore, it serves as a signaling tool between users. Use a custom data structure with a limited size for broadcast.

Define your data structure and send the following message for broadcasting:

{
	"action": "signal",
	"data": {
		/* Define your custom object here */
	}
}

Data Object:

Notifications

Video Embed sends notifications to the Parent Window, informing them of various events and the status of actions in the Video Session. Video Embed does not generate notifications unless the parent window is subscribed.

It ensures that the Parent Window is actively listening and can respond to certain events in the Video Session.

Parent Window must listen to the Events and take appropriate action.

Subscription

This notification group need not be subscribed to as is always available. Video Embed generates these notifications in response to the notification and subscription processes.

Notification Subscribed

This functionality notifies that Parent Window has subscribed to receive one or more notification groups.

Parent Window receives the following notification:

{
  "notification": "notification-subscribed",
  "data": [
    "live-streaming",
    "room-connection"
  ]
}

Data Object

Notification Unsubscribed

This functionality notifies that Parent Window has successfully unsubscribed from receiving one or more notification groups.

Parent Window receives the following notification:

{
  "notification": "notification-unsubscribed",
  "data": [
    "live-streaming",
    "room-connection"
  ]
}

Data Object

Room Connection

It is a Room Connection Notification Group. It covers notifications related to room connection, disconnection, and auto-reconnection into the Room. Parent Page needs to subscribe to room-connection Notification Group to receive some of these notifications.

Room Connected

This functionality notifies that the Video Embed is connected to Virtual Room for communication. Parent page needn't subscribe to receive this notification.

Parent Window receives the following notification:

{
  "notification": "room-connected",
  "data": {
    "room_name": "John's Room",
    "conf_num": "XOXOXO"
  }
}

Data Object:

Room Not Connected

This functionality notifies that the Video Embed is not connected to Virtual Room for communication. The parent page needn't subscribe to receive this notification.

Parent Window receives the following notification:

{
  "notification": "room-not-connected",
  "data": {}
}

Room Disconnected

This functionality notifies that the Video Embed is disconnected from the Video Session. Communication is no longer feasible until the Embed rejoins or reconnects the Virtual Room. The parent page needn't subscribe to receive this notification.

Parent Window receives the following notification:

{
	"notification": "room-disconnected",
	"data": {
		"message": "Reason for disconnection"
	}
}

You may get following reasons for disconnection:

• Session expired

• Room access denied

• Failed to reconnect

• Disconnected by Moderator

• Unexpected disconnection

• Normal disconnect

Room Re-connected

This functionality notifies that the Video Embed is reconnected to the Virtual Room. The Embed resumed communication. To receive this notification, the parent page must subscribe to the room-notification group.

Parent Window receives the following notification:

{
  "notification": "room-reconnected"
}

User Connection

It is a User Connection Notification Group. It covers notifications related to user connection and disconnection. Parent Page needs to subscribe to user-connection Notification Group to receive some of these notifications.

User-Connected

This functionality notifies that a new user got connected to the Virtual Room.

Parent Window receives the following notification:

{
  "notification": "user-connected",
  "data": {
    "clientId": "XOXO",
    "name": "John",
    "role": "participant"
  }
}

Data Object

User-Disconnected

This functionality notifies that the user got disconnected from the Virtual Rooms.

Parent Window receives the following notification:

{
  "notification": "user-disconnected",
  "data": {
    "clientId": "XOXO",
    "name": "John",
    "role": "participant"
  }
}

Data Object

Stream Updates

It is a Stream Updates Notification Group that covers local stream configuration, track, and attribute updates notifications. Parent Page must subscribe to stream-updates Notification Group to receive one or all notifications.

Video Muted

This functionality notifies that the Video is muted or stopped in the Local stream.

Parent Window receives the following notification:

{
  "notification": "video-muted"
}

Video Unmuted

This functionality notifies that the Video is unmuted or restarted in the Local stream.

Parent Window receives the following notification:

{
  "notification": "video-unmuted"
}

Audio Muted

This functionality notifies that the Audio is muted or stopped in the Local stream.

Parent Window receives the following notification:

{
  "notification": "audio-muted"
}

Audio Unmuted

This functionality notifies that the Audio is unmuted or restarted in the Local stream.

Parent Window receives the following notification:

{
  "notification": "audio-unmuted"
}

Live Streaming

It is a Live Streaming Notification Group. Parent Page must subscribe to live-streaming Notification Group to receive one or all notifications.

Live Streaming Started

This functionality notifies that the Live Streaming has started.

Parent Window receives the following notification:

{
    "notification": "live-streaming-started",
    "data": {
	"name": "Youtube",
	"rtmp_endpoint": "rtmp://a.rtmp.youtube.com/live2",
	"rtmp_key": "XOXOXO"
	}
}

Data Object

Live Streaming Stopped

This functionality notifies that ongoing Live Streaming of the Video Session to all RTMP Endpoints are stopped.

Parent Window receives the following notification:

{
    "notification": "live-streaming-stopped",
    "data": {}
}

Media Access

It is a Media Access Notification Group that covers notifications related to Media Device Accessibility. These notifications are always available. Parent Page needn't subscribe to the Notification Group.

Media Access Denied

This functionality notifies that the Video Embed failed to get Media Device Access (Media Device is a general term covers Camera and Microphone Devices). An endpoint may or may not join Video Room if Media Device Access is denied.

Parent Window receives the following notification:

// When room not connected
{
  "notification": "media-access-denied",
  "data": {
    "message": "Media access denied. Room not connected."
  }
}

// When room is connected without Media Device Access
{
  "notification": "media-access-denied",
  "data": {
    "message": "Mic and Camera access denied"
  }
}

Camera Access Denied

This functionality notifies that the Video Embed failed to get Camera Device Access. An endpoint may or may not join Video Room if Camera Device Access is denied.

Parent Window receives the following notification:

{
  "notification": "camera-access-allowed",
  "data": {}
}

Camera Access Allowed

This functionality notifies that the Video Embed is allowed access to Camera Device.

Parent Window receives the following notification:

{
  "notification": "camera-access-allowed",
  "data": {}
}

Microphone Access Denied

This functionality notifies that the Video Embed failed to get Microphone Device Access. An endpoint may or may not join Video Room if Microphone Device Access is denied.

Parent Window receives the following notification:

{
  "notification": "mic-access-denied",
  "data": {}
}

Microphone Access Allowed

This functionality notifies that the Video Embed is allowed access to Microphone Device.

Parent Window receives the following notification:

{
  "notification": "mic-access-allowed",
  "data": {}
}

Messaging

It is a Messaging Group that covers inter-user messaging and signaling notifications. Parent Page need to subscribe to "messaging" Notification Group to receive these notifications.

Custom Signal Received

This functionality notifies you that you have received a signal with a custom data structure to be used by your Parent Window to use it any way you want.

Parent Window receives the following notification:

{
	"notification": "signal-received",
	"data": {
		/* Custom data here */
	}
}

For more information, see Extend Video Embed