VideoConference API Reference

The Video Huddle component enables you to integrate reliable video huddle into your web application.

How to use

To initialize the Video Huddle component, you can follow our quickstart guide.

Properties

The Video Conference properties can be divided into four contexts: layout, presence controls, behavior, and 3D plugins. Please find below the available parameters:

Layout and languages

Here are properties that influence the visual layout and positioning of elements within the component. It includes settings for the offset, camera positioning, and color scheme.

Name	Type	Description
styles	string	Optional custom CSS styles to be applied to the component. This allows for customization of the component's appearance.
collaborationMode	CollaborationMode	In this object you can configure how to position the Video Conference and modals experience, allowing the participants to act with other collaboration tools.
language	string	The language property sets the default language for the meeting interface. While it's possible to change it to a custom language, it's important to remember that you'll need to include this custom language in the list of available locales for it to take effect. Default value: en
locales	Locale[]	The locales property allows you to expand language options beyond the default English. Use this field to provide a list of languages available in the meeting overlay.
offset	Offset	Position the iframe of the video conference by passing top, bottom, left and right. Default value: {0, 0, 0, 0}
participantType	ParticipantType	This object is used to assign appropriate participant permissions within the room. Options are host, guest, and audience. Default value: guest

Behavior

The behavior properties control the component's operational characteristics. These properties dictate behaviors such as turning off camera feeds, disabling screen sharing, and the use of chat.

Name	Type	Description
allowGuests	boolean	When set to true, this flag removes all users from the meeting one minute after the host leaves and there are no other users who can take on the host role. Default value: false
camsOff	boolean	Disables the participant's camera and hides the cameras of other participants in the room. Default value: false
chatOff	boolean	Disables chat for the participant. Default value: false
defaultToolbar	boolean	When set as false, this will remove the toolbar that contains options to open modals like chat, settings, share screen, open or close camera and microphone, and the leave meeting button. Default value: true
devices	DevicesOptions	With this field, you can disable participant-specific devices such as video input, audio input, and output options when joining the meeting.
screenshareOff	boolean	Disables screen sharing for the participant. Default value: false
skipMeetingSettings	boolean	Decides whether to bypass the default meeting setup screen and immediately join a meeting. When set as true, participants will enter the meeting with their cameras and microphones disabled. Default value: false
enableRecording	boolean	This will enable the recording feature during the meeting. Default value: true
canShowAudienceList	boolean	When set as true, this will show the audience list in the meeting. Default value: true

Presence controls

Presence control properties allow you to manage features related to participant interaction and engagement. These properties include options for enabling features like GoTo, Follow and Gather functionality.

Name	Type	Description
enableFollow	boolean	When set true, enables the Follow functionality, allowing participants to follow amother participant. Default value: false
enableGather	boolean	When set true, enables the Gather functionality, which aligns all participants' views with host's, ensuring a shared perspective with a single click. Default value: false
enableGoTo	boolean	When set true, enables the GoTo functionality, allowing participants to quickly jump to another's position by clicking on their webcam, facilitating quick location of participants. Default value: false

3D plugins

These properties are related to the incorporation of 3D elements within the component. It includes options for default avatars and using a custom avatar per participant.

Name	Type	Description
avatars	Avatar[]	Provide your own custom avatars to the participant.
defaultAvatars	boolean	Enables the "Choose Avatar" step during the meeting setup. This step is automatically hidden if a participant has an avatar attached in the SDK initialization. Default value: false

info

These controls are only useful if you are utilizing any of the 3D Presence plugins like Autodesk Viewer, Matterport, or Three.js.

Events

The Video Conference in SuperViz SDK offers a range of events that allow you to monitor and respond to several interactions and changes within the meeting. These events provide valuable insights into participant actions, meeting state transitions, and more.

onMeetingStart

Type: () => void

This event is dispatched when the Video Conference is initialized.

onMeetingStateChange

Type: (state: MeetingState) => void

<Videoconference> operates through a series of distinct states to ensure the meeting experience. The onMeetingStateChange event enables you to monitor and react to these state transitions.

Monitoring these states allows you to provide real-time feedback to participants and implement dynamic behavior based on the current state of the Video Conference. E. g. When the state is MEETING_READY_TO_JOIN it confirms that the user has already consented device permissions and it’s ready to join the meeting.

See the MeetingState section for more details.

onLocalParticipantJoin

Type: (participant: Participant) => void

This event is dispatched when the local participant enters the meeting.

onLocalParticipantLeave

Type: (participant: Participant) => void

This event is dispatched when the local participant leaves the meeting.

onParticipantJoin

Type: (participant: Participant) => void

This event dispatches when a participant enters the meeting room.

onParticipantLeave

Type: (participant: Participant) => void

This event dispatches when a participant leaves the meeting room.

onParticipantListChange

Type: (participant: Participant) => void

This event is dispatched when there is a change in the list of participants of the meeting.

onParticipantAmountChange

Type: (amount: number) => void;

This event dispatches when the number of participants in a meeting has changed.

onHostChange

Type: (participantId: string) => void;

This event is dispatched when a new participant is given the host capabilities for the current meeting.

onHostAvaliable

Type: () => void

This event dispatches when the host enters the meeting after guests and audience members have already joined.

If a host is the first to enter the meeting the event won't be dispatched.

onNoHostAvaliable

Type: () => void

This event dispatches when a guest or audience member enters the meeting, but there’s no host available yet.

If a host is the first to enter the meeting the event won’t be dispatched.

onWaitingForHostChange

Type: (waiting: boolean) => void

This event dispatches when a guest or audience member of the meeting tries to join the meeting, but there’s no host available yet. It will be triggered again, with the value false, when the host joins the room.

onKickLocalParticipant

Type: () => void

This event dispatches when a host kicks one participant out of the meeting,

onKickAllParticipants

Type: () => void

This event dispatches when two or more participants are in the room, one designated as a host and the other as a non-host (typically a guest). For the event to occur, the host must leave the room, leaving only the non-host inside. This situation results in the room being left without a host.

onConnectionStatusChange

Type: (status: MeetingConnectionStatus) => void

This event is dispatched when there is a change in the connection status of the participant in the meeting. This event provides real-time updates about the quality and availability of the audio/video service.

By monitoring this event and interpreting the status values, you can implement responsive actions, such as advising participants to turn off video in case of a BAD connection or handling reconnection scenarios when LOST_CONNECTION occurs.

See the MeetingConnectionStatus section for more details.

onDevicesStateChange

Type: (state: DeviceEvent) => void

This event is dispatched when there is a change in the local participant device list. E.g. This event will be triggered when the participant connects a headphone on the laptop.

onFrameDimensionsChange

Type: (dimensions: {width: number, height: number}) => void

The Video Conference, when initialized, inserts a SuperViz-enabled iframe into the Document Object Model (DOM). This event is dispatched when there is a change to the iframe dimensions.

onDestroy

Type: () => void

This event is dispatched when the participant leaves the meeting room.

Type Definitions

DeviceEvent

Type: enum

This enum helps to understand the status of the devices available for the local participant.

Here are the possible states and their meanings:

State	Description
NO_CAM	No camera is available for the local participant.
NO_DEVICES	No devices are currently connected.
DEVICES_BLOCKED	Device access is blocked for the participant.
DEVICES_CAM_BLOCKED	Camera access is blocked for the participant. Perhaps because it’s been used by other applications.
DEVICES_INITIALIZATION_ERROR	There was an error during device initialization.
DEVICES_UNKNOWN_ERROR	An unknown error occurred with the participant's devices.
DEVICES_ALLOWED	All device access is granted by the participant.

Dimensions

Type: object

An object that represents the Video Conference dimensions on the component’s frame.

Name	Type	Description
width	number	The width of the frame represented in pixels.
height	number	The height of the frame represented in pixels.

Example:

{
  "width": 921,
  "height": 678
}

Participant

Type: object

An object describing the participant information, like name and avatar.

Name	Type	Description
id	string	Identifier of the participant who is entering the room. Usually, this ID matches the internal ID of your users.
avatar	Avatar	Participant avatar information.
color	string	Unique color for the participant in the meeting, is used to identify the user cursor and avatar/laser in 3D space.
isHost	boolean	Indicates if the participant is the current host of the room.
name	string	The name of the participant who will enter the room.
type	ParticipantType	User it to give proper user permission in the room. Options are host, guest, and audience.

Example:

"participant": {
  "id": "USER_ID",
  "name": "USER_NAME",
  "type": "host",
  "color": "#878291",
  "avatar": {
    "imageUrl": "https://<PATH>",
    "model3DUrl": "https://<PATH>",
  }
}

MeetingConnectionStatus

Type: enum

The MeetingConnectionStatus serves as a dynamic indicator of the real-time connection quality and availability of the audio/video service. This enumeration defines a set of distinct values, each reflecting a specific state of the meeting's connection, allowing you to precisely monitor and respond to the meeting's operational status.

This enum has the following possible statuses:

Status	Value	Description
NOT_AVAILABLE	0	Indicates that the audio/video service is disconnected.
GOOD	1	Represents good connection quality, ensuring a stable and reliable audio/video experience.
BAD	2	Indicates a bad connection quality. It’s indicated to encourage the participants to consider turning off video to enhance the experience.
POOR	3	Signifies a poor connection, often due to participant connections and/or PC specifications not meeting the minimum requirements for a smooth audio/video experience.
DISCONNECTED	4	Indicates that audio/video transmission has been interrupted, with no network packets sent or received for at least 10 seconds.
RECONNECTING	5	Occurs during a reconnection process triggered by a loss of connection.
LOST_CONNECTION	6	Indicates a complete loss of connection to the audio/video service.

MeetingState

Type: enum

Represents the current state of the Video Conference meeting. This value reflects one of the possible states indicating the operational status of the meeting component. You can utilize this information in your callback function to respond to and manage the meeting's dynamic behavior based on its state.

Here are the possible states and their meanings:

State	Value
MEETING_FAILED	-1	Indicates a failure in the meeting, requiring attention or troubleshooting.
MEETING_DISCONNECTED	0	Indicates a state where the meeting is not connected.
MEETING_INITIALIZING	1	Signifies the meeting is in the process of initialization.
MEETING_READY_TO_JOIN	2	Confirms that the meeting was prepared for participants to join, meaning that device permissions were consent and everything is working.
MEETING_CONNECTING	3	Indicates an ongoing connection process that happens after the participant joins the meeting.
MEETING_CONNECTED	4	Confirms that the meeting is successfully connected.
MEETING_RECONNECT	5	Occurs when the meeting reconnects after a disruption.
FRAME_INITIALIZING	6	Indicates the initialization of the meeting iframe.
FRAME_INITIALIZED	7	Indicates a successfully initialized meeting iframe.
FRAME_UNINITIALIZED	8	Represents an uninitialized meeting iframe.

Hooks

useVideo Hook

toggleMeetingSetup

function () => void

Use this method to open or close the meeting setup options, such as input and output devices.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { toggleMeetingSetup } = useVideo();

  const toggle = (e) => {
    toggleMeetingSetup();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Toogle Meeting setup</button>
    </>
  );
}

export default Room;

toggleCam

Type: () => void

Use this method to toggle the participant’s camera on or off during the video conference.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { toggleCam } = useVideo();

  const toggle = (e) => {
    toggleCam();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Toogle Camera</button>
    </>
  );
}

export default Room;

toggleMicrophone

Type: () => void

This method allows you to mute or unmute the participant’s microphone during the video conference.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { toggleMicrophone } = useVideo();

  const toggle = (e) => {
    toggleMicrophone();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Toogle Mic</button>
    </>
  );
}

export default Room;

toggleScreenShare

Type: () => void

Use this method to enable or disable participants sharing the screen with other participants in the meeting. Once activated it will ask the participant to share their screen. If activated it stops sharing the screen in the meeting.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { toggleScreenShare } = useVideo();

  const toggle = (e) => {
    toggleScreenShare();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Toogle Screen share</button>
    </>
  );
}

export default Room;

toggleChat

Type: () => void

This method allows you to hide or show the chat modal.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { toggleChat } = useVideo();

  const toggle = (e) => {
    toggleChat();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Toogle Chat</button>
    </>
  );
}

export default Room;

toggleRecording

Type: () => void

This method toggles the recording feature on and off, enabling you to use the AI Transcript API of the meeting's spoken content and to get the recording using the Recordings API.

Be aware that when using the recording feature, the cost of the meeting will increase by one participant.

When activated it will ask first for the meeting language, this is helpful for the transcript process.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { toggleRecording } = useVideo();

  const toggle = (e) => {
    toggleRecording();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Toogle recording</button>
    </>
  );
}

export default Room;

hangUp

function () => void

This method allows you to end the video conference and disconnect from the meeting.

import {
  useSuperVizRoom,
  useVideo,
  VideoConference,
} from "@superviz/react-sdk";

function Room() {
  const { hangUp } = useVideo();

  const toggle = (e) => {
    hangUp();
  };

  return (
    <>
      <VideoConference participantType="host" />
      <button onClick={toggle}>Hang up</button>
    </>
  );
}

export default Room;

Type Definitions

Avatar[]

Type: list of objects

While the SuperViz SDK provides a range of default 3D avatars for meetings, you have the flexibility to enrich this experience by adding your list of custom avatars for the meeting.

Name	Type	Description
imageUrl	string	Required. Path to the thumbnail image. Supported formats: .png and .jpg.
model3DUrl	string	Path to a 3D model. Only applicable when using Presence3D components. Supported formats: .glb and .gltf.

Example:

avatars: [
  {
    imageUrl: "https://<PATH>",
    model3DUrl: "https://<PATH>",
  },
];

CamerasPosition

Type: enum

In the CamerasPosition field, you can select from the following options: top, right, left, and bottom. This choice allows you to determine whether you prefer a vertical or horizontal camera layout. Values are:

• left
• right
• top
• bottom

Default value: right

For additional information, please refer to the documentation on collaboration mode.

CollaborationMode

Type: object In this object you can configure the how-to position the Video Conference and modals experience, allowing the participants to act with other collaboration tools.

Name	Type	Description
enabled	boolean	This flag allows the participant to enable or disable the collaboration mode. When the collaboration mode is enabled, the video meeting will be overlayed on the page. When disabled, it will enable an experience where the Video Conference will be displayed on the full page. Default value: true
position	CamerasPosition	In this field, you can select from the following options: top, right, left, and bottom. This choice allows you to determine whether you prefer a vertical or horizontal camera layout. Default value: right
modalPosition	LayoutPosition	You have the flexibility to select the positioning of the meeting modals layout, like chat or settings, by choosing either left, right, or center. Default value: right
initialView	LayoutMode	You can change the layout mode of the video conference before initializing it, by selecting either list or grid. Default value: list

Example:

collaborationMode: {
  enabled: "true",
  position: "right",
  modalPosition: "right",
  initialView: "list"
}

tip

If the collaboration mode is disabled, the position, initialView, and modalPosition fields will be ignored.

For additional information, please refer to the documentation on collaboration mode.

DevicesOptions

Type: object

With this field, you can disable participant-specific devices such as video input, audio input, and output options when joining the meeting.

The DevicesOptions are represented for three values of boolean.

Name	Type	Description
audioInput	boolean	You can choose if the application will ask the participant to use an audio input device. When set true, it will ask user browser to consent access to its microphone. Default value: true
audioOutput	boolean	You can choose if the application will use the participant audio output device. Default value: true
videoInput	boolean	You can choose if the application will ask the participant to use a video input device. When set true, it will ask the user browser to consent access to its video camera. Default value: true

Example:

devicesOptions: {
  audioInput: true;
  audioOutput: true;
  videoInput: true;
}

LayoutMode

Type: enum

You can change the layout mode of the video conference before initializing it, by selecting one of the following values:

• list
• grid

Default value: list

For additional information, please refer to the documentation on collaboration mode.

LayoutPosition

Type: enum

You have the flexibility to select the positioning of the meeting modal layout, like chat or settings, by choosing either left, right, or center. Values are:

• left
• right
• center

Default value: right

For additional information, please refer to the documentation on collaboration mode.

Locale

Type: object

This allows you to expand language options beyond the default English. Use this field to provide a list of languages available in the meeting overlay. For additional information on how, please refer to the documentation on how to internationalize your application.

Offset

Type: object

Position the iframe of the video conference by passing top, bottom, left, and right.

Name	Type	Description
top	number	Specifies the distance between the iframe and the top of the page in pixels. Default value: 0
bottom	number	Specifies the distance between the iframe and the bottom of the page in pixels. Default value: 0
left	number	Specifies the distance between the iframe and the left edge of the page in pixels. Default value: 0
right	number	Specifies the distance between the iframe and the right edge of the page in pixels. Default value: 0

Example:

offset: {
  top: 0,
  bottom: 0,
  left: 0,
  right: 0
}

ParticipantType

Type: enum

User ParticipantType to assign appropriate participant permissions within the room. Values are:

• host can modify the grid mode and remove users from the room.
• guest can participate in the room with a camera or voice.
• audience can watch the meeting, but won’t be able to activate their camera and unmute themselves. Typically used in broadcast rooms.

Default value: guest