VCS Realtime SDK

# Classes

Device

The device object allows getting and setting the preferred devices, and WebRTC configuration settings.

LocalParticipant ⇐ Participant

Participant object of local user.

RemoteParticipant ⇐ Participant

Participant object for remote users.

Room ⇐ EventEmitter

Room the user joined. Contains the local and remote participant with their media streams. Also exposes functions such as muting or toggling video. Raises events when participants join/leave or media streams change.

Settings

The settings object allows getting and setting vcs-realtime settings.

# Constants

version

SDK version.

# Functions

setLogger(baseLogger)

Set the base logger object. baseLogger should implement the debug, warn, info and error functions.

joinRoom(token, [options]) ⇒ Promise.<Room>

Join a room.

# Device

The device object allows getting and setting the preferred devices, and WebRTC configuration settings.

Kind: global class

# Device.autoGainControl : boolean

Deprecated

Moved to Settings class.

Kind: static property of Device

# Device.setPreferredDevice(deviceId, kind)

Sets the preferred device for the given list of preferred device Ids. The preferred device is remembered using localStorage. Changing the preferred device during a session will immediately switch to the new device.

Kind: static method of Device

Param Type Description
deviceId string The device to set as preferred.
kind string The kind of device.

Example

import { Device } from 'vcs-realtime-sdk';
const devices = Device.getDevices();
Device.setPreferredDevice(devices.audioInputList[0].deviceId, 'audioinput');

# Device.supportsAudioOutputSelection() ⇒ boolean

Check if the browser allows the selection of an audio output device.

Kind: static method of Device
Returns: boolean - True is audio output selection is allowed.
Example

import { Device } from 'vcs-realtime-sdk';
const allowed = Device.supportsAudioOutputSelection();

# Device.getDevices() ⇒ Promise.<object>

Get the list of available media devices, and the selected preferred devices.

Kind: static method of Device
Returns: Promise.<object> - Object with audioOutput(List), audioInput(List) and videoInput(List) devices.
Example

import { Device } from 'vcs-realtime-sdk';
const devices = Device.getDevices();

# Device.getPreferredDevices() ⇒ object

Gets the configured preferred device IDs without checking whether the devices are connected.

Kind: static method of Device
Returns: object - The preferred device Ids for the different kinds.
Example

import { Device } from 'vcs-realtime-sdk';
const preferredDevices = Device.getPreferredDevices();

# LocalParticipant ⇐ Participant

Participant object of local user.

Kind: global class
Extends: Participant

# localParticipant.self : boolean

Indicates this participant is the LocalParticipant.

Kind: instance property of LocalParticipant

# localParticipant.attach(el, [style])

Attach video element to provided DOM element. mediaStream is automatically updated. No need for the application to listen for localStream or remoteStream events and manually update the video's srcObject.

Kind: instance method of LocalParticipant
Overrides: attach

Param Type Description
el object DOM element to attach the video to.
[style] object CSS styles to add to video element.

Example

const room = await joinRoom(<TOKEN>);
room.localParticipant.attach(document.getElementById('localVideo'), {
  width: '300px',
  'object-fit': 'cover'
});

# localParticipant.detach()

Detach video element from DOM element. Called automactially when session ends.

Kind: instance method of LocalParticipant
Overrides: detach

# RemoteParticipant ⇐ Participant

Participant object for remote users.

Kind: global class
Extends: Participant

# remoteParticipant.attach(el, [style])

Attach video element to provided DOM element. mediaStream is automatically updated. No need for the application to listen for localStream or remoteStream events and manually update the video's srcObject.

Kind: instance method of RemoteParticipant

Param Type Description
el object DOM element to attach the video to.
[style] object CSS styles to add to video element.

Example

const room = await joinRoom(<TOKEN>);
room.localParticipant.attach(document.getElementById('localVideo'), {
  width: '300px',
  'object-fit': 'cover'
});

# remoteParticipant.detach()

Detach video element from DOM element. Called automactially when session ends.

Kind: instance method of RemoteParticipant

# Room ⇐ EventEmitter

Room the user joined. Contains the local and remote participant with their media streams. Also exposes functions such as muting or toggling video. Raises events when participants join/leave or media streams change.

Kind: global class
Extends: EventEmitter
Emits: roomLeft, participantJoined, participantLeft, localStream, remoteStream

# room.name : string

Name of the room.

Kind: instance property of Room
Read only: true

# room.description : string

Description of the room.

Kind: instance property of Room
Read only: true

# room.conferenceType : string

Type of conference (MESH or SFU). MESH (default): End to end encrypted conference (peer-2-peer). SFU: Server-based conference. Suitable for larger conferences.

Kind: instance property of Room
Read only: true

# room.localParticipant ⇒ LocalParticipant

Local participant.

Kind: instance property of Room
Returns: LocalParticipant - Local participant.
Read only: true

# room.remoteParticipants ⇒ Array.<RemoteParticipant>

Remote participants.

Kind: instance property of Room
Returns: Array.<RemoteParticipant> - Array of remote participants.
Read only: true

# room.cameraFacingMode ⇒ string

Camera facing mode. Change mode via switchCamera.

Kind: instance property of Room
Returns: string - 'environment' or 'user'.
Read only: true

# room.toggleMute() ⇒ boolean

Mute/unmute preferred audio input device.

Kind: instance method of Room
Returns: boolean - True if muted.
Example

room.toggleMute();
const muted = room.isMuted();

# room.toggleAudio() ⇒ Promise.<boolean>

Toggle sending local audio. This API will add or remove an audio MediaStreamTrack to the local MediaStream. This is different from toggleMute which simply enables/disables the existing audio track.

Kind: instance method of Room
Returns: Promise.<boolean> - True if sending audio.
Example

const hasAudio = await room.toggleAudio();

# room.toggleVideo([hdVideo]) ⇒ Promise.<boolean>

Toggle sending local video.

Kind: instance method of Room
Returns: Promise.<boolean> - True if sending video.

Param Type Description
[hdVideo] boolean Whether or not HD video should be used. If not set the default options for the session is used.

Example

const hasVideo = await room.toggleVideo();

# room.toggleHdVideo() ⇒ Promise.<boolean>

Toggle between SD and HD if user is sending video.

Kind: instance method of Room
Returns: Promise.<boolean> - True if sending HD video.
Example

const hasHdVideo = await room.toggleHdVideo();

# room.scaleDownVideo(enable, [connectionId], [width])

Enables/disables scaling down video resolution for a given connection or all connections.

Kind: instance method of Room

Param Type Description
enable boolean True to enable scaling down video resolution.
[connectionId] string The connection ID. If not set then request applies to all connections.
[width] number The scaled down width. If not set default of 640px is used.

# room.isVideoScaledDown([connectionId]) ⇒ boolean

Checks if video resolution is being scaled down for the given connection or all connections.

Kind: instance method of Room
Returns: boolean - True if video resolution is being scaled down.

Param Type Description
[connectionId] string The connection ID. If not set then checks default setting for new connections.

# room.switchCamera() ⇒ Promise

Switch the camera on a mobile device between 'environment' and 'user'.

Kind: instance method of Room
Returns: Promise - Resolved when operation is completed.

# room.replaceVideoStream([stream])

Replace the sending video stream.

Kind: instance method of Room

Param Type Description
[stream] MediaStream The new MediaStream. If not set, fallback to local stream.

Example

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const room = await room.replaceVideoStream(stream);

# room.toggleDesktop() ⇒ Promise.<boolean>

Toggle sending local desktop (screen-share).

Kind: instance method of Room
Returns: Promise.<boolean> - True if sending desktop.
Example

const hasDesktop = await room.toggleVideo();

# room.hasAudio() ⇒ boolean

Check if user is sending audio.

Kind: instance method of Room
Returns: boolean - True if sending audio.

# room.hasVideo() ⇒ boolean

Check if user is sending video.

Kind: instance method of Room
Returns: boolean - True if sending video.

# room.hasHdVideo() ⇒ boolean

Check if user is sending HD video.

Kind: instance method of Room
Returns: boolean - True if sending HD video.

# room.hasDesktop() ⇒ boolean

Check if user is sending desktop (screen-share).

Kind: instance method of Room
Returns: boolean - True if sending desktop.

# room.isMuted() ⇒ boolean

Check if user is muted.

Kind: instance method of Room
Returns: boolean - True if muted.

# room.leave()

Leave the room.

Kind: instance method of Room

# room.sendMessageToParticipant(data, [address])

Sends a message through the active data channel.

Kind: instance method of Room

Param Type Description
data object The message to be sent.
[address] string The address of the participant to which message is to be sent. If address is not specified, the message would be sent to all the current participants in the room.

# "roomLeft"

Raised when local participant successfully left room.

Kind: event emitted by Room
Properties

Name Type Description
participant LocalParticipant Local participant.

Example

room.on('roomLeft', p => {
  console.log(`Local user ${p.name} has left the room`));
});

# "roomUpdated"

Raised when room name and/or description are updated.

Kind: event emitted by Room
Properties

Name Type Description
room string Room with updated name and description properties.

Example

room.on('roomUpdated', r => {
  console.log(`Room name ${r.name} description ${r.description}`));
});

# "roomTypeUpdated"

Raised when conference room type is updated.

Kind: event emitted by Room
Properties

Name Type Description
room string Room with name and updated conference type properties.

Example

room.on('roomTypeUpdated', r => {
  console.log(`Room name ${r.name} conference type ${r.conferenceType}`));
});

# "participantJoined"

Raised when a remote participant joined the room. Even though the participant has successfully joined, its media stream is not yet being stream. The event #remotestream will indicate that.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.

Example

room.on('participantJoined', p => {
  const div = document.createElement('div');
  // Let the SDK create the video tag and update the stream when needed
  participant.attach(div);
  document.body.appendChild(div);
});

# "participantLeft"

Participant left event.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.

Example

room.on('participantLeft', p => console.log(`${p.name} has left`));

# "localStream"

Raised when local stream is added, removed or changed. This event is handled internally when the SDK was used to create the video element via attach. If that is not the case then the application is responsible to update the video element's srcObject.

Kind: event emitted by Room
Properties

Name Type Description
participant LocalParticipant Local participant.

Example

room.on('localStream', p => {
  const el = document.getElementById('localVideoEl');
  el.srcObject = p.mediaStream;
});

# "remoteStream"

Raised when remote stream is added, removed or changed.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.

Example

room.on('remoteStream', p => {
  const el = document.getElementById(`video-${p.address}`);
  el.srcObject = p.mediaStream;
});

# "remoteAudioStream"

Raised when remote audio stream is added, removed or changed for mixed-audio streams. These audio streams are typically mixed at conference unit.

Kind: event emitted by Room
Properties

Name Type Description
stream stream Media stream of the mixed audio.

Example

room.on('remoteAudioStream', mediaStream => {
  const audioEl = document.getElementById('audio');
  audioEl.srcObject = mediaStream;
});

# "participantJoinFailed"

Raised when a participant failed to join.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.
reason string Reason text for join failure.

Example

room.on('participantJoinFailed', (participant, reason) => {
  console.log(`Participant ${participant.name} failed to join due to: ${reason});
});

# "activeSpeakers"

Raised when the list of active speaker in a conference room changes.

Kind: event emitted by Room
Properties

Name Type Description
activeSpeakers activeSpeakers List of participant addresses which are current active speakers.

Example

room.on('activeSpeakers', activeSpeakers => {
  console.log('current active speakers: ', activeSpeakers);
});

# "dataChannelOpen"

Raised when a data channel is opened.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.

Example

room.on('dataChannelOpen', (participant) => {
  console.log(`Data channel with participant ${participant.name} is open`);
});

# "dataChannelClosed"

Raised when a data channel is closed.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.

Example

room.on('dataChannelClosed', (participant, message) => {
  console.log(`Data channel with participant ${participant.name} is closed`);
});

# "messageReceived"

Raised when a data channel message is received.

Kind: event emitted by Room
Properties

Name Type Description
participant RemoteParticipant Remote participant.
message object The received data channel message.

Example

room.on('messageReceived', (participant, message) => {
  console.log(`Participant ${participant.name} sent message:`, message);
});

# Settings

The settings object allows getting and setting vcs-realtime settings.

Kind: global class

# Settings.autoGainControl : boolean

Enable or disable Automatic Gain Control on the audio track. Enabled by default. See MDN (opens new window) for details.

Kind: static property of Settings
Example

import { Settings } from 'vcs-realtime-sdk';
Settings.autoGainControl = false;

# Settings.preferredVideoCodec : string

Set the preferred video codec Possible values are 'VP8', 'VP9', 'H264'. Default: 'VP9'.

Kind: static property of Settings
Example

import { Settings } from 'vcs-realtime-sdk';
Settings.preferredVideoCodec = 'H264';

# Settings.defaultHdVideo : boolean

Set the HD Video as default. Default value is true.

Kind: static property of Settings
Example

import { Settings } from 'vcs-realtime-sdk';
Settings.defaultHdVideo = false;

# version

SDK version.

Kind: global constant
Example

import { version } from 'vcs-realtime-sdk';
console.log(version);

# setLogger(baseLogger)

Set the base logger object. baseLogger should implement the debug, warn, info and error functions.

Kind: global function

Param Type Description
baseLogger object The base logger object.

Example

import { setLogger } from 'vcs-realtime-sdk';
setLogger(console);

# joinRoom(token, [options]) ⇒ Promise.<Room>

Join a room.

Kind: global function
Returns: Promise.<Room> - Room.
Throws:

  • Error
Param Type Default Description
token string Token for room.
[options] object Options to join room.
[options.host] string "sandbox.virtualcareservices.net" VCS server host.
[options.name] string Own participant name.
[options.participantInfo] object Arbritary json object exchanged between participants in addition the name.
[options.audio] boolean true Use audio via default audio device.
[options.video] boolean true Use video via default video device.
[options.hdVideo] boolean true Use HD video via default video device.
[options.delayLocalStream] boolean false If true, the local media stream is only created after least two participants are connected to a room. Mutually exclusive with 'mediaStream' option.
[options.autoanswer] boolean true Auto answer incoming calls.
[options.mediaStream] MediaStream MediaStream to use. Overrules audio/video options.

Example

import { joinRoom } from 'vcs-realtime-sdk';
const room = await joinRoom(<TOKEN>, {
  host: 'sandbox.virtualcareservices.com',
  name: 'Bob',
  audio: false,
  video: true,
  hdVideo: true,
  participantInfo: { age: 24 }
});
console.log(`Joined ${room.name}`);
[room.localParticipant, ...room.remoteParticipants].forEach(p => {
  const div = document.createElement('div');
  room.localParticipant.attach(div, { width: '200px' });
  document.body.appendChild(div);
});