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
| Name | Type | Description |
|---|---|---|
| mute | boolean | A 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
| Name | Type | Description |
|---|---|---|
| participant | Participant | non null A remote participant |
| mute | boolean | A 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
| Name | Type | Description |
|---|---|---|
| mute | boolean | A 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
| Name | Type | Description |
|---|---|---|
| participant | Participant | non 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
| Name | Type | Description |
|---|---|---|
| participantId | String | non 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
| Name | Type | Description |
|---|---|---|
| participant | Participant | nullable 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
| Name | Type | Description |
|---|---|---|
| conferenceCreateOptions | ConferenceCreateOptions | non 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
| Name | Type | Description |
|---|---|---|
| conference | Conference | non 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
| Name | Type | Description |
|---|---|---|
| options | ConferenceListenOptions | non 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
| Name | Type | Description |
|---|---|---|
| conference | Conference | non 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
| Name | Type | Description |
|---|---|---|
| options | ConferenceJoinOptions | non 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
| Name | Type | Description |
|---|---|---|
| participant | Participant | non 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
| Name | Type | Description |
|---|---|---|
| participantPermissions | List<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
| Name | Type | Description |
|---|---|---|
| conference | Conference | non null conference |
| offset | long | the 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
| Name | Type | Description |
|---|---|---|
| requested | List<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
| Name | Type | Description |
|---|---|---|
| options | VideoForwardingOptions | non 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
| Name | Type | Description |
|---|---|---|
| conferenceId | String | non 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
| Name | Type | Description |
|---|---|---|
| conferenceId | String | non 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
| Name | Type | Description |
|---|---|---|
| direction | SpatialDirection | non 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 frontup= (0, 1, 0), where +Y axis is aboveright= (1, 0, 0), where +X axis is to the rightscale= (1, 1, 1), where one unit on any axis is 1 meter
The default spatial environment is presented in the following diagram:
Parameters
| Name | Type | Description |
|---|---|---|
| scale | SpatialScale | non 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. |
| forward | SpatialPosition | non 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. |
| up | SpatialPosition | non 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. |
| right | SpatialPosition | non 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
| Name | Type | Description |
|---|---|---|
| position | SpatialPosition | non 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:
Parameters
| Name | Type | Description |
|---|---|---|
| participant | Participant | non null The selected remote participant. |
| position | SpatialPosition | non 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:
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:
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:
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.
Updated about 1 month ago