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.
(Object) iceConfig (Optional) Settings for configurable TURN server support, which is available as an add-on feature. This object contains the following properties:

  • (string) includeServers: Set this to 'custom' and client will use only the custom TURN servers you provide in the customServers array. Set this to 'all' (the default) and the client will use both the custom TURN servers you provide along with OpenTok TURN servers.

  • (string) transportPolicy: Set this to 'all' (the default) and the client will use all ICE transport types (such as host, srflx, and TURN) to establish media connectivity. Set this to 'relay' to force connectivity through TURN always and ignore all other ICE candidates.

  • (Array) customServers: Set this to an array of objects defining your custom TURN servers. Each object corresponds to one custom TURN server, and it includes the following properties:

    • (string | Array of strings) urls: A string or an array of strings, where each string is a URL supported by the TURN server (and this may be only one URL).

    • (string) username: The username for the TURN server defined in this object.

    • (string) credential: The credential string for the TURN server defined in this object.

Note: To have the client only use the TURN servers you specify (and not use the OpenTok TURN servers), set the includeServers property to 'custom', set the transportPolicy property to 'relay', and set the customServers property to list your TURN servers.
(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.

  • (boolean) speakerHighlightEnabled: When a participant becomes the active speaker, highlights the user's video tile. This is an optional property, with the default set to false. Note: To enable speakerHighlightColor, this must be set to true.

  • (string) speakerHighlightColor: When a participant becomes the active speaker, highlights the user's video tile with the specified color value. This can be a hex-code (#4CBB17) or named color (red). This is an optional property, with the default set to #5ed4eb if speakerHighlightEnabled is true. Note: To highlight the active speaker, set speakerHighlightEnabled to true.

(number) maxVideoParticipantsOnScreen

The maximum number of CameraSubscriber videos shown in a room simultaneously. This affects the display of CameraSubscriber videos (not screen-sharing or CameraPublisher videos) in the local client only. After reaching the limit, the client will not subscribe to inactive participants' CameraSubscriber videos. CameraSubscriber videos for new participants are shown on entry, and CameraSubscriber videos for inactive participants are shown upon becoming active speakers.

If no value is passed in, the default threshold of 25 is used for the desktop layout. For the mobile layout, this is not configurable and is set to 3 participants.

Note: The local client may publish audio/video, but the other participants will not subscribe to the video if they set this option and the limit is reached (unless the video has an active speaker).

(number) mediaShutoffThreshold

The threshold for the current number of participants in the Room (upon joining) that will prevent the local client’s CameraPublisher from publishing audio and video. Upon joining the room, if the threshold is reached, the Room object will dispatch a cameraPublisherMediaDisabled event, and audio and video of the local client’s CameraPublisher are disabled.

(string) participantName (Optional) The participant's name, visible to other participants.
(string) participantInitials (Optional) The participant's initials, visible to other participants when the local client is not publishing video, and the disabledImageURI is not set.
(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.
(string) sessionId The OpenTok session ID using the API key.
(string) token An OpenTok token for the session.
For example: 
const room = new VideoExpress.Room({
  apiKey: '44444444',
  sessionId: '1_this1is2my3new4session5id6',
  token: 'T1==this1is2a3token5nekot6a7si8siht9...',
  roomContainer: 'roomContainer',
  managedLayoutOptions: {
    deviceLayoutMode: 'desktop',
    speakerHighlightEnabled: true,
    speakerHighlightColor: '#000000',
  },
  iceConfig: {
    includeServers: 'custom',
    transportPolicy: 'relay',
    customServers: [
      {
        urls: [
          'turn:123.124.125.126:3478?transport=udp',
          'turn:123.124.125.126:3478?transport=tcp'
        ],
        username: 'webrtc',
        credential: 'foO0Bar1'
      },
      {
        urls: [
          'turns:turntls.example.com:3478?transport=tcp'
        ],
        username: 'webrtc',
        credential: 'foO0Bar2',
      },
    ],
  },
  mediaShutoffThreshold: 25,
  maxVideoParticipantsOnScreen: 3,
});

Properties

Name Description
(string) apiKey The API key for a Vonage Video API project.
(CameraPublisher) camera Provides the mechanism for controlling the local video stream.
(Object) iceConfig

The iceConfig object passed in the constructor.

(Object) managedLayoutOptions

The managedLayoutOptions object passed in the constructor.

(number) maxVideoParticipantsOnScreen

The maximum number of CameraSubscriber videos shown in a room simultaneously.

(number) mediaShutoffThreshold

The threshold for the current number of participants in the Room (upon joining) that will prevent the local client’s CameraPublisher from publishing audio and video.

(string) participantConnectionData

The string passed from the OpenTok Connection object after successfully connecting to a session. For full token creation documentation, see Token Creation Overview.

(string) participantId Participant ID, set after joining the room. This is the connectionId string from the OpenTok Connection object.
(string) participantInitials The participant initials, as set in the constructor.
(string) participantName The participant name, as set in the constructor.
(Object) participants A key/value object containing Participant and LocalParticipantobjects by participantId.
(HTMLElement | string) roomContainer The DOM element (or the ID of the DOM element) that contains all of the Video Express UI elements.
(string) roomId The OpenTok session ID using the sessionId string from the constructor.
(ScreenPublisher) screen Provides the mechanism for controlling the local screen share stream.
(string) token An OpenTok token for the session.

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) setEncryptionSecret (encryptionSecret) Changes the encryption secret after room was already created. This method receives a string that represents the new secret.
(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.
(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.

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.
cameraPublisherMediaDisabled This event is dispatched when the mediaShutoffThreshold (set in the Room() constructor) is reached upon joining the room. Audio and for the local client’s CameraPublisher are disabled.
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) and was detected by the OpenTok platform.

  • 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.

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) and was detected by the OpenTok platform.

reconnected The local client has reconnected to the room after its connection was lost temporarily. Does not emit anything.
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.
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
(Object) publisherProperties (Optional) This object contains all OpenTok publisher properties, such as resolution, videoSource, audioSource, publishAudio, publishVideo, and more. See the complete list here.
(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.

SignalOptions

Name Description
(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.
(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.
(Participant) to (Optional) Participant to send signal to. If not specified, the signal is sent to all Participants.
(string) type (Optional) Type property of the signal parameter. This is a string value that clients can filter on when listening for signals.

SignalEvent

Name Description
(string) data The data string sent with the signal. undefined if omitted by sender.
(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.
(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".