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