Amazon Chime SDK for JavaScript

Build video calling, audio calling, and screen sharing applications powered by Amazon Chime.

The Amazon Chime SDK makes it easy to add collaborative audio calling, video calling, and screen share features to web applications by using the same infrastructure services that power millions of Amazon Chime online meetings.

This Amazon Chime SDK for JavaScript works by connecting to meeting session resources that you have created in your AWS account. The SDK has everything you need to build custom calling and collaboration experiences in your web application, including methods to: configure meeting sessions, list and select audio and video devices, start and stop screen share and screen share viewing, receive callbacks when media events occur such as volume changes, and control meeting features such as audio mute and video tile bindings.

To get started, see the following resources:

And review the following guides:

Examples

Installation

Make sure you have Node.js version 10 or higher. Node 14 is recommended and supported.

To add the Amazon Chime SDK for JavaScript into an existing application, install the package directly from npm:

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

Note that the Amazon Chime SDK for JavaScript targets ES2015, which is fully compatible with all supported browsers.

Setup

Create a meeting session in your client application.

import {
  ConsoleLogger,
  DefaultDeviceController,
  DefaultMeetingSession,
  LogLevel,
  MeetingSessionConfiguration
} from 'amazon-chime-sdk-js';
const logger = new ConsoleLogger('MyLogger', LogLevel.INFO);
const deviceController = new DefaultDeviceController(logger);
// You need responses from server-side Chime API. See below for details.
const meetingResponse = /* The response from the CreateMeeting API action */;
const attendeeResponse = /* The response from the CreateAttendee or BatchCreateAttendee API action */;
const configuration = new MeetingSessionConfiguration(meetingResponse, attendeeResponse);
// In the usage examples below, you will use this meetingSession object.
const meetingSession = new DefaultMeetingSession(
  configuration,
  logger,
  deviceController
);

Getting responses from your server application

You can use an AWS SDK, the AWS Command Line Interface (AWS CLI), or the REST API to make API calls. In this section, you will use the AWS SDK for JavaScript in your server application, e.g. Node.js. See Amazon Chime SDK API Reference for more information.

⚠️ The server application does not require the Amazon Chime SDK for JavaScript.

const AWS = require('aws-sdk');
const { v4: uuid } = require('uuid');

// You must use "us-east-1" as the region for Chime API and set the endpoint.
const chime = new AWS.Chime({ region: 'us-east-1' });
chime.endpoint = new AWS.Endpoint('https://service.chime.aws.amazon.com');

const meetingResponse = await chime.createMeeting({
  ClientRequestToken: uuid(),
  MediaRegion: 'us-west-2' // Specify the region in which to create the meeting.
}).promise();

const attendeeResponse = await chime.createAttendee({
  MeetingId: meetingResponse.Meeting.MeetingId,
  ExternalUserId: uuid() // Link the attendee to an identity managed by your application.
}).promise();

Now securely transfer the meetingResponse and attendeeResponse objects to your client application. These objects contain all the information needed for a client application using the Amazon Chime SDK for JavaScript to join the meeting.

The value of the MediaRegion parameter in the createMeeting() should ideally be set to the one of the media regions which is closest to the user creating a meeting. An implementation can be found in the getNearestMediaRegion()

Building and testing

git fetch --tags https://github.com/aws/amazon-chime-sdk-js
npm run build
npm run test

After running npm run test the first time, you can use npm run test:fast to speed up the test suite.

Tags are fetched in order to correctly generate versioning metadata.

To view code coverage results open coverage/index.html in your browser after running npm run test.

Generating the documentation

To generate JavaScript API reference documentation run:

npm run build
npm run doc

Then open docs/index.html in your browser.

Reporting a suspected vulnerability

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.

Usage

Device

Note: Before starting a session, you need to choose your microphone, speaker, and camera.

Use case 1. List audio input, audio output, and video input devices. The browser will ask for microphone and camera permissions.

const audioInputDevices = await meetingSession.audioVideo.listAudioInputDevices();
const audioOutputDevices = await meetingSession.audioVideo.listAudioOutputDevices();
const videoInputDevices = await meetingSession.audioVideo.listVideoInputDevices();

// An array of MediaDeviceInfo objects
audioInputDevices.forEach(mediaDeviceInfo => {
  console.log(`Device ID: ${mediaDeviceInfo.deviceId} Microphone: ${mediaDeviceInfo.label}`);
});

Use case 2. Choose audio input and audio output devices by passing the deviceId of a MediaDeviceInfo object.

const audioInputDeviceInfo = /* An array item from meetingSession.audioVideo.listAudioInputDevices */;
await meetingSession.audioVideo.chooseAudioInputDevice(audioInputDeviceInfo.deviceId);

const audioOutputDeviceInfo = /* An array item from meetingSession.audioVideo.listAudioOutputDevices */;
await meetingSession.audioVideo.chooseAudioOutputDevice(audioOutputDeviceInfo.deviceId);

Use case 3. Choose a video input device by passing the deviceId of a MediaDeviceInfo object.

If there is an LED light next to the attendee's camera, it will be turned on indicating that it is now capturing from the camera. You probably want to choose a video input device when you start sharing your video.

const videoInputDeviceInfo = /* An array item from meetingSession.audioVideo.listVideoInputDevices */;
await meetingSession.audioVideo.chooseVideoInputDevice(videoInputDeviceInfo.deviceId);

// You can pass null to choose none. If the previously chosen camera has an LED light on,
// it will turn off indicating the camera is no longer capturing.
await meetingSession.audioVideo.chooseVideoInputDevice(null);

Use case 4. Add a device change observer to receive the updated device list. For example, when you pair Bluetooth headsets with your computer, audioInputsChanged and audioOutputsChanged are called with the device list including headsets.

const observer = {
  audioInputsChanged: freshAudioInputDeviceList => {
    // An array of MediaDeviceInfo objects
    freshAudioInputDeviceList.forEach(mediaDeviceInfo => {
      console.log(`Device ID: ${mediaDeviceInfo.deviceId} Microphone: ${mediaDeviceInfo.label}`);
    });
  },
  audioOutputsChanged: freshAudioOutputDeviceList => {
    console.log('Audio outputs updated: ', freshAudioOutputDeviceList);
  },
  videoInputsChanged: freshVideoInputDeviceList => {
    console.log('Video inputs updated: ', freshVideoInputDeviceList);
  }
};

meetingSession.audioVideo.addDeviceChangeObserver(observer);

Starting a session

Use case 5. Start a session. To hear audio, you need to bind a device and stream to an <audio> element. Once the session has started, you can talk and listen to attendees. Make sure you have chosen your microphone and speaker (See the "Device" section), and at least one other attendee has joined the session.

const audioElement = /* HTMLAudioElement object e.g. document.getElementById('audio-element-id') */;
meetingSession.audioVideo.bindAudioElement(audioElement);

const observer = {
  audioVideoDidStart: () => {
    console.log('Started');
  }
};

meetingSession.audioVideo.addObserver(observer);

meetingSession.audioVideo.start();

Use case 6. Add an observer to receive session lifecycle events: connecting, start, and stop.

Note: You can remove an observer by calling meetingSession.audioVideo.removeObserver(observer). In a component-based architecture (such as React, Vue, and Angular), you may need to add an observer when a component is mounted, and remove it when unmounted.

const observer = {
  audioVideoDidStart: () => {
    console.log('Started');
  },
  audioVideoDidStop: sessionStatus => {
    // See the "Stopping a session" section for details.
    console.log('Stopped with a session status code: ', sessionStatus.statusCode());
  },
  audioVideoDidStartConnecting: reconnecting => {
    if (reconnecting) {
      // e.g. the WiFi connection is dropped.
      console.log('Attempting to reconnect');
    }
  }
};

meetingSession.audioVideo.addObserver(observer);

Audio

Note: So far, you've added

Last updated Popular

v2.0.0

Install

npm install amazon-chime-sdk-js
yarn add amazon-chime-sdk-js

BUNDLE SIZE

Not Available

DOWNLOAD TIME

Not Available

CDNs

extras

Contributors

  • aws