ConferenceService

The ConferenceService allows the application to manage the conference life-cycle and interact with the conference.

The ConferenceService introduces APIs that allow the application to:

The ConferenceService introduces events that inform the application that:

  • The participant has joined a conference or has left it
  • A connected participant joins a conference using another device and the same ExternalId
  • A conference participant has joined a conference or changed status
  • A stream is added, updated, or removed
  • The replayed conference has ended
  • An error has occurred

Additionally, every 5 seconds the application emits the qualityIndicators event informing about the audio and video quality of the remote participants.

If a browser blocks the received audio streams due to auto-play policy, the application can call the autoplayBlocked and playBlockedAudio APIs to enable playing the received audio.


Events

autoplayBlocked

autoplayBlocked(): void

Emitted when conference participant's audio streams are blocked by a browser's auto-play policy that requires access to the participant's camera. When this event occurs, the application requests permission to play the incoming audio stream. After a user interaction (click or touch), the application calls the playBlockedAudio method to play the audio stream.

example

VoxeetSDK.conference.on("autoplayBlocked", () => {
  button = document.getElementById("unmute_audio");
  button.onclick = () => {
    VoxeetSDK.conference.playBlockedAudio();
  };
});

Returns: void


ended

ended(): void

Emitted when the replayed conference has ended.

example

VoxeetSDK.conference.on("ended", () => {});

Returns: void


error

error(error: Error): void

Emitted when an error has occurred.

example

VoxeetSDK.conference.on("error", (error) => {});

Parameters:

NameType
errorError

Returns: void


joined

joined(): void

Emitted when the application has successfully joined the conference.

example

VoxeetSDK.conference.on("joined", () => {});

Returns: void


left

left(): void

Emitted when the application has left the conference.

example

VoxeetSDK.conference.on("left", () => {});

Returns: void


participantAdded

participantAdded(participant: Participant): void

Emitted when a participant is added to the conference. The SDK does not emit the participantAdded event for a local participant.

example

VoxeetSDK.conference.on("participantAdded", (user) => {});

Parameters:

NameType
participantParticipant

Returns: void


participantUpdated

participantUpdated(participant: Participant): void

Emitted when a participant changes ParticipantStatus. The following graphic shows possible status changes during a conference:

Statuses

example

VoxeetSDK.conference.on("participantUpdated", (participant) => {});

Parameters:

NameType
participantParticipant

Returns: void


qualityIndicators

qualityIndicators(indicators: Map‹string, QualityIndicator›): void

The Mean Opinion Score (MOS) which represents the participants' audio and video quality. The SDK calculates the audio and video quality scores and displays the values in a rage from 1 to 5, where 1 represents the worst quality and 5 represents the highest quality. In cases when the MOS score is not available, the SDK returns the value -1.

Note: With SDK 3.0, audio Mean Opinion Scores (MOS) are unavailable for web clients connected to Dolby Voice conferences.

Parameters:

NameTypeDescription
indicatorsMap‹string, QualityIndicatorA map of quality indicators per participantId

Returns: void


streamAdded

streamAdded(participant: Participant, stream: MediaStreamWithType): void

Emitted in the following situations:

  • A conference participant with disabled audio and video enables audio or video.
  • A conference participant starts sharing a screen.

Each conference participant can be connected to two streams: audio and video stream and screen-share stream. If a participant enables audio or video, the SDK adds the audio and video stream to the participant. However, if a participant connected to the audio and video stream changes the stream, for example, a user with enabled audio also enables a video, the SDK updates the audio and video stream. The following graphic shows this behavior: Audio streams map

When a participant joins a conference with enabled audio and video, the SDK emits the streamAdded and streamUpdated events.

Note: In Dolby Voice conferences, each conference participant receives only one mixed audio stream from the server. To keep backward compatibility with the customers' implementation, SDK 3.0 introduces a faked audio track for audio transmission. The faked audio track is included in the streamAdded and streamRemoved events. The SDK 3.0 takes the audio stream information from the participantAdded and participantUpdated events.

example

VoxeetSDK.conference.on("streamAdded", (participant, stream) => {
  node = document.getElementById("received_video");
  navigator.attachMediaStream(node, stream);
});

Parameters:

NameType
participantParticipant
streamMediaStreamWithType

Returns: void


streamRemoved

streamRemoved(participant: Participant, stream: MediaStreamWithType): void

Emitted when a participant removes audio and video stream or screen-share stream by disabling audio and video or by stopping a screen-share presentation.

Note: In Dolby Voice conferences, each conference participant receives only one mixed audio stream from the server. To keep backward compatibility with the customers' implementation, SDK 3.0 introduces a faked audio track for audio transmission. The faked audio track is included in the streamAdded and streamRemoved events. The SDK 3.0 takes the audio stream information from the participantAdded and participantUpdated events.

example

VoxeetSDK.conference.on("streamRemoved", (participant, stream) => {});

Parameters:

NameType
participantParticipant
streamMediaStreamWithType

Returns: void


streamUpdated

streamUpdated(participant: Participant, stream: MediaStreamWithType): void

Emitted when a conference participant updates the audio and video stream.

Each conference participant can be connected to two streams: audio and video stream and screen-share stream. If a participant enables audio or video, the SDK adds the audio and video stream to the participant. However, if a participant connected to the audio and video stream changes the stream, for example, a user with enabled audio also enables a video, the SDK updates the audio and video stream. The following graphic shows this behavior:

Audio streams map

Based on the stream type, the application chooses to either render a camera view or a screen-share view.

example

VoxeetSDK.conference.on("streamUpdated", (participant, stream) => {
  node = document.getElementById("received_video");
  navigator.attachMediaStream(node, stream);
});

Parameters:

NameType
participantParticipant
streamMediaStreamWithType

Returns: void


switched

switched(): void

Emitted when a new participant joins a conference using the same external ID as another participant who has joined this conference earlier. This event may occur when a participant joins the same conference using another browser or device. In such a situation, the SDK removes the participant who has joined the conference earlier.

Returns: void

Accessors

current

get current(): Conference | null

Returns the current conference.

Returns: Conference | null


participants

get participants(): Map‹string, Participant

Provides a list of conference participants.

Returns: Map‹string, Participant

Methods

audioLevel

audioLevel(participant: Participant, callback: Function): any

Gets the participant's audio level. The possible values of the audio level are in range from 0.0 to 1.0 point.

Note: This API is no longer supported for remote participants when the client connects to a Dolby Voice conference.

Parameters:

NameTypeDescription
participantParticipant-
callbackFunctionThe callback to retrieve the audio level

Returns: any


audioProcessing

audioProcessing(participant: Participant, options: AudioProcessingOptions): Promise‹void›

Enables and disables audio processing for the local participant.

Parameters:

NameType
participantParticipant
optionsAudioProcessingOptions

Returns: Promise‹void›


create

create(options: ConferenceOptions): Promise‹Conference

Creates a conference with ConferenceOptions.

Parameters:

NameType
optionsConferenceOptions

Returns: Promise‹Conference


demo

demo(): Promise‹Conference‹››

Creates and joins a demo conference.

Returns: Promise‹Conference‹››


fetch

fetch(conferenceId: string): Promise‹Conference

Provides a Conference object that allows joining a conference.

Parameters:

NameType
conferenceIdstring

Returns: Promise‹Conference


invite

invite(conference: Conference, participants: Array‹ParticipantInfo›): Promise‹any›

Sends the notifications to the conference participants to inform them about the invitation to the conference. The use of externalId from the ParticipantInfo model is mandatory.

Note: Use the invite method only after joining a conference.

VoxeetSDK.conference.invite((conference: Conference), (externalId: externalId));

Parameters:

NameTypeDescription
conferenceConference-
participantsArray‹ParticipantInfo

Returns: Promise‹any›


isMuted

isMuted(): Boolean

Gets the current mute state of the local participant.

Note: This API is no longer supported for remote participants.

Returns: Boolean


isSpeaking

isSpeaking(participant: Participant, callback: Function): any

Gets the participant's current speaking status for an active talker indicator.

Parameters:

NameTypeDescription
participantParticipant-
callbackFunctionThe callback to retrieve the status

Returns: any


join

join(conference: Conference, options: JoinOptions): Promise‹Conference

Joins the conference.

Note: Participants who use Apple Mac OS and the Safari browser to join conferences may experience problems with distorted audio. To solve the problem, we recommend using the latest version of Safari.

Note: Due to a known Firefox issue, a user who has never permitted Firefox to use a microphone and camera cannot join a conference as a listener. If you want to join a conference as a listener using the Firefox browser, make sure that Firefox has permission to use your camera and microphone. To check the permissions, follow these steps:

1. Select the lock icon in the address bar.
2. Select the right arrow placed next to Connection Secure.
3. Select More information.
4. Go to the Permissions tab.
5. Look for the Use the camera and Use the microphone permission and select the Allow option.

See also: listen, replay

example

// For example
const constraints = {
  audio: true,
  video: {
    width: {
      min: "320",
      max: "1280",
    },
    height: {
      min: "240",
      max: "720",
    },
  },
};

// A simplest example of constraints would be:
const constraints = { audio: true, video: true };

VoxeetSDK.conference
  .join(conference, { constraints: constraints })
  .then((info) => {})
  .catch((error) => {});

Parameters:

NameTypeDescription
conferenceConferenceThe conference to be joined
optionsJoinOptionsOptions for the conference

Returns: Promise‹Conference


leave

leave(__namedParameters: object): Promise‹void›

Leaves the conference.

Parameters:

NameTypeDefault
__namedParametersobject{}

Returns: Promise‹void›


listen

listen(conference: Conference): Promise‹Conference‹››

Joins a conference as a listener. You can choose to either join, replay, or listen to a conference. The listen method connects to the conference in the receiving only mode which does not allow transmitting video or audio.

See also: join, replay

Parameters:

NameTypeDescription
conferenceConference

Returns: Promise‹Conference‹››


localStats

localStats(): WebRTCStats

Provides standard WebRTC statistics for the application. Based on the WebRTC statistics, the SDK computes audio and video statistics.

Returns: WebRTCStats


mute

mute(participant: Participant, isMuted: boolean): any

Stops playing the specified remote participants' audio to the local participant or stops playing the local participant's audio to the conference. The mute method does not notify the server to stop audio stream transmission. To stop sending an audio stream to the server or to stop receiving an audio stream from the server, use the stopAudio method.

Note: The mute method depends on the Dolby Voice usage:

  • In conferences where Dolby Voice is not enabled, conference participants can mute themselves or remote participants.
  • In conferences where Dolby Voice is enabled, conference participants can only mute themselves.

Note: In SDK 2.4 and prior releases, if a conference participant calls the mute method, empty frames are sent to the other participants. Due to a Safari issue, participants who join a conference using Safari and start receiving the empty frames can experience a Safari crash. Due to a different API implementation in SDK 3.0, this problem does not occur during Dolby Voice conferences.

Parameters:

NameTypeDescription
participantParticipantThe local or remote participant
isMutedbooleanA boolean, true indicates that a participant is muted, false indicates that a participant is not muted.

Returns: any


playBlockedAudio

playBlockedAudio(): any

Allows a specific participant to play audio that is blocked by the browser's auto-play policy.

Returns: any


replay

replay(conference: Conference, offset: number, mixingOptions?: MixingOptions): Promise‹Conference

Replays a previously recorded conference.

See also: join, listen

Parameters:

NameTypeDefaultDescription
conferenceConference--
offsetnumber0Replays the conference from this offset (in milliseconds)
mixingOptions?MixingOptions--

Returns: Promise‹Conference


simulcast

simulcast(requested: Array‹ParticipantQuality›): any

Configures the quality of the received Simulcast streams.

Parameters:

NameTypeDescription
requestedArray‹ParticipantQualityan array of quality per participant.

Returns: any


startAudio

startAudio(participant: Participant): Promise‹any›

Notifies the server to either:

  • Start sending the local participant's audio stream to the conference, or
  • Start sending a remote participant's audio stream to the local participant

If the SDK does not transmit a specific remote participant's audio stream to the local participant, the local participant can enable the transmission of this stream through the startAudio method. In such a case, only the local participant starts receiving the audio stream; the startAudio method does not impact the rest of the conference participants.

If a remote participant does not transmit any audio stream, the local participant cannot change it using the startAudio method.

Note: This API is no longer supported for remote participants when the client connects to a Dolby Voice conference.

The Voxeet SDK automatically manages audio rendering and, therefore, the application does not need to implement its own <audio> element. The application can use selectAudioInput and selectAudioOutput methods to select the proper audio input and output devices.

Parameters:

NameTypeDescription
participantParticipanta participant who will receive the audio stream

Returns: Promise‹any›


startScreenShare

startScreenShare(sourceId: any): any

Starts a screen sharing session.

example

VoxeetSDK.conference
  .startScreenShare()
  .then(() => {})
  .catch((e) => {});

Parameters:

NameType
sourceIdany

Returns: any


startVideo

startVideo(participant: Participant, constraints: any): Promise‹any›

Notifies the server to either start sending the local participant's video stream to the conference or start sending a remote participant's video stream to the local participant. The startVideo method does not control the remote participant's video stream; if a remote participant does not transmit any video stream, the local participant cannot change it using the startVideo method.

example

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

voxeet.conference.startVideo(participantId, constraints).then(() => {});

Parameters:

NameTypeDescription
participantParticipantA participant to which the video will be started, either remote or local.
constraintsanyWebRTC video constraints

Returns: Promise‹any›


stopAudio

stopAudio(participant: Participant): Promise‹any›

Notifies the server to either:

  • Stop sending the local participant's audio stream to the conference, or
  • Stop sending a remote participant's audio stream to the local participant

If the SDK transmits a specific remote participant's audio stream to the local participant, the local participant can disable the transmission of this stream through the stopAudio method. In such a case, only the local participant stops receiving the audio stream; the stopAudio method does not impact the rest of the conference participants.

If a remote participant transmits an audio stream, the local participant cannot change it using the stopAudio method.

Note: This API is no longer supported for remote participants when the client connects to a Dolby Voice conference.

Parameters:

NameType
participantParticipant

Returns: Promise‹any›


stopScreenShare

stopScreenShare(): Promise‹any›

Stops the screen-sharing session.

Returns: Promise‹any›


stopVideo

stopVideo(participant: Participant): Promise‹void›

Notifies the server to either stop sending the local participant's video stream to the conference or stop sending a remote participant's video stream to the local participant.

Parameters:

NameType
participantParticipant

Returns: Promise‹void›