node package manager

@voxeet/voxeet-web-sdk

Voxeet Javascript SDK

The Voxeet SDK is an UMD Module that can be imported directly in the browser or via a npm package.

The SDK is asynchronous and uses promise at his core. Voxeet is natively running on Chrome and Firefox, and uses a plugin for Safari and Internet Explorer (>= 10)

Table of Contents

Getting Started

Installation

Browser

Include the following tag in the body:

<script src="https://unpkg.com/@voxeet/voxeet-web-sdk@Version" type="text/javascript"></script>

Replace 'Version' by whatever version you are using.

Npm

npm i @voxeet/voxeet-web-sdk

OAuth server authentication

Step 1: Encode consumer key and secret

  1. URL encode consumer key and consumer secret according to RFC 1738
  2. Concatenate the encoded customer key and secret with a colon separator, ":"
  3. Base64 encode the string from the previous step.

NodeJs example:

 btoa(encodeURI(consumerKey) + ":" + encodeURI(consumerSecret))

Step 2: Obtain an access token

  • Route: /v1/oauth2/token
  • Method: POST
  • Header: Authorization: Basic <base64 encoded value from Step 1>
  • body: grant_type=client_credentials

If the request is successfull, the server will respond with a json payload, containing an access token and a refresh token. This access token has a validity of 3600 seconds.

Step 3: Initialize the sdk

  1. Retrieve the access token from step 1 from your server.
  2. Initialize the sdk with the token and a method to refresh it

NodeJs example with axios:

axios.get("https://localhost:3000/token")
     .then(r => {
       return voxeet.initializeToken(r.accessToken, {name: "John doe"}, function() {
         return axios.get("https://localhost:3000/refresh").then(d => {
           return d.data;
         });
       });
     })
     .then(function(myUserId) {
     
       // The Voxeet Sdk is initialized, you can begin making calls. 
 
     })
     .catch(function(e) {
       console.error(e);
     });

The provided refresh token function must return a Promise<Token,Error>.

NodeJS Server Example

#!/usr/bin/env node
 
const express = require('express');
const https = require('https');
const axios = require('axios');
const btoa = require('btoa');
const fs = require('fs');
const cors = require('cors');
const bodyParser = require('body-parser');
const path = require('path');
 
const env = process.env.NODE_ENV;
 
const app = new express();
 
app.use(new cors());
app.use(bodyParser.json());
 
const consumerKey = "MyConsumerKey";
const consumerSecret = "MyConsumerSecret";
 
let accessToken = null;
let refreshToken = null;
 
const requests = {
  token: {
    method: "POST",
    url: "https://session.voxeet.com/v1/oauth2/token",
    headers: {
      'Authorization': "Basic " + btoa(encodeURI(consumerKey) + ":" + encodeURI(consumerSecret))
    },
    data: {
      grant_type: 'client_credentials'
    }
  },
  refresh: {
    method: "POST",
    url: "https://session.voxeet.com/v1/oauth2/refresh",
    headers: {
      'Authorization': "Basic " + btoa(encodeURI(consumerKey) + ":" + encodeURI(consumerSecret))
    }
  },
  invalidate: {
    method: "POST",
    url: "https://session.voxeet.com/v1/oauth2/invalidate",
    headers: {
      'Authorization': "Basic " + btoa(encodeURI(consumerKey) + ":" + encodeURI(consumerSecret))
    }
  }
};
 
app.get("/api/token", (req, res, next) => {
  return axios(requests.token)
           .then(r => {
             accessToken = r.data.access_token;
             refreshToken = r.data.refresh_token;
             return res.json(accessToken);
           })
           .catch(next);
});
 
app.get("/api/refresh", (req, res, next) => {
  let request = Object.assign({}, requests.refresh);
  request.data = {
    'refresh_token': refreshToken
  }
 
  return axios(request)
           .then(r => {
             accessToken = r.data.access_token;
             return res.json(accessToken);
           })
           .catch(next);
});
 
app.get("/api/invalidate", (req, res, next) => {
  let request = Object.assign({}, requests.invalidate);
  request.data = {
    'access_token': accessToken
  }
 
  return axios(request)
           .then(r => {
             return res.json("OK");
           })
           .catch(next);
});
 
https.createServer({
  key: fs.readFileSync(path.resolve(__dirname, './cert/key.pem')),
  cert: fs.readFileSync(path.resolve(__dirname, './cert/cert.pem'))
}, app).listen(3000);
 

API Reference

Classes

VoxeetSdkEventEmitter

Voxeet is the main Object for the sdk, providing methods and events to interact with voxeet servers. The SDK is asynchronous and uses promise at his core.

ConferenceErrorError

Generic error for conferences

Error names:

  • UninitializedError - The conference isn't initialized yet.
PeerErrorError

Errors on peer operations

Error names:

  • PeerNotFoundError - The peer could not be found for this operation.
  • RemoteDescriptionError - Failed to set remote description.
  • CreateAnswerError - Failed to create answer.
  • ConnectionFailedError - The peer connection failed to connect. (Only send for your own peer connection)
  • DisconnectedError - The peer connection has been disconnected. (Only send for your own peer connection)
MediaStreamErrorError

Errors happening when a stream cannot be captured from a device

Error names:

  • NotSupportedError - The operation is not supported.
  • PermissionDeniedError - The user did not grant permission for the operation.
  • ConstraintNotSatisfiedError - One of the mandatory constraints could not be satisfied.
  • NotFoundError - The object can not be found.
  • AbortError - The operatoin was aborted
  • SourceUnavailableError - The source of the MediaStream could not be accessed dure to a hardware error.
BrowserError

Browser specific errors

Error names:

  • NotSupportedError - Operation not supported on this browser
ServerError

Server return by voxeet servers

  • code : The specific error code, HTTP ones
  • reason : The error reason
  • description; the error long description

Typedefs

getUserLevelCallback : function

Callback to retreive a user's audio level

isUserSpeakingCallback : function

Callback to retreive if a user is speaking

VoxeetSdk ⇐ EventEmitter

Voxeet is the main Object for the sdk, providing methods and events to interact with voxeet servers. The SDK is asynchronous and uses promise at his core.

Kind: global class
Extends: EventEmitter

voxeetSdk.userId : String

The current user id

Kind: instance property of VoxeetSdk

voxeetSdk.userToken : String

The current user token

Kind: instance property of VoxeetSdk

voxeetSdk.initialize(consumerKey, consumerSecret, [userInfo]) ⇒ Promise.<(userdId|Error)>

Opens a session to Voxeet server (websocket included)

Kind: instance method of VoxeetSdk
Async:

Param Type Default Description
consumerKey String The consumer key
consumerSecret String The consumer Secret
[userInfo] Object {} A Json object containing custom user informations
[userInfo.name] String A Name for the user
[userInfo.externalId] String An externalId for the user
[userInfo.avatarUrl] String An avatar url for the user

Example

var voxeet = new VoxeetSdk();
voxeet.initialize('ConsumerKey', 'ConsumerSecret', {name: 'John Doe'})
  .then((myUserId) => {
    // VoxeetSdk is now initialized, you can create/join a conference
  })
  .catch((error) => {
    // An Error has occured, see Error Types
  });

voxeetSdk.initializeToken(accessToken, [userInfo], refreshTokenCb) ⇒ Promise.<(userdId|Error)>

Opens a session to Voxeet server (websocket included)

Kind: instance method of VoxeetSdk
Async:

Param Type Default Description
accessToken String An access token retreived from the customer server
[userInfo] Object {} A Json object containing custom user informations
[userInfo.name] String A Name for the user
[userInfo.externalId] String An externalId for the user
[userInfo.avatarUrl] String An avatar url for the user
refreshTokenCb function A function called to refresh the access token, must return a Promise

Example

voxeet.initializeToken("accessToken", {name: "John Doe"}, () => {
   return Promise.resolve("Refresh accessed Token");
})
.then((myUserId) => {
 
})
.catch((error) => {
 
});

voxeetSdk.enumerateAudioDevices() ⇒ Promise.<(Array.<MediaDeviceInfo>|Error)>

Enumerates all audio input devices on the computer, allowing you to further change it while in conference.

Kind: instance method of VoxeetSdk
Example

voxeet.enumerateAudioDevices()
  .then((devices) => {
     console.log(devices) // Will output [{label: "device1", ...}, {label: "device2", ...}]
  });

voxeetSdk.enumerateVideoDevices() ⇒ Promise.<(Array.<MediaDeviceInfo>|Error)>

Enumerates all video input devices on the computer, allowing you to further change it while in conference.

Kind: instance method of VoxeetSdk
Example

voxeet.enumerateVideoDevices()
  .then((devices) => {
     console.log(devices) // Will output [{label: "device1", ...}, {label: "device2", ...}]
  });

voxeetSdk.selectAudioInput(deviceId) ⇒ Promise.<Error>

Allows to select an audio device input while in conference.

Kind: instance method of VoxeetSdk

Param Type Description
deviceId String The select device id (provided with enumerateAudioDevices)

voxeetSdk.selectVideoInput(deviceId) ⇒ Promise.<Error>

Allows to select a video device input while in conference.

Kind: instance method of VoxeetSdk

Param Type Description
deviceId String The select device id (provided with enumerateVideoDevices)

voxeetSdk.createDemoConference()

Creates a conference demo.

Kind: instance method of VoxeetSdk

voxeetSdk.replayConference(conferenceId, offset) ⇒ Promise.<Error>

Replays a previously recorded conference.

Kind: instance method of VoxeetSdk

Param Type Default Description
conferenceId UUID The conference id returned when joining a conference
offset Number 0 Replays the conference from this offset in milliseconds

voxeetSdk.createConference([options]) ⇒ Promise.<(String|Error)>

Creates a conference. If conferenceAlias is empty, an id will be generated.

If the conference already exists, the current conference id is returned.

Kind: instance method of VoxeetSdk
Returns: Promise.<(String|Error)> - The corresponding conference id

Param Type Default Description
[options] object {} Information of the conference to be created
[options.alias] string "&quot;&quot;" An alias for the conference or empty
[options.params] object {} Parameters for this conference
[options.params.ttl] boolean 0 The conference time to live in seconds, default to 0
[options.params.rtcpMode] string "&quot;worst&quot;" The conference RTC Mode (best/worst) for quality control
[options.params.mode] string "&quot;standard&quot;" The conference mode (push/standard)

voxeetSdk.joinConference(conferenceId, [options]) ⇒ Promise.<(ConferenceInfo|Error)>

Joins a conference. If the conference doesn't exist, it will be created

Note that if you used createConference beforehand, the conference options in the following object are ignored.

Kind: instance method of VoxeetSdk

Param Type Default Description
conferenceId string The conference id or alias to be joined
[options] object {} Options for the conference
[options.constraints] object {audio: true, video: true} WebRTC constraints
[options.audio3D] boolean true Activate/Deactivate 3D audio
[options.user] object {} User options
[options.user.name] string The user name
[options.user.type] string "&quot;user&quot;" The user type
[options.conference] object {} The conference options
[options.conference.params] object {} Parameters for this conference
[options.conference.params.ttl] boolean 0 The conference time to live in seconds, default to 0
[options.conference.params.rtcpMode] string "&quot;worst&quot;" The conference RTC Mode (best/worst) for quality control
[options.conference.params.mode] string "&quot;standard&quot;" The conference mode (push/standard)

Example

// For example
var constraints = {
  audio: {
    mandatory: {
      sourceId: "audioDeviceId" // If you want to specifie an audio deviceId
    }
  },
  video: {
    mandatory: {
      minWidth: 160,
      minHeight: 120,
      maxWidth: 320,
      maxHeight: 240,
      minFrameRate: 10,
      maxFrameRate: 30
      sourceId: "videoDeviceId" // If you want to specifie an video deviceId
    }
  }
};
 
A simplest example of constraints would be: 
 
var constraints = {audio: true, video: true};
 
voxeet.joinConference(conferenceId, {constraints: constraints})
  .then((info) => {
 
  })
  .catch((error) => {
 
  });

voxeetSdk.leaveConference() ⇒ Promise.<Error>

Leaves the currently running conference

Kind: instance method of VoxeetSdk

voxeetSdk.conferenceStatus(conferenceId)

Deprecated

Returns the status of a conference.

Kind: instance method of VoxeetSdk

Param Type Description
conferenceId String The conference id or alias

voxeetSdk.subscribeConferenceStatus(conferenceId) ⇒ Promise.<Error>

Subscribe to receive updates on the conference status.

Kind: instance method of VoxeetSdk

Param Type Description
conferenceId String The conference id or alias

voxeetSdk.unsubscribeConferenceStatus(conferenceId) ⇒ Promise.<Error>

Unsubscribe to the conference status event.

Kind: instance method of VoxeetSdk

Param Type Description
conferenceId String The conference id or alias

voxeetSdk.sendConferenceMessage(message) ⇒ Promise.<Error>

Allows you to broadcast raw messages of any type (Json, Xml, simple string) to all participants of a conference

Kind: instance method of VoxeetSdk

Param Type Description
message String The message to be send as a raw string (can be json, xml, ...)

voxeetSdk.setUserPosition(userId, x, y)

Sets the user position

Kind: instance method of VoxeetSdk

Param Type Description
userId String The user to be moved
x Float The user's x position, between -1.0 and 1.0
y Float The user's y position, between 0.0 and 1.0

voxeetSdk.muteUser(userId, isMuted)

Allows to mute a user

Kind: instance method of VoxeetSdk

Param Type Description
userId String The user's id to be muted
isMuted boolean Mute On/Off

voxeetSdk.toggleMute(userId) ⇒ Boolean

Allows to toggle mute on a user

Kind: instance method of VoxeetSdk
Returns: Boolean - State of the user

Param Type Description
userId String The user's id to be muted

voxeetSdk.getUserLevel(userId, callback)

Allows to get the user's current audio level normalized between 0.0 and 1.0

Kind: instance method of VoxeetSdk

Param Type Description
userId userId The user's id of the level to be retreived
callback getUserLevelCallback The callback to retreive the audio level

voxeetSdk.isUserSpeaking(userId, callback)

Allows to get the user's current speech status

Kind: instance method of VoxeetSdk

Param Type Description
userId userId The user's id of the status to be retreived
callback isUserSpeakingCallback The callback to retreive the status

voxeetSdk.startVideoForUser(userId) ⇒ Promise.<Error>

Starts the video stream for a user

Kind: instance method of VoxeetSdk

Param Type
userId userId

voxeetSdk.stopVideoForUser(userId) ⇒ Promise.<Error>

Stops the video stream for a user

Kind: instance method of VoxeetSdk

Param Type
userId userId

voxeetSdk.startAudioForUser(userId) ⇒ Promise.<Error>

Starts the audio stream for a user

Kind: instance method of VoxeetSdk

Param Type
userId userId

voxeetSdk.stopAudioForUser(userId) ⇒ Promise.<Error>

Stops the audio stream for a user

Kind: instance method of VoxeetSdk

Param Type
userId userId

voxeetSdk.startScreenShare(options) ⇒ Promise.<Error>

Starts a screen sharing session

Kind: instance method of VoxeetSdk
Returns: Promise.<Error> - VoxeetSdk.ScreenShareOptions is an enum containing different possibilities for those options :

  • VoxeetSdk.ScreenShareOptions.SCREEN
  • VoxeetSdk.ScreenShareOptions.WINDOW_AND_TAB
  • VoxeetSdk.ScreenShareOptions.ALL

You can also use a simple array with string value, like: ['screen', 'tab']

Note that on Firefox, the array can't contain more than one value.

Param Type Default Description
options Array ['screen' An optional array to choose what type of capture options will presented to the user.

Example

voxeet.startScreenShare(['screen'])
  .then(() => {
 
  })
  .catch(e => {
 
  });

voxeetSdk.startRecording() ⇒ Promise.<Error>

Starts the current conference recording

Kind: instance method of VoxeetSdk

voxeetSdk.stopRecording() ⇒ Promise.<Error>

Stops the current recording

Kind: instance method of VoxeetSdk

voxeetSdk.stopScreenShare() ⇒ Promise.<Error>

Stops the screen sharing session

Kind: instance method of VoxeetSdk

voxeetSdk.setMode(mode) ⇒ Promise.<Error>

Sets the mode of the conference:

mode can be:

  • STANDARD
  • PUSH

Kind: instance method of VoxeetSdk

Param Type Description
mode String The mode to be set

voxeetSdk.reserve(conferenceId) ⇒ Promise.<Error>

Reserves a slot in the corresponding conference

Kind: instance method of VoxeetSdk

Param Type Description
conferenceId String The conference id or alias

"conferenceJoined"

Emitted when the conference has been successfully joined

Kind: event emitted by VoxeetSdk

"conferenceLeft"

Emitted when the conference has been successfully left

Kind: event emitted by VoxeetSdk

"conferenceEnded"

Emitted when the replayed conference has ended

Kind: event emitted by VoxeetSdk

"conferenceStatusUpdated" (conferenceInfo)

Emitted when a conference status is received

Kind: event emitted by VoxeetSdk

Param Type Description
conferenceInfo Object A Json object containing conference informations
[conferenceInfo.conferenceAlias] String The conference alias
[conferenceInfo.conferenceId] String The conference id
[conferenceInfo.isLive] boolean The conference status

"participantAdded" (userId, userInfo)

Emitted when a participant (user) has been added to the conference

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id
userInfo Object A Json object containing custom user informations
[userInfo.name] String A Name for the user
[userInfo.externalId] String An externalId for the user
[userInfo.avatarUrl] String An avatar url for the user

"participantStatusUpdated" (userId, status)

Emitted when the status of a participant has changed

Status can be one if those values:

  • RESERVED
  • CONNECTING
  • CONNECTED
  • INACTIVE
  • LEFT

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id
status String The corresponding status

"participantJoined" (userId, stream)

Emitted when the participant has joined the conference

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id
stream MediaStream The webrtc stream correponding to this participant

"participantUpdated" (userId, stream)

Emitted when a participant (user) stream has been updated

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id
stream MediaStream The webrtc stream correponding to this participant

"participantLeft" (userId)

Emitted when a participant has left the conference

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id

"messageReceived" (data)

Emitted when a broadcast message is received

Kind: event emitted by VoxeetSdk

Param Type Description
data String the received message

"screenShareStarted" (userId, stream)

Emitted when a screen share has been started

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id that started the screensharing
stream MediaStream The screenshare stream

"screenShareUpdated" (userId, stream)

Emitted when the stream of the screen share has changed

Kind: event emitted by VoxeetSdk

Param Type Description
userId String The user's id that started the screensharing
stream MediaStream The new screenshare stream

"screenShareStopped"

Emitted when a screen share has been stopped

Kind: event emitted by VoxeetSdk

"speakerChanged"

Emitted when the user that is speaking has changed.

Kind: event emitted by VoxeetSdk

"renegociationEnded"

Emitted when all peers (local and remote ones) have been successfully renegociated

Kind: event emitted by VoxeetSdk

"error"

Emitted when an error occured during a conference

Kind: event emitted by VoxeetSdk

VoxeetSdk.ScreenShareOptions : enum

Enum for screen sharing options

Kind: static enum of VoxeetSdk
Read only: true

ConferenceError ⇐ Error

Generic error for conferences

Error names:

  • UninitializedError - The conference isn't initialized yet.

Kind: global class
Extends: Error

PeerError ⇐ Error

Errors on peer operations

Error names:

  • PeerNotFoundError - The peer could not be found for this operation.
  • RemoteDescriptionError - Failed to set remote description.
  • CreateAnswerError - Failed to create answer.
  • ConnectionFailedError - The peer connection failed to connect. (Only send for your own peer connection)
  • DisconnectedError - The peer connection has been disconnected. (Only send for your own peer connection)

Kind: global class
Extends: Error

MediaStreamError ⇐ Error

Errors happening when a stream cannot be captured from a device

Error names:

  • NotSupportedError - The operation is not supported.
  • PermissionDeniedError - The user did not grant permission for the operation.
  • ConstraintNotSatisfiedError - One of the mandatory constraints could not be satisfied.
  • NotFoundError - The object can not be found.
  • AbortError - The operatoin was aborted
  • SourceUnavailableError - The source of the MediaStream could not be accessed dure to a hardware error.

Kind: global class
Extends: Error

BrowserError

Browser specific errors

Error names:

  • NotSupportedError - Operation not supported on this browser

Kind: global class

ServerError

Server return by voxeet servers

  • code : The specific error code, HTTP ones
  • reason : The error reason
  • description; the error long description

Kind: global class

getUserLevelCallback : function

Callback to retreive a user's audio level

Kind: global typedef

Param Type Description
level float the user's current audio level normalized between 0.0 and 1.0

isUserSpeakingCallback : function

Callback to retreive if a user is speaking

Kind: global typedef

Param Type Description
isSpeaking Boolean The state of the user

Sample Application

A sample application is available on this public repository on GitHub.

© Voxeet, 2016