Client SDK

Documentation for Web & Safari WebRTC SDK | Voxeet

Initialize the Voxeet SDK

Two methods are currently available to initialize the SDK:

  • Set the API keys in the app
  • Use an OAuth2 server to provide the keys

initialize

Initialize the SDK with your Voxeet user information.

Parameters

  • consumerKey string - The consumer key for your app from your developer account dashboard.
  • consumerSecret string - The consumer secret for your app from your developer account dashboard.

  • userInfo object - A JSON object that contains custom user information (default {}).

    • userInfo.name string - The user name.
    • userInfo.externalId string - An external ID for the user. The userInfo.externalId allows you to keep the same user information across different connections.
    • userInfo.avatarUrl string - An avatar URL for the user.

Returns

Promise<userId: String | Error> - The user ID of the current 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
  });

initializeToken

Initialize the SDK with a token retreived from your backend. You must provide a callback for refreshing this token.

Parameters

  • accessToken string - An access token retreived from your server.

  • userInfo object - A JSON object that contains custom user information (default {}).

    • userInfo.name string - The user name.
    • userInfo.externalId string - An external ID for the user. The userInfo.externalId allows you to keep the same user information across different connections.
    • userInfo.avatarUrl string - An avatar URL for the user.
  • refreshTokenCb function - A function called to refresh the access token. Must return a Promise.

Returns

Promise<userId: String | Error> - The user ID of the current user.

Example

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

})
.catch((error) => {

});

Conferences

See also: Conference Events.

createConference

Create a conference. If conferenceAlias is empty, a conference ID is generated. If the conference already exists, the current conference ID is returned.

This method is optional. if you use joinConference with an alias, createConference is called implicitly.

Parameters

  • options object - Information about the conference to be created (default {}).

    • options.alias string - An alias for the conference. or empty (default "").

    • options.params object - Parameters for the conference (default {}).

      • options.params.ttl integer - The conference time-to-live, in seconds (default 0).
      • options.params.rtcpMode string - The conference real-time communication (RTC) mode for quality control. Valid values are best and worst (default worst).
      • options.params.mode string - The conference mode. Valid values are push and standard (default standard).
      • options.params.videoCodec string - The conference video codec (VP8/H264) (default "VP8").
      • options.params.liveRecording boolean - Allows to mix the conference in realtime when calling startRecording (default false)

Returns

Promise<conferenceId: String | Error> - The corresponding conference ID.

joinConference

Join a conference. If the conference doesn't exist, it is created.

If you previously used createConference, the conference parameters in the joinConference object are ignored.

Parameters

  • conferenceId string - The ID or alias of the conference to join.

  • options object - Options for the conference (default {}).

    • options.constraints object - WebRTC audio and video contraints.
    • options.audio3D Boolean - Activate (true) or deactivate (false) 3D audio (default true).

    • options.user object - User options (default {}).

      • options.user.name string - The user name.
      • options.user.type string - The user type. Valid values are user or listener (default user).

    • options.conference object - The conference options (default {}).

      • options.conference.params object - Parameters for the conference (default {}).

        • options.conference.params.ttl integer - The conference time-to-live, in seconds (default 0).
        • options.conference.params.rtcpMode string - The conference real-time communication (RTC) mode for quality control. Valid values are best and worst (default worst).
        • options.conference.params.mode string - The conference mode. Valid values are push and standard (default standard).
        • options.conference.params.videoCodec string - The conference video codec (VP8/H264) (default VP8).
        • options.conference.params.liveRecording boolean - Allows you to mix the conference in real time when calling startRecording (default false)

Returns

Promise<conferenceId: String | Error> - The corresponding conference ID.

Example

// For example
var constraints = {
  audio: {
    mandatory: {
      sourceId: "audioDeviceId" // Use if you want to specify an audio device ID
    }
  },
  video: {
    mandatory: {
      minWidth: 160,
      minHeight: 120,
      maxWidth: 320,
      maxHeight: 240,
      minFrameRate: 10,
      maxFrameRate: 30
      sourceId: "videoDeviceId" // Use if you want to specify an video device ID
    }
  }
};

// Constraints example:

var constraints = {audio: true, video: true};

voxeet.joinConference(conferenceId, {constraints: constraints})
  .then((info) => {

  })
  .catch((error) => {

  });

leaveConference

Leave the currently running conference.

Parameters

  • leaveRoom Boolean - true if you want to close the call without leaving the conference (default). Otherwise, false.

Returns

Promise<Error>

Example

voxeet.leaveConference()
  .catch((error) => {

  });

listenConference

Listen to a conference without sharing your audio or video.

Parameters

  • conferenceId string - The ID or alias of the conference to listen to.

  • options object - Options for the conference (default {}).

    • options.user object - User options (default {}).

      • options.user.name string - The user name.
      • options.user.type string - Valid values are user or listener (default user).

Returns

Promise<conferenceId: String | Error> - The corresponding conference ID.

subscribeConferenceStatus

Subscribe to conference status events.

Parameters

  • conferenceId string - The ID of the conference whose status events you want to subscribe to.

Returns

Promise<Error>

Example

voxeet.on('conferenceStatusUpdated', (info) => {
  ...
});

voxeet.subscribeConferenceStatus("conferenceId")
  .then(() => { ... })
  .catch((e) => { ... });

unsubscribeConferenceStatus

Unsubscribe from conference status events.

Parameters

  • conferenceId string - The ID of the conference whose status events you want to unsubscribe from.

Returns

Promise<Error>

setMode

Set the mode of the conference to push (push to talk) or standard.

Parameters

  • mode string - The new mode of the conference (push/standard).

Returns

Promise<Error>

reserve

Reserve a slot in the specified conference.

Parameters

  • conferenceId string - The ID of the conference where you want to reserve a slot.

Returns

Promise<Error>

stats

Retrieve the stats for a specific conference.

Parameters

  • conferenceId string - The ID of the conference whose stats you want to retrieve.

Returns

Promise<stats: Object | Error>

Replay conferences

replayConference

Replay a recorded conference.

Parameters

  • conferenceId string - The ID of the conference you want to replay.
  • offset integer - The recording offset from the beginning of the conference, in milliseconds (default 0).

Returns

Promise<Error>

Record conferences

startRecording

Record a conference so you can replay it after it ends.

Returns

Promise<Error>

Example

voxeet.startRecording()
  .then(() => {...})
  .catch((e) => {...});

stopRecording

Stop the current recording.

Returns

Promise<Error>

Audio and video devices

enumerateAudioDevices

Enumerate all audio input devices on your computer so you can change the audio device you're using during conferences.

Returns

Promise<[MediaDeviceInfo>] | Error> - A list of audio devices.

Example

voxeet.enumerateAudioDevices()
  .then((devices) => {
    ...
  })
  .catch((e) => {...});

s

enumerateVideoDevices

Enumerate all video input devices on your computer so you can change the video device you're using during conferences.

Returns

Promise<[MediaDeviceInfo>] | Error> - A list of video devices.

Example

voxeet.enumerateVideoDevices()
  .then((devices) => {
    ...
  })
  .catch((e) => {...});

selectAudioInput

Select an audio device input while in the conference.

Parameters

  • deviceId string - The ID for the selected device (provided with enumerateAudioDevices).
  • constraints object - WebRTC audio constraints.

Returns

Promise<Error>

selectVideoInput

Select a video device input while in the conference.

Parameters

  • deviceId string - The ID for the selected device (provided with enumerateVideoDevices).
  • constraints object - WebRTC video constraints.

Returns

Promise<Error>

Example

const video = {
    mandatory: {
      minWidth: 160,
      minHeight: 120,
      maxWidth: 320,
      maxHeight: 240,
      minFrameRate: 10,
      maxFrameRate: 30,
   }
};

voxeet.selectVideoInput(deviceId, constraints)
 .then(() => {...})
 .catch((e) => {...});

startAudioForUser

Start the audio for a specific user.

Parameters

  • userId string - ID of the user whose audio you want to start.

Returns

Promise<Error>

stopAudioForUser

Stop the audio for a specific user.

Parameters

  • userId string - ID of the user whose audio you want to stop.

Returns

Promise<Error>

startVideoForUser

Start the video for a specific user.

Parameters

  • userId string - ID of the user whose video you want to start.
  • constraints object WebRTC video contraints.

Returns

Promise<Error>

Example

const video = {
    mandatory: {
      minWidth: 160,
      minHeight: 120,
      maxWidth: 320,
      maxHeight: 240,
      minFrameRate: 10,
      maxFrameRate: 30,
   }
};

voxeet.startVideoForUser(userId, constraints)
 .then(() => {

 });

stopVideoForUser

Stop the video for a specific user.

Parameters

  • userId string - ID of the user whose video you want to stop.

Returns

Promise<Error>

Manage users

invite

Invite users to a conference. Users will receive an invitationReceived event.

Parameters

  • conferenceId string - The ID or alias of the conference you want to invite users to.
  • externalIds array of string - An array of external IDs for users to invite.

Returns

Promise<Error>

setUserPosition

Set user position for the spatialized audio mode.

Parameters

  • userId string - The ID for the user whose position you want to set.
  • x float - The user's X position. Must be a value between -1.0 and 1.0.
  • y float - The user's Y position. Must be a value between 0.0 and 1.0.

muteUser

Mute or unmute the specified user.

Parameters

  • userId string - The ID of the user you want to mute.
  • isMuted Boolean - true if user is muted. Otherwise, false.

Returns

Promise<isMuted: Boolean | Error> - The mute or unmute status of the user.

toggleMute

Toggle mute for the specified user.

Parameters

  • userId string - The ID of the user you want to mute or unmute.

Returns

Promise<isMuted: Boolean | Error> - The mute or unmute status of the user.

getUserLevel

Retrieve the specified user's current audio level, normalized between 0.0 and 1.0.

Parameters

  • userId string - The ID of the user whose level you want to retreive.
  • callback function - The callback to retreive the audio level.

Example

voxeet.getUserLevel(userId, (level) => {
  ...
});

isUserSpeaking

Retrieve the specified user's current speaking status.

Parameters

  • userId string - The ID of the user whose speaking status you want to retrieve.
  • callback function - The callback to retreive the status.

Example

voxeet.isUserSpeaking(userId, (isSpeaking) => {
  ...
});

Broadcast messages

sendConferenceMessage

Broadcast messages as raw strings of any type (including JSON, XML, simple string) to all conference participants.

Parameters

  • message string - The message to broadcast as a raw string.

Returns

Promise<Error>

Screen-sharing

startScreenShare

Start a screen-sharing session.

VoxeetSdk.ScreenShareOptions is an enum that contains different possibilities for these options:

  • VoxeetSdk.ScreenShareOptions.SCREEN
  • VoxeetSdk.ScreenShareOptions.WINDOWANDTAB
  • VoxeetSdk.ScreenShareOptions.ALLY

You can also use a simple array with string values, like: ['screen', 'tab']. For Firefox, the array cannot contain more than one value.

Parameters

  • options array - An optional array for choosing the capture options that are available to the user (default VoxeetSdk.ScreenShareOptions.SCREEN = ['screen']).

Returns

Promise<Error>

Example

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

stopScreenShare

Stop the current screen-sharing session.

Returns

Promise<Error>

File Presentation

convertFile

Convert files users select through an input file box. Fires a fileConverted event when the converted file is ready.

Parameters

  • file object - The file to convert.

Returns

Promise<Error>

Example

voxeet.on('fileConverted', (file) => {

});

voxeet.convertFile(...)
  .then(() => {...})
  .catch((error) => {...};

startFilePresentation

Start a file presentation.

Parameters

  • file object - The JSON object received from the fileConverted event that contains the fileId.

    • file.fileId string - The ID of the converted file.
    • file.fileName - string - The file name of the converted file.
    • file.imageCount - string The number of images in the converted file.

Returns

Promise<Error>

Example

voxeet.startFilePresentation({fileId: 'fileId'})
      .catch((error) => {...});

updateFilePresentation

Update the current file presentation page.

Parameters

  • fileId string - The ID of the file that corresponds to the presentation page.
  • position integer - The page to present.

Returns

Promise<Error>

stopFilePresentation

Stop the current file presentation.

Parameters

  • fileId string - The ID of the file you want to stop presenting.

Returns

Promise<Error>

getThumbnail

Retrieve a thumbnail for a file page.

Parameters

  • fileId string - The ID for the corresponding file.
  • page integer - The file page number you want to retrieve.

Returns

Promise<url: String | Error> - The URL of the thumbnail.

getImage

Retrive an image for a file page.

Parameters

  • fileId string - The ID for the corresponding file.
  • page Integer - The file page number you want to retrieve.

Returns

Promise<url: String | Error> - The URL of the image.

Video Presentation

start

Start a video presentation.

Parameters

  • url string - The URL of the video to present.

Returns

Promise<Error>

Example

voxeet.videoPresentation.start("url")
      .catch(e => {...});

voxeet.videoPresentation.on('started', (event) => {

});

stop

Stop the video presentation.

Returns

Promise<Error>

Example

voxeet.videoPresentation.stop()
      .catch(e => {...});

voxeet.videoPresentation.on('stopped', () => {

});

play

Play the video.

Returns

Promise<Error>

Example

voxeet.videoPresentation.play()
      .catch(e => {...});

voxeet.videoPresentation.on('play', (event) => {

});

pause

Pause the video.

Parameters

  • timestamp integer - The timestamp where the video is paused. In milliseconds.

Returns

Promise<Error>

Example

voxeet.videoPresentation.pause(10000)
      .catch(e => {...});

voxeet.videoPresentation.on('pause', (event) => {
  //event.timestamp
});

seek

Find a timestamped point in the video.

Parameters

  • timestamp integer - The timestamp to find in the video.

Returns

Promise<Error>

Example

voxeet.videoPresentation.seek(10000)
      .catch(e => {...});

voxeet.videoPresentation.on('seek', (event) => {
  //event.timestamp
});

Events

Conference events

conferenceJoined

Emitted when you successfully join a conference.

conferenceLeft

Emitted when you successfully leave a conference.

conferenceEnded

Emitted when you end a conference you are replaying.

conferenceStatusUpdated

Emitted when you receive a conference status.

Parameters

  • conferenceInfo object - A JSON object that contains conference information.

    • conferenceInfo.conferenceAlias string - The alias of the conference.
    • conferenceInfo.conferenceId string - The ID of the conference.
    • conferenceInfo.isLive Boolean - true if the conference is live. Otherwise, false.

qualityIndicators

Emitted when a new conference quality indicator is available.

Parameters
  • indicators object - Conference quality indicators.
  • mos integer - The mean opinion score, a value from 1 to 5 that indicates the average conference quality.

messageReceived

Emitted when you receive a broadcast message.

Parameters

  • data string - The received message as a raw string.

Participant events

participantAdded

Emitted when a participant (user) is added to the conference.

Parameters
  • userId string - The ID of the user who is added.

  • userInfo object - A JSON object that contains custom user information.

    • userInfo.name string - The user's name.
    • userInfo.externalId string - The external ID for the user.
    • userInfo.avatarUrl string - An avatar URL for the user.

participantJoined

Emitted when a participant (user) joins the conference.

Parameters
  • userId string - The ID of the user who joins.
  • stream MediaStream - The WebRTC stream that correponds to the user who joins.

participantUpdated

Emitted when a participant (user) stream is updated.

Parameters
  • userId string - The ID of the user whose stream is updated.
  • stream MediaStream - The WebRTC stream that correponds to the user whose stream is updated.

participantLeft

Emitted when a participant (user) leaves the conference.

Parameters
  • userId string - The ID of the user who leaves.

participantStatusUpdated

Emitted when a particpant's (user's) status changes.

Status can be one of these values:

  • reserved
  • decline
  • connecting
  • connected
  • inactive
  • left
  • warning
  • error
Parameters
  • userId string - The ID of the user whose status changes.
  • status string - The user's status.

invitationReceived

Emitted when you receive an invitation.

Parameters
  • invitations object - Information about the conference invitation.

Screen-sharing

screenShareStarted

Emitted when a participant (user) starts sharing their screen in the conference.

Parameters
  • userId string - The ID of the user who starts sharing their screen.
  • stream MediaStream - The screenshare stream.

screenShareUpdated

Emitted when the screenshare stream changes.

Parameters
  • userId string - The ID of the user who started sharing their screen.
  • stream MediaStream - The new screenshare stream.

screenShareStopped

Emitted when a participant (user) stops sharing their screen in the conference.

File Presentation

fileConverted

Emitted when a file is converted.

Parameters

  • file object - A JSON object that describes the converted file.

    • file.fileId string - The ID of the converted file.
    • file.imageCount string - The number of images in the converted file.

filePresentationStarted

Emitted when a user starts a file presentation.

Parameters

  • file object - A JSON object that contains file presentation information.

    • file.conferenceId string - The ID of the conference in which the file is presented.
    • file.fileId string - The ID of the file that is presented.
    • file.userId string - The ID of the user who starts the file presentation.
    • file.position string - The current page of the presentation.
    • file.imageCount string - The number of images in the presentation.

filePresentationUpdated

Emitted when a user updates the file presentation (i.e., changes the page).

Parameters

  • file object - A JSON object that contains file presentation information.

    • file.conferenceId string - The ID of the conference in which the file is presented.
    • file.fileId string - The ID of the file that is presented.
    • file.userId string - The ID of the user who starts the file presentation.
    • file.position string - The current page of the presentation.

filePresentationStopped

Emitted when a user stops the file presentation.

Video Presentation

started: VideoPresentationStart

Parameters

  • event object - An event object that contains video presentation information.

    • event.conferenceId string - The corresponding conferenceId.
    • event.userId string - The user that launched the presentation.
    • event.url string - The URL of the video to present.
    • event.timestamp string - The current position in the video.

stopped: VideoPresentationStop

Parameters

  • event object - An event object that contains video presentation information.

    • event.conferenceId string - The corresponding conferenceId.
    • event.userId string - The user who launched the presentation.

play: VideoPresentationPlay

Parameters

  • event object - An event object that contains video presentation information.

    • event.conferenceId string - The corresponding conferenceId.
    • event.userId string - The user who launched the presentation.
    • event.timestamp string - The current position in the video.

pause: VideoPresentationPause

Parameters

  • event object - An event object that contains video presentation information.

    • event.conferenceId string - The corresponding conferenceId.
    • event.userId string - The user who launched the presentation.

seek: VideoPresentationSeek

Parameters

  • event object - An event object that contains video presentation information.

    • event.conferenceId string - The corresponding conferenceId.
    • event.userId string - The user who launched the presentation.
    • event.timestamp string - The current position in the video.

Error

error

Emitted when an error occurs during a conference.

Errors

ConferenceError

Generic conference errors.

Error names

  • UninitializedError The conference isn't initialized yet.

MediaStreamError

Errors that occur when a device cannot capture a stream.

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 cannot be found.
  • AbortError The operation was aborted.
  • SourceUnavailableError The source of the MediaStream could not be accessed due to a hardware error.

PeerError

Peer operations errors.

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. Sent only for your own peer connection.
  • DisconnectedError The peer connection has been disconnected. Sent only for your own peer connection.

BrowserError

Browser-specific errors.

Error names

  • NotSupportedError The operation is not supported on this browser.

ServerError

Errors returned by Voxeet servers.

ServerError messages include:

  • code: The HTTP status code for the error.
  • reason: The reason for the error.
  • description: A long description of the error.