README

Multiparty Toolkit

The Multiparty Toolkit is a JavaScript library to quickly create a multiparty video conference web application. It works on top of the Vonage Video API for JavaScript.

Documentation

The documentation and API reference can be found at https://tokbox.com/developer/multiparty/

Accessing MP library

Via npm installed package

Install package:

$ npm i --save @vonage/multiparty

import * as MP from "@vonage/multiparty";
// or
import { Room, PreviewPublisher} from "@vonage/multiparty";

Via script tag

In html:

<script src="https://static.opentok.com/v0/js/multiparty-sdk.js"></script>

In javascript, access via global MP object:

/* global MP */

// e.g usage:
const room = new MP.Room({...

Methods

See the OpenTok developer guides on Session Creation and Token Creation.

Instantiate a room instance (with only mandatory parameters)

// Example code 1: Only four parameters are required to set up a room instance. All other parameters have default values set internally
// API key, Session ID and Token needs to be generated through the Vonage Video API portal.
// roomContainer is an HTMLElement where all the participants who join the room will be displayed
const room = new MP.Room({
  apiKey: "44444444",
  sessionId: "1_this1is2my3new4session5id6",
  token: "T1==this1is2a3token5nekot6a7si8siht9",
  roomContainer: "roomcontainer",
});

Instantiate a room instance (with all parameters)

const room = new MP.Room({
  apiKey: "44444444",
  sessionId: "1_this1is2my3new4session5id6",
  token: "T1==this1is2a3token5nekot6a7si8siht9",
  roomContainer: "roomcontainer",
  managedLayoutOptions: {
    layoutMode: "active-speaker",
    cameraPublisherContainer: "cameraPublisherContainerDiv",
    screenPublisherContainer: "screenPublisherContainerDiv",
  }
});

Instantiate a room instance but excluding the camera and screen publishers in the layout grid. Notice that both cameraPublisherContainer and screenPublisherContainer are omitted within managedLayoutOptions.

const room = new MP.Room({
  apiKey: "44444444",
  sessionId: "1_this1is2my3new4session5id6",
  token: "T1==this1is2a3token5nekot6a7si8siht9",
  roomContainer: "roomcontainer",
  managedLayoutOptions: {
    layoutMode: "active-speaker",
  }
});

Setup preview media before joining the room

const previewPublisher = new MP.PreviewPublisher('previewContainer');
previewPublisher.previewMedia(
  publisherOptions: {
    targetElement: "previewContainer",
    publisherProperties: {
      resolution: "1280x720",
      publishAudio: true,
      publishVideo: true,
      mirror: false,
      audioBitrate: 15,
      audioFallbackEnabled: true,
    },
  },
);

Setting preview media audio/video devices

// Changes the audio input device
previewPublisher.setAudioDevice(audioDeviceId);

// Changes the video input device
previewPublisher.setVideoDevice(videoDeviceId);

Getting preview media audio/video devices

// Returns the current audio input device
const currentAudioDevice = await previewPublisher.getAudioDevice();

// Returns the current video input device
const currentVideoDevice = previewPublisher.getVideoDevice();

Join a room (with only mandatory parameters)

// All parameters are optional for this method. This method will internally initialize a session and join the call
room.join();

Join a room (with all parameters)

// All parameters are optional for this method. This method will internally initialize a session and join the call
room.join(
  publisherOptions: {
    targetElement: "publisherContainer",
    publisherProperties: {
      resolution: "1280x720",
      publishAudio: true,
      publishVideo: true,
      mirror: false,
      audioBitrate: 15,
      audioFallbackEnabled: true,
    },
  },
);

Leave a room (this method does not take any parameters)
```
room.leave();
```

Set the layout mode (only one parameter and its mandatory)

room.setLayoutMode('grid'); // Set layout mode to grid
room.setLayoutMode('active-speaker'); // Set layout mode to active-speaker

Start screensharing (only one parameter and its optional. If no parameter is passed, then the default value will be used)

room.startScreensharing("screenContainer")
  .then(() => console.log("Started screensharing"))
  .catch((err) => console.err(err));

Stop screensharing (this method does not take any parameters)
```
room.stopScreenSharing();
```

Accessing camera publisher's audio/video

// Returns a boolean. Checks whether a camera publisher video is enabled or not
room.camera.isVideoEnabled();

// Returns a boolean. Checks whether a camera publisher audio is enabled or not
room.camera.isAudioEnabled();

// Enables camera publisher's video
room.camera.enableVideo();

// Disables camera publisher's video
room.camera.disableVideo();

// Enables camera publisher's audio
room.camera.enableAudio();

// Disables camera publisher's audio
room.camera.disableAudio();

Setting camera publisher's audio/video devices

// Changes the audio input device
room.camera.setAudioDevice(audioDeviceId);

// Changes the video input device
room.camera.setVideoDevice(videoDeviceId);

Getting camera publisher's audio/video devices

// Returns the current audio input device
const currentAudioDevice = await room.camera.getAudioDevice();

// Returns the current video input device
const currentVideoDevice = room.camera.getVideoDevice();

Accessing screensharing publisher's audio/video

// Returns a boolean. Checks whether a screen publisher video is enabled or not
room.screen.isVideoEnabled();

// Returns a boolean. Checks whether a screen publisher audio is enabled or not
room.screen.isAudioEnabled();

// Enables screen publisher's video
room.screen.enableVideo();

// Disables screen publisher's video
room.screen.disableVideo();

// Enables screen publisher's audio
room.screen.enableAudio();

// Disables screen publisher's audio
room.screen.disableAudio();

Accessing camera subscriber's audio/video

// Returns a boolean. Checks whether a camera subscriber video is enabled or not
participant.camera.isVideoEnabled();

// Returns a boolean. Checks whether a camera subscriber audio is enabled or not
participant.camera.isAudioEnabled();

// Enables camera subscriber's video
participant.camera.enableVideo();

// Disables camera subscriber's video
participant.camera.disableVideo();

// Enables camera subscriber's audio
participant.camera.enableAudio();

// Disables camera subscriber's audio
participant.camera.disableAudio();

Accessing screen subscriber's audio/video

// Returns a boolean. Checks whether a screen subscriber video is enabled or not
participant.screen.isVideoEnabled();

// Returns a boolean. Checks whether a screen subscriber audio is enabled or not
participant.screen.isAudioEnabled();

// Enables screen subscriber's video
participant.screen.enableVideo();

// Disables screen subscriber's video
participant.screen.disableVideo();

// Enables screen subscriber's audio
participant.screen.enableAudio();

// Disables screen subscriber's audio
participant.screen.disableAudio();

Events

Events in Room

connected: This event fires when a connected to a room

room.on('connected', () => {
  console.log('Connected');
  // Can use this event to update visual indicator for connection status
});

reconnecting: This event fires when a client tried to automatically reconnect to a room

room.on('reconnecting', () => {
  console.log('Try to reconnect to the room');
  // Can use this event to update visual indicator for reconnection status, like a loading spinner
});

reconnected: This event fires when a client reconnects to a room

room.on('reconnected', () => {
  console.log('Reconnected to the room');
  // Can use this event to update visual indicator for reconnection is successfull
});

disconnected: This event fires when a disconnected from a room

room.on('disconnected', () => {
  console.log('Disconnected');
  // Can use this event to update visual indicator for connection status
});

participantJoined: This event fires when a participant joins a room. This event will emit the participant object

room.on('participantJoined', (participant) => {
  console.log('participantJoined: ', participant.id);
  // Can use this event to update visual indicator for participant joined
});

participantLeft: This event fires when a participant leaves a room. This event will emit the participant object, and reason

room.on('participantLeft', (participant, reason) => {
  console.log('participantLeft: ', participant.id, ' reason: ', reason);
  // Can use this event to update visual indicator for participant left
});

activeSpeakerChanged: This event will fire when the layout is set to active-speaker the user who is currently speaking changes.
```
room.on('activeSpeakerChanged', (participant) => {
  console.log('Active speaker changed', participant);
})
```

Events in CameraPublisher

created: This event fires when a camera publisher is created

room.camera.on("created", () => {
  console.log("Camera publisher created");
  // Do something else here
});

destroyed: This event fires when a camera publisher is destroyed

room.camera.on("destroyed", () => {
  console.log("Camera publisher destroyed");
  // Do something else here
});

audioLevelUpdated: This event fires when a audio level for camera publisher changes

room.camera.on("audioLevelUpdated", (audioLevel) => {
  console.log("Camera publisher's audio level: ", audioLevel);
  // Do something else here
  updateAudioIndicator(audioLevel);
});

accessAllowed: This event fires when access to camera and mic is granted

room.camera.on("accessAllowed", () => {
  console.log("Granted access to camera and mic");
  // Do something else here
});

accessDenied: This event fires when access to camera and mic is denied

room.camera.on("accessDenied", () => {
  console.log("Denied access to camera and mic");
  // Do something else here
});

accessDialogOpened: This event fires when access to camera and mic dialog box is opened

room.camera.on("accessDialogOpened", () => {
  console.log("The Allow/Deny dialog box opened");
  // Do something else here
});

accessDialogClosed: This event fires when access to camera and mic dialog box is closed

room.camera.on("accessDialogClosed", () => {
  console.log("The Allow/Deny dialog box opened");
  // Do something else here
});

Events in ScreenPublisher

started: This event fires when a screen publisher starts screensharing

room.screen.on("started", () => {
  console.log("Screen publisher created");
  // Do something else here
});

stopped: This event fires when a screen publisher stops screensharing

room.screen.on("stopped", () => {
  console.log("Screen publisher stopped");
  // Do something else here
});

audioLevelUpdated: This event fires when a audio level for screen publisher changes

room.screen.on("audioLevelUpdated", (audioLevel) => {
  console.log("Camera publisher's audio level: ", audioLevel);
  // Do something else here
  updateAudioIndicator(audioLevel);
});

Events in PreviewPublisher

created: This event fires when a preview publisher is created

previewPublisher.on("created", () => {
  console.log("Preview publisher created");
  // Do something else here
});

destroyed: This event fires when a preview publisher is destroyed

previewPublisher.on("destroyed", () => {
  console.log("Preview publisher destroyed");
  // Do something else here
});

audioLevelUpdated: This event fires when a audio level for preview publisher changes

previewPublisher.on("audioLevelUpdated", (audioLevel) => {
  console.log("Preview publisher's audio level: ", audioLevel);
  // Do something else here
  updateAudioIndicator(audioLevel);
});

accessAllowed: This event fires when access to camera and mic is granted

previewPublisher.on("accessAllowed", () => {
  console.log("Granted access to camera and mic");
  // Do something else here
});

accessDenied: This event fires when access to camera and mic is denied

previewPublisher.on("accessDenied", () => {
  console.log("Denied access to camera and mic");
  // Do something else here
});

accessDialogOpened: This event fires when access to camera and mic dialog box is opened

previewPublisher.on("accessDialogOpened", () => {
  console.log("The Allow/Deny dialog box opened");
  // Do something else here
});

accessDialogClosed: This event fires when access to camera and mic dialog box is closed

previewPublisher.on("accessDialogClosed", () => {
  console.log("The Allow/Deny dialog box opened");
  // Do something else here
});

Events in Participant

cameraCreated: This event fires when a camera subscriber is created

participant.on("cameraCreated", (cameraSubscriber) => {
    console.log("Camera subscriber created");
    // Do something else here
});

cameraDestroyed: This event fires when a camera subscriber is destroyed

participant.on("cameraDestroyed", () => {
  console.log("Camera subscriber destroyed");
  // Do something else here
});

screenCreated: This event fires when a screen subscriber is created

participant.on("screenCreated", (screenSubscriber) => {
  console.log("Screen subscriber created");
  // Do something else here
});

screenDestroyed: This event fires when a screen subscriber is destroyed

participant.on("screenDestroyed", () => {
  console.log("Screen subscriber destroyed");
  // Do something else here
});

Events in CameraSubscriber

audioLevelUpdated: This event fires when a audio level for camera subscriber changes

camera.on("audioLevelUpdated", (audioLevel) => {
  console.log("Camera subscriber audio level: ", audioLevel);
  // Do something else here
  updateAudioIndicator(audioLevel);
});

Events in ScreenSubscriber

audioLevelUpdated: This event fires when a audio level for screen subscriber changes

screen.on("audioLevelUpdated", (audioLevel) => {
  console.log("Screen subscriber audio level: ", audioLevel);
  // Do something else here
  updateAudioIndicator(audioLevel);
});

Usage no npm install needed!