This guide gives an overview of the API methods that you can use to create a meeting with audio and video.
The MeetingSession and its AudioVideoFacade are the starting points for creating meetings. You will need to create a Logger and MeetingSessionConfiguration before creating a meeting session.
You can utilize the ConsoleLogger to write logs with Android's Log. You can also implement the Logger interface to customize the logging behavior.
val logger = ConsoleLogger(LogLevel.DEBUG)
Create a MeetingSessionConfiguration object with the responses to chime:CreateMeeting and chime:CreateAttendee. Your server application should make these API calls and securely pass the meeting and attendee responses to the client application.
Using the above objects and an application context, create a DefaultMeetingSession.
val meetingSession = DefaultMeetingSession(sessionConfig, logger, applicationContext)
Before starting the meeting session, you should configure the audio device.
To retrieve a list of available audio devices, call meetingSession.audioVideo.listAudioDevices().
To use the chosen audio device, call meetingSession.audioVideo.chooseAudioDevice(mediaDevice).
You can receive events about changes to available audio devices by implementing a DeviceChangeObserver and registering the observer with the audio video facade.
To add a DeviceChangeObserver, call meetingSession.audioVideo.addDeviceChangeObserver(observer).
To remove a DeviceChangeObserver, call meetingSession.audioVideo.removeDeviceChangeObserver(observer).
A DeviceChangeObserver has the following method:
- onAudioDeviceChanged: called when audio devices are changed
Before starting audio or video, you will need to request permissions from the user and verify that
they are granted. Otherwise, the API will throw a SecurityException. Amazon Chime SDK for Android
already declares these permissions in its manifest file.
Audio permissions:
Manifest.permission.MODIFY_AUDIO_SETTINGS,
Manifest.permission.RECORD_AUDIO
Video permissions:
Manifest.permission.CAMERA
You can receive events about the audio session, video session, and connection health by implementing an AudioVideoObserver and registering the observer with the audio video facade.
To add an AudioVideoObserver, call meetingSession.audioVideo.addAudioVideoObserver(observer).
To remove an AudioVideoObserver, call meetingSession.audioVideo.removeAudioVideoObserver(observer).
An AudioVideoObserver has the following methods:
- onAudioSessionStartedConnecting: called when the audio session is connecting or reconnecting
- onAudioSessionStarted: called when the audio session has started
- onAudioSessionDropped: called when the audio session got dropped due to poor network conditions
- onAudioSessionStopped: called when the audio session has stopped
- onAudioSessionCancelledReconnect: called when the audio session cancelled reconnecting
- onConnectionBecamePoor : called when connection health has become poor
- onConnectionRecovered: called when connection health has recovered
- onVideoSessionStartedConnecting: called when the video session is connecting or reconnecting
- onVideoSessionStarted: called when the video session has started
- onVideoSessionStopped: called when the video session has stopped
Call this method after doing pre-requisite configuration (See previous sections). Audio permissions are required for starting the meeting session.
To start the meeting session, call meetingSession.audioVideo.start(). This will start underlying media clients and will start sending and receiving audio.
To stop the meeting session, call meetingSession.audioVideo.stop().
You can use a RealtimeObserver to learn when attendees join and leave and when their volume level, mute state, or signal strength changes.
To add a RealtimeObserver, call meetingSession.audioVideo.addRealtimeObserver(observer).
To remove a RealtimeObserver, call meetingSession.audioVideo.removeRealtimeObserver(observer).
A RealtimeObserver has the following methods:
- onVolumeChanged: called when one or more attendees' volume levels change
- onSignalStrengthChanged: called when one or more attendees' signal strengths change
- onAttendeesJoined: called when one or more attendees join the meeting
- onAttendeesDropped: called when one or more attendees drop from the meeting
- onAttendeesLeft: called when one or more attendees leave the meeting
- onAttendeesMuted: called when one or more attendees become muted
- onAttendeesUnmuted: called when one or more attendees become unmuted
Note that only attendees whose volume level, mute state, or signal strength has changed will be included. All callbacks provide both the attendee ID and external user ID from chime:CreateAttendee so that you may map between the two IDs.
If you are interested in detecting the active speaker (e.g. to display the active speaker's video as a large, central tile), implement an ActiveSpeakerObserver and register the observer with the audio video facade.
You will also need to provide an ActiveSpeakerPolicy. You can use DefaultActiveSpeakerPolicy or implement the ActiveSpeakerPolicy interface to customize the policy.
To add an ActiveSpeakerObserver, call meetingSession.audioVideo.addActiveSpeakerObserver(policy, observer).
To remove an ActiveSpeakerObserver, call meetingSession.audioVideo.removeActiveSpeakerObserver(observer).
An ActiveSpeakerObserver has the following methods:
- onActiveSpeakerDetected: called when one or more active speakers have been detected
- onActiveSpeakerScoreChanged: called when active speaker scores change at a given interval
You can control onActiveSpeakerScoreChanged's interval by providing a value for
scoreCallbackIntervalMs while implementing ActiveSpeakerPolicy. You can prevent this callback
from occurring by using a null value.
To mute the local attendee's audio, call meetingSession.audioVideo.realtimeLocalMute().
To unmute the local attendee's audio, call meetingSession.audioVideo.realtimeLocalUnmute().
You can use the following methods in order to send, receive, and display video.
A VideoTile is a binding of a tile ID, an attendee ID, that attendee's video, and a video view. The VideoTileState will contain further information such as if the video tile is for the local attendee. Video tiles start without a video view bound to it.
You can view content share the same way that you view a remote attendee's video. The video tile state will contain additional information to distinguish if that video tile is for content share.
Video permissions are required for sending the local attendee's video.
To start sending the local attendee's video, call meetingSession.audioVideo.startLocalVideo().
To stop sending the local attendee's video, call meetingSession.audioVideo.stopLocalVideo().
When starting the local attendee's video, the underlying media client will use the active video device or the front facing camera if there is no active video device. You can use the following methods to get or switch the active video device.
To get the active video device, call meetingSession.audioVideo.getActiveCamera().
To switch the active video device, call meetingSession.audioVideo.switchCamera().
To start receiving video from remote attendees, call meetingSession.audioVideo.startRemoteVideo().
To stop receiving video from remote attendees, call meetingSession.audioVideo.stopRemoteVideo().
You will need to implement a VideoTileObserver and register the observer with the audio video facade to receive video tile events for displaying video.
To add a VideoTileObserver, call meetingSession.audioVideo.addVideoTileObserver(observer).
To remove a VideoTileObserver, call meetingSession.audioVideo.removeVideoTileObserver(observer).
A VideoTileObserver has the following methods:
- onVideoTileAdded: called when an attendee starts sharing video
- onVideoTileRemoved: called when an attendee stops sharing video
- onVideoTilePaused: called when a video tile's pause state changes from Unpaused
- onVideoTileResumed: called when a video tile's pause state changes to Unpaused
- onVideoTileSizeChanged: called when a video tile's content size changes
A pause or resume event can occur when the underlying media client pauses the video tile for connection reasons or when the pause or resume video tile methods are called.
The video tile state is represented by a VideoPauseState that describes if and why (e.g., paused by user request, or paused for poor connection) it was paused.
To display video, you will also need to bind a video view to a video tile. Create a
VideoRenderView and bind that view to the video tile in VideoTileObserver's onVideoTileAdded
method. You can use DefaultVideoRenderView or customize the behavior by implementing the
VideoRenderView interface.
To bind a video tile to a view, call meetingSession.audioVideo.bindVideoView(videoView, tileId).
To unbind a video tile from a view, call meetingSession.audioVideo.unbindVideoView(tileId).
To pause a remote attendee's video tile, call meetingSession.audioVideo.pauseRemoteVideoTile(tileId).
To resume a remote attendee's video tile, call meetingSession.audioVideo.resumeRemoteVideoTile(tileId).
You can receive events about available audio and video metrics by implementing a MetricsObserver and registering the observer with the audio video facade. Events occur on a one second interval.
To add a MetricsObserver, call meetingSession.audioVideo.addMetricsObserver(observer).
To remove a MetricsObserver, call meetingSession.audioVideo.removeMetricsObserver(observer).
A MetricsObserver has the following method:
- onMetricsReceived: called when audio/video related metrics are received
Attendees can broadcast small (2KB max) data messages to other attendees. Data messages can be used to signal attendees of changes to meeting state or develop custom collaborative features. Each message is sent on a particular topic, which allows you to tag messages according to their function to make it easier to handle messages of different types.
To send a message on a given topic, meetingSession.audioVideo.realtimeSendDataMessage(topic, data, lifetimeMs).
When sending a message, the media server stores the messages for the duration specified by lifetimeMs. Up to 1024 messages may be stored for a maximum of 5 minutes. Any attendee joining late
or reconnecting will automatically receive the messages in this buffer once they connect. You can use
this feature to help paper over gaps in connectivity or give attendees some context into messages that were recently received.
To receive messages on a given topic, implement a DataMessageObserver and subscribe it to the topic using meetingSession.audioVideo.addRealtimeDataMessageObserver(topic, observer). Through onDataMessageReceived method in the observer, you receive a DataMessage containing the payload of the message and other metadata about the message.
To unsubscribe all DataMessageObservers from the topic, call meetingSession.audioVideo.removeRealtimeDataMessageObserverFromTopic(topic).
If you send too many messages at once, your messages may be returned to you with the throttled flag set. If you continue to exceed the throttle limit, the server may hang up the connection.
Note: You can only send and receive data messages after calling meetingSession.audioVideo.start(). To avoid missing messages, subscribe the DataMessageObserver to the topic prior to starting audio video.