Video Conference

The Video Conference component enables you to integrate reliable video conferences into your web application.

Before we start

Before utilizing the Video Conference, it is essential to initialize the room with a defined name and ID for the participant and the group.

How to use

To add a Video Conference to your web page, you can use the following code:

import { VideoConference } from "@superviz/sdk";

video = new VideoConference({
  avatars: [
    {
      imageUrl: "https://<PATH>",
      model3DUrl: "https://<PATH>"
    }
  ],
  camsOff: false,
  canShowAudienceList: true,
  chatOff: false,
	collaborationMode: {
    enabled: "true",
    position: "right",
    modalPosition: "right",
    initialView: "list"
  },
  defaultAvatars: false,
  defaultToolbar: false,
  devices: {
    audioInput: false,
    audioOutput: false,
    videoInput: false
  },
  enableFollow: false,
  enableGather: false,
  enableGoTo: false,
  language: "en-US",
  locales: [ ],
  screenshareOff: false,
  skipMeetingSettings: false,
  offset: {
    top: 0,
    bottom: 0,
    left: 0,
    right: 0
  },
  participantType: "host"
});

room.addComponent(video);

After being initialized, the Video Conference inserts a SuperViz-enabled iframe into the Document Object Model (DOM). Additionally, if necessary, it sends a request to the browser to consent to access the participant's camera and microphone.

With the necessary permissions consented, the participant can set up the input and output devices, like a camera and microphone, and enter the meeting room.

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
`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
`callbacks`	`object`	This object allows you to define a range of callbacks to handle specific interactions within the meeting. See more about it in the callbacks section.
`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" 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 the leader in the 3D model. Default value: `false`
`enableGather`	`boolean`	When set true, enables the Gather functionality, which aligns all participants' views with the 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 in the 3D model by clicking on their webcam, facilitating quick location of participants. 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.

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.

For a comprehensive understanding of events associated with the Video Conference, please refer to the Video Conference Events documentation. This dedicated resource will provide you with detailed information on subscribing to, handling, and utilizing events specific to this component.

By visiting the component-specific documentation, you'll gain access to insights into events like participant join/leave notifications, meeting state changes, and other event-driven functionalities tailored to the Video Conference.

Callbacks

When using the Video Conference, you can define a range of callbacks to handle specific events and interactions within the meeting. These callbacks allow you to respond to participant actions, meeting state changes, and other event-driven functionalities.

To define a callback, you need to pass a function when creating the Video Conference, as shown in the example below:

const video = new VideoConference({
  callbacks: {
    onToggleMicrophone: () => {},
    onToggleCam: () => {},
    onToggleRecording: () => {},
    onToggleChat: () => {},
    onToggleScreenShare: () => {},
    onClickHangup: () => {},
    onToggleMeetingSetup: () => {},
  },
});

When you pass a function to the callbacks object, the default behavior of the Video Conference will be overridden by the function you provide. This allows you to customize the behavior of the Video Conference to suit your specific requirements.

For example, when using onToggleChat(), the chat modal will not be displayed when the participant clicks the chat button, as a custom function has been provided by you. To ensure the chat modal is displayed, you need to include the logic to show the chat modal within the function you provide, like so:

const video = new VideoConference({
  callbacks: {
    onToggleChat: () => {
      // Your logic
      video.toggleChat();
    },
  },
});

`onToggleMicrophone`

This callback is triggered when the participant toggles their microphone on or off during the video conference.

If you just need to wrap the default behavior with your custom logic, you can use the toggleMicrophone() method inside the callback function to ensure the default behavior is maintained.

Example:

const video = new VideoConference({
  callbacks: {
    onToggleMicrophone: () => {
      // Your logic
      video.toggleMicrophone();
    },
  },
});

`onToggleCam`

This callback is triggered when the participant toggles their camera on or off during the video conference.

If you just need to wrap the default behavior with your custom logic, you can use the toggleCam() method inside the callback function to ensure the default behavior is maintained.

Example:

const video = new VideoConference({
  callbacks: {
    onToggleCam: () => {
      // Your logic
      video.toggleCam();
    },
  },
});

`onToggleRecording`

This callback is triggered when the participant toggles the recording feature on and off during the video conference.

If you just need to wrap the default behavior with your custom logic, you can use the toggleRecording() method inside the callback function to ensure the default behavior is maintained.

Example:

const video = new VideoConference({
  callbacks: {
    onToggleRecording: () => {
      // Your logic
      video.toggleRecording();
    },
  },
});

`onToggleChat`

This callback is triggered when the participant toggles the chat modal on and off during the video conference.

If you just need to wrap the default behavior with your custom logic, you can use the toggleChat() method inside the callback function to ensure the default behavior is maintained.

Example:

const video = new VideoConference({
  callbacks: {
    onToggleChat: () => {
      // Your logic
      video.toggleChat();
    },
  },
});

`onToggleScreenShare`

This callback is triggered when the participant toggles the screen-sharing feature on and off during the video conference.

If you just need to wrap the default behavior with your custom logic, you can use the toggleScreenShare() method inside the callback function to ensure the default behavior is maintained.

Example:

const video = new VideoConference({
  callbacks: {
    onToggleScreenShare: () => {
      // Your logic
      video.toggleScreenShare();
    },
  },
});

`onClickHangup`

This callback is triggered when the participant leaves the video conference.

Example:

const video = new VideoConference({
  callbacks: {
    onClickHangup: () => {
      // Your logic
      video.hangUp();
    },
  },
});

`onToggleMeetingSetup`

This callback is triggered when the participant clicks the settings button in the video conference.

If you just need to wrap the default behavior with your custom logic, you can use the toggleMeetingSetup() method inside the callback function to ensure the default behavior is maintained.

Example:

const video = new VideoConference({
  callbacks: {
    onToggleMeetingSetup: () => {
      // Your logic
      video.toggleMeetingSetup();
    },
  },
});

Methods

`subscribe()`

The subscribe method allows you to register your application to listen for specific events within the Video Conference. By subscribing to events, you can capture and respond to important interactions or changes that occur during a video conference session.

Example:

video.subscribe(MeetingEvent.MEETING_START, onStart);

function onStart() {
	// do something
}

Please refer to the Video Conference Events documentation for a list of available event names.

`unsubscribe()`

The unsubscribe method allows you to stop listening to a previously subscribed event within the Video Conference.

Example:

video.unsubscribe(MeetingEvent.MEETING_START, onStart);

`hangUp()`

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

Example:

video.hangUp();

`toggleCam()`

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

Example:

video.toggleCam();

`toggleChat()`

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

Example:

video.toggleChat();

`toggleMeetingSetup()`

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

Example:

video.toggleMeetingSetup();

`toggleMicrophone()`

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

Example:

video.toggleMicrophone();

`toggleScreenShare()`

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.

Example:

video.toggleScreenShare();

`toggleRecording()`

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.

Example:

video.toggleRecording();

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

Video Conference

Before we start​

How to use​

Properties​

Layout and languages​

Behavior​

Presence controls​

3D plugins​

Events​

Callbacks​

onToggleMicrophone​

onToggleCam​

onToggleRecording​

onToggleChat​

onToggleScreenShare​

onClickHangup​

onToggleMeetingSetup​

Methods​

subscribe()​

unsubscribe()​

hangUp()​

toggleCam()​

toggleChat()​

toggleMeetingSetup()​

toggleMicrophone()​

toggleScreenShare()​

toggleRecording()​

Type Definitions​

Avatar[]​

CamerasPosition​

CollaborationMode​

DevicesOptions​

LayoutMode​

LayoutPosition​

Locale​

Offset​

ParticipantType​

Before we start

How to use

Properties

Layout and languages

Behavior

Presence controls

3D plugins

Events

Callbacks

`onToggleMicrophone`

`onToggleCam`

`onToggleRecording`

`onToggleChat`

`onToggleScreenShare`

`onClickHangup`

`onToggleMeetingSetup`

Methods

`subscribe()`

`unsubscribe()`

`hangUp()`

`toggleCam()`

`toggleChat()`

`toggleMeetingSetup()`

`toggleMicrophone()`

`toggleScreenShare()`

`toggleRecording()`

Type Definitions

`Avatar[]`

`CamerasPosition`

`CollaborationMode`

`DevicesOptions`

`LayoutMode`

`LayoutPosition`

`Locale`

`Offset`

`ParticipantType`