Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

VideoExpress.Room

Constructor Options Properties Methods Events 

The first step in using Vonage Video Express is to create the Room object. For creating a Room object, VideoExpress contains a static Room constructor method which received RoomProperties object as argument for setting up Room

Constructor Options

Name Description
(string) apiKey The API key for a Vonage Video API project.
(string) sessionId The OpenTok session ID using the API key.
(string) token An OpenTok token for the session.
(string) participantName (Optional) The participant's name, visible to other participants.
(HTMLElement | string) roomContainer (Optional) The DOM element (or the ID of the DOM element) that contains all of the Video Express UI elements. If no value is passed in, then this defaults to the body element of the HTML page.
(Object) managedLayoutOptions (Optional) This object contains the following properties:

  • (string) layoutMode: "grid" (default) or "active-speaker"

  • (HTMLElement | string) cameraPublisherContainer: The container for the camera publisher video element. This can be an HTMLElement or the ID (string) of the element. This is an optional property, with the default set to the roomContainer constructor option, if specified. If you do not set a cameraPublisherContainer or roomContainer constructor option, the container defaults to the body element of the HTML page.

  • (HTMLElement | string) screenPublisherContainer: The container for the screen publisher video element. This can be an HTMLElement or the ID (string) of the element. This is an optional property, with the default set to the roomContainer constructor option, if specified. If you do not set a screenPublisherContainer or roomContainer constructor option, the container defaults to the body element of the HTML page.

  • (string) deviceLayoutMode: The device layout for the Room — either "auto" (the default), "desktop", or "mobile". This affects the layout of elements in the local client's page. This is an optional property, with the default set to "auto". If you do not set a deviceLayoutMode, the layout manager sets the layout automatically, based on the client's user agent.

    This is a beta feature.

For example: 
const room = new VideoExpress.Room({
  apiKey: '44444444',
  sessionId: '1_this1is2my3new4session5id6',
  token: 'T1==this1is2a3token5nekot6a7si8siht9...',
  roomContainer: 'roomContainer',
  managedLayoutOptions: {
    deviceLayoutMode: 'desktop',
  },
});

Properties

Name Description
(CameraPublisher) camera Provides the mechanism for controlling the local video stream.
(ScreenPublisher) screen Provides the mechanism for controlling the local screen share stream.
(string) participantId Participant ID, set after joining the room.
(string) participantName The participant name, as set in the constructor.
(Object) participants A key/value object containing Participant objects by participantId.

Methods

Name Description
(Promise<void>) join () Connects the local client to the room. Once connected, the client start publishing and subscribing to media. This method has an optional publisherOptions argument, described here. The promise returned by this method is rejected with an error if the client cannot join the room successfully (for example, due to the user denying access to the camera or microphone or to a timeout when publishing).
(void) leave () This method disconnects the client and leaves the room. It also stops publishing audio/video before leaving the room.
(Promise<void>) startScreensharing () Starts screen sharing. This method has an optional targetElement argument of type HTMLElement or string. If no parameter is passed in, it uses the default screenPublisherContainer from ManagedLayoutOptions.
(void) stopScreensharing () Stops screen sharing.
(void) setLayoutMode (mode) Updates the layout mode. This method receives a string that represents the new layout mode, which can be grid or active-speaker.
(Promise) signal (SignalOptions) Sends a signal. Accepts a SignalOptions object. For full signaling documentation see Signaling overview.

Events

Name Description
activeSpeakerChanged Dispatched when there is a new active speaker in the room. This can be used to add UI effects based on which participant is loudest in the room. Emits a Participant object.
connected This event is dispatched when the local client has joined the room. Does not emit anything.
disconnected Dispatched when the local client disconnects from the room. Emits a reason, which can have the following values:

  • clientDisconnected: The client disconnected from the room by calling the leave() method of the Room object or by closing the browser.

  • networkDisconnected: The network connection terminated abruptly (for example, the client lost their internet connection).

  • cameraPublisherDestroyed: The camera publisher was destroyed for some reason. In this scenario the participant is disconnected, since you are not allowed to join a room without publishing.

reconnecting The local client has lost its connection to the room and is trying to reconnect. This can result from a loss in network connectivity. Does not emit anything.
reconnected The local client has reconnected to the room after its connection was lost temporarily. Does not emit anything.
participantJoined Dispatched when a new remote participant joined the room. This event emits a Participant object, which contains information about the participant.
participantLeft Dispatched when a participant has disconnected from the room. Emits a Participant object, which contains information about the participant, and a reason, which can have the following values:

  • clientDisconnected: The client disconnected from the room by calling the leave() method of the Room object or by closing the browser.

  • networkDisconnected: The network connection terminated abruptly (for example, the client lost their internet connection).

signal Dispatched when the participant receives a signal from the room. Emits a SignalEvent object.
signal: Dispatched when the participant receives a signal of a specific typefrom the room. Emits a SignalEvent object.

PublisherOptions Properties

Name Description
(HTMLElement | string) targetElement (Optional) The HTMLElement or the id property of the element, used to determine the location of the Publisher video in the HTML DOM. If you do not specify a targetElement, the application appends a new DOM element to the room container DOM element.
(Object) publisherProperties (Optional) This object contains all OpenTok publisher properties, such as resolution, videoSource, audioSource, publishAudio, publishVideo, and more. See the complete list here.

SignalOptions

Name Description
(Participant) to (Optional) Participant to send signal to. If not specified, the signal is sent to all Participants.
(string) data (Optional) The data property of the signal parameter is the data string you send with the message. This property is optional. If you omit it, the message is sent without a data payload. The limit to the size of data is 8KB.
(string) type (Optional) Type property of the signal parameter. This is a string value that clients can filter on when listening for signals.
(boolean) retryAfterReconnect (Optional, default is true) Upon reconnecting to the session, whether to send any signals that were initiated while disconnected. See: Automatic reconnection in signaling.

SignalEvent

Name Description
(Participant) from The Participant that sent the signal. If the signal was sent from a server, this property is null. If sent by the local participant, this property is undefined.
(string) data The data string sent with the signal. undefined if omitted by sender.
(boolean) isSentByMe Whether the signal was sent by the local participant (true) or by another participant in the room (false).
(string) type "signal:<type>" where <type> is the type property sent in the signal. If no type is specified, type is "signal".