ConferenceService

The ConferenceService allows an application to manage a conference life cycle and interact with the conference. Using the service, you can create, join, and leave conferences.

For more information about creating and joining conferences, see the Basic Application Concepts guides.

Always implement an error for each called promise. You can also use the execute method, but in case of exceptions it triggers errors.

Available in the package com.voxeet.sdk.services.ConferenceService.

Methods

mute

mute(mute: boolean): boolean

Stops playing the local participant's audio to the conference. The mute method does not notify the server to stop audio stream transmission.

Parameters

NameTypeDescription
mutebooleanA boolean, true indicates that the local participant is muted, false indicates that a participant is not muted

Returns: boolean - informs if the mute state has changed.


mute

mute(@NonNull participant: Participant, mute: boolean): boolean

Stops playing the specified remote participants' audio to the local participant. The mute method does not notify the server to stop audio stream transmission.

Note: This API is not supported when the client connects to a Dolby Voice conference. If you wish to mute remote participants in Dolby Voice conferences, you must use the stop API. This API allows the conference participants to stop receiving the specific audio streams from the server.

Parameters

NameTypeDescription
participantParticipantnon null A remote participant
mutebooleanA boolean, true indicates that the participant is muted, false indicates that a participant is not muted

Returns: boolean - informs if the mute state has changed.


isMuted

isMuted(): boolean

Informs whether the local participant is muted.

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

Returns: boolean - information if the local participant is muted. Returns false if the participant is not muted or is not present at the conference. Returns true if the participant is muted.


muteOutput

muteOutput(mute: boolean): boolean

Controls playing remote participants' audio to the local participant.

Note: This API is only supported when the client connects to a Dolby Voice conference.

Parameters

NameTypeDescription
mutebooleanA boolean, true indicates that remote participants are muted, false indicates that remote participants are not muted.

Returns: boolean - a boolean indicating whether remote participants are muted.


isOutputMuted

isOutputMuted(): boolean

Informs whether the application plays the remote participants' audio to the local participant.

Returns: boolean - a boolean indicating whether the application plays the remote participants' audio to the local participant.


isSpeaking

isSpeaking(@NonNull participant: Participant): boolean

Indicates whether the current participant is speaking.

Parameters

NameTypeDescription
participantParticipantnon null participant

Returns: boolean - a boolean indicating whether the current participant is speaking.


findParticipantById

findParticipantById(@NonNull participantId: String): Participant

Provides the instance of the desired participant.

Parameters

NameTypeDescription
participantIdStringnon null participant's ID

Returns: @Nullable Participant - the instance of the participant. The null value informs that the conference or the participant does not exist in the current time session.


getConferenceType

getConferenceType(): LocalConferenceType

Gets the current conference type.

Returns: @NonNull LocalConferenceType - the ConferenceType. the ConferenceType.NONE is a default value.


getConference

getConference(): Conference

Gets the current Conference object.

Returns: @Nullable Conference - the nullable object.


isInConference

isInConference(): boolean

Informs if the specific conference exists. It can be used together with the ConferenceStatus.

Returns: boolean - Returns true if the conference exists or if the connection attempt to the conference is pending.


audioLevel

audioLevel(@Nullable participant: Participant): double

Gets the participant's audio level. The audio level value ranges from 0.0 to 1.0.

Note: When the local participant is muted, the audioLevel value is set to a non-zero value, and isSpeaking is set to true if the audioLevel is greater than 0.05. This implementation allows adding a warning message to notify the local participant that their audio is not sent to a conference.

Parameters

NameTypeDescription
participantParticipantnullable participant, the value can be safely set to an incorrect one

Returns: double - the value between 0 and 1.


create

create(@NonNull conferenceCreateOptions: ConferenceCreateOptions): Promise<Conference>

Creates the conference based on information from the ConferenceCreateOptions.

Parameters

NameTypeDescription
conferenceCreateOptionsConferenceCreateOptionsnon null information holder where the ID, parameters, and metadata can be passed

Returns: @NonNull Promise<Conference> - the conference creation information holder.


listen

listen(@NonNull conference: Conference): Promise<Conference>

Joins the conference in the listener mode in which the conference participant can only receive video and audio and cannot transmit any media.

Possible rejection causes :

  • ServerErrorException
  • InConferenceException
  • MediaEngineException
  • ParticipantAddedErrorEventException

Note: Conference events from other listeners are not available for listeners. Only users will receive conference events from other listeners.

Parameters

NameTypeDescription
conferenceConferencenon null conference

Returns: @NonNull Promise<Conference> - the promise to resolve.


listen

listen(@NonNull options: ConferenceListenOptions): Promise<Conference>

Joins the conference in the listener mode in which the conference participant can only receive video and audio and cannot transmit any media.

Possible rejection causes :

  • ServerErrorException
  • InConferenceException
  • MediaEngineException
  • ParticipantAddedErrorEventException

Parameters

NameTypeDescription
optionsConferenceListenOptionsnon null the holder of the options to join

Returns: @NonNull Promise<Conference> - the promise to resolve.


broadcast

broadcast(@NonNull conference: Conference): Promise<Conference>

Joins the conference in the broadcaster mode which allows transmitting audio and video.

Possible rejection causes:

  • ServerErrorException
  • InConferenceException
  • MediaEngineException
  • ParticipantAddedErrorEventException

Parameters

NameTypeDescription
conferenceConferencenon null conference

Returns: @NonNull Promise<Conference> - the promise to resolve.


join

join(@NonNull options: ConferenceJoinOptions): Promise<Conference>

Joins the conference with the conference. The ConferenceJoinOptions model can be constructed using the ConferenceJoinOptions.Builder model.

The possible exception in the rejection:

  • ServerErrorException
  • InConferenceException
  • MediaEngineException
  • ParticipantAddedErrorEventException

Parameters

NameTypeDescription
optionsConferenceJoinOptionsnon null the holder of the options to join

Returns: @NonNull Promise<Conference> - the promise to resolve.


kick

kick(@NonNull participant: Participant): Promise

Allows the conference owner, or a participant with adequate permissions, to kick another participant from the conference by revoking the conference access token. The kicked participant cannot join the conference again. This method is not available for mixed listeners.

Parameters

NameTypeDescription
participantParticipantnon null The participant who needs to be kicked from the conference.

Returns: @NonNull Promise - the promise to resolve.


updatePermissions

updatePermissions(@NonNull participantPermissions: List<ParticipantPermissions>): Promise

Updates the participant's conference permissions. If a participant does not have permission to perform a specific action, this action is not available for this participant during a conference, and the participant receives ConferencePermissionException. If a participant started a specific action and then lost permission to perform this action, the SDK stops the blocked action. For example, if a participant started sharing a screen and received the updated permissions that do not allow him to share a screen, the SDK stops the screen sharing session and the participant cannot start sharing the screen again.

Parameters

NameTypeDescription
participantPermissionsList<ParticipantPermissions>non null An array of ParticipantPermissions that includes the new participant's permissions.

Returns: @NonNull Promise - a promise with a boolean indicating conference permissions were successfully updated.


replay

replay(@NonNull conference: Conference, offset: long): Promise<Conference>

Replays the previously recorded conference. For more information, see the Recording Conferences article.

Possible rejection causes:

  • ServerErrorException
  • InConferenceException
  • MediaEngineException
  • ParticipantAddedErrorEventException

Parameters

NameTypeDescription
conferenceConferencenon null conference
offsetlongthe offset to start with

Returns: @NonNull Promise<Conference> - the promise to resolve that indicates the result of the request.


localStats

localStats(): Map<String, JSONArray>

Provides standard WebRTC statistics for the application to implement its own quality monitoring mechanisms.

Returns: @NonNull Map<String, JSONArray> - The WebRTC Stat Matrix.


simulcast

simulcast(@NonNull requested: List<ParticipantQuality>): Promise

Requests a specific quality of the received Simulcast video streams. You can use this method only for selected conference participants or for all participants who are present in a conference. For more information, see the Simulcast guide.

This method is not supported for mixed listeners.

Parameters

NameTypeDescription
requestedList<ParticipantQuality>non null list of simulcast configurations

Returns: @NonNull Promise - the promise to resolve.


getMaxVideoForwarding

getMaxVideoForwarding(): Integer

Gets the maximum number of video streams that may be transmitted to the local participant.

Returns: @Nullable Integer - The maximum number of video streams that the local participant can receive in the current conference.


getVideoForwardingStrategy

getVideoForwardingStrategy(): VideoForwardingStrategy

Gets the video forwarding strategy that the local participant uses in the current conference. This method is available only in SDK 3.6 and later.

Returns: @Nullable VideoForwardingStrategy - The strategy that the local participant uses in the current conference.


videoForwarding

videoForwarding(@NonNull options: VideoForwardingOptions): Promise

Sets the video forwarding functionality for the local participant. The method allows:

  • Setting the maximum number of video streams that may be transmitted to the local participant
  • Prioritizing specific participants' video streams that need to be transmitted to the local participant
  • Changing the video forwarding strategy that defines how the SDK should select conference participants whose videos will be received by the local participant

This method is available in SDK 3.6 and later and is not supported for mixed listeners.

Parameters

NameTypeDescription
optionsVideoForwardingOptionsnon null The video forwarding options.

Returns: @NonNull Promise


getInvitedParticipants

getInvitedParticipants(@NonNull conferenceId: String): Promise<ConferenceParticipantsInvitedResult>

Retrieves the list of participants invited to the conference.

Parameters

NameTypeDescription
conferenceIdStringnon null conference ID

Returns: @NonNull Promise<ConferenceParticipantsInvitedResult> - the promise to resolve.


getParticipants

getParticipants(): List<Participant>

Retrieves a list of conference participants.

Returns: @NonNull List<Participant> - A list of conference participants.


leave

leave(): Promise

Leaves the current conference.

Returns: @NonNull Promise


fetchConference

fetchConference(@NonNull conferenceId: String): Promise<Conference>

Provides a Conference object that allows joining a conference. For more information about using the fetch method, see the Conferencing document.

Parameters

NameTypeDescription
conferenceIdStringnon null conference ID.

Returns: @NonNull Promise<Conference> - the ConferenceInformation in the Promise to resolve.


hasParticipants

hasParticipants(): boolean

Informs that at least one participant is actively connected.

Returns: boolean - indicates if at least one participant is actively connected to the conference.


setSpatialDirection

setSpatialDirection(@NonNull direction: SpatialDirection): void

Sets the direction the local participant is facing in space. This method is available only for participants who joined the conference with the setSpatialAudio parameter enabled. Otherwise, SDK triggers the SpatialAudioException.

This method is not available for listeners. To set a spatial direction for listeners, use the Set Spatial Listeners Audio REST API. Using setSpatialDirection for listeners triggers the SpatialAudioException.

If the local participant hears audio from the position (0,0,0) facing down the Z-axis and locates a remote participant in the position (1,0,1), the local participant hears the remote participant from their front-right. If the local participant chooses to change the direction they are facing and rotate +90 degrees about the Y-axis, then instead of hearing the speaker from the front-right position, they hear the speaker from the front-left position. The following video presents this example:

Parameters

NameTypeDescription
directionSpatialDirectionnon null The direction the local participant is facing in space.

setSpatialEnvironment

setSpatialEnvironment(@NonNull scale: SpatialScale, @NonNull forward: SpatialPosition, @NonNull up: SpatialPosition, @NonNull right: SpatialPosition): void

Configures a spatial environment of an application, so the audio renderer understands which directions the application considers forward, up, and right and which units it uses for distance. This method is available only for participants who joined the conference with the setSpatialAudio parameter enabled. Otherwise, SDK triggers the SpatialAudioException.

This method is not available for listeners. To set a spatial environment for listeners, use the Set Spatial Listeners Audio REST API. Using setSpatialEnvironment for listeners triggers the SpatialAudioException.

If not called, the SDK uses the default spatial environment, which consists of the following values:

  • forward = (0, 0, 1), where +Z axis is in front
  • up = (0, 1, 0), where +Y axis is above
  • right = (1, 0, 0), where +X axis is to the right
  • scale = (1, 1, 1), where one unit on any axis is 1 meter

The default spatial environment is presented in the following diagram:

1920

Parameters

NameTypeDescription
scaleSpatialScalenon null A scale that defines how to convert units from the coordinate system of an application (pixels or centimeters) into meters used by the spatial audio coordinate system. For example, if SpatialScale is set to (100,100,100), it indicates that 100 of the applications units (cm) map to 1 meter for the audio coordinates. In such a case, if the listener's location is (0,0,0)cm and a remote participant's location is (200,200,200)cm, the listener has an impression of hearing the remote participant from the (2,2,2)m location. The scale value must be greater than 0. For more information, see the Spatial Chat article.
forwardSpatialPositionnon null A vector describing the direction the application considers as forward. The value can be either +1, 0, or -1 and must be orthogonal to up and right.
upSpatialPositionnon null A vector describing the direction the application considers as up. The value can be either +1, 0, or -1 and must be orthogonal to forward and right.
rightSpatialPositionnon null A vector describing the direction the application considers as right. The value can be either +1, 0, or -1 and must be orthogonal to forward and up.

setSpatialPosition

setSpatialPosition(@NonNull position: SpatialPosition): void

Sets a location from which the local participant listens to a Dolby Voice conference with enabled spatial audio. If the local participant does not have an established location, the participant hears audio from the default location (0, 0, 0). This method is available for the local participant only if the participant joined a conference with the setSpatialAudio parameter enabled. Otherwise, SDK triggers the SpatialAudioException.

This method is not available for listeners. To set a spatial position for listeners, use the Set Spatial Listeners Audio REST API. Using setSpatialPosition for listeners triggers the SpatialAudioException.

For example, if a local participant Eric, who does not have a set direction, calls setSpatialPosition(VoxeetSDK.session.participant, {x:3,y:0,z:0}), Eric hears audio from the position (3,0,0).

Parameters

NameTypeDescription
positionSpatialPositionnon null The location from which the participant will hear a conference.

setSpatialPosition

setSpatialPosition(@NonNull participant: Participant, @NonNull position: SpatialPosition): void

Sets a remote participant's position in space in a Dolby Voice conference to render the participant's audio from the specified location. Setting the remote participants’ positions is required in conferences that use the individual spatial audio style. In these conferences, if a remote participant does not have an established location, the participant does not have a default position and will remain muted until a position is specified. The shared spatial audio style does not support setting the remote participants' positions. In conferences that use the shared style, the spatial scene is shared by all participants, so that each client can set a position and participate in the shared scene. Calling this method for remote participants in the shared spatial audio style triggers the SpatialAudioException.

This method is available only for participants who joined a conference using the join method with the setSpatialAudio parameter enabled. Otherwise, SDK triggers the SpatialAudioException. To set a spatial position for listeners, use the Set Spatial Listeners Audio REST API.

For example, if a local participant Eric, who does not have a set direction, calls setSpatialPosition(VoxeetSDK.session.participant, {x:3,y:0,z:0}), Eric hears audio from the position (3,0,0). If Eric also calls setSpatialPosition(Sophia, {x:7,y:1,z:2}), he hears Sophia from the position (7,1,2). In this case, Eric hears Sophia 4 meters to the right, 1 meter above, and 2 meters in front. The following graphic presents the participants' locations:

1920

Parameters

NameTypeDescription
participantParticipantnon null The selected remote participant.
positionSpatialPositionnon null The participant's audio location from which their audio will be rendered.

Events

ActiveSpeakerChangeEvent

Emitted when an active speaker changes during a conference.

Available in the package com.voxeet.sdk.events.v3.ActiveSpeakerChangeEvent.

conference (Conference)

The conference in which an active speaker changed.


activeParticipants (List)

The list of active speakers.


unknownActiveSpeakers (List)

The optional list of participants who are known to be active, but not currently synced with the SDK.

ConferenceHistoryResult

Emitted when the application asks about historical conference elements (by calling the history restful endpoint).

Available in the package com.voxeet.sdk.events.sdk.ConferenceHistoryResult.

items (List)

The events list.

ConferenceStatusUpdatedEvent

Emitted when the conference changes status.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.sdk.ConferenceStatusUpdatedEvent.

state (ConferenceStatus)

The new status.


conference (Conference)

The conference. It can be a null value in case when nobody joined the conference.


conferenceAlias (String)

The conference alias. It is a mandatory property if nobody joined the conference.


error (Throwable)

The error object informing that participant's permissions changed.

ConferenceTimeoutNoParticipantsJoinedEvent

Emitted when within the maximum awaiting time nobody has joined the current participant at the conference.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.sdk.ConferenceTimeoutNoParticipantsJoinedEvent.

timeout (long)

A timeout set in the SDK.

IncomingCallEvent

Emitted when the application receives an incoming call. This event is optional when the NotificationService is properly referenced and set up on the developer side.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.sdk.IncomingCallEvent.

conferenceId (String)

The conference ID.

ParticipantAddedEvent

Emitted when a new participant is invited to a conference. The SDK does not emit ParticipantAddedEvent for a local participant. Listeners only receive the participantAdded events about users; they do not receive events for other listeners. Users receive the participantAdded events about users and do not receive any events about listeners. To notify all application users about the number of participants who are present at a conference, use the activeParticipants event.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.v2.ParticipantAddedEvent.

participant (Participant)

The conference participant.

ParticipantUpdatedEvent

Emitted when a participant changes ConferenceParticipantStatus. Listeners only receive the participantUpdated events about users; they do not receive events for other listeners. Users receive the participantUpdated events about users and do not receive any events about listeners. To notify all application users about the number of participants who are present at a conference, use the activeParticipants event.

The following graphic shows possible status changes during a conference:

5122

Diagram that presents the possible status changes

This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.v2.ParticipantUpdatedEvent.

participant (Participant)

The conference participant.

PermissionsUpdatedEvent

Emitted when the local participant's permissions are updated.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.sdk.PermissionsUpdatedEvent.

permissions (Set)

The updated conference permissions.

QualityIndicators

The Mean Opinion Score (MOS) which represents the participants' audio quality. The SDK calculates the audio quality scores and displays the values in a range from 1 to 5, where 1 represents the worst quality and 5 represents the highest quality. In cases when the audio MOS score is not available, the mos property returns the value -1.
This object can be accessed through the WebSocket usage.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.sdk.QualityIndicators.

mos (float)

The quality indicator.

StreamAddedEvent

Emitted when the SDK adds a new stream to a conference participant. Each conference participant can be connected to two streams: the audio and video stream and the screen-share stream. If a participant enables audio or video, the SDK adds the audio and video stream to the participant and emits StreamAddedEvent to all participants. When a participant is connected to the audio and video stream and changes the stream, for example, enables a camera while using a microphone, the SDK updates the audio and video stream and emits StreamUpdatedEvent. When a participant starts sharing a screen, the SDK adds the screen-share stream to this participants and emits StreamAddedEvent to all participants. The following graphic shows this behavior:

3048

The difference between the streamAdded and streamUpdated events

When a new participant joins a conference with enabled audio and video, the SDK emits StreamAddedEvent that includes audio and video tracks.

The SDK can also emit StreamAddedEvent only for the local participant. When the local participant uses the stopAudio method to locally mute the selected remote participant who does not use a camera, the local participant receives StreamRemovedEvent. After using the startAudio method for this remote participant, the local participant receives StreamAddedEvent.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.v2.StreamAddedEvent.

participant (Participant)

The conference participant.


mediaStream (MediaStream)

The media stream.

StreamRemovedEvent

Emitted when the SDK removes a stream from a conference participant. Each conference participant can be connected to two streams: the audio and video stream and the screen-share stream. If a participant disables audio and video or stops a screen-share presentation, the SDK removes the proper stream and emits StreamRemovedEvent to all conference participants.

The SDK can also emit StreamRemovedEvent only for the local participant. When the local participant uses the stopAudio method to locally mute a selected remote participant who does not use a camera, the local participant receives StreamRemovedEvent.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.v2.StreamRemovedEvent.

participant (Participant)

The conference participant.


mediaStream (MediaStream)

The media stream.

StreamUpdatedEvent

Emitted when a conference participant who is connected to the audio and video stream changes the stream by enabling a microphone while using a camera or by enabling a camera while using a microphone. The event is emitted to all conference participants. The following graphic shows this behavior:

3048

The difference between the streamAdded and streamUpdated events

The SDK can also emit StreamUpdatedEvent only for the local participant. When the local participant uses the stopAudio or startAudio method to locally mute or unmute a selected remote participant who uses a camera, the local participant receives StreamUpdatedEvent.
This object is generated locally by the SDK.

Available in the package com.voxeet.sdk.events.v2.StreamUpdatedEvent.

participant (Participant)

The conference participant.


mediaStream (MediaStream)

The media stream.

VideoStateEvent

Emitted when the local video state information has changed.

Available in the package com.voxeet.sdk.events.v2.VideoStateEvent.

mediaState (MediaState)

The new local video state.