Business Productivity

How to Enable Client-Side Recording Using the Amazon Chime SDK

Builders who integrate real-time communications in their own web applications with the Amazon Chime SDK often ask how to enable client-side recording of audio calling, video calling, and screen sharing sessions. In this blog post, we demonstrate how you can deploy web-based recording service into your AWS account and record an Amazon Chime SDK session.

Solution overview

You begin this walkthrough by creating a AWS Cloud9 environment in your AWS account and deploying a docker container image containing the demo recording application into the Amazon Elastic Container Registry (Amazon ECR). AWS Cloud9 environments come pre-installed with AWS Command Line Interface (AWS CLI), AWS Serverless Application Model (AWS SAM), Docker, Git, and Node.js, which are necessary to deploy the demo recording application.

Next, you deploy an AWS CloudFormation stack that creates several resources such as an Amazon Elastic Container Service (Amazon ECS) cluster with an auto-scaling group, AWS Lambda, and a recording endpoint in Amazon API Gateway to start and stop recording. At this point, you have a generic website recording service that records audio and video for any web page that can be visited by a URL. The recording service can be scaled on-demand using Amazon ECS. For the best performance, you can deploy the recording service in the media region of the Chime SDK meetings you plan to record.

Once invoked, the recording service starts a recording task within the Amazon ECS cluster whose ARN is returned in the API response. This ARN is required to stop the recording at any time. The recording application joins the meeting as a participant, captures the web page rendered in Firefox using FFMpeg, xvfb, and PulseAudio, transcodes it to an Mpeg-4 video file format, and uploads the resulting media file via a multi-part upload to an Amazon S3 bucket.

The diagram below depicts this flow:

Demo recording application walkthrough

Prerequisites

To deploy and explore the recording service, you should have the following prerequisites:

Note: Deploying the recording demo application can incur charges on your AWS account.

Key steps

Here is an outline of the key steps involved in deploying and using the application.

  1. Create an AWS Cloud9 environment
  2. Create an Amazon ECR repository, build, and upload the docker image
  3. Set up the recording service
  4. Start an Amazon Chime SDK meeting with the Amazon Chime SDK demo and join with multiple participants
  5. Start the meeting recording
  6. Stop the recording and view the recording artifact
  7. Cleanup

Create an AWS Cloud9 environment

  1. Log in with your AWS credentials and go to the AWS Cloud9 Console. If you have previously set up a AWS Cloud9 environment in your account you can use it and skip this step entirely.
  2. Press the Create environment button or go here.
  3. For the Name enter <unique environment name> and press the Next step button.
  4. For Environment Settings use the defaults and press the Next step button.
  5. Review the Environment name and settings and press the Create environment button.
  6. You can optionally use your own Amazon EC2 instance if you have configured.

Wait for the environment to start. Once completed, a welcome message from AWS Cloud9 along will a bash shell will be displayed.

Create an Amazon ECR repository, build, and push the docker image

  1. In the bash shell of the AWS Cloud9 instance, run the below command to create a repository in Amazon ECR:
aws ecr create-repository --repository-name repository-name

This returns a JSON response similar to the following:

{ "repository": {"repositoryArn":"arn:aws:ecr:us-east-1:<accountId>:repository/<repository-name>","registryId": "<accountId>","repositoryName": "<repository-name>", "repositoryUri": "<accountId>.dkr.ecr.us-east-1.amazonaws.com/<repository-name>","createdAt": 1585247726,"imageTagMutability": "MUTABLE","imageScanningConfiguration": {"scanOnPush": false}}}

2. Execute the following commands to clone the recording demo in the AWS Cloud9 instance.

git clone https://github.com/aws-samples/amazon-chime-sdk-recording-demo.git
cd amazon-chime-sdk-recording-demo

3. Once done, execute the following command with the value of repositoryUri from step 1 to build and upload the docker image into Amazon ECR.

make ECR_REPO_URI=<repositoryUri>

Navigate to Amazon ECR console to verify that the image exists.

Amazon ECR Docker Image Confirmation

Set up the recording service

  1. Execute the following command to deploy the AWS CloudFormation stack shipped with the demo. This sets up the recording service along with IAM roles and networking resources such as Amazon Virtual Private Cloud (Amazon VPC), subnets, security groups, and an auto-scaling group required for the Amazon ECS Cluster.
node ./deploy.js -b <my-bucket> -s <my-stack> -i <my-docker-image> -r <region>

This step can take several minutes to complete. Once done, the Recording Service URL is printed in the output.
Recording Service URI

Start an Amazon Chime SDK meeting with the Amazon Chime SDK meeting demo and join with multiple participants

  1. You can download the Amazon Chime SDK Meeting demo by executing the following:
cd ../
git clone https://github.com/aws/amazon-chime-sdk-js

cd demos/serverless

 

2. Once done, deploy this demo by:

node ./deploy.js -r us-east-1 -b <my-bucket> -s <my-stack-name> -a meeting

The bucket name should be lower case and globally unique. The deploy script creates an AWS CloudFormation stack along with AWS Lambda and API Gateway resources required to use the demo. After the script finishes, it outputs a URL that can be opened in a browser.

3. Open the demo using the link which was obtained in the previous step and create a meeting with the text box provided. Once the permissions to use the microphone and speakers are granted, you will join an Amazon Chime SDK meeting.

4. Copy the URL obtained in the previous step in multiple tabs in any web browser supported by Amazon Chime SDK to simulate several participants joining the meeting. Optionally enable video or content sharing modalities for each participant in addition to audio.

Start the meeting recording

There are multiple ways for invoking a REST API in Amazon API Gateway. In this example, we use Postman.

  1. Follow the steps highlighted in this developer guide to install Postman.
  2. You need to select “AWS Signature” in the Postman application and add your AccessKey, SecretKey & AWS Region in the Authorization tab.

Entering authentication in the postman application

Entering authentication with the Postman Application

    3. Start recording by passing the recordingAction as “start” and a meetingURL to the recording service as query parameters in the POST request to the recording service. The URL must be URL encoded. This is shown in the picture below.

Initiating recording with Postman application

Initiating recording with the Postman Application

The entire web page is captured by FFmpeg at 720p (1280 X 720) fidelity and automatically transcoded and uploaded to Amazon S3. The file created in S3 remains hidden until the capture is complete. The Amazon Chime SDK demo application has been modified to suppress prompts for input device permissions and display customized UI for the recording bot.

Recording service - Joining the meetingRecording Application Joining the Meeting

It takes up to 30 seconds for the meeting bot to join the meeting for the first time. Subsequently, the bot takes under 5 seconds to join.

Stop the recording and view the recording artifact

  1. To stop the recording, you need to pass the ARN that was received in the API response to start the recording along with the recordingAction as “stop”.

Stopping the recording in the POSTMAN application

Stopping recording with the Postman Application

      2. Once the recording stops open the AWS Console and navigate to Amazon S3. The recording is saved in the bucket chime-meeting-sdk-<aws-account-id>-<region>-recording-artifacts with the following format: YYYY/MM/DD/HH/<ISO8601 time when meeting started>.mp4. You can now play or edit this recording, as necessary.

Cleanup

To avoid incurring any unintended charges as a result of deploying the recording demo application, it is important to delete any resources in your AWS account that you are not using such as the AWS CloudFormation stacks, AWS Cloud9 environment, and Amazon S3 recordings. Deleting these should automatically delete the resources used in this demo recording service.

Next Steps & Resources

In this blog, we have shown how your Amazon Chime SDK meeting can be recorded. It works by installing a docker image that runs in an Amazon ECS container and creates a meeting bot that joins a meeting, records the entire web page along with the media, transcodes it as an MPEG-4 file, and stores the file in an Amazon S3 bucket.

As an application builder you can customize the web page being recorded for any layout, control whether the recording participant is seen on the roster or not, and control which region the recording artifacts is stored in for compliance reasons.

To learn more about how you can use the Amazon Chime SDK, visit the Amazon Chime SDK web page. To start building, visit the Amazon Chime SDK GitHub repository for sample code and downloads. You can also refer to service documentation using the following links:.