To allow extended scaling of meetings that expect significant portions of attendees be non-active participants (e.g. a live event or presentation), the Amazon Chime SDK supports the creation of Replica meetings with specialized behavior. For explanation of how to create Replica meetings via the CreateMeeting and CreateMeetingWithAttendees APIs, a high level overview of how Replica meetings work, and a walkthrough of how to incorporate this type of scaling in your applications meetings, see the section above.
In short, an attendee in a Replica meeting will receive remote media and metadata from the Primary meeting as if they were attendees of the Primary meeting (though they will not require authentication for the Primary meeting unless they would like to be promoted to an active participant, which is covered in a separate section below).
Note: This guide will refer to the meeting which is replicated as a Primary meeting, however there is no difference between a Primary meeting and a normal meeting. There is additionally no difference in the behavior and features of an attendee of a Primary meeting, so builders should not need to use the SDK any differently from the way they would for non-replicated meetings for those Primary meeting attendees.
As mentioned above, an attendee in a Replica meeting will receive remote media and metadata as if they were attendees of the Primary meeting. They will not require authentication for the Primary meeting unless they would like to be promoted to a fully-interactive participant; see section below. For extended clarity, we can further break down this behavior by section. Details on send limitations are explained in the following section.
Replica meeting attendees should subscribe to real time events as they would in a normal meeting. This is covered in the API Overview. Post-subscription, the Replica attendee can expect following behavior:
realtimeSubscribeToAttendeeIdPresence) will be received for the Primary meeting attendees. The callback will contain both the attendee ID and external user ID from
CreateAttendee for the aforementioned Primary meeting attendee. There will be no callback for attendees of the same Replica meeting that was joined, or any other Replica meeting.
subscribeToActiveSpeakerDetector) will correspond to Primary meeting attendees. There will be no callback for attendees of the same Replica meeting that was joined, or any other Replica meeting.
A Replica attendee will receive audio played out to their chosen audio device from the Primary meeting (see this section in the API Overview for information on setting up an audio output device). This will not include any audio from any Replica meeting attendees.
Similarly, remote video availability notified via
videoTileDidUpdate will all correspond to Primary meeting attendees (i.e. they will contain the Attendee ID and External ID from a
CreateAttendee call for the Primary meeting). Builders should handle and respond to those callbacks and
videoTileWasRemoved in the same fashion as normal meetings.
All information related to receipt and display of video in User guide for Priority-based downlink policy and Managing Video Quality for Different Video Layouts continue to apply to Replica meeting attendees.
A replica meeting attendee which has subscribed to meeting data messages via
realtimeSubscribeToReceiveDataMessage will receive data messages (i.e. those sent via
realtimeSendDataMessage) from Primary meeting attendees. They will not receive any from other Replica meeting attendees.
If live transcription is enabled for the Primary meeting, Replica meeting attendees will receive Transcription Events just as they would any Primary meeting data message. See the Developer Guide for more information on how to handle Transcription Events.
The client events and ingestion covered in Meeting Events and Event Ingestion (note, these are different the events such as provided by
realtimeSubscribeToAttendeeIdPresence) will continue to work as before for Replica meeting attendees, all events have the meetingId attribute set to the Replica meeting ID.
As covered in the previous section, Replica meeting attendees will not receive media, data messages, or attendee events for any other Replica meeting attendee, regardless of whether they are in the same replica meeting. Additionally, Primary meeting attendees will not receive media, data messages, or attendee events for any Replica meeting attendee.
Therefore application builders should be considerate of that fact and avoid displaying UI which may indicate that other participants may be able to receive transmitted media unless there is the ability to promote as covered in section below.
Although application builders should already be aware of when attendees are in a replica meeting, they will additionally be notified of video-related restrictions via
videoSendDidBecomeUnavailable. In particular:
videoAvailabilityDidChange will always return a MeetingSessionVideoAvailability object with canStartLocalVideo set to false.
videoSendDidBecomeUnavailable. As mentioned before, builders should avoid code which tries to enable video for attendees in Replica meetings.
Since transmitted media from non-promoted Replica meeting attendee will not be visible to any other participants, it is recommended to avoid querying for device permissions that are not necessary. Refer to this section in the API Overview for instructions on how to optimally set up a view-only/spectator experience.
Primary meeting credentials for Replica attendees which desire promotion need to be retrieved in the same way as a normal Primary meeting attendee via
CreateAttendee Chime APIs. See Getting responses from your server application for more information. Once the Primary meeting credentials have been retrieved, they can be provided to an
AudioVideoFacade which is already connected to a Replica meeting:
// We assume `replicaMeetingSession` is created using configuration created
// with Replica meeting credentials.
const replicaMeetingSession = new DefaultMeetingSession(
// Can then use `replicaMeetingSession` as non-participating session.
// When promotion is desired...
// Response from Primary's CreateMeeting API call
const meetingResponse = getPrimaryMeeting();
//Response from CreateAttendee API call against Primary
const attendeeResponse = createPrimaryMeetingAttendee();
const configuration = new MeetingSessionConfiguration(
// This could also be created solely through the `CreateAttendee` response
const credentials = configuration.credentials;
const status = meetingSession.audioVideo.promoteToPrimaryMeeting(credentials);
status is a
MeetingSessionStatus object. See
promoteToPrimaryMeeting documentation for possible return codes. If status.code is
MeetingSessionStatusCode.OK, the connection has successfully authenticated as a Primary meeting attendee and the attendee experience should now be as if you had joined the Primary meeting directly. This means:
videoAvailabilityDidChange should eventually be called
canStartLocalVideo set to true.
startVideoInput can then be used as normally to enable
video in the conference. Further information on configuring video input can be found in the API Overview. In the same way as audio, this video will be associated with the Primary meeting attendee.
realtimeSendDataMessage will be forwarded to all Primary and Replica meeting attendees. They will also be associated with the Primary meeting attendee.
Builders should be considerate of these changes by showing UI related to video enable/disable, audio mute/unmute, etc. on promoted attendees.
A promoted attendee can be considered as authenticated in two meetings, as two attendees, at the same time. However with regards to their connection to the Amazon Chime SDK servers, their 'root' connection is as a Replica attendee, and thus there are three ways for the attendee to 'revert' to a view-only, Replica meeting attendee with behavior explained in earlier sections. (i.e. demotion will lead to audio, video, and data messages ceasing to be forwarded from the client). All demotions will result in a call to
AudioVideoObserver.audioVideoWasDemotedFromPrimaryMeeting with a corresponding status code.
DeleteAttendee on the Chime API.
promoteToPrimaryMeeting should be called again with the same credentials.
Generated using TypeDoc