Business Productivity

Building a Meeting Application using the Amazon Chime SDK

The Amazon Chime SDK provides a set of real-time communications components that developers can use to add audio, video, and screen sharing sessions to their own applications. The Amazon Chime SDK can be used to build solutions like full unified communications (UC) applications, distance learning solutions, tele-health applications, and simple one-to-one video interaction with customers.

This blog post guides you on how to deploy the demo meeting application code that is included with the Amazon Chime SDK using AWS Cloud9. After the demo meeting application is deployed, key steps of building your own meeting application using the sample code are described.

Amazon Chime SDK overview

Three major components support the development of your real-time media applications using the Amazon Chime SDK. These are:

  • Amazon Chime Application Programming Interfaces (APIs) in the AWS SDK.
  • Amazon Chime Client SDK libraries.
  • Amazon Chime Media Services.

Let’s review these next.

Amazon Chime APIs

The Amazon Chime APIs in the AWS SDK are used to manage the meeting lifecycle. Your meeting service can use the APIs to create meetings, manage the attendees allowed to join the meeting, and securely provide the information needed to join the meeting.

Amazon Chime SDK client libraries

There are three Amazon Chime SDK client libraries. The Amazon Chime SDK for JavaScript enables real-time media in WebRTC-enabled browsers. The mobile device client libraries can similarly be used when developing applications for third party iOS and Android devices. The client library contains methods to configure media sessions, list and select audio and video devices, start and stop content sharing and viewing, receive callbacks when media events occur such as volume changes, and control meeting features such as audio mute and video tile bindings.

Amazon Chime Media Services

Amazon Chime Media Services support the audio, video, and content sharing in your application. These services are the same as those that power the Amazon Chime application, available in 14 AWS regions. However, applications built using the Amazon Chime SDK work independently of meetings created in Amazon Chime. The Amazon Chime client cannot be used to join a meeting created with the Amazon Chime SDK.

The Amazon Chime SDK is provided with several demonstration applications. There is a browser-based demo of a meeting application that can be run on a local server, a serverless version of the same demo that creates the meeting service in AWS Lambda, a virtual classroom demo, and a distinct demo for a video help desk implementation.

The remainder of this blog describes deploying and exploring the serverless version of the browser-based meeting demo application using AWS Cloud9. The serverless demo provides several Node.js Lambda functions that implement the meeting service and serve the web-based meeting application.

Deploying the demo meeting application using AWS Cloud9

Prerequisites

For this walkthrough, you need an AWS account and Identity and Access Management (IAM) role that has the AdministratorAccess policy. To build applications using the Amazon Chime SDK, development experience and familiarity with JavaScript is required.

Note: Deploying the demo code in AWS Cloud9 environment may incur AWS charges.

Key Steps

The following steps show you how to create an AWS Cloud9 environment, download the Amazon Chime SDK, and build the sample application.

  1. Log into your AWS account with an IAM role that has the AdministratorAccess policy.
  2. Use the us-east-1 (N. Virginia) region of your AWS account. You can use any AWS region that is supported by AWS Cloud9.
  3. Go to the AWS Cloud9 Dashboard.
  4. Press Create environment.
  5. Enter “chime-meeting-sdk” for the Name and press Next step.
  6. Leave the default Environment settings and press Next step.
  7. On the Review page, press Create environment.
  8. Wait for the environment to start.
  9. In the bash terminal, enter the following commands (substituting unique names for <my-bucket> and <my-stack-name>):

git clone https://github.com/aws/amazon-chime-sdk-js
cd amazon-chime-sdk-js/demos/serverless/
node ./deploy.js -r us-east-1 -b <my-bucket> -s <my-stack-name> -a meeting

The script deploys the meeting demo application and provides an API endpoint URL. Open the URL in a new window to see the application. Take some time to use the meeting demo application by going to the API endpoint URL provided by the deployment script, creating a meeting, and joining that meeting from different locations.

Building the Amazon Chime SDK demo in AWS Cloud9

The AWS Cloud9 environment while building the Amazon Chime SDK demo application.

Demo meeting application walk-through

Resources

Understanding the AWS resources that the demo meeting application deployed can help you to understand the requirements for your own meeting service. In the left-hand pane of AWS Cloud9, navigate to the amazon-chime-sdk-js/demos/serverless directory and examine template.yaml to see these AWS CloudFormation resources:

  • An IAM policy template that is used to create the role for the AWS Lambda functions. This policy gives the functions the ability to call the Amazon Chime API to create and manage meetings. In your application, you could use the AWS managed policy named AmazonChimeSDK.
  • Two Amazon DynamoDB tables for storing the Meetings and Attendees created by the demo application. Your meeting service may need to store friendly meeting names, attendee display names, or authenticated identities that are allowed to join specific meetings.
  • An Amazon SQS queue that could be used for meeting event notifications. The Amazon Chime SDK sends various meeting lifecycle events. You could use these events trigger actions upon meeting start, meeting end, or when attendees join or leave your meetings, for example.
  • Several AWS Lambda functions for displaying the meeting app, creating a meeting, adding attendees, managing the meeting join, and processing meeting events. These are exposed via the Amazon API Gateway.

As a model for how to build your meeting service, it is helpful to examine the code in the demo. The following section considers a small part of the back-end meeting service and the front-end meeting application.

Creating a meeting

In the AWS Cloud9 environment, open /amazon-chime-sdk-js/demos/serverless/src/handlers.js. Find the section that begins with:

exports.join = async(event, context, callback) => {

This defines the meeting join handler that can be invoked with the URL:

https://<API-gateway-URL>/Prod/join?title=<meeting-title>&name=<attendee-name>&region=<meeting-region>

Because the demo meeting service allows the meeting to be created as the first attendee is joining, the join handler checks to see if the specified meeting already exists and creates it, if needed, in this code:

  let meetingInfo = await getMeeting(title);
  if (!meetingInfo) {
    const request = {
      ClientRequestToken: uuid(),
      MediaRegion: region,
      NotificationsConfiguration: getNotificationsConfig(),
    };
    console.info('Creating new meeting: ' + JSON.stringify(request));
    meetingInfo = await chime.createMeeting(request).promise();
    await putMeeting(title, meetingInfo);
  }

Like the other Amazon Chime API calls, this request is signed using the service name chime in the region us-east-1 and sent to the single REST endpoint for Amazon Chime at https://service.chime.aws.amazon.com. Although there is a single API endpoint, this does not limit the regions that can provide local meeting services to your users.

A media region that is closer to your users can be specified to minimize latency. Your application should identify the best region to host the meeting before calling the CreateMeeting API. Regions with media services include ap-northeast-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1, eu-north-1, eu-west-1, eu-west-2, eu-west-3, sa-east-1, us-east-1, us-east-2, us-west-1, and us-west-2. You can use https://l.chime.aws to return the region closest to the user.

It is important to note that the meeting is an ephemeral resource – it does not persist beyond what is needed for the meeting lifecycle. You can delete the meeting with an API call. It is also deleted if no audio connections are present in the meeting for more than five minutes or for some other scenarios that indicate the meeting is no longer needed. To avoid meeting join failures, your meeting service must ensure that the meeting is created (or re-created) just prior to joining.

Since the meeting is first created without attendees, the meeting service must also add them with a call to the CreateAttendee API. The handler does that in this code:

  const attendeeInfo = (await chime.createAttendee({
      MeetingId: meetingInfo.Meeting.MeetingId,
      ExternalUserId: uuid(),
    }).promise());

  putAttendee(title, attendeeInfo.Attendee.AttendeeId, name);

This request allows you to associate an external user ID with the attendee. This external ID could be an identifier from your directory service that helps you to authorize the meeting join request later from your application.

The response to the CreateAttendee request is an Attendee object that contains an Id and JoinToken. The meeting and attendee objects must be securely returned to the client when starting the meeting session.

Note that the demo application does not provide any authentication of users or limit which endpoints can join a meeting. The meeting service that you develop should restrict the ability to create meetings by authenticating users.

Joining the meeting

To join a meeting, this application must initialize the meeting session with a MeetingSessionConfiguration which is constructed from the results of the CreateMeeting and CreateAttendee APIs used by your meeting service.

To see this in the sample meeting application, in the AWS Cloud9 environment, open /amazon-chime-sdk-js/demos/browser/app/meetingV2/meetingV2.ts. Find the initializeMeetingSession definition that looks like this:

  async initializeMeetingSession(configuration: MeetingSessionConfiguration): Promise<void> {
    const logger = new ConsoleLogger('SDK', LogLevel.INFO);
    const deviceController = new DefaultDeviceController(logger);
    configuration.enableWebAudio = this.enableWebAudio;
    this.meetingSession = new DefaultMeetingSession(configuration, logger, deviceController);
    this.audioVideo = this.meetingSession.audioVideo;

    this.audioVideo.addDeviceChangeObserver(this);
    this.setupDeviceLabelTrigger();
    await this.populateAllDeviceLists();
    this.setupMuteHandler();
    this.setupCanUnmuteHandler();
    this.setupSubscribeToAttendeeIdPresenceHandler();
    this.audioVideo.addObserver(this);
    this.audioVideo.addContentShareObserver(this);
    this.initContentShareDropDownItems();
  }

The media session created here contains a DeviceController for interacting with the browser’s media input and output devices. The meeting application must use the DeviceController to select audio/video devices and bind them to elements in your web page.

Although we have explored the sample applications by cloning the source code from GitHub, you should add the library to your application by installing the appropriate package from npm with:

npm install amazon-chime-sdk-js --save

Cleaning up

If you no longer want to keep the demo active in your AWS account and wish to avoid incurring AWS charges, the demo resources can be removed by deleting the two AWS CloudFormation stacks created in the walkthrough. There is one stack for the AWS Cloud9 environment and one stack created when deploying the serverless meeting demo. These stacks can be found in the AWS CloudFormation console.

Next Steps and Resources

To learn more about how to build using the Amazon Chime SDK here are few more resources you can use.

Conclusion

Developers can use the Amazon Chime SDK to integrate communications services into their applications to deliver reliable end-user experiences without the need to manage infrastructure or networking components. The brief overview of the SDK in this article should help you understand what it offers and how you can quickly get started.